Configure the Virtual Roster Employee Job History Export 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 A search engine that filters and selects groups of employees through queries that specify conditions or locations (criteria). query to select the employees whose records are exported.

Typically, you run this integration once a day.

Before you start

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 A category of time or money that employees earn, for example, Regular Hours, Bonus, or Sick. 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 Integrations.

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.

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

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

  1. Select Connection Settings.

  2. From the Connection dropdown list, select and configure the following:

    Connection Settings
    Setting Required Actions
    APIGatewayServer Required

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

  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.

    Process Properties
    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 A query that returns a list of employees associated with a manager's employee group. All Home finds people who are active employees or active users as of today. 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 Jobs that an employee can perform but that are not the employee's primary job.:

    1. Clear Use Default. 
    2. Select true.

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

    SFTP Properties
    Property Required Actions
    OutputDirectory Not required

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

    Default = /Outbound.

    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

  • File Name: JobHistoryExport_yyyyMMddHHmmss.csv
  • Format: Comma delimited
  • Frequency: On-demand or scheduled
  • Header Row: Yes, 1 row
  • Output Folder: /Outbound
Output file
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

API details
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