Dynamic Paycode Allocation for Activities

Note: This integration is an extension that 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.

The Dynamic Paycode Allocation for Activities extension proportionally distributes absence hours on the occurrence date to activities worked during the same pay period.

For organizations that rely on UKG Pro Workforce Management™ Activities to track labor, this dynamic allocation calculates the ratio of an employee’s worked hours for each activity to the total worked hours for all activities in the pay period. It then distributes absence hours, such as vacation or sick, on the occurrence date, to the appropriate activities.

Before activating the integration, an administrator will:

  • Identify the activities to which absence hours are allocated.

  • Define the number of pay periods included in the allocation process.

  • Determine whether processing is allowed in signed-off periods.

An hourly employee is assigned a 9a-5p schedule spanning Monday—Friday. Throughout the week, the employee distributes worked hours between two activities; each of which is identified for allocation.

A time-off request for Friday is approved by the employee's manager.

Timecard content before dynamic allocation - hourly employee
Date Schedule Pay Code Shift Daily Activity Actual Start Actual Stop Allocated Hours
Mon 10/31 9:00 AM—5:00 PM   8:00 8:00        
          Activity 1 9:00 AM 11:00 AM 2:00
          Activity 2 11:00 AM 5:00 PM 6:00
Tue 11/01 9:00 AM—5:00 PM   8:00 8:00        
          Activity 1 9:00 AM 11:00 AM 2:00
          Activity 2 11:00 AM 5:00 PM 6:00
Wed 11/02 9:00 AM—5:00 PM   8:00 8:00        
          Activity 1 9:00 AM 1:00 PM 4:00
          Activity 2 1:00 PM 5:00 PM 4:00
Thu 11/03 9:00 AM—5:00 PM   8:00 8:00        
          Activity 2 9:00 AM 5:00 PM 8:00
Fri 11/04   Duration Absent 8:00 8:00        
          IDLE 9:00 AM 5:00 PM 8:00

When the integration runs, it identifies absences:

Duration Absent = 8 hours

It then totals worked hours associated with each allocated activity in the pay period:

Activity 1 = 2+2+4+0 = 8 hours

Activity 2 = 6+6+4+8 = 24 hours

Total worked hours = 8 + 24 = 32 hours

It then calculates the ratio of worked hours for each activity to the total worked hours for all activities in the pay period:

Activity 1 = 8 / 32 = 25%

Activity 2 = 24 / 32 = 75%

Time-off hours are distributed to each applicable activity:

Activity 1 = 25% * 8 = 2 hours

Activity 2 = 75% * 8 = 6 hours

Comments, and optionally Notes, are attached to the allocated activities.

Timecard content after dynamic allocation - hourly employee
Date Schedule Pay Code Daily Period Activity Actual Start Actual Stop Allocated Hours
Mon 10/31 9:00 AM—5:00 PM   8:00 8:00        
          Activity 1 9:00 AM 11:00 AM 2:00
          Activity 2 11:00 AM 5:00 PM 6:00
Tue 11/01 9:00 AM—5:00 PM   8:00 16:00        
          Activity 1 9:00 AM 11:00 AM 2:00
          Activity 2 11:00 AM 5:00 PM 6:00
Wed 11/02 9:00 AM—5:00 PM   8:00 24:00        
          Activity 1 9:00 AM 1:00 PM 4:00
          Activity 2 1:00 PM 5:00 PM 4:00
Thu 11/03 9:00 AM—5:00 PM   8:00 32:00        
          Activity 2 9:00 AM 5:00 PM 8:00
Fri 11/04   Duration Absent 8:00 40:00        
          Activity 1 9:00 AM 11:00 AM 2:00
          Activity 2 11:00 AM 5:00 PM 6:00

  • A Hyperfind or location that selects only the employees for whom the integration will run is required. See the Hyperfind queries topic.

  • Absence duration paycodes that populate the timecard must originate from a time-off request entered by either the employee through the request tile, or the manager through the time-off request option in the Schedule.

  • When it is necessary to add a duration-type paycode directly in the timecard, you must enter In and Out-punches instead of a symbolic amount.

  • The tracking status must remain consistent for the entire pay period; make changes only on the first day of the employee's pay period.

  • When the integration is run multiple times for the same date range, changes to the comment notes occur only when the worked activities or duration change from one run to another.

Before you configure this integration, you must do the following:

  1. Configure Access to Integrations.
  2. Configure the following:

  • Comment: Configure a comment, such as Activities Dynamic Allocation, that has a selected category of Activities Events. See the Comments topic.

  • Paycode: Configure a duration-type paycode, such as Duration Absent, that identifies the qualifying absence hours. Map the intermediate and replacement paycodes under the Totals Pay Code Replacement, using appropriate paycodes. See the Paycode definition topic.

  • Data Access Profile: Configure a paycode data access profile (DAP) that identifies all absence paycodes for which the dynamic allocation is processed. See the Data Access Profiles overview topic.

  • Activities: Configure all activities that will be processed by the integration. In the same User Field (1, 2, 3, or 4) for each configured activity, enter the paycode data access profile name. See the Activities topic.

  • Request Subtype: Configure a request subtype, such as Duration — Casual Leave. In the Default Pay Code, select the absence duration paycode. See the Configure Request Subtypes topic.

  1. Get the URL, User, and Password for the APIGatewayServer.

Version Description
1

Initial release.
1.1

The integration failed when more than 1000 activities were returned. The integration now batches records to prevent service limit errors.
1.2

  • The integration was not picking up system-generated activities.

  • The integration returned vague and unhelpful error messages when:

    • the timecard response did not contain activity segments.

    • a paycode, that was defined in the paycode display access profile, was entered in the timecard with a symbolic amount.
1.3 When criteria selections were specified in the Hyperfind or Location and the Individual Employee IDs parameter, the integration processed both criteria instead of only one.
iPack_v2 The Dynamic Paycode Allocation for Activities integration delivery is now by way of an iPack.

Deploy the Dynamic Paycode Allocation for Activities integration

For more information, see the Deploy Integrations topic.

  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. Make sure that the Account is correct. If not, select the right account.

  3. Select the Deploy tab > Integration Packs.
  1. From the list in the left column, search for and select the Pro WFM Dynamic Paycode Allocation for Activities Extension integration.

  1. From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button Select items.

Configure the Dynamic Paycode Allocation for Activities integration settings

Select the environment

  1. Select the Manage tab > Atom Management.
  2. 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.
  1. Scroll to and select the integration pack: Dynamic Paycode Allocation For Activities > DynamicPaycodeAllocationForActivities_iPack_v2.

Configure connection settings

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.

  1. Select Connection Settings.

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

    Connection Settings
    Setting Required Actions
    DynamicPayCodeAllocationForActivities_iPack_v2_APIGatewayServer Required

    To change the default API gateway server:

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

      Example: <tenantURL>/api
    DynamicPayCodeAllocationForActivities_iPack_v2_Locale_CRT Required Enable Override.

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.

  1. Select DynamicPayCodeAllocationForActivities_iPack_v2_CRTConfig to set process properties that must be configured before the integration can run. This main process starts the integration process and handles errors.

Process Properties
Process property name Column header value
_DynamicPayCodeAllocationForActivities_iPack_v2_Locale_CRT Parameter Name,Locale Policy,Message,Description

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 the DynamicPayCodeAllocationForActivities_iPack_v2_Locale_CRT table.

  3. Select Override, which allows you to:

  • Download the table when you run the integration
  • Edit the table cells in Extensions
  1. When you finish, click tap OK.

DynamicPayCodeAllocationForActivities_iPack_v2_Locale_CRT: Allows translation of messages and labels into different languages.

Dynamic Paycode Allocation for Activities - Locale CRT structure
Column name Description
Parameter Name Key for which localization is defined.
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.
Message

Message shown in Additional Details, or value of the label defined in the Run Summary section.

Comment was not provided.

Description

The description that is shown in Additional Details.

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

Sample Locale CRT content
Parameter name Locale Policy Message
Label_EmployeeID * Employee
Error_MessageInvalidEmployeeNumberDesc * An employee with ID <Employee ID> does not exist.
Error_MessageCommentNoteLengthExceeded * Comment Note cannot exceed 250 characters.
Error_MessageInvalidComment * Comment <Comment> not found.
Error_MessageNoPersonNumber * Hyperfind or Person Number was not provided.
Error_MessageEmptyComment * Comment was not provided.
Error_MessageEmptyAbsencePaycodeDAP * Absence Pay Code DAP was not provided.
Error_MessageInvalidAbsencePaycodeDAP * Absence pay code data access profile <Absence Pay Code DAP> not found in UKG Pro Workforce Management™.
Error_MessageNumberoflastPayPeriod * The number of Previous Pay Periods should not exceed 10 pay periods.
Error_MessageSignedOffDetails * Validation period <pay period start—pay period end> falls in signed-off period for employee <Employee ID>. Last sign-off date <sign-off date>.
Label_IndividualEmployeeKey * Person
Error_MessageSignedOff * Activities validation period falls in the signed-off period.
Error_MessageInvalidCommentCategory * Comment <Comment> should include <Activities Event> category.
Label_MessageInvalidPersonNumber * Invalid Person Number
Message_Comment Note *

Date range: <StartDate> - <EndDate>

|| <ActivityNameAndHours>

|| Ratio - <PercentageRatio>

|| #InternalID.
Error_MessageInvalidDAP * Data Access Profile does not exist in UKG Pro Workforce Management™.
Error_MessageInvalidPayCode * <Employee> has selected an invalid Paycode on <Date> Absence Paycode:<PayCode>.

Custom tags used in the comment notes are replaced with actual values.

Custom tags
Tag Description
<Employee ID> Employee ID.
<Absence Pay Code DAP> Pay code data access profile that contains the duration-type absence paycodes.

<pay period start—pay period end>

 Employee's signed-off pay period start and end dates.

<sign-off date>

 Employee's signed-off date.

<Comment>

 The comment that the integration adds with the activities to the employee timecard.
<Activities Event> The activity event with which a comment is associated.
<Start Date> The start date that is added to the comment note that is associated with the activity.
<End Date> The end date that is added to the comment note that is associated with the activity.
<ActivityNameAndHours> The activity name and hours that are added to the comment notes that is associated with the activity.
<PercentageRatio> The percentage ratio of worked activities.
<Ratio> The hours ratio of worked activities.
#InternalID Used for internal code validation. Do NOT modify.
|| The character which indicates that subsequent content appears in a new comment.
<Employee> The employee for whom an error is displayed.
<Date> The date of an absence paycode in the timecard.
<PayCode> The absence paycode.

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 DynamicPayCodeAllocationForActivities_iPack_v2.
  4. (Optional) Enter a Description.

Note: Do not select API Integration.

  1. In File Access, select None to not select a connection.
  2. (Optional) 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 DynamicPayCodeAllocationForActivities_iPack_v2.
    2. Click Tap Assign .
    3. In Integration Parameters, you can override default settings. Click Tap Create.
    4. Complete the configuration for each integration control parameter value.

    5. Click Tap Save.

      Repeat this step for each integration control parameter that supports the Dynamic Paycode Allocation for Activities process.

      Integration Parameters
      Parameter name Description / User prompt / Mandatory Template parameter Parameter type
      Hyperfind or Location

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

      Default = 1 (All Home Locations)

      User prompt = Yes

      Mandatory = Yes

      Note: Ad-hoc Hyperfinds are not supported.

      All Home does not include terminated and inactive employees even if they have totals during the period. To include these totals, configure a Hyperfind that includes terminated and inactive employees, and select that Hyperfind in this process property.

      The maximum number of employees in a Hyperfind is 3500. To process more employees, divide the population into smaller Hyperfinds to run sequentially.

      		 HyperfindorLocationID Hyperfind
      Individual Employee IDs

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

      When no value is entered, the integration defaults to the Hyperfind or Location 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 = Yes

      Mandatory = Yes

      		 EmployeeIDs Text
      Number of last Pay Period

      Count of previous Pay Periods to process when the Previous Pay Period option is selected in the Date Range parameter.

      Minimum value = 1 (default).

      Maximum value = 10.

      User prompt = Yes

      Mandatory = Yes

      		 Numberoflastpayperiod Number
      Time period

      Range of dates for which the integration will process data.

      Default = Previous Pay Period

      User prompt = Yes

      Mandatory = Yes

      		 SymbolicPeriod Time period
      Comment

      Comment added to the timecard by the integration.

      Default = Activities Dynamic Allocation

      User prompt = No

      Mandatory = Yes

      		 Comment Text
      Absence Pay Code DAP

      Pay Code Data Access profile that contains duration-type absence paycodes.

      Default = Dynamic Allocation Paycodes

      User prompt = No

      Mandatory = Yes

      		 AbsencePayCodeDAP Text
      Activity user field for DAP

      The specific User Field in Activity configuration that contains the name of the Absence Paycode DAP.

      Enter one of the following: 1 (default), 2, 3, or 4.

      User prompt = No

      Mandatory = Yes

      		 ActivityuserfieldforDAP Text
      Enable Edits

      When true, the integration automatically enables edits as part of the process.

      When false (default) and the signed-off period is not enabled for edits, the integration does not perform the process.

      User prompt = No

      Mandatory = Yes

      		 EnableEdits Boolean

  1. Make sure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. 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 DynamicPayCodeAllocationForActivities_iPack_v2 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:
    • Hyperfind or Location: Select a Hyperfind query of employees.
    • Employee IDs: 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

    • Number of last pay period: Enter the number of previous pay periods to process.
    • Time Period: Select a symbolic pay period.

  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 Type Resource path Description
Retrieve Comments-Manager GET /v1/commons/comments Returns a filtered list of comments.
Create or Update Activity Shifts POST /v1/work/activity_shifts/multi_upsert Creates or updates activity shifts from a third-party source for multiple employees.
Retrieve Timecards as Manager POST /v1/timekeeping/timecard/multi_read

Returns a list of timecards based on the employees or Hyperfind details provided.

Required parameters include employee ID or person number, and a date range or symbolic period ID.
Execute Hyperfind Query POST /v1/commons/hyperfind/execute Retrieves employee details using a Hyperfind ID or location ID.
Retrieve Paycode Data Access Profiles POST /v1/timekeeping/setup/pay_codes/data_access_profiles/multi_read Returns a list of Paycode Data Access Profiles by object references.
Retrieve User Preferences for Current User GET /v1/commons/user_preferences/locale_ policy?tenantDefault=true Returns user preferences for the current user or tenant.
Bulk Enable Edits POST v1/timekeeping/enable_edits/import

Returns a list of employees with enabled edits.

Supports partial success.
Retrieve Pay Period Timespans POST v1/commons/pay_period Returns a pay period time span based on the pay period ID, pay rule ID, user, date, and period type.
Retrieve Symbolic Periods GET /v1/commons/symbolicperiod Returns all symbolic periods in the system.
Retrieve Persons GET v1/commons/persons/extensions/multi_read

Returns multiple person records based on search criteria.

Search criteria includes personid, personnumber, jobassignmentid, username, useraccountid, and badgenumber.
Retrieve Locale Date Span POST /v1/commons/symbolicperiod/read

Returns a locale date span, or symbolic period, according to the data provided.

The data can include locationId, employee ID, person number, current user, and current tenant.

The returned response can be specified.
Retrieve Activities POST /v1/work/activities/multi_read Returns one or more activities by object references.
Retrieve User Preferences for Current User GET /v1/commons/user_preferences/locale_policy?userCurrent=true Returns user preferences for the current user or tenant.
Delete Activity Shifts POST /v1/work/activity_shifts/multi_delete Deletes one or more activity shifts.
Update Timecard as Manager POST /v1/timekeeping/timecard Retrieve timecard details for an employee.