Configure the Virtual Roster Timecard Export Integration

How to configure connection settings, process properties, and cross-reference tables for this integration.

This topic describes how to configure this integration.

Dimensions is the system of record for timecard totals.

This integration exports all timecard totals — including punches, paid time off , unpaid breaks, and timecard edits such as role transfers — to a flat file for import by Virtual Roster. Virtual Roster uses this information for reports and to generate workload.

Use a hyperfind query to select the employees whose records are exported for the previous and current pay periods.

It exports all timecard records to different files for the following pay periods:

  • Previous Pay Period
  • Current Pay Period

You can disqualify paycodes by excluding them from the Paycodes cross-reference table, and the integration supports custom sorting to group records by person and then order by ascending start date and time.

Configure the integration

How to configure this integration

Select the environment

Select the environment for this integration

  1. Open the Integration Template Designer: Select Main Menu > Administration > Application Setup > Integrations Setup > Design Integration Templates.
    Note: If prompted, enter your Username and Password. Click Log in.
  2. Select the Manage tab, then select Atom Management.
  3. Select your environment.

Select environment extensions

Select environment extensions for this integration

  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass . It can take several seconds before the button becomes active.

    Search button
  3. Scroll to and select the integration pack: Virtual Roster Timecard Export > TimecardExport.

Configure connection settings

Virtual Roster Timecard Export integration

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 the following:

    Connection Settings

    Connection Settings for the Virtual Roster Timecard Export 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

Virtual Roster Timecard Export integration

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. Process Properties:
    Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.
  2. From the Process Property dropdown list, select TimecardExport_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.

    For TimecardExport_Paycodes:

    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 TimecardExport_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 Virtual Roster Timecard Export integration

    Property

    Required

    Actions

    HyperfindID

    Not required

    Default = 1 (shown as blank) which indicates All Home and includes all active employees.

    To select another Hyperfind query:

    1. Clear Use Default.
    2. (Required) Enter the ID of a single Hyperfind.
      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 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.

    StartDate

    Not required

    The start date of the pay period:

    1. Clear Use Default.
    2. Enter the date as the symbolic period (preferred), symbolic period span, or date in YYYY-MM-DD format.

    EndDate

    Not required

    The end date of the pay period:

    1. Clear Use Default.
    2. Enter the date as the symbolic period (preferred), symbolic period span, or date in YYYY-MM-DD format.

    CacheBusinessStructure

    Required

    The Caching Business Structure is required so that the output file can contain the Job and the parent path in the business structure.

    Default = true; do not change this value.

    SymbolicPeriod

    Preferred

    Symbolic name for the pay period or date range:

    1. Clear Use Default.
    2. Enter one of the following symbolic values for the pay period:
      • 1 (Default) = Current Pay Period
      • 0 = Previous Pay Period

    SymbolicPeriodSpan

    Not required
    1. Clear Use Default.
    2. Enter the symbolic period span.

    BusinessStructureRootName

    Required if CacheBusinessStructure is true

    If CacheBusinessStructure is enabled, you must specify the root node in the business structure.

    Note: The locations request for Virtual Roster is updated to a LocationId of —1, so the name of the root node is no longer required.

    (Optional) To define the name of the root node:

    1. Clear Use Default.
    2. Enter the name of the root node.

    CacheEmployeeData

    Required

    No employee data is required in the output file.

    Default = false; do not change this value.

    AllEmployeeHyperfindName

    Required

    Define the name of the hyperfind that contains all employees:

    1. Clear Use Default.
    2. Enter the name of the hyperfind.
      Caution: Do not enter All Home.
  4. From the Process Property dropdown list, select TimecardExport_SFTPProperties.
    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.

    SFTP Properties

    SFTP Properties for the Virtual Roster Timecard 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.

    File Name

    Not required
    1. Clear Use Default.
    2. Enter a static prefix for the filename; the integration adds a timestamp to the end.

      Example: TimecardExport_YYYYMMddHHmmss.csv

    Action

    Not required
    1. Clear Use Default.
    2. Select one of the following:
      • Overwrite(default)
      • Append
      • Create New Name
      • Error

Configure cross-reference tables

Virtual Roster Timecard Export integration

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 TimecardExport_Paycodes. Dimensions Paycode Name,Virtual Roster Leave Type Name

    This table maps paycodes between source and destination.

    You cannot change the name of the table.

    Column headers:

  4. Select Override to:
    • Download the tables when you run the integration
    • Edit the table cells in Extensions
  5. To disqualify and not export records for specific paycodes, do not add those paycodes to the cross-reference table. No other configuration is required. The disqualified records are logged by paycode in Run Summary > Additional Details.
  6. When you finish, click tap OK.

Output file from the Virtual Roster Timecard Export integration

Virtual Roster Timecard Export integration

  • File Name: TotalsExport_yyyyMMddHHmmss.csv
  • Format: Comma delimited
  • Frequency: On-demand or scheduled
  • Header Row: Yes, 1 row
  • Output Folder: /Outbound

Output file

Output file for the Virtual Roster Timecard Export integration

Field

Data type

Comments or examples

Person Number

String

  • Maximum length: 15 characters

—

Start(In Punch)

Date-Time

  • Format: YYYY-MM-DD hh:mm

Date and time of one of the following:

  • In Punch
  • Paycode Edit when the paycode start time is not defined and the value is 00:00(default)

End(Out Punch)

Date-Time

  • Format: YYYY-MM-DD hh:mm

Date and time of one of the following

  • Out Punch
  • Paycode Edit if End= Start with empty output

Pay Code / Leave Type Code

String

Mapped by Paycode cross-reference table

Time Off Hours(Hours Worked)

Decimal

—

Job Parent Path

String

Business-structure path to the job but excluding the job

Job

String

—

APIs

Virtual Roster Timecard Export integration

API details

APIs for the Virtual Roster Timecard Export integration

API name

API section

Type

Resource path

Location

Timecard Multi-Read API (For Punches)

Timekeeping

POST

v1/timekeeping/timecard/multi_read

—

Timecard Metrics Multi-Read API (For Pay Codes)

Timekeeping

POST

/v1/timekeeping/timecard_metrics/multi_read

—

Get Business Structure

commons/Timekeeping

POST

/v1/commons/locations/multi_read

_Retrieve Business Structure

Get Hyperfinds

commons/hyperfinds

GET

/v1/commons/hyperfind/public

_Retrieve Hyperfinds

Execute Hyperfind

commons/hyperfind

POST

v1/commons/hyperfind/execute

_Execute - Hyperfind

Data — Multi Read

commons/data

POST

/v1/commons/data/multi_read

_Data Multi-Read for PP Ranges

Retrieve Emp Extensions

commons/persons

POST

/v1/commons/persons/extensions/multi_read

_Retrieve Person Extensions

Retrieve Span Start Data

commons/data

POST

/v1/commons/data/multi_read

_Retrieve Span Start Data