Timecard Save Validation

Note: This business process 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 and paycode 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, such as in a dataview, are not routed through the validation workflow.

Mandatory Paycode Comments — Global Time Off Requests validation

See the Global Time Off Requests (GTOR) Validation Rules topic.

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.

  • Historical edits restriction does not apply to the pending corrections functionality.

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 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 configure this business process, you must do the following:

Attestation conditions: Create an attestation condition type of Always. See the Attestation Conditions topic.

Attestation buttons: Create an attestation button type of Timecard Action with a button subtype of Save. See the Attestation Buttons topic.

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 Attestation Assignments topic.

Note: You must add the Attestation Process to the Attestation Profile that is assigned to managers who use the Timecard Save Validation business process.
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:

  • Mandatory comments for punch edits and overtime approval.

  • Historical edit restrictions.

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).

  1. Log in to the appropriate tenant.

  2. Go to Main Menu > Administration > Setup Data Manager.

  3. 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.

  4. Click Tap Review and Publish. The Publish Summary panel appears.

  5. 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.

  6. 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.

  7. To view details, click tap the appropriate row and click tap View Selected.

  8. 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.

  1. Go to Main Menu > Administration > Application Setup > Business Process setup > Process Models.

  2. Select the TimecardValidation_v4 process and click tap Edit. The process model enters edit mode.

  3. Select the Decision Tables tab.

  4. Click Tap Everyone's, and then select a decision table to edit.

  5. Click Tap Decision Table Editor to add or update the rows in the table.

  6. 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-LEVEL3
MaxPayPeriodsToAllowHistoricalEdits

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 = 10

0 = 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 as Null or Default.
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 as Null or Default.

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 the contains operator 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 (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 addition

Yes: 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 as No, 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 as Null or Default.
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 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# — amount

Note: 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# — amount

Note: 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# — amount

Note: 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 dates
Error_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 dates
Error_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".)

Deploy the updated business process model

Process models must be redeployed every time changes are made to an existing model. Re-deployment is not required for decision table changes.

Model deployment steps:

  1. Go to Main Menu > Administration > Application Setup > Business Process Setup > Process Models.

  2. Select the TimecardValidation_v4 model.

  3. Click Tap Edit, and then configure the required parameters and deployment dates. Select Attestation from the Template Categories list.

  4. Click Tap Save, and then select Return to deploy.

API details
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.