Absence-Based Accrual Adjustment

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 Absence-Based Accrual Adjustment integration extension is an automated process that adjusts employee accrual balances based on the number of calendar days that the employee is absent in a month.

In organizations where employees earn accrual days by working, this extension supports a policy that reduces earned accruals when employees are absent for a period of time. The extension works for only day-based accruals.

Combined paycodes identify the penalizing hour- and day-based absences that are used to compare absent calendar days with the total number of calendar days in the month. Prorated adjustments are made directly to the accrual balance on the grant date, and then an indicative paycode and comment are added to the timecard, identifying the adjustment.

Grant adjustments are performed by looking back to previous months for unplanned absences, and forward to future months for planned absences. Calculated adjustment amounts are truncated to two digits after the decimal point; for example, 0.469 truncates to 0.46 days. Corrections are made in signed-off periods, when editing is enabled.

In an organization, full-time employees earn 25 vacation days each year. The entitlement is divided into 12 segments, granted on the first day of each month. In other words, over the year, full-time employees accrue 2.08 days each month. The extension processes accrual adjustments by comparing the number of calendar days with qualifying absences in the month.

An employee's monthly vacation grant is awarded on the first of the month. The grant assumes that the employee does not incur absences during the month. However, during a 31-day month, the employee incurs 5 days of qualifying absences. Calculations are performed as follows:

Initial grant: (31/31)*2.08 = 2.08 days.

Adjusted grant: ((31-5)/31)*2.08 = 1.74 days.

Adjustment amount: 2.08 — 1.74 = 0.34 days.

The accrual adjustment of -0.34 days is inserted on the grant date, and the timecard displays an indicative paycode with comment on the adjusted day.

  1. Configure Access to Integrations.
  2. Configure a comment, such as Adjusted by Integration, that has a selected category of Pay Codes. See the Comments topic.
  3. Configure day-based and hour-based combined paycodes identifying the qualifying absences. See the Combined Paycodes topic.
  4. Deploy the AbsenceBasedAccrualAdjustment_v1 integration; see the Deploy Integrations topic.
  5. 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: AbsenceBasedAccrualAdjustment > AbsenceBasedAccrualAdjustment_v1.

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 AbsenceBasedAccrualAdjustment_v1_ProcessProperties to set the extension's global properties.

    Absence-Based Accrual Adjustment - Control Properties

    Parameter name

    Description

    Template parameter

    Parameter type

    Default value

    User prompt

    Need

    Employee IDs

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

    Employee IDs

    Text

     

    Yes

    Mandatory

    Hourly Threshold (HH:mm)

    Determines whether the amount of the Combined Absence Pay Code Hourly control property qualifies as an absence.

    The value identifies the minimum time that is required in the timecard before an hourly-based paycode qualifies as an absence.

    Hourly Threshold (HH:mm)

    Text

    00:01

    No

    Mandatory

    Hourly Rounding (HH:mm)

    Determines whether the amount of the Combined Absence Pay Code Hourly control property counts as a full-day or half-day absence.

    The value:

    • Represents the maximum amount of time that is required in the timecard for an hourly-based paycode to qualify as a half-day absence.

    • Must be greater than or equal to Hourly Threshold (HH:mm).

    Hourly Rounding (HH:mm)

    Text

    04:00

    No

    Mandatory

    Day Threshold

    Determines whether the amount of the Combined Absence Pay Code Days control property qualifies as an absence.

    The value identifies the minimum time that is required in the timecard before a day-based paycode qualifies as an absence.

    Day Threshold

    Text

    0.01

    No

    Mandatory

    Day Rounding

    Determines whether the amount of the Combined Absence Pay Code Days control property counts as a full-day or half-day absence.

    The value:

    Represents the maximum amount of time that is required in the timecard for a day-based paycode to qualify as a half-day absence.

    Must be great than or equal to Day Threshold.

    Day Rounding

    Text

    0.5

    No

    Mandatory

    Indicative Pay Code

    Paycode that identifies the accrual adjustment in the timecard.

    The value must adhere to the same locale as the user who initiates the integration.

    Indicative Pay Code

    Text

     

    No

    Mandatory

    Indicative Comment

    Comment attached to the Indicative Pay Code.

    The value must adhere to the same locale as the user who initiates the integration.

    Indicative Comment

    Text

     

    No

    Mandatory

    Lookback Period

    Number of past months for which adjustments are made.

    The current month is included in this value. For example, if the parameter value is set to 1, the integration processes data only for the current month. When the parameter value is set to 2, the integration processes data for the current and previous months.

    Look Back Period

    Number

    1

    No

    Mandatory

    Look Forward Period

    Number of future months for which adjustments are made.

    The current month is included in this number. For example, if the parameter value is set to 1, the integration processes data only for the current month. When the parameter value is set to 2, the integration processes data for the current and next months.

    Look Forward Period

    Number

    3

    No

    Mandatory

    Hyperfind & Location Selector

    Hyperfind or Location query for which the integration will run.

     

    Hyperfind & Location Selector

    Hyperfind

    /Location

     

    Yes

    Mandatory

    Combined Absence Pay Code Hourly

    Combined paycode that controls the list of penalizing hourly-based absences.

    The value must adhere to the same locale as the user who initiates the integration.

    Combined Absence Paycode Hourly

    Text

     

    No

    Mandatory

    Combined Absence Pay Code Days

    Combined paycode that controls the list of penalizing day-based absences.

    The value must adhere to the same locale as the user who initiates the integration.

    Combined Absence Paycode Days

    Text

     

    No

    Mandatory

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.

A cross-reference table (CRT) translates parameter values in an integration as follows:

  • Organizes data values into rows and columns:
    • Maximums = 20 columns, 10,000 rows.
  • Can combine values from multiple columns to determine a single output value.
  • 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 list, select the following tables:

    AbsenceBasedAccrualAdjustment_v1_AccrualPolicy_CRT: Identifies the accrual profiles and codes that will be processed by the extension.

    Column headers and definitions:

    Accrual Profile,Accrual Code,Grant Date(mm/dd),Monthly Grant(Y/N)

    • Accrual Profile = The accrual profile, assigned in the people record, to which the adjustment applies. The value must adhere to the same locale as the user who initiates the integration.

    • Accrual Code = The accrual code adjusted by the extension. The value must adhere to the same locale as the user who initiates the integration.

    • Grant Date(mm/dd) = The accrual grant date, represented in mm/dd format.

    • Monthly Grant(Y/N) = The frequency of the grant. Enter Y for monthly or N for yearly.

    Note:

    • Values must be entered in each column of every row.

    • The extension supports only monthly and yearly grants.

    • When a monthly grant falls on the last day of the month, and the grant date has been entered as 31, the integration will automatically use the last day of the month when the month contains fewer than 31 days. For example, when the monthly grant date is configured as 31, the integration will automatically check the grant on day 30 for April.

    • When the integration is localized, the Accrual Profile and Accrual Code must adhere to the same locale as the user that initiates the integration.

    AbsenceBasedAccrualAdjustment_v1_Localization_CRT: Allows translation of messages into different languages.

    Column headers and definitions:

    Parameter Name,Locale Policy,Value,Description.

    • Parameter Name = Parameters defined in AbsenceBasedAccrualAdjustment_v1_Localization_CRT process property.

    • Locale Policy = Locale policy.

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

    • Description = Parameter description.

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

  3. Select Override to:

    • Download the tables when you run the integration
    • Edit the table cells in Extensions
  4. Click Tap OK.

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. Enter a unique Integration Name.
  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 AbsenceBasedAccrualAdjustment_v1.
    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 Tap Save.

      Repeat this step for each integration parameter that supports the Absence-Based Accrual Adjustment process.

       

      Employee IDs
      Parameter Name Enter Employee IDs.
      Description (Optional)
      Template Parameter

      Select Employee IDs.
      Parameter Type

      Select Text.
      Default Value Not specified.
      User Prompted

      To prompt the person who manually runs the integration to set this parameter, select Yes.

       

      Hourly Threshold (HH:mm)
      Parameter Name Enter Hourly Threshold (HH:mm).
      Description (Optional)
      Template Parameter

      Select Hourly Threshold (HH:mm).
      Parameter Type

      Select Text.
      Default Value

      Default = 00:01

      To use an alternative value:

      1. Clear Use Default.

      2. Enter an appropriate value.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Hourly Rounding (HH:mm)
      Parameter Name Enter Hourly Rounding (HH:mm).
      Description (Optional)
      Template Parameter

      Select Hourly Rounding (HH:mm).
      Parameter Type

      Select Text.
      Default Value

      Default = 04:00

      To use an alternative value:

      1. Clear Use Default.

      2. Enter an appropriate value.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Day Threshold
      Parameter Name Enter Day Threshold.
      Description (Optional)
      Template Parameter

      Select Day Threshold.
      Parameter Type

      Select Text.
      Default Value

      Default = 0.01

      To use an alternative value:

      1. Clear Use Default.

      2. Enter an appropriate value.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Day Rounding
      Parameter Name Enter Day Rounding.
      Description (Optional)
      Template Parameter

      Select Day Rounding.
      Parameter Type

      Select Text.
      Default Value

      Default = 0.5

      To use an alternative value:

      1. Clear Use Default.

      2. Enter an appropriate value.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Indicative Pay Code
      Parameter Name Enter Indicative Pay Code.
      Description (Optional)
      Template Parameter

      Select Indicative Pay Code.
      Parameter Type

      Select Text.
      Default Value Not specified.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Indicative Comment
      Parameter Name Enter Indicative Comment.
      Description (Optional)
      Template Parameter

      Select Indicative Comment.
      Parameter Type

      Select Text.
      Default Value Not specified.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Lookback Period
      Parameter Name Enter Lookback Period.
      Description (Optional)
      Template Parameter

      Select Lookback Period.
      Parameter Type

      Select Number,
      Default Value

      Default = 1

      1. Clear Use Default.

      2. Enter an appropriate value.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Look Forward Period
      Parameter Name Enter Look Forward Period.
      Description (Optional)
      Template Parameter

      Select Look Forward Period.
      Parameter Type

      Select Number.
      Default Value

      Default = 3

      1. Clear Use Default.

      2. Enter an appropriate value.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Hyperfind & Location Selector
      Parameter Name (Required) Enter Hyperfind & Location Selector.
      Description (Optional)
      Template Parameter (Required) Select Hyperfind & Location Selector.
      Parameter Type (Required) Select Hyperfind.
      Default Value Not specified.
      User Prompted

      To prompt the person who manually runs the integration to set this parameter, select Yes.

       

      Combined Absence Pay Code Hourly
      Parameter Name Enter Combined Absence Pay Code Hourly.
      Description (Optional)
      Template Parameter

      Select Combined Absence Pay Code Hourly.
      Parameter Type

      Select Text.
      Default Value Not specified.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      Combined Absence Pay Code Days
      Parameter Name Enter Combined Absence Pay Code Days.
      Description (Optional)
      Template Parameter

      Select Combined Absence Pay Code Days.
      Parameter Type

      Select Text.
      Default Value Not specified.
      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

  2. Click Tap Save.
  3. 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 AbsenceBasedAccrualAdjustment_v1 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:
    • 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

    • Hyperfind & Location Selector: Select a Hyperfind query of employees.

  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 view 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

API section

Type

Resource path

Location

Description

Retrieve persons

Commons

POST

v1/commons/persons/extensions/multi_read

_Person Extension

Returns multiple person records based on search criteria.

Execute Hyperfind query

Commons

POST

/v1/commons/hyperfind/execute

_Execute Hyperfind

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

Bulk accrual update

Timekeeping

POST

v1/timekeeping/accruals/updates

_Update Accrual Balance

Updates accrual balances in bulk.

Update timecard

Timekeeping

POST

/v1/timekeeping/timecard

_Update Paycode and Comments

Adds, updates, or removes paycode edits.

Retrieve timecard data

Timekeeping

POST

/v1/timekeeping/timecard_metrics/multi_read

_Retrieve Absence Data

Returns timecard data for a set of employees or locations.

Retrieve timecards as manager

Timekeeping

POST

v1/timekeeping/timecard/multi_read

_Retrieve Paycode Edits

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

Retrieve employment terms

Timekeeping

POST

v1/timekeeping/setup/employment_terms/multi_read

_Employment Term & Accrual Profile

Returns one or more employment terms by object references.

Retrieve full paycodes as manager

Timekeeping

GET

v1/timekeeping/setup/pay_codes/multi_read

_Validate Pay Codes

Returns one or more paycodes available to the logged-in manager by object references.

Retrieve comments-manager

Commons

GET

/v1/commons/comments

_Validate Comment

Returns a filtered list of comments.