Configure the Universal Payroll 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 exports payroll data to a flat file.

Universal integration packs exchange data by way of flat files, either to export data to the file or import data from the file. Other systems access the data in these flat files to complete the import or export integration. The default settings allow rapid configuration and runs of the integration process, while the exposure of the data maps and cross-reference tables in the extensions allows overrides and customizations of the default data mappings or values.

Before you start

Before you start to configure the Universal Payroll Export integration.

Deploy the Universal Payroll Export > DREmployees, DRPaycodes, TimeByEmployees, or TimeByPaycode integration pack; see Deploy Integration Packs to your Atom.

Configure the integration

How to configure this integration.

Select the environment

How to select the environment for theintegration.

  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.

Export payroll daily records by employee

DR = Daily record

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: Universal Payroll Export > DREmployees.
  2. 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 dropdown list, select and configure:

      Connection Settings

      Connection Settings for the Universal Payroll Employee Daily Records Export integration

      Property

      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

      SFTPServer

      Required

      The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account.

      To change the default SFTP server parameters:

      1. For each field, clear Use Default.
      2. Enter the following values:

        • Enter the name of the internal Host.

        • Enter the number of the Port for the internal SFTP account.

        • In User, enter the username for the internal SFTP account.

        • In Password, select <Encrypted>. Enter the new password for the internal SFTP account.

        • Click Tap Apply.

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

    2. From the Process Property dropdown list, select DREmployees_ProcessProperties to set process properties that must be configured before the integration can run.

      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 Universal Payroll Employee Daily Records Export 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

      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

      ResultFileName

      Not required

      Name of the file to store the generated export data

      1. Clear Use Default.
      2. Enter the file name. Use a .csv extension.

      Example: ExportPayrollData.csv

      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 (#).

      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

      Required

      Default = Hyperfind

      1. Clear Use Default.

      2. Select one of the following:

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

      _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 (,).

      Delimiter

      Not required

      Default = comma (,)

      To change the character that separates data values in the flat file:

      1. Clear Use Default.

      2. Enter the character.

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

      UserInput1—6

      Not required

      To require that the payroll administrator enter data for a custom field:

      1. Clear Use Default.
      2. Enter the label for the field.

      _DisableQuotes

      Not required

      To remove double quotation marks from the exported file:

      1. Clear Use Default.
      2. Select Value.

      If the value of any field contains any character that is used as a delimiter, this property converts that character in the data map to another character that is not used in the file. Example: Convert the comma (,) delimiters in a comma-separated values file to a pipe (|) character.

    3. From the Process Property dropdown list, select DREmployees_SFTPProperties.

      SFTP Properties

      SFTP Properties for the Universal Payroll Employee Daily Records Export integration

      Property

      Required

      Actions

      OutputDirectory

      Not required

      The directory on the SFTP server to archive the output files.

      Default = /Outbound.
      Caution:

      Do not change the name of the folder from Outbound. Additional or differently named folders are not supported by .

      To define a different directory path:

      1. Clear Use Default.
      2. Enter the directory path.

      AppendRecords

      Not required

      To append records to any previous payroll export file:

      1. Clear Use Default.
      2. Select Value.

      _FileNameWithTimestamp

      Not required

      To add a time stamp to the end of the file name of the export file:

      1. Clear Use Default.
      2. Select Value.
  6. Configure data maps

    (Optional)

    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. Editing of the default map is limited to adding fields, changing mappings, or inserting functions. Any changes override the previous values. If the predefined fields do not suite your requirements, use the default map as a guide when you create your custom data map.

    1. Select Data Maps.

    2. From the Data Maps dropdown list, select one of the following:

      • DREmployees_PayrollDefinedFields—DREmployees_PayrollOutputFields(default map): Accept the predefined order of fields to export to the destination file. The names match the fields in the data map. If needed, you can edit this map. The _EnableCustomMapping process property must be set to false.

        Example data map


        Map Export Payroll - Payroll Output Fields
      • DREmployees_PayrollDefinedFields—DREmployees_CustomizedOutputFields: Define a custom map with your own fields and ordering to map the data from the source to the destination. You can also define functions to transform mapped data. The _EnableCustomMapping process property must be set to true.

      • DREmployees_QualifierFieldsProfile—DREmployees_QualifierFieldsProfile: This map translates paycodes.

        Example data map


        Map Export Payroll QualifierInput—QualifierFieldsProfile
    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. (Optional)

      Caution: The default mappings are developed and tested based on best practices. If you make changes, you may get unexpected results. Modify and test carefully.
      • Change mappings — When you customize a default data map, you can add fields only to the end of the map.

        You can select and drag to change the links between the source (left column), function (middle column), and destination (right column) items. A single source field can link to multiple destination fields, but a destination field can link to only one source field.

      • Transform the data — A map can include intermediate functions that transform the data. Examples: Perform mathematical calculations on the values or get values from a cross-reference table.
        Note: To override a field — for example because you cannot delete it from a default map — insert a function that has a null output.
        1. In Function, click tap the plus button
          Add map function
          to add an intermediate function.
        2. From Category, select a category of functions:

          String — Trim, add to, concatenate, replace, remove, split, or change the case of text.

          Caution: Do not use special characters such as angle brackets (< or >) in data in cross-reference tables, data maps, and input files. These characters can make the integration fail.

          Numeric — Perform mathematical calculations on the data.

          Date — Change the format or get the current date.

          Lookup — Get data from a cross-reference table (CRT), document cache, SQL query, or define a key-value change.

          Connector — Call a value from a connector to an application or data source.

          Custom Scripting — Transform data by way of Groovy or JavaScript code.

          Properties — Get or set process or document properties.

        3. Select the function from the list in the selected category.
        4. Click Tap OK.
        5. If prompted in Configure Defaults, enter the relevant values. Select a Caching. Click Tap OK.
        6. Select and drag from a source field to an input of the function.
        7. Select and drag from the output of the function to a destination field.
        8. Repeat to add another function.
    5. When you finish, click tap OK.

Export payroll daily records by paycode

DR = Daily record

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: Universal Payroll Export > DRPaycodes.
  2. 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

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

      Connection Settings

      Connection Settings for the Universal Payroll Paycode Daily Records Export integration

      Property

      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

      SFTPServer

      Required

      The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account.

      To change the default SFTP server parameters:

      1. For each field, clear Use Default.
      2. Enter the following values:

        • Enter the name of the internal Host.

        • Enter the number of the Port for the internal SFTP account.

        • In User, enter the username for the internal SFTP account.

        • In Password, select <Encrypted>. Enter the new password for the internal SFTP account.

        • Click Tap Apply.

  4. 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. 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.
    2. From the Process Property dropdown list, select DRPaycodes-v1_CRTConfig to define headers in 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.

      Caution: The Boomi™ application does not return default values for cross-reference table headers. You have to enter the headings in Value.

      In _DRPaycodes-v1_PaycodesCRT:

      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.

    3. From the Process Property dropdown list, select DRPaycodes_ProcessProperties to set process properties that must be configured before the integration can run.

      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 Universal Payroll Paycode Daily Records Export 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

      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

      ResultFileName

      Not required

      Name of the file to store the generated export data

      1. Clear Use Default.
      2. Enter the file name. Use a .csv extension.

      Example: ExportPayrollData.csv

      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 (#).

      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

      Required

      Default = Hyperfind

      1. Clear Use Default.

      2. Select one of the following:

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

      _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 (,).

      Delimiter

      Not required

      Default = comma (,)

      To change the character that separates data values in the flat file:

      1. Clear Use Default.

      2. Enter the character.

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

      UserInput1—6

      Not required

      To require that the payroll administrator enter data for a custom field:

      1. Clear Use Default.
      2. Enter the label for the field.

      _DisableQuotes

      Not required

      To remove double quotation marks from the exported file:

      1. Clear Use Default.
      2. Select Value.

      If the value of any field contains any character that is used as a delimiter, this property converts that character in the data map to another character that is not used in the file. Example: Convert the comma (,) delimiters in a comma-separated values file to a pipe (|) character.

    4. From the Process Property dropdown list, select DRPaycodes_SFTPProperties.

      SFTP Properties

      SFTP Properties for the Universal Payroll Paycode Daily Records Export integration

      Property

      Required

      Actions

      OutputDirectory

      Not required

      The directory on the SFTP server to archive the output files.

      Default = /Outbound.
      Caution:

      Do not change the name of the folder from Outbound. Additional or differently named folders are not supported by .

      To define a different directory path:

      1. Clear Use Default.
      2. Enter the directory path.

      AppendRecords

      Not required

      To append records to any previous payroll export file:

      1. Clear Use Default.
      2. Select Value.

      _FileNameWithTimestamp

      Not required

      To add a time stamp to the end of the file name of the export file:

      1. Clear Use Default.
      2. Select Value.
  6. 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 DRPaycodes-v1_PaycodesCRT.

      This table maps exported paycodes to destination paycodes. The table has many rows; to navigate, click tap Next, Previous, First, or Last.

      Column headers:

      KronosPayCode,ThirdPartyPayCode,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

    4. Select Override to:

      • Download the tables when you run the integration
      • Edit the table cells in Extensions
  8. Configure data maps

    (Optional)

    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. Editing of the default map is limited to adding fields, changing mappings, or inserting functions. Any changes override the previous values. If the predefined fields do not suite your requirements, use the default map as a guide when you create your custom data map.

    1. Select Data Maps.

    2. From the Data Maps dropdown list, select one of the following:

      • DRPaycodes_PayrollDefinedFields—DRPaycodes_PayrollOutputFields(default map): Accept the predefined order of fields to export to the destination file. The names match the fields in the data map. If needed, you can edit this map. The _EnableCustomMapping process property must be set to false.

        Example data map


        Map Export Payroll - Payroll Output Fields
      • DRPaycodes_PayrollDefinedFields—DRPaycodes_CustomizedOutputFields: Define a custom map with your own fields and ordering to map the data from the source to the destination. You can also define functions to transform mapped data. The _EnableCustomMapping process property must be set to true.

      • DRPaycodes_QualifierInput—DRPaycodes_QualifierFieldsProfile: This map translates paycodes.

        Example data map


        Map Export Payroll QualifierInput—QualifierFieldsProfile

        Example data map: Export Payroll Qualifier

    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. (Optional)

      Caution: The default mappings are developed and tested based on best practices. If you make changes, you may get unexpected results. Modify and test carefully.
      • Change mappings — When you customize a default data map, you can add fields only to the end of the map.

        You can select and drag to change the links between the source (left column), function (middle column), and destination (right column) items. A single source field can link to multiple destination fields, but a destination field can link to only one source field.

      • Transform the data — A map can include intermediate functions that transform the data. Examples: Perform mathematical calculations on the values or get values from a cross-reference table.
        Note: To override a field — for example because you cannot delete it from a default map — insert a function that has a null output.
        1. In Function, click tap the plus button
          Add map function
          to add an intermediate function.
        2. From Category, select a category of functions:

          String — Trim, add to, concatenate, replace, remove, split, or change the case of text.

          Caution: Do not use special characters such as angle brackets (< or >) in data in cross-reference tables, data maps, and input files. These characters can make the integration fail.

          Numeric — Perform mathematical calculations on the data.

          Date — Change the format or get the current date.

          Lookup — Get data from a cross-reference table (CRT), document cache, SQL query, or define a key-value change.

          Connector — Call a value from a connector to an application or data source.

          Custom Scripting — Transform data by way of Groovy or JavaScript code.

          Properties — Get or set process or document properties.

        3. Select the function from the list in the selected category.
        4. Click Tap OK.
        5. If prompted in Configure Defaults, enter the relevant values. Select a Caching. Click Tap OK.
        6. Select and drag from a source field to an input of the function.
        7. Select and drag from the output of the function to a destination field.
        8. Repeat to add another function.
    5. When you finish, click tap OK.

Export payroll time by employee

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: Universal Payroll Export > TimeByEmployees.
  2. 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

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

      Connection Settings

      Connection Settings for the Universal Payroll Time by Employee Export integration

      Property

      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

      SFTPServer

      Required

      The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account.

      To change the default SFTP server parameters:

      1. For each field, clear Use Default.
      2. Enter the following values:

        • Enter the name of the internal Host.

        • Enter the number of the Port for the internal SFTP account.

        • In User, enter the username for the internal SFTP account.

        • In Password, select <Encrypted>. Enter the new password for the internal SFTP account.

        • Click Tap Apply.

  4. 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, elect TimeByEmployee_ProcessProperties to set process properties that must be configured before the integration can run.

      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 Universal Payroll Time by Employee Export 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

      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

      ResultFileName

      Not required

      Name of the file to store the generated export data

      1. Clear Use Default.
      2. Enter the file name. Use a .csv extension.

      Example: ExportPayrollData.csv

      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 (#).

      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

      Required

      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 (,).

      Delimiter

      Not required

      Default = comma (,)

      To change the character that separates data values in the flat file:

      1. Clear Use Default.

      2. Enter the character.

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

      UserInput1—6

      Not required

      To require that the payroll administrator enter data for a custom field:

      1. Clear Use Default.
      2. Enter the label for the field.

      _DisableQuotes

      Not required

      To remove double quotation marks from the exported file:

      1. Clear Use Default.
      2. Select Value.

      If the value of any field contains any character that is used as a delimiter, this property converts that character in the data map to another character that is not used in the file. Example: Convert the comma (,) delimiters in a comma-separated values file to a pipe (|) character.

    4. From the Process Property dropdown list, select TimeByEmployee_SFTPProperties.

      SFTP Properties

      SFTP Properties for the Universal Payroll Time by Employee Export integration

      Property

      Required

      Actions

      OutputDirectory

      Not required

      The directory on the SFTP server to archive the output files.

      Default = /Outbound.
      Caution:

      Do not change the name of the folder from Outbound. Additional or differently named folders are not supported by .

      To define a different directory path:

      1. Clear Use Default.
      2. Enter the directory path.

      AppendRecords

      Not required

      To append records to any previous payroll export file:

      1. Clear Use Default.
      2. Select Value.

      _FileNameWithTimestamp

      Not required

      To append a time stamp to the name of the exported

      1. Clear Use Default.
      2. Select Value.
  6. Configure data maps

    (Optional)

    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. Editing of the default map is limited to adding fields, changing mappings, or inserting functions. Any changes override the previous values. If the predefined fields do not suite your requirements, use the default map as a guide when you create your custom data map.

    To customize data transformation:

    1. Select Data Maps.

    2. From the Data Maps dropdown list, select one of the following:

      • TimeByEmployee_PayrollDefinedFields—TimeByEmployee_PayrollOutputFields(default map): Accept the predefined order of fields to export to the destination file. The names match the fields in the data map. If needed, you can edit this map. The _EnableCustomMapping process property must be set to false.

        Example data map


        Map Export Payroll - Payroll Output Fields
      • TimeByEmployee_PayrollDefinedFields—TimeByEmployee_CustomizedOutputFields: Define a custom map with your own fields and ordering to map the data from the source to the destination. You can also define functions to transform mapped data. The _EnableCustomMapping process property must be set to true.

      • TimeByEmployee_PayrollQualifierInput—TimeByEmployee_PayrollQualifierOutput: This map translates paycodes.

        Example data map


        Map Export Payroll QualifierInput—QualifierFieldsProfile

        Example Map Export Payroll: Payroll Qualifier

    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. (Optional)

      Caution: The default mappings are developed and tested based on best practices. If you make changes, you may get unexpected results. Modify and test carefully.
      • Change mappings — When you customize a default data map, you can add fields only to the end of the map.

        You can select and drag to change the links between the source (left column), function (middle column), and destination (right column) items. A single source field can link to multiple destination fields, but a destination field can link to only one source field.

      • Transform the data — A map can include intermediate functions that transform the data. Examples: Perform mathematical calculations on the values or get values from a cross-reference table.
        Note: To override a field — for example because you cannot delete it from a default map — insert a function that has a null output.
        1. In Function, click tap the plus button
          Add map function
          to add an intermediate function.
        2. From Category, select a category of functions:

          String — Trim, add to, concatenate, replace, remove, split, or change the case of text.

          Caution: Do not use special characters such as angle brackets (< or >) in data in cross-reference tables, data maps, and input files. These characters can make the integration fail.

          Numeric — Perform mathematical calculations on the data.

          Date — Change the format or get the current date.

          Lookup — Get data from a cross-reference table (CRT), document cache, SQL query, or define a key-value change.

          Connector — Call a value from a connector to an application or data source.

          Custom Scripting — Transform data by way of Groovy or JavaScript code.

          Properties — Get or set process or document properties.

        3. Select the function from the list in the selected category.
        4. Click Tap OK.
        5. If prompted in Configure Defaults, enter the relevant values. Select a Caching. Click Tap OK.
        6. Select and drag from a source field to an input of the function.
        7. Select and drag from the output of the function to a destination field.
        8. Repeat to add another function.
    5. When you finish, click tap OK.

Export payroll time by paycode

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: Universal Payroll Export > TimeByPaycode.
  2. 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

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

      Connection Settings

      Connection Settings for the Universal Payroll Time by Paycode Export integration

      Property

      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

      SFTPServer

      Required

      The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account.

      To change the default SFTP server parameters:

      1. For each field, clear Use Default.
      2. Enter the following values:

        • Enter the name of the internal Host.

        • Enter the number of the Port for the internal SFTP account.

        • In User, enter the username for the internal SFTP account.

        • In Password, select <Encrypted>. Enter the new password for the internal SFTP account.

        • Click Tap Apply.

  4. 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 TimeByPaycode-v1_CRTConfig to define headers in 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.

      Caution: The Boomi™ application does not return default values for cross-reference table headers. You have to enter the headings in Value.

      For each of the tables:

      1. Clear Use Default.
      2. In Value, enter the header column names, 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.
      3. Repeat for the other tables.

    4. Select TimeByPaycode_ProcessProperties to set process properties that must be configured before the integration can run.

      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 Universal Payroll Time by Paycode Export 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

      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

      ResultFileName

      Not required

      Name of the file to store the generated export data

      1. Clear Use Default.
      2. Enter the file name. Use a .csv extension.

      Example: ExportPayrollData.csv

      Default = payrollTPPaycode.csv.

      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 (#).

      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

      Required

      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 (,).

      Delimiter

      Not required

      Default = comma (,)

      To change the character that separates data values in the flat file:

      1. Clear Use Default.

      2. Enter the character.

      BatchOutputData

      To combine the output data into a batched file:

      1. Clear Use Default.
      2. Select Value.

      BatchingMethod

      Default = Week

      To change the batching method of the exported data:

      1. Clear Use Default.
      2. Select Week, Count, or PrimaryBusinessStructureNode.

      CountToBatchBy

      Default = 25

      To change the number of records to put into each batch:

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

      MultipleOutputFiles

      To write each batch to a separate file:

      1. Clear Use Default.
      2. Select Value.

      BatchHeaderRecord

      To write a batch header record:

      1. Clear Use Default.
      2. Select Value.

      BatchFooterRecord

      To write a batch footer record:

      1. Clear Use Default.
      2. Select Value.

      _FileFooterExists

      This property produces a file footer in addition to batch footers. You cannot select the footer.

      To add a footer record as the last record in the output file:

      1. Clear Use Default.
      2. Select Value.

      _FileHeaderExists

      This property produces a file header in addition to batch headers. You cannot select the header.

      To add a header record as the first record in the output file:

      1. Clear Use Default.
      2. Select Value.

      _DateInFileName

      To add the current date to the name of the output file:

      1. Clear Use Default.
      2. Select Value.

      StartDayOfWeek

      Default = Start day of week is the Start Date of the pay period.

      To change the start day of week:

      1. Clear Use Default.
      2. Enter the name of the day. Example: Monday

      _InputToBatchRoutineNotSortedByDate

      Default = Sort input data by date.

      To not sort by date:

      1. Clear Use Default.
      2. Select Value.

      _InputToBatchRoutineNotSortedByPersonNo

      Default = Sort input data by person number.

      To not sort by person number:

      1. Clear Use Default.
      2. Select Value.

      BatchOnNodeNumber

      Default = 1

      To select another primary job:

      1. Clear Use Default.
      2. Enter the number of the primary job.

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

      UserInput1—6

      Not required

      To require that the payroll administrator enter data for a custom field:

      1. Clear Use Default.
      2. Enter the label for the field.

      _DisableQuotes

      Not required

      To remove double quotation marks from the exported file:

      1. Clear Use Default.
      2. Select Value.

      If the value of any field contains any character that is used as a delimiter, this property converts that character in the data map to another character that is not used in the file. Example: Convert the comma (,) delimiters in a comma-separated values file to a pipe (|) character.

    5. From the Process Property dropdown list, select TimeByPaycode _SFTPProperties.

      SFTP Properties

      SFTP Properties for the Universal Payroll Time by Paycode Export integration

      Property

      Required

      Actions

      OutputDirectory

      Not required

      The directory on the SFTP server to archive the output files.

      Default = /Outbound.
      Caution:

      Do not change the name of the folder from Outbound. Additional or differently named folders are not supported by .

      To define a different directory path:

      1. Clear Use Default.
      2. Enter the directory path.

      AppendRecords

      Not required

      To append records to any previous payroll export file:

      1. Clear Use Default.
      2. Select Value.

      _FileNameWithTimestamp

      Not required

      To append a time stamp to the name of the exported

      1. Clear Use Default.
      2. Select Value.
  6. 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 one of the following:

      You cannot change the names of the tables.

      TimeByPaycode-v1_PaycodesCRT

      This table maps exported paycodes to destination paycodes.

      Column headers:

      KronosPayCode,ThirdPartyPayCode,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

      TimeByPaycode _CRTConfig

      Column headers:

      KronosPaycode,ThirdPartyPaycode,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

    4. Select Override to:

      • Download the tables when you run the integration
      • Edit the table cells in Extensions
    5. Repeat for other tables.
    6. To import mappings from a source file, set _EnableCustomMapping to true.
  8. Configure data maps

    (Optional)

    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. Editing of the default map is limited to adding fields, changing mappings, or inserting functions. Any changes override the previous values. If the predefined fields do not suite your requirements, use the default map as a guide when you create your custom data map.

    To customize data transformation:

    1. Select Data Maps.

    2. From the Data Maps dropdown list, select one of the following:

      • TimeByPaycode_PayrollAllFields—TimeByPaycode_PayrollOutputFields(default map): Accept the predefined order of fields to export to the destination file. The names match the fields in the data map. If needed, you can edit this map. The _EnableCustomMapping process property must be set to false.

        Example data map


        Map Export Payroll - Payroll Output Fields
      • TimeByPaycode_PayrollAllFields—TimeByPaycode_CustomizedOutputFields: Define a custom map with your own fields and ordering to map the data from the source to the destination. You can also define functions to transform mapped data. The _EnableCustomMapping process property must be set to true.

      • TimeByPaycode_QualifierInput—TimeByPaycode_QualifierFieldsProfile: This map translates paycodes.

        Example data map


        Map Export Payroll QualifierInput—QualifierFieldsProfile

        Example Map Export Payroll: Payroll Qualifier

    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. (Optional)

      Caution: The default mappings are developed and tested based on best practices. If you make changes, you may get unexpected results. Modify and test carefully.
      • Change mappings — When you customize a default data map, you can add fields only to the end of the map.

        You can select and drag to change the links between the source (left column), function (middle column), and destination (right column) items. A single source field can link to multiple destination fields, but a destination field can link to only one source field.

      • Transform the data — A map can include intermediate functions that transform the data. Examples: Perform mathematical calculations on the values or get values from a cross-reference table.
        Note: To override a field — for example because you cannot delete it from a default map — insert a function that has a null output.
        1. In Function, click tap the plus button
          Add map function
          to add an intermediate function.
        2. From Category, select a category of functions:

          String — Trim, add to, concatenate, replace, remove, split, or change the case of text.

          Caution: Do not use special characters such as angle brackets (< or >) in data in cross-reference tables, data maps, and input files. These characters can make the integration fail.

          Numeric — Perform mathematical calculations on the data.

          Date — Change the format or get the current date.

          Lookup — Get data from a cross-reference table (CRT), document cache, SQL query, or define a key-value change.

          Connector — Call a value from a connector to an application or data source.

          Custom Scripting — Transform data by way of Groovy or JavaScript code.

          Properties — Get or set process or document properties.

        3. Select the function from the list in the selected category.
        4. Click Tap OK.
        5. If prompted in Configure Defaults, enter the relevant values. Select a Caching. Click Tap OK.
        6. Select and drag from a source field to an input of the function.
        7. Select and drag from the output of the function to a destination field.
        8. Repeat to add another function.
    5. When you finish, click tap OK.

Default files for Payroll Export

Base integration: TimeByPaycode-v1

Default source file = PayrollTPPaycode.csv.

Design of the Payroll Export integration

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


Payroll Export flowchart

Work account transfers

If destination payroll systems need to track the difference between expected and actual work for payment, reports, and aggregate views, transfers need to collect the appropriate set of totals and transactional data that accurately reflect the following:

  • The work that was performed
  • How that work differs from the employees' default or home assignments
  • How that work differs from the employees' primary assignments

The timecard provides the relevant data in the following sets of Totals columns:

  • Totals by paycode
  • Totals for reports and payroll exports

Both sets of Totals columns exclude and do not support historical corrections that were applied during the selected time period. Schedule Totals do not support historical corrections.

This integration exports the following data with the pay totals:

  • Worked accounts only: Export the worked job, labor category, cost center, or a combination.
  • Transfer accounts only: Export the worked job, labor category, or cost center only for job transfers.
  • Combined worked and transfer: Export the worked account, the default account, and the transfer indicator.

This integration exports the following data elements:

  • Job

    • Worked job
    • Primary job

  • Labor Category

    • Worked labor category
    • Primary labor category
    • Default or home labor category

  • Cost Center

    • Worked cost center
    • Home or default cost center for the primary job

Example without transfer

An employee works their primary job without a transfer.

  • Primary labor category = 101, 201, 301
  • Default labor category is derived from the primary job = 101, 201

The exported data is:

  • Primary job
  • Worked job = same as primary
  • Job transfer = false
  • Worked labor category = 101, 201
  • Primary labor category = 101, 201, 301
  • Default labor category = 101, 201
  • Labor category transfer = false

Example with transfer

An employee transfers their job. The labor category changes to match the primary job.

The exported data is:

  • Primary job
  • Worked job = transfer job
  • Job transfer = true
  • Worked labor category = 101, 201, 301
  • Primary labor category = 101, 201, 301
  • Default labor category = 101, 201
  • Labor category transfer = true

If there is a primary cost center, the exported data is:

  • Worked cost center = 101, 201, 301
  • Primary cost center = 101, 201, 301
  • Default or derived cost center = 101, 201
  • Transfer = true

Required data

All of the following data is required for calculation and mapping:

  • Worked Job account
  • Primary Job assignment for the employee
  • Job Transfer indicator
  • Worked Labor Category
  • Primary Labor Category for the employee
  • Default Labor Category that is derived from the Primary Job
  • Labor Category Transfer indicator
  • Worked Cost Center
  • Default Cost Center that is associated with the Primary Job

The default payroll export for job, cost center, and labor category includes the following:

  • Worked Job: full path
  • Primary Job: full path
  • Worked Labor Category 1—6
  • Default Labor Category 1—6
  • Worked Cost Center
  • Default Cost Center

The default payroll export data map includes the following for filtering and calculations:

  • Worked Job: full path
    • Name
    • Description
  • Home Job: full path
    • Name
    • Description
    • Transfer indicator: True or False
  • Worked Labor Category 1—6
    • Worked Labor Category Name
    • Worked Labor Category Description
  • Default Labor Category 1—6
    • Default Labor Category Name
    • Default Labor Category Description
  • Primary Labor Category 1—6
    • Primary Labor Category Name
    • Primary Labor Category Description
    • Transfer indicator: True or False
  • Worked Cost Center
    • Worked Cost Center Name
    • Worked Cost Center Description
  • Default Cost Center
    • Default Cost Center Name
    • Default Cost Center Description

The data is aggregated based on the entire worked data set.

  • Data that is aggregated by paycode includes the employees, paycodes, and totals for each combined data set of Job, Labor Category, and Cost Center. Any deviation creates a new record.
  • If there are multiple transfers in a day, the data is aggregated for the complete Worked Account.

Paycode maps and filters

The required paycode properties for the data map and filtering follow.

Paycode mapping

If paycodes are missing from the data map or cross-reference table, the integration does not export the payroll data. The integration fails but completes so that it can generate an error message that lists all of the paycodes that are missing. The error message aggregates the missing paycodes for all users and not by employee. Example: The payroll manager runs the payroll export for two employees. Both are missing the 101 and 102 paycodes. The list of errors shows the error for paycodes 101 and 102, but not each failure for both employees such as 101, 102, 101, 102.

Paycode filtering

You can include or exclude paycodes as follows:

  • Filter from the data map (primary method): In the paycode mapping table, select whether to include (true) or exclude (false) each paycode.
  • Filter from a process property: Select whether to include (true) or exclude (false) paycodes. Process property settings override paycode mappings. Example: Payroll managers run specific exports such as for bonuses.