Configure the HCM Payroll Export-v2 Integration

How to configure connection settings and process properties 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.

To edit the payroll data, see:

Payroll data that is processed

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

  • Hours, pay rate (optional), and amounts
  • Business structure as Cost Center 1
  • Labor categories, if configured, as a cost center
  • 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.
  • Previous Pay Period is selected by default, but you can select other time periods.

Before you start

HCM Payroll Export integration.
  1. Deploy the Dimensions HCM Payroll Export integration; see Deploy Integrations.
  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.
  4. Configure HCM Payroll.
  5. Configure Payroll to Paycode Mappings.

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

    Connection Settings

    Connection Settings for the HCM Payroll Export-v2 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

HCM Payroll Export-v2 integration
  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-v2_External_HCMAuthenticationProperties to edit the properties to connect to the HCM 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. From the Process Property dropdown list, select HCMLaborCategories to map labor categories or WFM cost centers to cost centers in the payroll system.

    • Each employee can be assigned to up to six primary labor categories. The integration can use cost center trees to assign one or more primary labor categories to employees. Any cost center tree that populates a labor category is configured with one level.
    • This integration can pass the values of WFM Cost Centers in the business structure or timecard override to a cost center in the payroll system.
    Caution:

    Make sure that you know which labor categories to map and in which order; see the Labor Categories topic.

    • The name of each labor category indicates the order; examples: Labor Category 1 is first, Labor Category 2 is second, and so on.
    • The Name and Description of the job in HCM must match the Name and Description of the labor category. Do not use any of the following restricted characters: / | \ * ( ) : , ; # % ^ ? [ ] =
    • If HR Job is a labor category, you can use the default job (Cost Center 10).
    • If the system includes or will include Healthcare Analytics, HR Job must be Labor Category 1.

    For each Labor Category 1—6 or the WFM Cost Center:

    1. Clear Use Default.
      Caution: If Use Default is selected, the value is Not Used and labor categories or WFM cost centers are not defined.
    2. Select one of the following:
      • Not Passed(default): The labor category or WFM cost center is not passed to payroll.
      • Cost Center 2—9: Map cost center fields to labor categories or the WFM cost center.
        Note:
        • Cost Center 1 maps node-by-node to the business structure and includes the job.
          Caution: If nobusiness structure corresponds to the default cost center, the integration run fails that record.
        • Cost Center 10 is reserved for the HR job and is not available to be assigned to a labor category.
      • Default Job(CC 10): Pass the labor category to payroll in the Default Job/Cost Center 10 column of the payroll export.

      Example labor category definitions

      Example labor category definitions for the HCM Payroll Export-v2 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

      WFM Cost Center

      Not Passed

  6. From the Process Property dropdown list, select HCMPayrollExport-v2_ProcessProperties to set process properties that must be configured before the integration can run. In most cases, use the default values.
    Caution:

    Recommendation: Leave the process properties at the default settings.

    • Exceptionally to use a cost center other than 1, change the default value of the _HCMCostCenter process property.
    • For all other process properties, instead use integration parameters to change default values; see Install HCM Integrations.
    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-v2 integration

    Property

    Required

    Actions

    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

    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 = blank which includes all active employees.

    Caution: Do not change the default and do not select a location. Otherwise, the locations are not valid when you run the integration.

    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.
    Note: You can specify up to 20 paycodes to include.

    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.
    Note: You can specify up to 20 paycodes to exclude.

    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.

    PayStatementType

    Not required

    Type of pay statement in HCM

    Default = Regular

    (Not recommended) To change the type:

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

    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

    _HCMCostCenter

    Not required

    Assign the cost center for the primary job.

    Default = Cost Center 1

    (Rarely) To change the cost center:

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

    Changes Only

    Not required

    Default = true

    • If this integration runs on the same day as a previous run of the same integration is completed, export the payroll data only for employees who had changes or corrections made to their timecard.
    • If the process parameters have any changes, export the payroll data for all employees.
    • This integration does not consider who runs the integration. If one person runs the integration, and another person who logged in separately runs the integration again, the integration looks only for changes to the employee timecards.
    • If the IncludeEmployees process property is used during the integration run, do not check for changes but export the payroll data for all employees.

    To export the payroll data for all employees regardless of whether an HCM Payroll Export integration run is completed on the same day:

    1. Clear Use Default.
    2. You don't need to select Value.

    Create File

    Not required

    Select whether to export the payroll data to a spreadsheet (.xls file).

    1. Clear Use Default.
    2. Select one of the following:
      • No(default) = Do not export the data to a file.
      • Yes= Export the payroll data to a file.
        Caution: You can import the payroll file in a batch process, but you must add Payroll Name and Payroll Pay Date to the payroll file. For descriptions of all fields in the payroll file, see Employee Payroll Data.
  7. When you finish, click tap OK.
  8. You can close the tab for the Integration Template Designer.

APIs

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

APIs for the HCM Payroll Export-v2 integration

API

Operation

Description

HCM Employees

GET

Look up the employee’s Account ID that corresponds to the Employee ID.

Dimensions HCM creates pay statements from the Account ID.

Note: Tip: Store external IDs that are required by the payroll system in a custom field.

HCM Pay Statement Types

GET

Return the IDs of the Pay Statement Types.

These are required by the Pay Statement Request.

HCM Payroll ID

GET

Return the Payroll ID from the Pay Date that is derived from Days to Pay Date.

The Payroll ID is based on From and To dates of the pay period.

HCM Post Pay Statements

POST

Populate the destination Pay Statements with timecard totals from the source.