Configure the HCM Accruals Export Integration

How to configure connection settings, process properties, cross-reference tables, and data maps for this integration.

This topic describes how to configure this integration.

This integration pack exports accruals balances to Dimensions HCM by way of APIs. The purpose is to include accruals information on pay statements as follows:

  • Balance, Taken to Date, and Accrued
  • By default, all accruals codes are exported.
  • Use a cross-reference table to map accrual codes.

If employees have multiple account records in HCM:a

  • Accruals are exported to all active account records.
  • Accruals are exported to terminated records if the termination date is during the pay period.

Before you start

HCM Accruals Export integration
  1. Deploy the Dimensions HCM Accrual Export integration pack; see Deploy Integration Packs.
  2. Get the URL for the HCMAuthenticationServer from the tenant details.
  3. Get the following HCMAuthenticationProperties from the tenant details:
    • username: This is the username for the account that accesses the APIs and all employee groups.
    • password: For the same account

    • api-key: The API key calls the HCM REST APIs from the HTTP request header. Get the key as follows:

      • Log in to the HCM Company tenant with an administrator user account.
      • Find and select the Company.
      • Click Tap Log in as SA.
      • Select Home > Maintenance > Company Settings > Global Setup > Company Setup > the Company Config tab.
      • Select and expand API Keys.
      • Do one of the following:

        If a key has been generated already, do not generate another one. Click Tap View to show the API Key. Copy and use this key.

        If a key has not been generated, click tap GENERATE.

    • targetCompany: If you don't have access to this credential, contact UKG support.
    • targetCompanyId: If you don't have access to this credential, contact UKG support.

Configure the integration

How to configure this integration.

Select the environment

How to select the environment for the integration.

  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

HCM Accruals Export integration
  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass
    Search button
    .
  3. Scroll to and select the integration pack: Dimensions HCM Accruals Export > HCMAccrualExport-v1.

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 Connection, select and configure:

    Connection Settings

    Connection Settings for the HCM Accruals Export integration

    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

    HCMAuthenticationServer

    Required

    (Optional) To change the HCM authentication server:

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

Configure process properties

Process properties apply globally to all records that an integration processes. When you install the integration, you can define the parameter values or configure a prompt for the user to define the value when they run the integration.

Note: Most of the process properties have default values, even though the Integration Template Designer does not display these values.
  1. Select Process Properties.
  2. Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

    Only while you test or design integration templates, should you edit the properties to connect to the authentication server and get the access token to execute APIs.

    1. From the Process Property dropdown list, select AuthenticationProperties.
    2. In GatewayDefaultPort, clear Use Default. Enter the path to the port for the API gateway.
    3. Note: You no longer need an AppKey to call API operations. If one is defined, it is ignored.
  3. From the Process Property dropdown list, select HCMAccrualsExport-vx_External_HCMAuthenticationProperties to edit the properties to connect to the authentication server and get the access token to execute APIs.
    Caution: You must edit the authentication properties for the account that accesses the APIs and all employee groups. This information is part of the tenant details for the destination system.

    Edit the following:

    • username: Clear Use Default. Enter the username.
    • password: Clear Use Default. Enter the password.
    • api-key: The API key calls the REST APIs from the HTTP request header. Clear Use Default. Enter the key for the destination.
    • targetCompany: Default = Not Mapped. Clear Use Default. Enter the short name of the company exactly as it is defined in the destination system.
    • targetCompanyId: Default = Not Mapped. Clear Use Default. Enter the Company ID exactly as it is defined in the destination system.

  4. (Optional) HCMAPIErrorHandler properties define how the integration responds if an integration run exceeds an API limit.

    Caution: In most circumstances, do not edit the HCMAPIErrorHandler properties; leave these settings at their default values.

    From the Process Property dropdown list, select _HCMAPIErrorHandler to change how to handle errors if integration runs exceed the limitations of an API.

    • MaxRetry: This property defines the maximum number of times to retry integration runs if errors occur.

      Default = 5.

      To change the number of retries:

      Clear Use Default.

      Enter the number of retries up to a maximum of 5.

    • TimeToWait: If an API limit is exceeded, this property defines how long to wait before sending the next API call.

      Default = 60000 ms. If the API call has to be sent again, each repetition adds 60,000 ms (1 minute) to the wait time.

      Examples:

      1st TimetoWait = 60,000 ms (InitialTimeToWait)

      2nd TimetoWait = 60,000 ms + 60,000 ms = 120,000 ms

      3rd TimetoWait = 60,000 ms + (2 * 60,000 ms) = 180,000 ms

      To change the initial wait time:

      Clear Use Default.

      Enter the wait time in milliseconds (ms) up to a maximum of 180000 ms.
  5. Caution: You must edit the authentication properties for the account that accesses the APIs and all employee groups. This information is part of the tenant details for the destination system.

    Edit the following:

    • username: Clear Use Default. Enter the username.
    • password: Clear Use Default. Enter the password.
    • api-key: The API key calls the REST APIs from the HTTP request header. Clear Use Default. Enter the key for the destination.
    • targetCompany: Default = Not Mapped. Clear Use Default. Enter the short name of the company exactly as it is defined in the destination system.
    • targetCompanyId: Default = Not Mapped. Clear Use Default. Enter the Company ID exactly as it is defined in the destination system.
  6. From the Process Property dropdown list, select HCMAccrualExport-vx_CRTConfig to define headers in the cross-reference table.

    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.

    Caution: The Boomi™ application does not return default values for cross-reference table headers. You have to enter the headings in Value.
    Note: For details, see Configure cross-reference tables.

    In _HCMAccrualExport_AccrualCodeMapping:

    1. Clear Use Default.
    2. In Value, enter the headers, separated by commas (,) but no spaces, exactly as shown below the Value field. You can select and copy the headers from the screen, then paste them in the Value field.

  7. From the Process Property dropdown list, select HCMAccrualExport_ProcessProperties to set process properties that must be configured before the integration can run. In most cases, use the default values.

    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.

    Process Properties

    Process Properties for the HCM Accruals Export integration

    Property

    Required

    Actions

    ProcessTheseAccrualCodesOnly

    Not required

    Enter the short names for the accrual codes to export.

    • Separate each name with a comma.
    • Leave blank to export all accrual codes.

    SuppressRecordsWithZeroAccrualBalance

    Not required

    Default = true(recommended)

    To include accruals that have a balance of zero:

    1. Clear Use Default.
    2. Select Value.

    PayPeriod

    Not required

    Accrual balances go to the last day of the selected pay period.

    Default = 0(Previous pay period)

    To change the pay period:

    1. Clear Use Default.
    2. Enter one of the following values for the pay period:

      0 = Previous pay period

      1 = Current pay period

      2 = Next pay period

      3 = Previous schedule period

      4 = Current schedule period

      5 = Next schedule period

      6 = Week to date

      7 = Last week

      8 = Yesterday

      10 = Range of relative dates

      11 = Specific date

      12 = Relative specific date

      13 = Today

    IncludeEmployees

    Not required

    Default = Include all employees.

    To process data for only a limited group of employees:

    1. Clear Use Default.
    2. Enter the person numbers, as defined in the source system, each separated by a comma (,) but no spaces.

      Example: 13997,15556,20012

    HyperfindAndLocations

    Not required

    Default = 1 (shown as blank) which indicates All Home and includes all active employees.

    To select another hyperfind and locations:

    1. Clear Use Default.
    2. (Required) Enter the ID of a single hyperfind, or the IDs of one or more locations each separated by a comma (,) or number sign (#).
      Caution: If you do not enter an ID for the Template Parameter, the integration cannot identify the hyperfind and the integration run fails.
    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 for the organization and select that hyperfind in this process property.

    The maximum number of employees in a hyperfind is 3500. To process more employee records, divide the population into smaller hyperfinds to run sequentially.

    _AccrualCodeMappingIsRequired

    Not required

    Uses a reference table to map accrual code names between the systems.

    To not change the accrual code names:

    1. Clear Use Default.
    2. Clear Value.

    _HyperfindQueryThreshold

    Not required

    Default = 5000

    To set a different number of queries as the hyperfind threshold:

    1. Click Tap Use Default.
    2. Enter the number in Value.
      Caution: Important: High thresholds can impede system performance.

    _HoursPerDay

    Not required

    Default = 8

    To convert the day accrual code amount to a different number of hours:

    1. Clear Use Default.
    2. Enter the number of hours.

    Pass Money Types

    Not required

    Default = not selected

    To pass money-type accrual codes to UKG Pro Workforce Management HCM:

    1. Clear Use Default.
    2. Select Pass Money Types.

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.

The source of the look-up keys are SuccessFactors fields in the data map.

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. Caution: For the cross-reference tables that you are customizing, make sure that Use Default is not selected in Process Properties > {ProcessName}_CRTConfig, and that the headers are defined.
  2. Select Cross Reference.
  3. From the Cross Reference dropdown list, select _AccrualCodeMapping.

    You cannot change the name of the table.

    This table assigns accrual profiles during the import.

    Column headers

    TimekeeperAccrualCode,PayrollAccrualCode

  4. Select Override to:

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

Select data maps

A data map translates a data structure from the source format to the destination format. Examples: Map "PersonID" in the source to "Person ID" in the destination or "LastName" to "Last Name".

Each integration pack has a default data map. You cannot edit the default map for HCM integrations. If the predefined fields do not suite your requirements, use the default map as a guide when you edit or create a custom data map.

To display the data maps:

  1. Select Data Maps.
  2. From the Data Maps dropdown list, select HCMAccrualExport_TimekeeperBalances—HCMAccrualExport_PayrollBalances to accept the predefined order of fields to export to the destination file. The names match the fields in the data map.
  3. Select
    Expand
    to expand or
    Collapse
    to collapse levels.
    To expand all levels, right-click the green boxes icon
    Map level options
    . Select Expand All
    Expand all map levels
    .

    The lines show the links between fields in the source (left side), any intermediate functions, and the destination (right side).
  4. Click Tap OK.

Design of the HCM Accruals Export integration

This section provides detailed information to help you to assess whether this integration meets your business needs.

This integration pack is an API to API integration that depends on the configuration of the source and destination systems. Knowledge of configuration and navigation in both environments helps you to make adjustments for testing.

This integration uses the following APIs:

API details

API details for the HCM Accruals Export integration

API

Operation

Description

HCM Post Accrual Balances

POST

Update the HCM accrual balances with the accrual balances.

The API request body requires the Company Name and the Employee ID.

Output fields

Output fields for the HCM Accruals Export integration

HCM field

How populated

Example

Username

blank

—

Employee ID

Person number

45688

SSN

Tip: Tip: Social Security Number (SSN) is an identity number that is issued by the United States government to citizens, and permanent and temporary working residents for Social Security and taxation purposes.

blank

—

Employee External ID

blank

—

EIN Tax ID

blank

—

EIN Name

blank

—

Time Off Code

Accruals code:

  • Earned
  • Taken
  • End Balance
  • Balance Forward

Vacation Accrual

Vacation Taken

Vacation Balance

Effective Date

Always the end date of the Previous Pay Period

2017-01-21 00:00:00.000

Amount

Accruals code:

  • Earned
  • Taken
  • End Balance
  • Balance Forward
  • 80.00
  • 40.00
  • 8.65
  • 110.02

External Accrued

blank

—

External Taken

blank

—

External Carry Over

blank

—

Note: In most cases, only a few fields are passed. Example: Employee ID, Time Off Code, Effective Date, and Amount (Balance) are enough to identify employee accruals.

Upload file formats: Export accruals balances to HCM.