Configure the HCM Payroll Export-v1 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.

Note:

Version 2 of the HCM Payroll Export integration improves performance because it only transfers data and does not modify or transform that data. It does not have cross-reference tables or data maps. The HCM Payroll Configuration and Payroll Code Mapping setup pages replace the PaycodeCRT cross-reference table.

See Configure the Dimensions HCM Payroll Export-v2 Integration.

Payroll data that is processed

This integration pack exports the following payroll data from HCM by way of APIs:

  • Hours, pay rate (optional), and amounts
  • Business structure as Cost Center 1
  • Labor categories, if configured, as a cost center

Before you start

HCM Payroll
  1. Deploy the Dimensions HCM Payroll 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

  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 Payroll Export > HCMPayrollExport-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 Payroll Export-v1 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

  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 HCMPayrollExport-v1_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. (Optional) From the Process Property dropdown list, select HCMLaborCategories to map labor categories to cost centers to pass to payroll.

    The worked labor category can be passed to payroll as a cost center.

    Example labor category definitions

    Example labor category definitions for the HCM Payroll Export-v1 integration

    Labor category

    Value

    Labor Category 1

    Cost Center 2

    Labor Category 2

    Cost Center 3

    Labor Category 3

    Not Passed

    Labor Category 4

    Not Passed

    Labor Category 5

    Not Passed

    Labor Category 6

    Not Passed

    For each Labor Category:

    1. Clear Use Default.
      Caution: If Use Default is selected, the value is Not Passed and labor categories are not passed to payroll.
    2. Select one of the following:

      Not Passed(default): The labor category is not passed to payroll.

      Cost Center 2—9: Map cost center fields to labor categories.
  6. From the Process Property dropdown list, select HCMPayrollExport-v1_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.

    Select _HCMPayrollExport-v1_PaycodeCRT. This table assigns paycodes during the export.

    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 HCMPayrollExport_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 Payroll Export-v1 integration

    Property

    Required

    Actions

    ExcludeEmployees

    Not required

    To exclude employees from the integration:

    1. Clear Use Default.
    2. Enter the person numbers each separated by a comma (,) or number sign (#).

    PayPeriod

    Not required

    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

    Payrules

    Not required

    To consider pay rules during the payroll export:

    1. Clear Use Default.
    2. Enter the PayruleNames each separated by a comma (,) or number sign (#).
    Caution:

    The HCM Payroll Export integration fails after you change an employee's pay rule from Monthly or Biweekly to Weekly if the start date of the weekly pay period is earlier than the end date of the monthly or biweekly pay period. The error message states: Payroll does not exist.

    To prevent this failure when you change the pay rule, make sure that the start date of the new weekly pay period is not earlier than the end date of the monthly or biweekly pay period.

    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.

    IncludePaycodes

    Not required

    To export only a limited group of paycodes:

    1. Clear Use Default.
    2. Enter the paycodes each separated by a comma (,) or number sign (#), but no spaces.

    ExcludePaycodes

    Not required

    To exclude paycodes from the integration:

    1. Clear Use Default.
    2. Enter the paycodes each separated by a comma (,) or number sign (#), but no spaces.

    IgnoreSignoff

    Not required

    Default = Only signed-off data is exported.

    To export signed-off and not signed-off data:

    1. Clear Use Default.
    2. Select Value.

    PayperiodWeekNumber

    Not required

    Default = Export data for the entire pay period.

    To export only a specific number of weeks in a pay period:

    1. Clear Use Default.
    2. Enter the number of weeks from 1-2 in a pay period, or from 1-4 in a month.

    TimeWorkedUnit

    Not required

    To export a specific unit of worked time:

    1. Clear Use Default.
    2. Enter the duration of the worked time in HH:mm, HH.hh, or mmm (minutes) format.

    Custom 1—4

    Not required

    A custom field can be a search criterion to extract payroll data for specific employees or groups.

    Examples:

    • Custom 1 = Payroll_ID to export data for a specific identifier in the payroll application.
    • Custom 2 = Temporary to export data only for temporary employees.
    • Custom 3 = Contract to export data only for employees who work on contract.
    • Custom 4 = Minor to export data only for employees who are under 18 years of age.

    To process a custom field:

    1. Clear Use Default.
    2. Enter the value of the custom field.

    _ HyperfindAndLocationsType

    Not required

    Default = blank

    Default = Hyperfind

    1. Clear Use Default.

    2. Select one of the following:

      • Hyperfind = Preferred
      • Location
      • Custom — Required for IncludeEmployees and any Disqualify properties

    IsWeeklyAggregation

    Not required

    To categorize exported records by week number 1, 2, 3, or 4:

    1. Clear Use Default.
    2. Select Value.

    _EnableCustomMapping

    Not required

    To use a custom map:

    1. Clear Use Default.
    2. Select Value.

    Custom 5—10

    Not required

    A custom field can be a search criterion to extract payroll data for specific employees or groups. This integration can support up to 10 custom fields.

    To process a custom field:

    1. Clear Use Default.
    2. Enter the value of the custom field.

    _CustomFields

    Not required

    To process custom fields:

    1. Clear Use Default.
    2. Enter the names of the custom fields each separated by a comma (,).

    PayStatementType

    Not required

    Type of pay statement in HCM

    Default = Regular

    To change the type:

    1. Clear Use Default.
    2. Enter the name of the type of pay statement.

    _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.

    HCMPayrollCompanyList

    Not required

    Define the format to export payroll data. This data includes the base rate combinations for EINs, pay periods, and base rate.

    Default = Not defined

    1. Clear Use Default.
    2. Enter the EIN, pay period, and base rate, each element separated by a semicolon ( ;), and each grouping separated by a double hash ( ##).

      Possible values for base rate = Yes, No, True, or False

      Example: EIN1;Weekly;Yes##EIN2;Biweekly;No

    DailyRecords

    Not required

    Default = Exported records are aggregated by pay period.

    To aggregate exported records daily:

    1. Clear Use Default.
    2. Select Value.

    BusinessStructureType

    Not required

    Matches the business-structure location type for the worked job to the Company EIN in HCM

    Default = Region

    To change the location type:

    1. Clear Use Default.
    2. Enter the location type.
    3. You must also configure the Integration List Parameters.

    PassRate

    Not required

    Select whether to export the pay rate. Integration List Parameters override this property.

    Default = Export the pay rate.

    To not export the pay rate:

    1. Clear Use Default.
    2. Select Value.

    _HCMCostCenter

    Not required

    Assign the cost center for the primary job.

    Default = Cost Center 1

    To change the cost center:

    1. Clear Use Default.
    2. Select another cost center.

    _DeterminePayrollBatchEIN

    Not required

    Define whether to use the worked or primary job to decide which payroll EIN batch to populate.

    Example: An employee's primary job is Job1, but the employee can also work Job2. If Worked Job is selected, the payroll batch assigns the hours that are worked on Job2 to EIN2. If Primary Job is selected, the payroll batch assigns the hours that are worked on Job2 to EIN1.

    Default = Worked Job

    To use the primary job to determine the payroll EIN to populate:

    1. Clear Use Default.
    2. Select Primary Job.
      Caution: When Primary Job is selected, mid-pay period changes to the primary job are not supported. Only the primary job as of the end of the pay period is used.

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. 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 HCMPayrollExport-v1_PayCodeCRT.

    This table assigns paycodes during the export.

    You cannot change the name of the table.

    Column headers:

    TimekeeperPayCode,PayrollPayCode,ExcludePaycode(T/F),Column 4,Column 5,Column 6,Column 7,Column 8,Column 9,Column 10,Column 11,Column 12,Column 13,Column 14,Column 15,Column 16,Column 17,Column 18,Column 19,Column 20

    The values are dynamic, are defined in Dimensions HCM, and can include wildcards such as *.

  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 HCMPayrollExport-v1_Timekeeper — HCMPayrollExport-v1_Payroll(default map) to accept the predefined order of fields to export to the destination file. The names match the fields in the data map.

    Data Map: HCMPayrollExport-v1_Timekeeper — HCMPayrollExport-v1_Payroll

  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.

Workflow

  • Hours and money records are aggregated by pay period, by employee, by worked account, by up to 6 levels of worked labor categories, by paycode type, by HCM (payroll) paycode name, worked labor category, by mapped cost center, by worked cost center, and by base pay rate.
  • A standard paycode reference table translates the paycode name to the HCM earnings (E) code.
  • Previous Pay Period is selected by default, but you can select other time periods.
  • Ignore sign off (T/F) parameters are populated.
  • Pass only paycodes from the source paycode column of the cross-reference tables. Combined paycodes are excluded.