Hours and Dollars Allocation

Note: This extension, a combined integration and workflow model, is developed outside the normal release schedule to meet specific customer needs. To request one of these extensions, you must submit a Salesforce Service Request to UKG. After the extension is delivered to your tenant, you can edit it accordingly.

In organizations where two accrual types are used to reflect the state of an employee’s entitlement, the Hours and Dollars Allocation business process simultaneously deducts hour and money amounts when a time-off request is approved.

This solution:

  • Calculates the dollar equivalent of an approved time-off request and inserts the amount in the timecard as a money paycode-taking.

  • Verifies whether previously inserted money amounts are still accurate, and adjusts the amount when required to accommodate to base wage changes.

Employee time-off requests initiate the Hours and Dollars Allocation workflow. This real-time process multiplies the requested accrual hours with the employee’s base wage, on the day of the accrual, to determine the money paycode-taking amount.

A Boomi™ application extension detects changes in employee base wages. This integration, normally scheduled on a daily basis, automatically checks future periods, and then updates previously added money paycodes, if necessary.

Vacation request

An employee, who has sufficient vacation accrual balances from the previous and current years, requests 8 hours of vacation.

When the manager approves the request:

  • The workflow calculates equivalent money amounts, based on current base wages, and then adds money-taking paycodes in the timecard details and totals add-on.

  • The timecard totals add-on displays paycodes from the cascade, reflecting hours deducted from each year’s accrual balance.

Base wage change recalculation

An employee requests a future vacation using the current year’s accrual balance. The manager approves the request, and the equivalent money deduction is planned in the timecard by using the employee’s current base wage. Before the vacation, the employee's base wage increases.

The integration, which is scheduled to run every day:

  • Detects the base wage change.

  • Adds a money-taking paycode, containing the base wage adjustment, to the timecard details and totals add-on.

Users of this business process can take advantage of the enhanced cancellation request states.

Organizations that have enabled the UseNewRequestCancelSubmittedStatuses feature switch will see new states:

  • Cancel Approved — the employee's request to cancel a previously approved request is approved.

  • Cancel Refused — the employee's request to cancel a previously approved request is refused.

Existing Canceled and Approved states remain, and retain their original use.

Before you configure the Hours and Dollars integration and process model, you must configure the following:

Comments: Create a comment, such as Adjustment Amount. The pay codes category must be selected during configuration. This comment must be used exclusively by the Hours and Dollars Allocation extension. See the Comments topic.

Paycodes: Configure cascading hours and money paycodes dedicated for use by time-off requests and corresponding monetary deduction. See the Paycode definition topic.

Accrual codes: Configure hours and money type accrual codes dedicated for use by the integration. See the Accrual codes topic.

Accrual policies: Configure accrual policies corresponding to the accrual codes. See the Accrual policies topic.

Accrual profiles: Configure an accrual profile that includes all accrual policies that need to be assigned to the employee. See the Accrual profiles topic.

Workflow notifications: Configure generic workflow notifications to support the Hours and Dollars Allocation business process. See the Configure Notifications for Business Processes topic.

Workflow notification examples include:

Name: Time-off request — Employee — Submission Notification.

Subject: <Employee Name>, your request for <Request Subtype> is submitted.

Long Message: Your request for <Request Subtype> has been submitted, and is pending approval.

Select Recipient List will be supplied at runtime and Do not suppress duplicates.

Control center fields
Field Label Value
1 Requested Period <Requested Period>
2 Approver Name <Approver Name>

Name: Time-off request — Manager — Submission Notification.

Subject: Request submitted by <Employee Name> for <Request Subtype>.

Long Message: Request submitted by <Employee Name> for <Request Subtype. Please review the details and approve or reject.

Select Recipient List will be supplied at runtime and Do not suppress duplicates.

Control center fields
Field Label Value
1 Requested Period <Requested Period>
2 Status <Status>

Name: Hours and Dollars Allocation — Employee Notification.

Subject: Hours and Dollars Allocation Employee Notification

Long Message: The time-off request submitted for <Start Date> and <End Date> has been <Approval Status>.

Select Recipient List will be supplied at runtime and Do not suppress duplicates.

Select Trigger Business Process.

Select HoursAndDollarsAllocation_v1.1 from Template.

Select System User from Business Process will run as.

Control center fields
Field Label Value
1 Approval Status <Approval Status>
2 Start Date <Start Date>
3 End Date <End Date>

Name: Hours and Dollars Error Notification.

Subject: Hours and Dollars Error Notification.

Long Message: Your request for <Request Subtype> has been submitted, and is pending approval.

Select Recipient List will be supplied at runtime and Do not suppress duplicates.

Control center fields
Field Label Value
1 Person Number <Person Number>
2 Start Date <Start Date>
3 End Date <End Date>

Request subtype: Configure a time-off request subtype to initiate the business process. Select the previously configured workflow notifications during configuration. See the Configure Request Subtypes topic.

Version history
Version Description
1

Initial release.
1.1

Enhancement.

The Hours and Dollars Allocation workflow allows users to take advantage of the enhanced cancellation request states.

Migrate the business process model to the tenant

Migrate the HoursAndDollarsAllocation_v1.1 process model to the customer tenant using Setup Data Manager (SDM).

  1. Log in to the tenant to which you are migrating the process model.

  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 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 Publish with Comment or just Publish.

  6. Click 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 the appropriate row and click View Selected.

  8. On the History for publish run page, click 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 Hours and Dollars Allocation decision tables.

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

  2. Select the HoursAndDollarsAllocation_v1.1 process and click Edit. The process model enters edit mode.

  3. Select the Decision Tables tab.

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

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

  6. Click Save and close.

Caution:

  • Values entered in the decision tables are case-sensitive, and must match configured values in UKG Pro Workforce Management™.

  • Do not remove variables, variable names, or variable types from any decision table.

Edit the following decision tables: 

HoursAndDollarsAllocation_v1.1_Variables — holds process parameters.

Hours and Dollars Allocation Variables decision table
Variable name Default value Description
Workflow Notification Hours And Dollars Error Notification Notification initiated on error.
Totalization Wait Time 30 Wait time, in seconds, for timecard data totalization.
Approved Status Approved Comma-separated list of system status names representing approved time-off requests.
Cancelled Status CancelApproved,Canceled

Comma-separated list of system status names representing canceled time-off requests.
Admin SERVICES-LEVEL1 Internal user; do not change.
RequestId RequestId_1 Time-off request.
Comment Adjustment Amount Comment used for paycode edit.
Comment Note Paycode Edit Note used for paycode edit.

HoursAndDollarsAllocation_v1_1_AbsenceLookup — defines the 1-to-1 mapping between request paycodes and money paycodes.

Hours and Dollars Allocation Absence Lookup decision table
Variable name Description
S No. Sequence number.
Request Pay Code The cascading or hour paycode used for time-off requests.
Money Pay Code

The money paycode that corresponds to the time-off paycode.

Note: When the Request Paycode is set to a cascading paycode, the corresponding Money Pay Code must be configured as a cascading paycode.
Note:

  • The S No. column must contain sequential values that begin with 1.

  • The Request Pay Code column must contain hours and cascading paycodes.

  • An hour-based Request Pay Code value must have a corresponding money-based paycode configured in the Money Pay Code column.

  • It is recommended to include "Cascading" in the name of the cascading-type Request Pay Code.

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.

Follow these steps to deploy the process model. For detailed information, see the online help topic Deploy Business Process Models.

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

  2. Select the HoursAndDollarsAllocation_v1.1 model.

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

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

API details
API name Section Type Resource path
Retrieve Timecard Data for Multiple Employees Timekeeping Timecards POST /v1/timekeeping/timecard_metrics/multi_read
Delete Paycode Edits by ID Scheduling POST /v1/scheduling/schedule/pay_code_edits/multi_delete
Create Paycode Edits Scheduling POST /v1/scheduling/schedule/pay_code_edits/multi_create
Retrieve Schedule Scheduling POST /v1/scheduling/schedule/multi_read
Retrieve Time Off Request by ID as Manager Employee Self-Service POST /v1/scheduling/timeoff/{timeOffRequestId}
Version history
Version Description
1

Initial release.
1.1

Enhancement.

The Hours and Dollars Allocation integration allows users to take advantage of the enhanced cancellation request states.
1.2

Correction.

The create, update, and delete paycode edit APIs were replaced to support partial success.
  1. Configure Access to Integrations.
  2. Deploy the HoursAndDollarsAllocation_v1.2 integration.
  3. Get the URL for the APIGatewayServer for the tenant.

Select the environment

  1. Open the Integration Template Designer: Select Main Menu  > Administration > Application Setup > Integrations Setup > Design Integration Templates.

    Note: If prompted, enter your Username and Password. Click Tap Log in.

  2. Select the Manage tab > Atom Management.
  3. Select your environment.

Select environment extensions

  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass Search button. It can take several seconds before the button becomes active.
  3. Scroll to and select the integration pack: HoursAndDollarsAllocation > HoursAndDollarsAllocation_v1.2.

Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

Configure connection settings

  1. Select Connection Settings.

  2. From the Connection list, select and configure the following:

    Connection Settings
    Setting Required Actions
    APIGatewayServer Required

    To change the default API gateway server:

    1. Clear Use Default.
    2. Enter the URL to the server.

      Example: <tenantURL>/api

Configure process properties

  1. Select Process Properties.

    Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

  2. Select HoursAndDollarsAllocation_v1.2_CRTConfig.
  3. For each process property, disable the Use Default option and then provide the cross-reference table (CRT) column header value.
Process Properties
Process property name Column header value
_HoursAndDollarsAllocation_v1.2_AbsenceLookup_CRT S no.,Request Pay Code,Money Pay Code
_HoursAndDollarsAllocation_v1.2_Locale_CRT Parameter Name,Locale Policy,Message,Description
  1. In the Cross Reference section, enable the override option for each CRT.

Configure cross-reference tables

Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

  • If more than one row matches a reference value, the first match is the output value.
  • If no match is found, the output value can be null, or the integration can produce errors.
  1. Select Cross Reference.
  2. From the Cross Reference dropdown list, select an HoursAndDollarsAllocation table.
  3. Select Override, which allows you to:
  • Download the tables when you run the integration.
  • Edit the table cells in Extensions.
  1. When you finish, click tap OK.

Repeat the steps for each of the HoursAndDollarsAllocation tables.

HoursAndDollarsAllocation_v1.2_AbsenceLookup_CRT: Used by the integration to evaluate the need to update the money paycode.

Hours and Dollars Allocation — Absence Lookup CRT
Column header Description
S No. Identifies the row using a sequential value, beginning with 1.
Request Pay Code

Identifies the hours and cascading paycodes used in time-off requests.

Note:

Any cascading paycodes entered in the column must contain "Cascading" as part of the paycode name.

Every hours-type paycode entered in the Request Pay Code column must be mapped to a corresponding money paycode in the Money Pay Code column.

The case-sensitive values must be configured in the application.
Money Pay Code

Identifies the money paycode used to hold the dollar equivalent of the time-off request.

Note: The case-sensitive value must be configured in the application.
Note:

A 1-to-1 mapping between Request Pay Code and Money Pay Code must exist for each row in AbsenceLookup_CRT.

HoursAndDollarsAllocation_v1.2_Locale_CRT: Allows translation of messages and labels into different languages.

Hours and Dollars Allocation — Locale CRT
Column header Description
Parameter Name Parameters defined in HoursAndDollarsAllocation_v1.2_Locale_CRT process property.
Locale Policy Locale Policy.

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.
Value Message shown in Additional Details, or value of the label defined in the Run Summary section.

Example: Comment was not provided.
Description The description that is shown in Additional Details.

Example: The employee is not assigned a shift.
Note:

  • Localization of integration extensions remains optional, but is supported.

  • The cross-reference table (CRT) 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 CRT.

  • Names of the parameters in the CRT 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 CRT with the appropriate Locale Policy, and then add the localized values in the Message (or Value) and Description CRT columns.

  • Do not enter values in the CRT column "Description" if it is blank.

  • Do not modify placeholders (<>) or the configurable values that are included in the CRT column "Message" (or "Value").

Hours and Dollars Allocation - Locale parameters list

S.No.

Parameter Name

Usage

Default Message

Message Description

1

_MessageBlankHoursAndDollarsComment

Comment parameter value is missing.

Hours and Dollars Comment was not provided.

 

 

2

_MessageInvalidHoursAndDollarsComment

Comment parameter value is invalid.

Hours and Dollars Comment <Comment Name> not found.

 

3

_MessageInvalidCommentNoteLength

Comment length exceeds 250 characters.

Comment Note cannot exceed 250 characters.

 

4

_MessageInvalidDayDuration

Number of days parameter value exceeds 365.

The Number of days passed is above threshold limit of 365 days.

 

5

_MessageWithoutErrors

No error occurred during the integration run.

Integration has completed without errors.

 

6

_MessageWithErrors

Error occurred during the integration run.

Integration has completed with errors.

 

7

_MessageAdditionalDetails

Process completed with transaction errors.Additional details may be accessible displays in the Message section of Integration Run Details.

Process completed with transaction errors. Additional details, such as disqualifications, may be accessible using the button below.

 

8

_MessageIntegrationType

Displays the type of Integration.

Import.

 

9

_LabelIntegrationType

Text displayed in Run Summary section of Integration Run Details for the Integration Type.

Integration Type

 

10

_LabelProcessedEmployees

Text displayed in Run Summary section of Integration Run Details for Processed Employees.

Processed Employees

 

11

_LabelInvalidEmployees

Text displayed in Run Summary section of Integration Run Details for Invalid Employees.

Invalid Employees

 

12

_LabelAddedSchedulePaycodeEdits

Text displayed in Run Summary section of Integration Run Details for Added Schedule Paycode Edits

Added Schedule Paycode Edits

 

13

_MessageInvalidEmployee

Invalid Employee.

 

Invalid Employee.

Employee with ID <employee number> does not exist.

14

_MessageTerminatedEmployee

Terminated Employee.

Terminated Employee.

Employee <employee number> is not active in the application.

15

_LabelDeletedSchedulePaycodeEdits

Text displayed in Run Summary section of Integration Run Details for Deleted Schedule Paycode Edits.

Deleted Schedule Paycode Edits

 

16

_LabelUpdatedSchedulePaycodeEdits

Text displayed in Run Summary section of Integration Run Details for updated Schedule Paycode Edits.

Updated Schedule Paycode Edits

 

17

_MessageInvalidHoursAndDollarsCommentCategory

Comment is not configured with the paycode category.

Comment is not configured with the paycode category.

 

18

_MessageNoEmployeeIDandHyperfind

Hyperfind or Individual Employee ID not provided.

Hyperfind or individual employee ID not provided.

 

19

_MessageEmptyDaysDuration

Number of Days parameter value not provided.

Number of Days was not provided.

 

20

_MessageBlankDraftStatus

Draft Status parameter value is missing.

Draft Status was not provided.

 

21

_MessagePartialFailedEmployee

Employee's accrual balance is insufficient.

Paycode Edit Error.

Employee ID <employee number> on <employee date> does not have a sufficient accrual balance.
Custom tags
Tag Description
<employee number> The employee's ID number.
employee date> The date that employee's accrual balance was updated.

After the integrations are deployed and the connection settings and process properties are configured, install the integrations to make them available for running or scheduling.

Note:
  • An integration template is the configured integration that you deploy to an Atom and then install to make available for running or scheduling.
  • An installed integration is a single instance of an integration that is based on an integration template. When you install an integration, you can define parameters or set parameters to be defined when the integration is run.

  1. Select Main Menu  > Administration > Application Setup > Integrations Setup > Install Integrations.

  2. Click Tap Create .

  3. In Integration Name, enter a unique name, such as HoursAndDollarsAllocation_v1.2.

  4. (Optional) Enter a Description.

Note: Do not select API Integration.

  1. In File Access, select None to not select a connection.

  2. If the person who runs the integration does not have full access to integrations, select Execute Integration with System Account. This allows the integration access to all APIs in the FAP, and the relevant permissions and data, regardless of the FAP and GDAP of the person who runs the integration.

  3. (Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.

  4. Email Notifications

    (Optional)

    1. Select Yes to send email and control center notifications for integration runs.
    2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces:

      In Progress — The integration run started and has not finished.

      Completed — The integration ran successfully without errors.

      Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.

      Completed with Errors — The integration run has errors or could not run.

  5. In Skip Configuration, select None (default) to allow multiple integrations to run at the same time or with the same data without restrictions.

Note: Do not select Allow Minute Interval.

  1. Integration template and parameters

    1. In Integration Template, select HoursAndDollarsAllocation_v1.2.

    2. Click Tap Assign .

    3. In Integration Parameters, you can override default settings. Click Tap Create.

    4. Complete the configuration for each parameter value.

    5. Click Save.

Repeat this step for each integration parameter that supports the Hours and Dollars Allocation process.

Integration Parameters
Parameter name Description / Default value / User prompt Template parameter Parameter type
Hyperfind

The default Hyperfind or Location query that contains the active employees for whom the integration is run.

Default = All Home

User prompt = false

 Hyperfind Hyperfind
Individual Employee ID

A comma-separated list of specific employees for whom the integration is run.

When no value is entered, the integration defaults to the Hyperfind parameter.

To process the integration for only a limited group of employees, enter the person numbers as defined in the source system, each separated by a comma (,) but not spaces.

User prompt = true

 Individual Employee ID Text
Number of Days

The number of days, beyond the signed-off day plus one day, during which the employee’s data can be processed.

Default = 120

User prompt = false

 Number of Days Number
Comment

Comment added to the paycode edit in the timecard.

Default = Adjustment Amount

User prompt = false

 Comment Text
Comment Note

Note added to the paycode edit in the timecard.

Default = Paycode Edit

User prompt = false

 Comment Note Text
Locale

Locale for error messages.

User prompt = false

 Locale Text
Draft Status

The draft status symbolic ID, such as draft.

Default = draft

User prompt = false

 Draft Status Text

  1. Ensure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. Select Administration > Application Setup > Integrations Setup > Access Profiles; see Configure Access to Integrations.

Run integrations to test that the configuration is set up correctly.

Run the integration

  1. Select the integration:
    1. Select Main Menu  > Maintenance > Integrations. 
    2. Click Tap Run an Integration . 
    3. Select the HoursAndDollarsAllocation_v1.2 integration from the list. Click Tap Select. 
    4. (Optional) Enter a unique Integration Run Name to make it easier to identify the run of the integration. Otherwise, the system assigns a default name, which ends with a date and time stamp.
  2. Set parameters as follows:
    • Individual Employee ID: To process data for only a limited group of employees, enter the person numbers, as defined in the source system, each separated by a comma, but no spaces.

      For 3 employees: 13997,15556,20012

  3. Select the following:

    • Run Integration: If this is the first time this integration is being run.
    • Re-Run: If this integration has been run before, and the status is not In-Progress, you can run the integration again without entering the parameter values again. Click Tap Yes to continue, or No to not run the integration and to return to the parameter settings.

  4. Wait for the confirmation that the integration completed or failed. Close the panel.
  5. Click Tap Refresh . 
  6. To see details, select the integration run. Select Run Summary.

Check the results

Status indicators

  •  In-Progress: The run of this integration has not yet completed.
  •  Completed: The integration ran successfully without errors.
  •  Scheduled: This integration is scheduled to run later or repeatedly.
  • (Grayed out) Scheduled but Deleted: This integration is scheduled to run, but the integration template has been deleted. When it runs, it will generate an error. To prevent this error, delete the scheduled integration run.
  •  Completed with Errors: The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
  •  Failed: The integration run has errors or could not run.
  • To troubleshoot and resolve errors, do the following:

    Check the Run Summary for details.

    • To troubleshoot all types of errors, or if the Run Summary shows a large number of errors, click tap Go to Additional Details (if available), or click tap the Source File to open and examine the input source file.
    • (Only for import integrations) To troubleshoot and resubmit integrations that have transactional or data errors, click tap Go to Transaction Assistant.

To check the results in more detail:

  1. Click Tap the tile for the integration run.
  2. Click Tap Run Summary to see the results of the integration run.

    Example Run Summary details

    Note: The available details vary by integration and configuration.

    • Integration Run Name: Name of this run of the integration.
    • Process Name: Name of any integration set that includes this integration.
    • Integration Name: Name of the installed integration.
    • Integration Reference ID: Unique identifier for this integration run (to help in troubleshooting errors).
    • User: The person or user account that ran the integration.
    • Integration Type: Import, Export, or None
    • Start Date: Date and time when the integration run started.
    • End Date: Date and time when the integration run finished.
    • Status: In-Progress, Completed, Completed with Errors, or Failed.
    • Records Processed: Number of records that were processed.
    • Records Created: Number of records that were created.
    • Errors: Number of records that failed.
    • Source Files, Output File, and Error Files: For file-based import integrations, use Manage SFTP to access the source and output files on the inbound (source) and outbound (destination) SFTP folders. See the Manage SFTP topic.
  3. Log in to the destination system and ensure that the data has been correctly updated.

Note: You can schedule integrations and integration sets to run once later or at a recurring frequency. See the topic.

API details
API name Section Type Resource path
Retrieve Comments-Manager Common Resources I GET /v1/commons/comments
Retrieve User Preferences for Current User Common Resources II GET /v1/commons/user_preferences/locale_policy?tenantDefault=true
Retrieve All Extensions People POST v1/commons/persons/extensions
Retrieve Time Off Requests as Manager Employee Self-Service POST /v1/scheduling/timeoff/multi_read
Retrieve Schedule Scheduling POST /v1/scheduling/schedule/multi_read
Retrieve Timecard Data for Multiple Employees Timekeeping Timecards POST /v1/timekeeping/timecard_metrics/multi_read
Delete Paycode Edits by ID Scheduling POST /v1/scheduling/schedule/pay_code_edits/multi_delete
Create Paycode Edits Scheduling POST /v1/scheduling/schedule/pay_code_edits/multi_create
Update Paycode Edits Scheduling POST /v1/scheduling/schedule/pay_code_edits/multi_update