Note: This business process An organized flow of activities or tasks that achieves a business goal. An automated business process minimizes the amount of paperwork and manual tasks to complete that process by way of automatic actions, online forms, and automatically generated messages. is an extension model that is developed outside the normal release schedule to meet specific customer needs. To request one of these models, you must submit a Salesforce Service Request to UKG. After the model is delivered to your tenant, you can edit it to meet your needs.
The Timecard Save Validation process provides a framework that offers granular control over transactional data passed to the Workflow Engine by a manager who saves timecard changes.
Organizations have the option to enforce one or more validation workflows at any given time. When the process is initiated by the manager timecard save action, supported validation workflows include:
Historical Edits Restriction
Enabling edits in signed-off periods allows the manager to edit the timecard in any signed-off period.
When you enable the Historical Edits Validation function and an employee’s timecard is signed-off, the manager is restricted to a certain number of signed-off pay periods in which editing is allowed. Restriction is dependent on the employee's primary location (primary assignment) on the edit date.
Timecard edits that are validated under this functionality include:
-
Punch The entries on a timecard that mark the beginning (in-punch) or end (out-punch) of a work interval, such as the beginning of a shift or transfer. and paycode A category of time or money that employees earn, for example, Regular Hours, Bonus, or Sick. edits
-
Accrual edits
-
Overtime approvals
-
Move amounts
-
Activity segments and team membership
-
Job transfers
Manager Access to Employee
Manager access to an employee timecard is based on the employee group assignment. When the employee works for a manager at least one day during the selected time period, the manager has access to all days in the time period.
When you enable the Manager Access to Employee function and an employee works on different contracts or has multiple primary locations and jobs that are not part of the manager's employee group, the manager is prevented from making paycode edits on days when the employee reports to some other manager.
Mandatory Comments
Mandatory Paycode Comments — Timecard entry
Adding a comment to a paycode edit in a timecard is a common business requirement. A missing comment can disrupt an established business process, as in the following examples.
-
Operational reasons
A production line encounters downtime, which prevents its operators from working. A comment attached to the excused paycode edit identifies the reason, such as malfunction or material shortage, and is then used for reporting purposes. The absence of a comment prevents correct reporting related to the cause of the incident.
-
Payroll reasons
In certain regions, customers use one generic paycode for a series of different absences. A comment identifies the absence type and is referenced during payroll export. When no comment is provided, payroll is not processed correctly, resulting in payment errors.
-
Missing time audit
When employees are late, a duration paycode is added to justify missing time. The missing time must be accompanied by a comment for tracking purposes.
To prevent disruption of an organization's established business processes, the Mandatory Paycode Comments function prevents a timecard save action by using a two-step validation. First, the validation checks whether the paycode requires a comment. Second, the validation checks the appropriateness of the comment selection. When no comment or an incorrect comment is attached to the paycode, the system displays an error message and prevents the timecard save action.
Granular control over action types, such as add, edit, and delete, is supported by this function.
Note: The Mandatory Paycode Comments validation process initiates only when a paycode action is performed in the timecard. Paycode actions performed during a group edit Changes made to more than one employee record at a time, for example, add or delete a paycode or punch to a group of timecards., such as in a dataview A configurable tool for analyzing data and taking actions on a group of employees or an organization., are not routed through the validation workflow.
Mandatory Paycode Comments — Global Time Off Requests validation
See the Global Time Off Requests (GTOR) Validation Rulestopic.
The GTOR validation process supports mandatory paycode comments when submitting requests. Enable this validation process according to customer need.
Mandatory Overtime Approval Comments
In some organizations, the manager is required to approve overtime worked by an employee. During approval, the manager approves all, some or no overtime with the expectation that a comment is selected.
The Mandatory Overtime Approval Comments function prevents a timecard save action after overtime approval unless a comment and note are entered. The validation is only applicable when approving overtime since comment and note selection do not apply when editing or resetting overtime. If the overtime approval is reset, the mandatory comment and note are removed.
Mandatory Punch Edits Comments
Adding a comment to a punch edit in the timecard is a common business requirement.
The Mandatory Punch Edits Comments function validates that a comment is present before the timecard save action is allowed. Granular control over different punch actions — add, edit, or delete — allows organizations to configure punch actions that require a comment and note. For example, some organizations could require comments for each punch action, while other organizations could require comments only when adding a punch.
Deleting a punch from the timecard typically requires a document trail for compliance purposes.
When the Mandatory Punch Edits Comments function and granular control over punch comments are enabled, the manager must add a justification comment to a punch before it can be deleted. If the comment is not present, the workflow displays an error message and prevents the deletion. After the manager adds the comment and then deletes the punch, the deleted punch and justification comment can be viewed in the timecard’s audit tab. This action ensures that documentation exists in the system for the auditing staff to review, when required.
Limitations
Historical edits restriction does not apply to the pending corrections functionality.
User experience
Historical Edit Restriction
A manager notices that a bonus paycode is missing in the previous pay period of a signed-off timecard. The manager navigates to a dataview in the application, and then enables editing for the employee. After returning to the timecard to make the appropriate adjustment, the manager saves the edit.
The manager then attempts to edit the timecard on a date that falls before the previous pay period. Because the organization restricts historical corrections Edits that occur after timecards are approved and signed-off. to one pay period prior to the last sign-off date, the timecard save action generates an error and prevents the action.
Manager Access to Employee
A contract employee works on multiple short-term contracts for the organization. Manager A oversees contract A; and Manager B oversees contract B.
The contract employee works the first 3 days of the pay period on contract A, and then works the last 3 days of the pay period on contract B.
If Manager A adds a paycode on the last day of the pay period, which is outside Manager A's span of control, the system displays an error message and prevents the timecard save action.
Mandatory Comments
Mandatory Paycode Comments — Timecard entry
When adding the "Sick" paycode to a timecard, the paycode must be accompanied with at least one of the following comments:
-
COVID
-
Doctor visit
-
Blood donation
-
Migraine
A manager who is responsible for entering the "Sick" paycode to an absent employee's timecard forgets to select a comment before saving the paycode edit.
Because the paycode is configured with mandatory comments, the validation generates an error and prevents the timecard save action.
Mandatory Overtime Approval Comments
An employee worked overtime one day during the previous pay period. The overtime requires manager approval in order to be paid.
When approving the overtime, the manager forgets to add a comment before saving the timecard. Because overtime approval is configured with mandatory comments, the timecard save action generates an error and prevents the action.
Mandatory Punch Edits Comments
An employee receives manager approval to leave work one hour early. The punch edit requires a comment to indicate manager consent. When the manager signs-off the employee timecard, they forget to select a comment.
Because punch editing is configured with mandatory comments, the validation generates an error and prevents the timecard save action.
Before you start
Before you configure this business process, you must do the following:
-
Attestation The act of confirming or attesting that something is true. For example, when punching out, users may need to attest that they took their meal breaks. conditions: Create an attestation condition type of Always. See the
-
Attestation buttons: Create an attestation button with a button type of Timecard Action and a button subtype of Save. See the
-
Attestation assignments: After you have deployed the Timecard Save Validation model, create an attestation assignment, and then select the appropriate attestation condition, attestation button, and business process model. See the
Note: You must add the Attestation Process to the Attestation Profile that is assigned to managers who use the Timecard Save Validation business process.
Configure Timecard Save Validation
Version history
| Version | Description |
|---|---|
| 1 |
Initial release. |
| 2 | Enhanced to support mandatory paycode comments. |
| 2.1 | Addressed an error that occurred when the integration attempted to update the timecard as a system user. |
| 3 |
Introduces:
Enhanced to provide granular control of mandatory paycode and punch comments for add, edit, and delete actions. |
| 4 | The Timecard Validation extension did not return the expected error message when the manager approved multiple overtime occurrences without adding mandatory comments. |
- Migrate the business process model to the tenant Migrate the Timecard Save Validation process model to the customer tenant using Setup Data Manager (SDM) Moves and manages configuration data across software and hardware environments. (SDM Setup Data Manager moves and manages configuration data across software and hardware environments.).
Log in to the appropriate tenant.
Go to Main Menu > Administration > Setup Data Manager.
Select the Source tenant where the Process Model resides, and select the template to copy. It is a .zip file. A message appears in the Source column: Source: Import from <filename>.zip.
Click Tap Review and Publish. The Publish Summary panel appears.
Review the Publish Summary panel. It lists the items that were extracted from the migration file. If you approve, click tap Publish with Comment or just Publish.
Click Tap Go to Publish History at the bottom of the panel to view the status of the data transfer. The Publish History page contains a table that lists the items you have published. If there were errors during the transfer, the button under the Errors column for that row is black.
To view details, click tap the appropriate row and click tap View Selected.
On the History for publish run page, click tap Show all to view the setup data that you published, and the errors that occurred, if any, listed by item type and name.
- Configure the decision tables Configure the Timecard Save Validation decision tables.
Go to Main Menu > Administration > Application Setup > Business Process setup > Process Models.
Select the TimecardValidation_v4 process and click tap Edit. The process model enters edit mode.
Select the Decision Tables tab.
Click Tap Everyone's, and then select a decision table to edit.
Click Tap Decision Table Editor to add or update the rows in the table.
Click Tap Save and close.
- Repeat the step for each Timecard Save Validation decision table.
- TimecardValidation_v4_InternalParameters — Controls internal timecard validation parameters.
Timecard Validation Internal Parameters decision table structure Parameter name Description Admin Internal user; do not change.
Default =
SERVICES-LEVEL3MaxPayPeriodsToAllowHistoricalEdits The maximum number of signed-off pay periods in which historical edits are allowed.
Only numerical values are supported. For optimal performance, the recommended setting is
10.Default =
100= Editing is not allowed in signed-off periods.10= Editing is allowed in up to 10 signed-off periods. - TimecardValidation_v4_Parameters — Controls the active validation processes in the workflow framework.
Timecard Validation Parameters decision table structure Parameter name Description EnableHistoricalEditsValidation Enables the historical edits validation functionality.
Yes(Default) — enables the functionality.No— does not enable the functionality.EnableManagerAccessToEmployeeValidation Enables the manager access to employee validation functionality.
Yes(Default) — enables the functionality.No— does not enable the functionality.EnableMandatoryCommentsValidation Enables the mandatory comments validation functionality.
Yes(Default) — enables the functionality.No— does not enable the functionality.MandatoryOvertimeComments A semicolon-separated list of comments that are required when validating overtime approval on an employee's timecard.
Note: Each comment must be configured in the application. Do not use comment names such asNullorDefault.MandatoryPunchComments A semicolon-separated list of comments that are required when validating a punch that was added, edited or deleted on an employee's timecard.
Note: Each comment must be configured in the application. Do not use comment names such asNullorDefault. - TimecardValidation_v4_PayPeriodsToAllowHistoricalEdits — Allows granular control over the location and number of signed-off periods in which to allow historical edit functionality.
Timecard Validation Pay Periods to Allow Historical Edits decision table structure Parameter name Description Location Identifies the location for which the historical edit validation functionality applies.
Enter the location as a business structure, such as
Company1/Region1/.Note: Select thecontainsoperator in the Location column when adding new rows to the decision table.Number Of Pay Periods The number of signed-off pay periods in which historical edits are allowed.
Supports numerical values
0-10.Caution: The value must not exceed the MaxPayPeriodsToAllowHistoricalEdits defined in the TimecardValidation_v4_InternalParameters decision table.0= Editing is not allowed in signed-off periods.10= Editing is allowed in up to 10 signed-off periods. - TimecardValidation_v4_ManagerAccessToEmployee_Parameters — Contains configurable parameters for manager access to employee functionality.
Timecard Validation Manager Access to Employee Parameters decision table structure Parameter name Description ValidateTransferredIn Primary Job:When the employee's primary job is not part of the manager's employee group, disallow paycode edit.
Transfer Job Jobs that an employee can perform but that are not the employee's primary job.(Default):When the employee's primary job is not part of the manager's employee group and the employee's transfer job is part of the manager's employee group, allow paycode edit.
When the employee's primary job and transfer job are not part of the manager's employee group, do not allow paycode edit.
Note: The primary and transfer job are validated based on the paycode edit effective location.ValidateTransferredOut Primary Job:When the employee's primary job is part of the manager's employee group, allow paycode edit regardless of the transfer job.
Transfer Job(Default):When the employee's primary job and transfer job are part of the manager's employee group, allow paycode edit.
Note: The primary and transfer job are validated based on the paycode edit effective location.EnableLaborCategoryValidation Determines whether the workflow validates the labor category.
Yes— validates the labor category.No(Default) — does not validate the labor category.EnableAllEntriesValidation Determines when to display error messages generated by the workflow.
Yes(Default) — displays the error after validating all entries.No— displays the error immediately after the first validation failure.Note: The Manager Access to Employee functionality allows the manager to add or modify paycode edits in the employee timecard only when the job effective on the paycode edit date belongs to at least one of the employee groups assigned to the manager on the respective date.
- TimecardValidation_v4_MandatoryComments_FeatureMatrix — provides granular control of mandatory comments for different paycode and punch actions, and overtime approval.
Timecard Validation Mandatory Comments Feature Matrix Functionality Add Edit Delete PayCodeComment Yes: Enables mandatory comment validation on paycode edit addition.No: Disables mandatory comment validation on paycode edit additionYes: Enables mandatory comment validation on paycode edit editing.No: Disables mandatory comment validation on paycode edit editing.Yes: Enables mandatory comment validation on paycode edit deletion.No: Disables mandatory comment validation on paycode edit deletion.PayCodeNote Yes: Enables mandatory comment note validation on paycode edit addition.No: Disables mandatory comment note validation on paycode edit addition.Yes: Enables mandatory comment note validation on pay code edit editing.No: Disables mandatory comment note validation on pay code edit editing.Yes: Enables mandatory comment note validation on paycode edit deletion.No: Disables mandatory comment note validation on paycode edit deletion.PunchComment Yes: Enables mandatory comment validation on punch addition.No: Disables mandatory comment validation on punch addition.Yes: Enables mandatory comment validation on punch editing.No: Disables mandatory comment validation on punch editing.Yes: Enables mandatory comment validation on punch deletion.No: Disables mandatory comment validation on punch deletion.PunchNote Yes: Enables mandatory comment note validation on punch addition.No: Disables mandatory comment note validation on punch addition.Yes: Enables mandatory comment note validation on punch editing.No: Disables mandatory comment note validation on punch editing.Yes: Enables mandatory comment note validation on punch deletion.No: Disables mandatory comment note validation on punch deletion.OvertimeComment Yes: Enables mandatory comment validation on overtime approval.No: Disables mandatory comment validation on overtime approval.Not Applicable Not Applicable OvertimeNote Yes: Enables mandatory comment note validation on overtime approval.No: Disables mandatory comment note validation on overtime approval.Not Applicable Not Applicable Note: Note functionality related to paycode, punch, and overtime is effective only when the corresponding Comment functionality is enabled. For example, if the Add functionality associated with PayCodeComment =
No, then the process automatically treats the Add functionality for PayCodeNote asNo, regardless of the configuration. - Shared_MandatoryPayCodeComment — Contains a list of paycodes that require a comment and identifies the associated acceptable comments.
Shared Mandatory Paycode Comment decision table structure Column name Description Pay Code Identifies paycodes that require a mandatory comment.
Note: Each paycode must be configured in the application.Comments A semicolon-separated list of comments that identifies the acceptable comments for the associated paycode.
Note: Each comment must be configured in the application. Do not use comment names such asNullorDefault.Note:The last row in the Shared_MandatoryPayCodeComment decision table must remain empty ("!=empty".)
This decision table is utilized by other business processes. It is recommended that a backup of the existing table is created before deploying other business processes that use the same decision table.
- TimecardValidation_v4_HistoricalEditsValidation_Locale — Allows customization of the text in the workflow form and notifications related to Historical Edit A change made to an employee’s time record, in a signed-off time period, that impacts their totals. Restriction functionality for different locales.
Timecard Validation Historical Edits Validation Locale decision table structure Variable name Variable type Description Locale Parameter Name Text Internal field label; do not change. Locale Policy Text Locale policy for which the text applies.
You can use an asterisk (*) as a wildcard, but put the less-restrictive locale policy names at the bottom of the table because the integration scans cross-reference tables from the top.
Locale Message Text Text displayed in the workflow form or notification. Locale Description Text (Optional) The description that is shown in Additional information. Sample table - Historical Edits Validation Locale Locale Parameter Name Description Error_ScriptError Internal processing error message.
Error_APIError API failure error message. Error_HistoricalEditsValidation Historical edit validation error message.
Supported tags include:
#PayPeriodCount#— the number of pay periods allowed for a historical edit.#Date#— sign-off date.#LastAllowedDate#— last date on which an historical edit is allowed.Label_ConfirmButton Confirm button label. Error_InvalidHistoricalEditsValidation Invalid value configured in the EnableHistoricalEditsValidation parameter error message. - TimecardValidation_v4_ManagerAccessToEmployee_Locale — Allows customization of the text in the workflow form and notifications related to Manager Access to Employee functionality for different locales.
Timecard Validation Manager Access to Employee Locale decision table structure Variable name Variable type Description Locale Parameter Name Text Internal field label; do not change. Locale Policy Text Locale policy for which the text applies.
You can use an asterisk (*) as a wildcard, but put the less-restrictive locale policy names at the bottom of the table because the integration scans cross-reference tables from the top.
Locale Message Text Text displayed in the workflow form or notification. Locale Description Text (Optional) The description that is shown in Additional information. Sample table - Manager Access to Employee Locale Locale Parameter Name Description Error_InvalidManagerAccessToEmployee Invalid value configured in the EnableManagerAccessToEmployeeValidation parameter error message.
Error_InvalidValidateTransferredOut Invalid value configured in the ValidateTransferredOut parameter error message. Error_InvalidValidateTransferredIn Invalid value configured in the ValidateTransferredIn parameter error message. Error_InvalidValidateLaborCategory Invalid value configured in the EnableLaborCategoryValidation parameter error message.
The Locale Description is repeatable for each invalid paycode entry.
Supported tags include:
#date#— invalid dates#paycode#— paycode#amount#— amountNote: The Locale Description is repeatable for each invalid paycode entry.Error_LaborCategoryValidation Labor category validation error message when the employee does not belong to the manager.
Supported tags include:
#date#— invalid dates#paycode#— paycode#amount#— amountNote: The Locale Description is repeatable for each invalid paycode entry.Error_PrimaryJobValidation Primary job and location validation error message when the employee does not belong to the manager. Error_ScriptError Script or internal workflow error message. Error_APIError API error message. Label_ConfirmButton Confirm button label. - TimecardValidation_v4_MandatoryComment_Locale — Allows customization of the text in the workflow form and notifications related to Mandatory Comment functionality for different locales.
Timecard Validation Mandatory Comment Locale decision table structure Variable name Variable type Description Locale Parameter Name Text Internal field label; do not change. Locale Policy Text Name of the locale policy for which the text applies.
When the text applies to all locales, retain the empty value.
Locale Message Text Text displayed in the workflow form or notification. Locale Description Text (Optional) Additional information. Sample table - Mandatory Comment Locale Locale Parameter Name Description Error_InvalidMandatoryCommentsValidation Invalid value configured in the EnableMandatoryCommentsValidation’ parameter error message.
Error_MandatoryPaycodeComment Mandatory comment not selected for the paycode edit error message.
Supported tags include:
#date#— invalid dates#paycode#— paycode#amount#— amountNote: The Locale Description is repeatable for each invalid paycode entry.Error_MandatoryPunchComment Mandatory comment not selected for the punch edit error message.
Supported tag:
#date#— invalid datesError_MandatoryPaycodeNote Mandatory comment note not selected for the paycode edit error message.
Error_MandatoryPunchNote Mandatory comment note not selected for the punch edit error message. Error_InvalidPunchComment Invalid value configured in the MandatoryPunchComments parameter error message. Error_MandatoryOvertimeComment Mandatory comment not selected for overtime approval error message.
Supported tag:
#date#— invalid datesError_MandatoryOvertimeNote Mandatory comment note not selected for overtime approval error message. Error_InvalidOvertimeComment Invalid value configured in the MandatoryOvertimeComments parameter error message. Error_InvalidValueFeatureMatrix Invalid value configured in the TimecardValidation_v4_MandatoryComments_FeatureMatrix decision table error message. Error_ScriptError Script or internal workflow error message. Error_APIError API error message. Label_ConfirmButton Confirm button label. Note:Localization of business process workflows remains optional, but is supported.
The decision table holds all messages represented with standard English labels; these apply to all locales when the Locale is set to a wildcard (*).
Some or all messages can be translated by adding lines to the table in their preferred translation for specific locales. Messages for the most commonly used Locale Policy should be defined at the top of the decision table. Text within tags ("<>") must not be changed.
Names of the parameters in the decision table column Parameter Name must be used as is. If any parameter value needs to be localized for a different Locale Policy, copy the Parameter Name with the * Locale Policy, add a new row to the decision table with the appropriate Locale Policy, and then add the localized values in the Message column.
The last row in the decision table must remain empty ("!=empty".)
- TimecardValidation_v4_InternalParameters — Controls internal timecard validation parameters.
- Deploy the updated business process model
Note: Process models must be redeployed every time changes are made to an existing model. Re-deployment is not required for decision table changes.
Go to Main Menu > Administration > Application Setup > Business Process Setup > Process Models.
Select the TimecardValidation_v4 model.
Click Tap Edit, and then configure the required parameters and deployment dates. Select Attestation from the Template Categories list.
Click Tap Save, and then select Return to deploy.
APIs
| API name | Type | Resource path | Description |
|---|---|---|---|
| Retrieve Manager Role Assignments | POST | /v1/commons/persons/manager_role_assignments/multi_read | Retrieves Manager’s manager role assignment. |
| Retrieve Employee Group by ID | GET | /v1/commons/employee_groups/{Id} | Retrieves employee group details. |
| Retrieve Location Set by ID | GET | /v1/commons/location_sets/{id} | Retrieves location and jobs from org set assigned in employee group. |
| Retrieve Person by Extension | GET | /v1/commons/persons/{extensionType}?person_number={personNumber} | Retrieves the employee’s primary job and primary labor categories. |
| Retrieve Labor Category Profile by ID | GET | /v1/commons/labor_category_profiles/{id} | Retrieves labor categories entry from labor category profile assigned in employee group. |
| Retrieve All Labor Categories | GET | /v2/commons/labor_categories | Retrieves all labor categories. |
| Retrieve User Preferences for Current User | GET | /v1/commons/user_preferences | Retrieves manager’s locale. |
| Retrieve Display Profile by ID | GET | /v1/commons/display_profiles/{displayProfileID} | Retrieves manager's display profile. |
| Retrieve Comments — Manager | GET | /v1/commons/comments | Retrieves all comments details. |
| Retrieve Pay codes as Manager | GET | /v2/timekeeping/setup/pay_codes | Retrieves all paycode details. |
| Retrieve Pay Period Timespans | GET | /v1/commons/pay_period?date={date}&employee_id=employee_id} | Retrieves pay period start and end dates. |
| Retrieve Timecards as Manager | POST | /v1/timekeeping/timecard/multi_read | Returns a list of timecards based on the employees provided. |