Configure the Universal Accruals Import 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 imports all accrual records for a set of employees from a flat file and contains the following integration processes:

  • Accruals Balances Earned, Payout, and Reset
  • Accruals Move Between Bins

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

As needed, deploy the following integration packs:

Accruals Balances Earned, Payout, and Reset

The integration contains the following integration processes:

  • Accrual Earned Import: Import accruals balances.
  • Accrual Payout Import: Import accruals paid-out balances.
  • Accrual Reset Import: Import accruals balances to update existing records.

Expected input

Expected fields

Expected format

Accrual code name

—

Accrual amount

Integer or Float

Dates

YYYY-MM-DD or MM/DD/YYYY

Hours

HH.hh or HH:mm

Currency

—

Configure the integration

Select the environment

    1. Open the Integration Template Designer: Select Main Menu Administration > Application Setup > Integrations Setup > Design Integration Templates.

      Note: If prompted, enter your Username and Password. Click Tap Log in.
    2. Select the Manage tab > Atom Management.
    3. Select your environment.
  2. 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: Accrual Import and the AccrualEarnedImport, AccrualPayoutImport, or AccrualResetImport process.
  4. 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

      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

      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.

  6. 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. AuthenticationProperties define properties to connect to the authentication server and get the access token to execute APIs. Leave all of these values at their default settings.

    3. From the Process Property dropdown list, select _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

      Property

      Required

      Actions

      SourceDirectory

      Required

      The directory path on the SFTP server where the integration process reads the file.

      Default = Use the /Inbound directory.
      Caution:

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

      To define a different directory path:

      1. Clear Use Default.
      2. Enter the path to the directory.
        Caution: Make sure that this directory is configured on the SFTP server.

      Expected value =

      SourceFileName

      Not required

      The name of the file that contains the data to import.

      Default = true, use the default file name.

      To define a different file name:

      1. Clear Use Default.

      2. Enter the filename. Use a .csv extension.

        You can use the asterisk (*) or question mark (?) as wildcard characters to enter patterns of file names so that the integration reads only files that have names that match this filter.

      Example: AccrualImportData_MMDDYYYY.csv

      Default files = EarnedAccrualImportData.csv, AccrualPayoutImportData.csv, or AccrualImportData.csv.

      EnableTransactionAssistant

      Not required

      Default = true

      To not submit import errors to Transaction Assistant:

      1. Clear Use Default.
      2. Select Value.

      _MoveProcessedFileToDirectory

      Not required

      The directory on the SFTP server to move the destination file after data is successfully uploaded.

      Default = true, use the default directory.

      To define a different directory path:

      1. Clear Use Default.
      2. Enter the path to the directory.
        Caution: Make sure that this directory is configured on the SFTP server.

      _DeleteFileAfterReading

      Not required

      Default = false, delete the source file after processing.

      Default = false; do not delete the source file after processing.

      To delete the source file but archive it to _DestinationDirectoryPath:

      1. Clear Use Default.
      2. Select Value.

      _IsCustomInput

      Not required

      The standard payload is the default ordering or sequence of the fields that is defined in the PredefinedInputProfile - PredefinedInputProfile data map.

      To use a custom formatted input payload in which the field names and ordering are defined in the CustomProfile - PredefinedInputProfile data map:

      1. Clear Use Default.
      2. In Value, select True.
    4. From the Process Property dropdown list, select CallbackProcessProperty to define properties for the run summary and Transaction Assistant.
      1. To change the batchName label in the run summary and Transaction Assistant:
      2. Clear Use Default.
      3. In Value, enter the label. Example: AccrualImport.
    5. From the Process Property dropdown list, select {ProcessName}_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.
  8. 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 to map imported accrual codes to destination accrual codes:

      • AccrualEarnedLookupTable

        Column headers:

        ThirdPartyAccrualCode,TimeKeeperAccrualCode,Column3,Column4, Column5,Column6
      • AccrualPayoutLookupTable

        Column headers:

        ThirdPartyAccrualCode,TimeKeeperAccrualCode,Column3,Column4, Column5,Column6
      • AccrualResetLookupTable

        Column headers:

        ThirdPartyAccrualCode,TimeKeeperAccrualCode,Column3,Column4, Column5,Column6

    4. Select Override to:

      • Download the tables when you run the integration
      • Edit the table cells in Extensions
    5. Repeat for other tables.
  10. 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:

      • Default map: PredefinedAccrualEarnedImport - PredefinedAccrualEarnedImport or PredefinedInputProfile - PredefinedInputProfile

        Accept a predefined order of fields from the source file. The names match the fields in the data map. The _IsCustomInput process property must be set to false.

        The paycode mapping can be used from the configured data map.

        Default data map

        Source Element

        Function Default

        Function Input

        Function Output

        Default Value

        Destination Element

        Record/Elements/AccrualAmount

        —

        —

        —

        —

        Record/Elements/AccrualAmount

        Record/Elements/AccrualCodeName

        —

        —

        —

        —

        Record/Elements/AccrualCodeName

        Record/Elements/EffectiveDate

        —

        —

        —

        —

        Record/Elements/EffectiveDate

        Record/Elements/ManagerRole

        —

        —

        —

        True

        Record/Elements/ManagerRole

        Record/Elements/PersonNumber

        —

        —

        —

        —

        Record/Elements/PersonNumber

        Record/Elements/ProbationAmount

        —

        —

        —

        —

        Record/Elements/ProbationAmount

        Record/Elements/AccrualUnits

        —

        Cross Reference Lookup[1]/AccrualUnits

        Cross Reference Lookup[1]/AccrualUnits

        —

        Record/Elements/AccrualUnits

        Example data map


        Data Map Predefined Input Profile

      • Custom map: CustomProfile - PredefinedAccrualEarnedImport or CustomProfile - PredefinedInputProfile

        Define a custom map with your own fields and ordering to map the data from the source to the destination. The _IsCustomInput process property must be set to true.

    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.

Accruals Move Between Bins

This integration moves accrual balances between an employee’s accrual buckets.

  • Trigger an earning in one accrual code based on the balance in another accrual code. Adjust the balance in the trigger code so that the earning can occur again later.
  • Transfer time from one accrual code to another when requested by an employee. Example: Move the unused accruals from Sick to Vacation at the end of the year.
  • Typically done yearly. Example: Account for unused vacation at the start of a new year.
  • Can be used to process rehired employees.
  • Creates an input.csv file.
  • Cannot accept zero or negative amounts.

Expected input

Expected input for the Universal Accruals Move to Bin Import integration

Expected fields

Expected format

Accrual code name

—

Accrual amount

Integer or Float

Dates

YYYY-MM-DD or MM/DD/YYYY

Hours

HH.hh or HH:mm

Currency

—

Configure the integration

Select the environment

    1. Open the Integration Template Designer: Select Main Menu Administration > Application Setup > Integrations Setup > Design Integration Templates.

      Note: If prompted, enter your Username and Password. Click Tap Log in.
    2. Select the Manage tab > Atom Management.
    3. Select your environment.
  2. 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: Base-Accrual Import and the AccrualMoveToBinImport process.
  4. 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 Accruals Move to Bin Import 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.

  6. 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. AuthenticationProperties define properties to connect to the authentication server and get the access token to execute APIs. Leave all of these values at their default settings.

    3. From the Process Property dropdown list, select AccrualMoveBetweenBins_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 Accruals Move to Bin Import integration

      Property

      Required

      Actions

      SourceDirectory

      Not required

      The directory path on the SFTP server where the integration process reads the file.

      Default = Use the /Inbound directory.
      Caution:

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

      To define a different directory path:

      1. Clear Use Default.
      2. Enter the path to the directory.
        Caution: Make sure that this directory is configured on the SFTP server.

      SourceFileName

      Not required

      The name of the file that contains the data to import.

      Default = true, use the default file name.

      To define a different file name:

      1. Clear Use Default.

      2. Enter the filename. Use a .csv extension.

        You can use the asterisk (*) or question mark (?) as wildcard characters to enter patterns of file names so that the integration reads only files that have names that match this filter.

      Example: AccrualImportData_MMDDYYYY.csv

      Default = AccrualMoveBalanceData.csv.

      _DeleteFileAfterReading

      Not required

      Default = false; do not delete the source file after processing.

      To delete the source file but archive it to _DestinationDirectoryPath:

      1. Clear Use Default.
      2. Select Value.

      _ResponseLogDirectory

      Not required

      Enter the path to the directory to write response logs.

      _IsCustomInput

      Not required

      The standard payload is the default ordering or sequence of the fields that is defined in the PredefinedInputProfile - PredefinedInputProfile data map.

      To use a custom formatted input payload in which the field names and ordering are defined in the CustomProfile - PredefinedInputProfile data map:

      1. Clear Use Default.
      2. In Value, select True.

      _SpecialMappingRequired

      Not required

      To map the accrual codes from the input file to the accrual codes:

      • Clear Use Default.

      • In Value, select true.

    4. From the Process Property dropdown list, select AccrualMoveToBinImport-vx_AccrualCodeMapping to define headers in cross-reference tables.
      Caution: The Boomi™ application does not return default values for cross-reference table headers. You have to enter the headings in Value.
      1. Clear Use Default.

      2. In Value, enter the following headers, separated by commas ( ,) but no spaces, as follows:

        Tip: Tip: The column headers are shown below the Value field. Rather than type the headers, you can select and copy the headers, then paste them in the Value field.
        ThirdPartyAccrualCode,TimeKeeperAccrualCode,Column3,Column4, Column5,Column6
  8. Select cross-reference tables

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

    • Organizes data values into rows and columns:
      • Maximums = 20 columns, 10,000 rows.
    • Can combine values from multiple columns to determine a single output value.
    • If more than one row matches a reference value, the first match is the output value.
    • If no match is found, the output value can be null, or the integration can produce errors.
    1. Caution: For the cross-reference tables that you are customizing, make sure that Use Default is not selected in Process Properties > {ProcessName}_CRTConfig, and that the headers are defined.
    2. Select Cross Reference.
    3. From the Cross Reference dropdown list, select AccrualCodeMapping to map input accrual codes to accrual codes.

    4. Select Override to:

      • Download the tables when you run the integration
      • Edit the table cells in Extensions
    5. To import mappings from a source file, set _SpecialMappingRequired to true.
  10. Configure data maps

    (Optional)

    To customize data transformation, select the data map extension.

    1. Select Data Maps.

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

      • Default map: ReformatInputData - ReformatedInputData

        Accept a predefined order of fields from the source file. The names match the fields in the data map. The _IsCustomInput process property must be set to false.

        The paycode mapping can be used from the configured data map.

      • Custom map: CustomProfile - ReformatedInputData

        Define a custom map with your own fields and ordering to map the data from the source to the destination. The _IsCustomInput process property must be set to true.

    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 Accruals Import

Base integration: AccrualEarnedImport-v1

Default source file = EarnedAccrualImportData.csv.

Base integration: AccrualPayoutImport-v1

Default source file = AccrualPayoutImportData.csv.

Base integration: AccrualResetImport-v1

Default source file = AccrualImportData.csv

Base integration: AccrualMoveToBinImport-v1

Default source file = AccrualMoveBalanceData.csv.

Design of the Universal Accruals Import integration

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


Import Accruals Data Flow

Process

  • Use a cross-reference table to select accrual codes and calculate amounts in time or currency.
  • Multiply, add, or round the amounts by way of data maps.
  • Calculate accrual amount balances based on corresponding leave totals that are recorded in employee records.

Format

  • Import the data from a flat, fixed-length file.
  • Provide accrual codes with effective dates. If the effective date is not defined, the system selects the current date. Alternatively, derive the Current Pay Period from the database as the effective date of the accruals.
  • Provide accrual codes with effective dates for the source system.
  • Provide a cross-reference table to map accrual codes between the systems.
  • Use accrual codes to import accruals.

Put employee accrual balances by paycode as paycode edits in the time card on the termination date.

Import base hours rather than minimum-qualified hours as paycode edits to hide accrual earnings paycodes as of the effective date of the accrual.

File format

Define the required file format for each field in the source.

Example Accruals Balance Earned:

  • Person #
  • Accrual Code Name
  • Accrual Amount
  • Effective Date
  • Manager Role

Example EarnedAccrualInputData.csv

Example earned accrual input file

Person Number

Accrual Code Name

Accrual Amount

Effective Date

20005

Personal Day

1

11/01/2017

Example AccrualsReset.csv

Example accruals reset file

Person Number

Accrual Code Name

Accrual Amount

Probation Amount

Effective Date

20005

Sick Hours

1

—

12/01/2017