Configure the Virtual Roster Employee Job History Export Integration

How to configure connection settings and process properties for this integration.

This topic describes how to configure this integration.

HCM Dimensions is the system of record for job history data.

This integration exports employees' past, present, and future job assignments to a flat file for import by Virtual Roster. Primary jobs are exported automatically, and you can include jobs in employees' job transfer sets.

Use a hyperfind query to select the employees whose records are exported.

Typically, you run this integration once a day.

Before you start

Virtual Roster Employee Job History Export integration

Before you run this integration, you must do the following:

  1. Map the organization chart in Virtual Roster to the business structure in Workforce Dimensions.
  2. Map the leave types in Virtual Roster to the paycodes in Workforce Dimensions.
  3. Get the URL for the APIGatewayServer and the URL, User, and Password for the VRServer.
  4. Assign the Virtual Roster license to the people whose records are to be exported.
  5. Configure the hyperfind query for Virtual Roster; see the Hyperfind Queries topic.
  6. Deploy the JobHistoryExport integration pack; see Deploy Integration Packs to your Atom.

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 People Export > JobHistoryExport-v1.

Configure connection settings

Virtual Roster Employee Job History 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 Employee Job History Export integratio

    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 Employee Job History Export integration

  1. Select 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. Select JobHistoryExport-v1_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 Employee Job History Export integration

    Property

    Required

    Actions

    HyperfindID

    Not required

    Use a hyperfind query to filter and select employees whose records are exported to Virtual Roster.

    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.

    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.

    PastTerminationDays

    Not required

    This integration exports job history for all currently active employees and employees who were terminated recently, today, or are set to be terminated in the future. This property controls the number of days in the past to look for terminated employees.

    Default = 7 days; export records for employees who were terminated up to 7 days ago, today, and will be terminated in the future.

    To change the number of days:

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

    PastJobHistoryDays

    Not required

    When LimitJobHistory is set to true, this property sets the number of days in the past to look for primary job and job transfer set assignments to export.

    Default = 30 days; export all primary job and job transfer set assignments that have an Expiry Date that is 30 days or less in the past, along with current and future-dated assignments.

    To change the number of days:

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

    LimitJobHistory

    Not required

    This property sets whether to limit the export of the job history to go back only as far as the PastJobHistoryDays setting.

    Default = false; export all past, current, and future-dated primary job and job transfer set assignments.

    Typically, the default setting is needed for the initial run of this integration. For subsequent runs, limit the number of days to only the number in the PastJobHistoryDays setting:

    1. Clear Use Default.
    2. Select true.

    IncludeJTSJobs

    Not required

    The property sets whether to include jobs from job transfer sets (JTS) in the export.

    Default = false, export only primary jobs.

    To export primary and transfer jobs:

    1. Clear Use Default.
    2. Select true.
  3. From the Process Property dropdown list, select JobHistoryExport_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 Employee Job History 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: JobHistoryExport_YYYYMMddHHmmss.csv

    Action

    Not required
    1. Clear Use Default.
    2. Select one of the following:
      • Overwrite(default)
      • Append
      • Create New Name
      • Error
  4. When you finish, click tap OK.

Output file from the Virtual Roster Employee Job History Export integration

Virtual Roster Employee Job History Export integration

  • File Name: JobHistoryExport_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 Employee Job History Export integration

Field

Data type

Comments or examples

Person Number

String

  • Maximum length: 15 characters

—

EIN

String

For tax purposes

  • Not required
  • For future use

Contract#

String

For tax purposes

  • Not required
  • For future use

First Name

String

—

Last Name

String

—

Middle Initial

String

—

Short Name

String

The employee's preferred name

Phonetic Full Name

String

(Optional)

Romanized Full Name

String

(Optional) The full name of the employee translated into the Latin alphabet

Job

String

The full path in the business structure to and including the job

Effective Date

Date

  • Format: YYYY-MM-DD

The first date when the employee worked this job:

  • For primary jobs, the Effective Dates of the primary job assignments are used.
  • For transfer jobs, the Effective Dates of the employees' job transfer set assignments are used.
  • If a transfer job has an Effective Date that is later than the assignment date to the job transfer set, the Effective Date of the transfer job is used.
  • If the Effective Date is the Beginning of time, the output is blank.

Expiry Date

Date

  • Format: YYYY-MM-DD

The last date when the employee worked this job:

  • For primary jobs, the Expiration Dates of the primary job assignments are used.
  • For transfer jobs, the Expiration Dates of the employees' job transfer set assignments are used.
  • If a transfer job has an Expiration Date that is earlier than the assignment date to the job transfer set, the Expiration Date of the transfer job is used.
  • If the Effective Date is the End of time, the output is blank.

Date Terminated

Date

  • Format: YYYY-MM-DD

The first date when the employee stopped working this job:

  • Includes past, current, and future-dated terminations; the PastTerminationDays process property defines the number of days in the past to export records for terminated employees.
  • If the employee is current and assigned to this job, the output is blank.

Date Hired

Date

  • Format: YYYY-MM-DD

The first date when the employee worked for this company.

Date Re-Hired

Date

  • Format: YYYY-MM-DD

Only if the employee was rehired, otherwise the output is blank.

  • Not required
  • For future use

Source

String

  • Maximum length: 1 character

Tracks whether the worked job was the primary or a transfer job

  • If Primary Job= P.
  • If Job Transfer Set= T.

Is Home Job / Is HD

String

  • Maximum length: 1 character
  • If Primary Job= Y.
  • If Job Transfer Set and the path to the parent node is the same as for the Primary Job for the same date range = Y.
  • If Job Transfer Set but the parent path is different from the Primary Job= N.

APIs

Virtual Roster Employee Job History Export integration

API details

APIs for the Virtual Roster Employee Job History Export integration

API name

API section

Type

Resource path

Location

Execute Hyperfind Query

commons/hyperfind/hyperfind queries

POST

/v1/commons/hyperfind/execute

_Execute - Hyperfind

Retrieve Locations

commons/business structures/locations

POST

/v1/commons/locations/multi_read

_Jobs Details Cache

_Retrieve JTS Data

Retrieve Persons

people/persons

POST

/v1/commons/persons/extensions/multi_read

_Retrieve Job History Data

_Primary Job for JTS Eff Date

Retrieve Location Sets by List

commons/business structures/location sets

POST

/v1/commons/location_sets/multi_read

_Retrieve JTS Data