Paid Sick Yearly Bonus Payout

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 Paid Sick Yearly Bonus Payout extension automates the calculation and payout amount of an employee’s eligible bonus for remaining paid sick days at the end of a calendar year.

In some Canadian regions, such as British Columbia, employees are entitled to paid sick leave each year to cover personal sickness or injury. Remaining days from that entitlement are eligible to be paid out as bonus pay.

To define the hourly equivalent of one remaining paid sick day, the process calculates the average worked hours during a configurable lookback period. That average is then multiplied by the number of remaining sick days to determine the paid sick bonus hours payout.

Sick Bonus Payout = (Number of remaining sick days) * (Average hours worked during a defined lookback period).

The process runs for all employees, regardless of employment status – Active, Inactive, or Terminated.

A paycode edit in the amount of the paid sick bonus hours is added to the timecard for each eligible employee. A comment is attached to the paycode edit along with a note providing detailed information about the amounts used in the calculation. Because the calculation is performed using the decimal equivalent of the hours, both the hourly amounts and decimal equivalents are displayed in the note.

Note: The Paid Sick Yearly Bonus Payout does not apply an accrual balance reset. It is expected that this is handled using the standard options in the accrual policy (carryover limit or balance cascade.)

The Bonus Pay Code must not be configured as a taking paycode for any accrual policy.

Employees are granted 5 sick days each year. On December 31st, the ending balances are reviewed, and any remaining days qualify for a bonus pay that is paid out on January 1st.

The organization looks back at the average hours worked during the month of December.

One employee used only 2 days, and ends the year with a balance of 3 remaining paid sick days. During December, the employee worked 168 qualifying hours across 20 days.

The process calculates the average worked hours as (168.0/20) = 8:24. This average is multiplied by the remaining day, which results in a bonus hours amount of (3*8:24) = 25:12.

A paycode edit with 25:12 hours is placed in the employee’s timecard, and is used for the bonus payout. A comment and note are attached to the paycode edit. Sample note contents:

Worked Hours: 168:00 (168.0)

Worked Days: 20.0

Average Hours: 8:24 (8.4)

Accrual Balance: 3.0

Bonus Amount: 25:12 (25.2)

Validation Period: 12/01/2022 12/31/2022

Validation Date: 12/31/2022

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

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

Paycode: Create an hours-based paycode, such as Paid Sick Bonus, dedicated to the process. See the Paycode definition topic.

Combined paycode: Create a combined paycode, such as Paid Sick Bonus Combined, that contains all hour-based paycodes associated with worked hours. See the Combined Paycodes topic.

Accrual code: Create an accrual code that tracks an employee's paid sick days. See the Accrual codes topic.

Comment: Create a comment, such as Adjusted by Paid Sick Bonus Integration, that has a selected category of Pay Codes. See the Comments topic.

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

Version Description
1 Initial release.
iPack_v2

The Paid Sick Yearly Bonus Payout integration delivery is now by way of an iPack.

Deploy the Paid Sick Yearly Bonus Payout 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 Paid Sick Yearly Bonus Payout 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.

  1. Configure Access to Integrations.

Configure the Paid Sick Yearly Bonus Payout 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: Paid Sick Yearly Bonus Payout > PaidSickYearlyBonusPayout_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
    PaidSickYearlyBonusPayout_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
    PaidSickYearlyBonusPayout_iPack_v2_Locale_CRT Require 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.

  2. Select PaidSickYearlyBonusPayout_iPack_v2 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
    _PaidSickYearlyBonusPayout_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 PaidSickYearlyBonusPayout_iPack_v2_Locale_CRT table.

  3. Select Override to:

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

PaidSickYearlyBonusPayout_iPack_v2_Locale_CRT: Allows translation of messages into different languages.

Paid Sick Yearly Bonus Payout — 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 Description
Error_BlankAccrualCode * Accrual Code is not configured.  
Error_BlankBonusPaycode * Bonus Pay Code is not configured.  
Error_BlankBonusPayoutDate * Bonus Payout Date is not configured.  
Error_BlankComment * Comment is not configured.  
Error_BlankHyperfindandEmployeeIDs * The 'Hyperfind and Location' or 'Employee IDs' must be configured.  
Error_BlankLookbackPeriod * Lookback Period is not configured.  
Error_BlankValidationDate * Validation Date is not configured.  
Error_BlankValidationYear * Validation Year is not configured.  
Error_BlankWorkedHoursPaycode * Worked Hours pay code is not configured.  
Error_InvalidBonusPaycode * Bonus Pay Code '<Bonus Pay Code>' not found.  
Error_InvalidBonusPayoutDate * Bonus Payout Date value must be configured in MM/dd format.  
Error_InvalidComment * Comment '<Comment>' not found.  
Error_InvalidCommentCategory * Comment '<Comment>' must be configured with 'Pay Codes' category.  
Error_InvalidCommentNoteLength * Comment Note cannot exceed 250 characters.  
Error_InvalidLookbackPeriod * Lookback Period (days) must be between 1-365.  
Error_InvalidValidationYear * Validation Year must be 'current' or 'previous'.  
Error_InvalidWorkedHoursPaycode * Worked Hours pay code '<Worked Hours>' not found.  
Label_AddedPaycodeEdits * Added Paycode edits  
Label_BoomiExecutionId * Integration Execution Id  
Label_DeletedPaycodeEdits * Deleted Paycode edits  
Label_DisqualifiedEmployees * Disqualified Employees  
Label_FailedEmployees * Failed Employees  
Label_IntegrationType * Integration Type  
Label_InvalidEmployees * Invalid Employees  
Label_ProcessedEmployees * Processed Employees  
Label_UpdatedPaycodeEdits * Updated Paycode edits  
Message_AddBulkPaycodeEditError * Added bulk pay code edit(s) failed  
Message_AdditionalDetails * Process completed with transaction errors. Additional details, such as disqualifications, may be accessible using the button below. Error returned when adding bulk paycode edits.
Message_BonusPaycodeNotPrimary * Bonus Pay Code '<Bonus Pay Code>' must be a primary pay code.  
Message_DeletedPaycodeEditError * Deleted pay code edit(s) failed. Error returned when deleting paycode edits.
Message_EnableEditsFalse * Bonus pay-out date falls in signed-off period. Bonus pay-out date '<Pay-out date>' falls in signed-off period for employee '<Employee ID>'. Last sign-off date '<sign-off date>'.
Message_InvalidAccrualCode * Accrual Code '<Accrual Code>' not found.  
Message_InvalidAccrualCodeType * Accrual Code '<Accrual Code>' must be as day type.  
Message_InvalidBonusPaycodeType * Bonus Pay Code '<Bonus Pay Code>' must be hours-based.  
Message_InvalidEmployeeIds * Invalid Employees Employee with ID '<Person Number>' does not exist.
Message_InvalidValidationDate * Validation Date value must be configured in MM/dd format.  
Message_UpdatePaycodeEditError * Update paycode edit(s) failed. Error returned when updating paycode edits.
Message_WithErrors * Integration completed with errors.  
Message_WithoutErrors * Integration completed without errors.  
Message_WorkedHoursPaycodeNotCombined * Worked Hours pay code '<Worked Hours>' must be configured as a combined paycode.  

Custom tags used in the Locale_CRT are replaced with actual values.

Custom tags
Tag Description
<WorkedHours> Total number of worked hours in the lookback period.
<WorkedDays> Total number of days where worked hours exceeds 0.
<AverageHours> Calculated by dividing WorkedHours by WorkedDays.
<AccrualBalance>

Accrual code balance on the ValidationDate.
<BonusAmount> Calculated bonus payout amount.
<ValidationPeriod> Date range for which the calculation is performed.
<ValidationDate> The date on which the accrual ending balance is checked.

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 PaidSickYearlyBonusPayout_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. 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 PaidSickYearlyBonusPayout_iPack_v2.
    2. Click Tap Assign .
    3. In Integration Parameters, you can override default settings. Click Tap Create .
    4. Complete the configuration for each parameter.
    5. Click Tap Save.

Repeat this step for each integration control parameter that supports the Paid Sick Yearly Bonus Payout process.

Integration parameters
Parameter name Description / User prompt / Mandatory Template parameter Parameter type

Hyperfind and Location

Hyperfind or location for which the integration will run.

Default = All Home

User prompt = Yes

Mandatory = Yes

HyperfindAndLocation

Hyperfind

Employee IDs

Comma-separated list of employee IDs for which the integration will run.

When no value is entered, the integration defaults to the Hyperfind and 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

Accrual Code

Day-type accrual code that identifies the paid sick amount.

User prompt = No

Mandatory = Yes

Caution: The value is case-sensitive and must match the configured value in the application.

AccrualCode

Text

Bonus Pay Code

Hour-type paycode that identifies the payout.

User prompt = No

Mandatory = Yes

Caution: The value is case-sensitive and must match the configured value in the application.

BonusPayCode

Text

Bonus Payout Date

Bonus payout date.

Use the MM/dd format.

Must fall on or after the Validation Date integration parameter value.

User prompt = No

Mandatory = Yes

BonusPayoutDate

Text

Comment

Comment attached to the Bonus Pay Code.

User prompt = No

Mandatory = Yes

Caution: The value is case-sensitive and must match the configured value in the application.

Comment

Text

Comment Note

Free text attached to the Comment.

Contains calculation details.

Default =

Worked Hours : <WorkedHours>|| Worked Days : <WorkedDays>||Average Hours : <AverageHours>|| Accrual Balance : <AccrualBalance>|| Bonus Amount : <BonusAmount>||Validation Period : <ValidationPeriod>||Validation Date : <ValidationDate>

User prompt = No

Mandatory = No

Caution: Tags, when added in the Comment Note parameter, track auditing of the calculation. Do not modify tag values. Use the double pipe symbol (||) as a carriage return, to allow easier readability.

CommentNote

Text

Enable Edits

Enables editing when the Bonus Payout Date falls in a signed-off period.

Supported values include:

  • true

  • false (default)

User prompt = No

Mandatory = Yes

EnableEdits

Boolean

Lookback Period

The number of days before the Validation Date, The total number of hours worked during this period is used to calculate the average hours worked per day.

Maximum: 365

Minimum: 1

User prompt = No

Mandatory = Yes

LookbackPeriod

Number

Validation Date

The date on which the accrual ending balance is checked.

Use the MM/dd format.

User prompt = No

Mandatory = Yes

ValidationDate

Text

Validation Year

Defines whether the current or previous year will be validated by the extension.

Valid entries include:

  • current — Allows testing of the current year.

  • previous (default) — Validates hours from the previous year.

User prompt = No

Mandatory = Yes

ValidationYear

Text

Worked Hours

Combined paycode that holds all hourly-based paycodes that count as worked.

User prompt = No

Mandatory = Yes

Caution: The value is case-sensitive and must match the configured value in the application.

WorkedHours

Text
  1. Ensure 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 PaidSickYearlyBonusPayout_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 and 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

  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 title URI Method Description

Retrieve user preferences for current user

/v1/commons/user_preferences/locale_policy?userCurrent=true

GET

Returns user preferences for the current user.

Retrieve user preferences for current user

/v1/commons/user_preferences/locale_policy?tenantDefault=true

GET

Returns user preferences for the tenant.

Retrieve paycodes as manager

/v2/timekeeping/setup/pay_codes

GET

Returns a list of paycodes available to a manager.

Retrieve comments-manager

/v1/commons/comments

GET

Returns a filtered list of comments.

Retrieve timezone

/v1/commons/setup/timezones?person_number=SERVICES_LEVEL1

GET

Returns time zone details for the logged-in user, or uses the person_number as the qualifier.

Retrieve accrual codes

/v2/timekeeping/setup/accrual_codes

GET

Returns a list of accrual code types according to the user's access rights.

Execute Hyperfind query

/v1/commons/hyperfind/execute

POST

Executes a Hyperfind query by ID or qualifier, and then returns the result.

Retrieve persons

v1/commons/persons/extensions/multi_read

POST

Returns multiple person records based on search criteria.

Retrieve locales

/v1/commons/locale_policies/multi_read

POST

Returns locales related to the request.

Retrieve timecard data for multiple employees

/v1/timekeeping/timecard_metrics/multi_read

POST

Returns timecard data for a set of employees or location.

Retrieve timecards as manager

/v1/timekeeping/timecard/multi_read

POST

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

Bulk delete paycode edits

/v1/timekeeping/pay_code_edits/multi_delete

POST

Performs a bulk delete of paycode edits for multiple employees using a list of paycode edit IDs.

Bulk import paycode edits

/v1/timekeeping/pay_code_edits/import

POST

Imports paycode edits in bulk.

Update timecard as manager

/v1/timekeeping/timecard

POST

As a manager, updates a timecard for an employee by adding, updating, or deleting punches, paycode edits, hours worked, and exception comments.

Bulk enable edits

/v1/timekeeping/enable_edits/import

POST

Returns a list of employees with enabled edits.