Configure the Universal Punches 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 punch data from 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.

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.

Select environment extensions

How to select the environment extensions for the Universal Punches Import integration.
  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 Punch Import > PunchImport.

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 Punches Import integration

    Setting

    Required

    Actions

    APIGatewayServer

    Required

    To change the default API gateway server:

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

      Example: <tenantURL>/api

    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.

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. Edit the properties:
    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.
      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 PunchImport-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.
    Note: For details, see Configure cross-reference tables.

    In _PunchImport-v1_PunchImportTimezoneLookup:

    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.
  4. From the Process Property dropdown list, select PunchImport_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 Punches Import integration

    PropertyRequiredActions
    EnableTransactionAssistant Not required

    Default = true

    To not submit import errors to Transaction Assistant:

    1. Clear Use Default.
    2. Select Value.
    BatchName Not required

    Default =

    PunchImport

    To change the value:

    1. Clear Use Default.
    2. Select Value.
    3. Enter the batch name to group the failed records in Transaction Assistant.

    RunSinglePunch

    Caution: Enable only one of RunSinglePunch, RunDualPunch, or RunDualPunchPCE.
    		Not required

    To import punches from the SinglePunch file:

    1. Clear Use Default.
    2. Select Value.

    RunDualPunch

    Caution: Enable only one of RunSinglePunch, RunDualPunch, or RunDualPunchPCE.
    		Not required

    To import punches from the DualPunch file:

    1. Clear Use Default.
    2. Select Value.

    RunDualPunchPCE

    Caution: Enable only one of RunSinglePunch, RunDualPunch, or RunDualPunchPCE.
    		Not required

    To import punches and paycode edits from the DualPunchPCE file:

    1. Clear Use Default.
    2. Select Value.
    CustomTransferProcessing Not required

    Assume that the full path of the organizational transfer is in the Account column of the input file.

    To form the organizational transfer path appending the Home Job to the path in the Account column of the file:

    1. Clear Use Default.
    2. Select Value.
    UpdateExistingPunches Not required

    Default = true

    • If true, the integration imports and replaces only updated punches from the input file.
    • If false, the integration deletes all existing punches and imports the punches from the input file.
  5. From the Process Property dropdown list, select PunchImport_SFTPProperties.

    Select:

    SFTP Properties

    SFTP Properties for the Universal Punches Import integration

    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.
    SinglePunchFileFilter Not required

    Read the file of single punches.

    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.

    Default = SinglePunch.csv.

    RunSinglePunch must be set to true.

    DualPunchFileFilter Not required

    Read the file of dual punches.

    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.

    Default = DualPunch.csv.

    RunDualPunch must be set to true.

    DualPunchPCEFileFilter Not required

    Read the file of dual punches and paycode edits.

    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.

    Default = PCEMix.csv.

    RunDualPunchPCE must be set to true.

    _OutputDirectory Not required

    Directory on the SFTP server where the destination file is archived after processing.

    Default = use the default /Outbound directory.
    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 path to the directory.
      Caution: Make sure that this directory is configured on the SFTP server.
    _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.
    _DeleteSourceFileAfterReading 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.

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

    You cannot change the name of the table.

    Column headers:

    Name,Id

  4. Select Override to:

    • Download the tables when you run the integration
    • Edit the table cells in Extensions

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.

Known issues

  • The timecard collects punches from schedules which interfere with punch imports. Before importing punches, delete the schedules for the targeted employees and time periods.
  • The timecard does not import break rule overrides, and these overrides break the timecard.
  • Bad paycode IDs incorrectly trigger a system error rather than an API error.
  • You cannot delete the first punch of a pair because it becomes a purple in-punch. Comments that are attached to these punches are not imported.
  • A duplicate punch error incorrectly triggers a "duplicate comments not allowed” error.
Caution: The time format of imported punches must not include a colon or any other special character. The acceptable time format is military style. Examples: 0700, 1010, 1900, 2130.
  1. Select Data Maps.

  2. From the Data Maps dropdown list, select one of the following:
  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 Punches Import

Base integration: PunchImport-v1

Default source files:

  • SinglePunch.csv= Single punches.
  • SinglePunch_crossdaydivide.csv= Single punches that cross the day divide.
  • SinglePunch_jobtransfer.csv= Single punches for transfer jobs.
  • DualPunch.csv= Dual punches.
  • PCEMix.csv= Dual punches and paycode edits.

Design of the Universal Punches Import integration

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

Punch integrations must ensure that incoming punches are displayed and interpreted correctly in the timecard as In, Out, Type, or Missing. The pay rules and schedules that are assigned to the employees distribute the durations to the right accounts and paycodes.

  • All imports are bulk because the source file lists many employees each with multiple punches.
  • Maximum of 500 employees and 5000 paycode edits for each integration run.

This integration pack contains the following integrations:

  • Punches only:
    • Punch with employee ID, punch date and time
    • Punch with override type
    • Punch with the override type derived from the relationship of the punch to other punches or the day divide
    • Punch with the override type derived from the account transfer of the punch
    • Punches that are on the same row of the source file and that must be transformed into one row for each punch
  • Punches with paycode edits:
    • Non-canceling paycode edits
    • Labor account transfers
    • Work rule transfers
    • Comments and notes
    • Time zone, daylight savings
    • Update existing punches with new attributes
  • Filter out duplicate punches

Approaches to punch imports

  • Hands Off

    Only the source file provides the punches. Upon import, the timecard sequences the punches based on date and time. However, interpretation and display of the punches is based on the pay rule and schedule.

    If a punch is missing, the interpretation can be incorrect.

    Example:

    This set of punches are interpreted as In Out In Out:

    21003, 5/3/2016, 0700

    21003, 5/3/2016, 1800,3100

    21003, 5/3/2016, 1900

    21003, 5/3/2016, 2100

    A Missed Out Limit Rule of 10 Hours results in the following interpretation:

    Example hands-off punches

    Example hands-off import punch totals

    Date

    In

    Out

    Tues 5/03

    7:00 am

    missing

    Tues 5/03

    6:00 pm

    7:00 pm

    Tues 5/03

    9:00 pm

    missing

    A manager must manually override this interpretation if it is incorrect.

  • Override

    Assign each punch a Type, or derive the Type from the punch sequence within each pair of punches or by the punch's relationship to the day divide or whether the punch carries an account transfer.

    Punch override types

    • Break
    • In punch
    • New shift
    • Out punch

    The following punches:

    21003, 5/3/2016, 0700, In

    21003, 5/3/2016, 1800, Out

    21003, 5/3/2016, 1900, In

    21003, 5/3/2016, 2100, Out

    Are interpreted as follows:

    Example punch overrides

    Example punch override totals

    Date

    In

    Out

    Tues 5/03

    7:00 am

    6:00 pm

    Tues 5/03

    7:00 pm

    9:00 pm

Updates

When punches from the source file are already in the timecard, perhaps from a previous import, from a data collection system, or manually added, the API generates errors for the duplicate punch records.

Updates of existing punches may be needed if the new versions have an added account transfer, comment, or other attribute.

To suppress the errors, integrations can identify and delete the duplicate punches from the timecard then import them again from source, or exclude the duplicate punches in the source file. First, the integration must retrieve, cache, and look up the existing punches.

Validation

Punch imports are validated to make sure that:

  • The employee is configured.
  • The punch contains both a date and a time.
  • The date of the punch is on or after the employee's current active status date.
  • Attributes of the punch, such as a business structure account transfer, a work rule transfer, a comment, or a time zone, are in the relevant data dictionaries.