Install Virtual Roster Integrations

How to configure parameters and install Virtual Roster integrations to make them available for running and scheduling.

After the integrations are deployed and the connection settings and process properties are configured, install the integrations to make them available for running or scheduling.

Note:

An integration template is the configured integration that you deploy to an Atom and then install to make available for running or scheduling.
An installed integration is a single instance of an integration that is based on an integration template. When you install an integration, you can define parameters or set parameters to be defined when the integration is run.

Select Main Menu Administration > Application Setup > Integrations Setup > Install Integrations.

Install the HCM Demographics Export integration

Virtual Roster HCM Demographics Export integration

Click Tap Create .
Enter an appropriate, unique, and descriptive Integration Name.
(Optional) Enter a Description.
Do not select API Integration.
Complete the SFTP settings:
- In File Access, select one of the following:
  None: Do not select a Connection.
  File Upload:
  Caution: Import integrations accept only UTF-8 encoded input files.
  
  Source/Output Download
- In Connection, click tap Internal SFTP.
(Optional) To allow the integration access to all APIs in the FAP, and the relevant permissions and data even if the person who runs the integration doesn't have full access, select Execute Integration with System Account.
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
(Optional) Email Notifications
1. Select Yes to send email and control center notifications for integration runs.
2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces: In Progress — The integration run started and has not finished.
  
  Completed — The integration ran successfully without errors.
  
  Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
  
  Completed with Errors — The integration run has errors or could not run.
(Optional, not available for API-based integrations) Select Enhanced Payroll Monitoring to identify whether this integration is part of a payroll process. This setting allows to monitor the integration and sub-processes and help to troubleshoot payroll processes if the integration has errors or fails.
Scheduling Configuration
(Optional)

(Only for file-based integrations) For integrations that will be scheduled to run frequently, configure the behavior if integrations overlap in time. These settings allow frequent integration runs that avoid redundant processing of data and avoid multiple integrations processing the same data.
- In Skip Configuration, select one of the following:
  None (default): Allow multiple integrations to run at the same time or with the same data without restrictions.
  Installed Instance (Recommended): Do not run a scheduled integration if another instance of the same installed integration is in-progress. Only once such integrations finish, this integration can run at the next scheduled time.
  Integration Template: Do not run a scheduled integration if any installed instance of the same integration template is in-progress. Only once such integrations finish, can this integration run at the next scheduled time.
- Only if Installed Instance or Integration Template is selected, select Allow Minute Interval to allow the person who schedules the integration to select the By Minute recurrence to repeat the integration run every 5, 10, 15, 20, 25, or 30 minutes.
Integration template and parameters
1. In Integration Template, select HCMDemographicsExport.
2. Click Tap Assign .
3. (Optional) In Integration Parameters, you can override default settings:
  1. Click Tap Create .
  2. (Required) Specify the parameter to select the hyperfind query of employees:
    HyperfindID
    Parameter Name: (Required) Enter Hyperfind ID.
    Description: (Optional)
    Template Parameter: (Required) Select HyperfindID.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional) Enter the ID of a single hyperfind, or the IDs of one or more locations each separated by a comma (,) or number sign (#).
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the pay period:
    Click Tap Create .
    PayPeriod
    Parameter Name: (Required) Enter Pay Period.
    Description: (Optional)
    Template Parameter: (Required) Select PayPeriod.
    Parameter Type: (Required) Select Time period.
    Default Value: (Optional) Enter one of the following pay periods:
    - 0 = Previous pay period
    - 1 = Current pay period
    - 2 = Next pay period
    - 3 = Previous schedule period
    - 4 = Current schedule period
    - 5 = Next schedule period
    - 6 = Week to date
    - 7 = Last week
    - 8 = Yesterday
    - 10 = Range of relative dates
    - 11 = Specific date
    - 12 = Relative specific date
    - 13 = Today
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
Click Tap Save.

Install the Employee Job History integration

Virtual Roster Employee Job History integration

Click Tap Create .
Enter an appropriate, unique, and descriptive Integration Name.
(Optional) Enter a Description.
Do not select API Integration.
Complete the SFTP settings:
- In File Access, select one of the following:
  None: Do not select a Connection.
  File Upload
  Source/Output Download
- In Connection, click tap Internal SFTP.
(Optional) To allow the integration access to all APIs in the FAP, and the relevant permissions and data even if the person who runs the integration doesn't have full access, select Execute Integration with System Account.
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
(Optional) Email Notifications
1. Select Yes to send email and control center notifications for integration runs.
2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces: In Progress — The integration run started and has not finished.
  
  Completed — The integration ran successfully without errors.
  
  Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
  
  Completed with Errors — The integration run has errors or could not run.
(Optional, not available for API-based integrations) Select Enhanced Payroll Monitoring to identify whether this integration is part of a payroll process. This setting allows to monitor the integration and sub-processes and help to troubleshoot payroll processes if the integration has errors or fails.
Scheduling Configuration
(Optional)

(Only for file-based integrations) For integrations that will be scheduled to run frequently, configure the behavior if integrations overlap in time. These settings allow frequent integration runs that avoid redundant processing of data and avoid multiple integrations processing the same data.
- In Skip Configuration, select one of the following:
  None (default): Allow multiple integrations to run at the same time or with the same data without restrictions.
  Installed Instance (Recommended): Do not run a scheduled integration if another instance of the same installed integration is in-progress. Only once such integrations finish, this integration can run at the next scheduled time.
  Integration Template: Do not run a scheduled integration if any installed instance of the same integration template is in-progress. Only once such integrations finish, can this integration run at the next scheduled time.
- Only if Installed Instance or Integration Template is selected, select Allow Minute Interval to allow the person who schedules the integration to select the By Minute recurrence to repeat the integration run every 5, 10, 15, 20, 25, or 30 minutes.
Integration template and parameters
1. In Integration Template, select JobHistoryExport-v1.
2. Click Tap Assign .
3. (Optional) In Integration Parameters, you can override default settings:
  1. Click Tap Create .
  2. (Required) Specify the parameter to select the hyperfind query of employees:
    HyperfindID
    Parameter Name: (Required) Enter Hyperfind ID.
    Description: (Optional)
    Template Parameter: (Required) Select HyperfindID.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional) Enter the ID of a single hyperfind, or the IDs of one or more locations each separated by a comma (,) or number sign (#).
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the start date of the pay period:
    StartDate
    Parameter Name: (Required) Enter Start Date.
    Description: (Optional)
    Template Parameter: (Required) Select StartDate.
    Parameter Type: (Required) Select Date.
    Default Value: (Optional) Enter a default date as the symbolic period (preferred), symbolic period span, or date in MM-DD-YYYY format.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the end date of the pay period:
    EndDate
    Parameter Name: (Required) Enter End Date.
    Description: (Optional)
    Template Parameter: (Required) Select EndDate.
    Parameter Type: (Required) Select Date.
    Default Value: (Optional) Enter a default date as the symbolic period (preferred), symbolic period span, or date in MM-DD-YYYY format.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the pay period:
    SymbolicPeriod
    Parameter Name: (Required) Enter Pay Period.
    Description: (Optional)
    Template Parameter: (Required) Select SymbolicPeriod.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional) Enter one of the following symbolic values for the pay period:
    - 1 (Default) = Current Pay Period
    - 0 = Previous Pay Period
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the span of the pay period:
    SymbolicPeriodSpan
    Parameter Name: (Required) Enter Pay Period Span.
    Description: (Optional)
    Template Parameter: (Required) Select SymbolicPeriodSpan.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional)
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the number of days in the past to look for terminated employees:
    PastTerminationDays
    Parameter Name: (Required) Enter Past Termination Days.
    Description: (Optional)
    Template Parameter: (Required) Select PastTerminationDays.
    Parameter Type: (Required) Select Number.
    Default Value: (Optional) Enter 7 days to export records for employees who were terminated up to 7 days ago, today, and will be terminated in the future.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the number of days in the past to look for primary job and job transfer set assignments to export. LimitJobHistory must be set to true.
    PastJobHistoryDays
    Parameter Name: (Required) Enter Past Job History Days.
    Description: (Optional)
    Template Parameter: (Required) Select PastJobHistoryDays.
    Parameter Type: (Required) Select Number.
    Default Value: (Optional) Enter 30 days to 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.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select whether to limit the export of the job history to go back only as far as the PastJobHistoryDays setting:
    LimitJobHistory
    Parameter Name: (Required) Enter Limit Job History.
    Description: (Optional)
    Template Parameter: (Required) Select LimitJobHistory.
    Parameter Type: (Required) Select Boolean.
    Default Value: (Optional) Enter false to export all past, current, and future-dated primary job and job transfer set assignments. Typically, the default false setting is needed for the initial run of this integration. For subsequent runs, enter true to limit the number of days to only the number in the PastJobHistoryDays setting.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select whether to include jobs from job transfer sets (JTS) in the export:
    IncludeJTSJobs
    Parameter Name: (Required) Enter Include Transfer Jobs.
    Description: (Optional)
    Template Parameter: (Required) Select IncludeJTSJobs.
    Parameter Type: (Required) Select Boolean.
    Default Value: (Optional) Enter false to export only primary jobs.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
Click Tap Save.

Install the Timeclock Export integration

Virtual Roster Timeclock Export integration

Click Tap Create .
Enter an appropriate, unique, and descriptive Integration Name.
(Optional) Enter a Description.
Do not select API Integration.
Complete the SFTP settings:
- In File Access, select one of the following:
  None: Do not select a Connection.
  File Upload
  Source/Output Download
- In Connection, click tap Internal SFTP.
(Optional) To allow the integration access to all APIs in the FAP, and the relevant permissions and data even if the person who runs the integration doesn't have full access, select Execute Integration with System Account.
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
(Optional) Email Notifications
1. Select Yes to send email and control center notifications for integration runs.
2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces: In Progress — The integration run started and has not finished.
  
  Completed — The integration ran successfully without errors.
  
  Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
  
  Completed with Errors — The integration run has errors or could not run.
(Optional, not available for API-based integrations) Select Enhanced Payroll Monitoring to identify whether this integration is part of a payroll process. This setting allows to monitor the integration and sub-processes and help to troubleshoot payroll processes if the integration has errors or fails.
Scheduling Configuration
(Optional)

(Only for file-based integrations) For integrations that will be scheduled to run frequently, configure the behavior if integrations overlap in time. These settings allow frequent integration runs that avoid redundant processing of data and avoid multiple integrations processing the same data.
- In Skip Configuration, select one of the following:
  None (default): Allow multiple integrations to run at the same time or with the same data without restrictions.
  Installed Instance (Recommended): Do not run a scheduled integration if another instance of the same installed integration is in-progress. Only once such integrations finish, this integration can run at the next scheduled time.
  Integration Template: Do not run a scheduled integration if any installed instance of the same integration template is in-progress. Only once such integrations finish, can this integration run at the next scheduled time.
- Only if Installed Instance or Integration Template is selected, select Allow Minute Interval to allow the person who schedules the integration to select the By Minute recurrence to repeat the integration run every 5, 10, 15, 20, 25, or 30 minutes.
Integration template and parameters
1. In Integration Template, select TimecardExport.
2. Click Tap Assign .
3. (Optional) In Integration Parameters, you can override default settings:
  1. Click Tap Create .
  2. (Required) Specify the parameter to select the hyperfind query of employees:
    HyperfindID
    Parameter Name: (Required) Enter Hyperfind ID.
    Description: (Optional)
    Template Parameter: (Required) Select HyperfindID.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional) Enter the ID of a single hyperfind, or the IDs of one or more locations each separated by a comma (,) or number sign (#).
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the start date of the pay period:
    StartDate
    Parameter Name: (Required) Enter Start Date.
    Description: (Optional)
    Template Parameter: (Required) Select StartDate.
    Parameter Type: (Required) Select Date.
    Default Value: (Optional) Enter a default date as the symbolic period (preferred), symbolic period span, or date in MM-DD-YYYY format.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the end date of the pay period:
    EndDate
    Parameter Name: (Required) Enter End Date.
    Description: (Optional)
    Template Parameter: (Required) Select EndDate.
    Parameter Type: (Required) Select Date.
    Default Value: (Optional) Enter a default date as the symbolic period (preferred), symbolic period span, or date in MM-DD-YYYY format.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Required) CacheBusinessStructure must be set to true so that the output file can contain the Job and the parent path in the business structure. Do not change this parameter.
    (Optional) Specify the parameter to select the pay period:
    SymbolicPeriod
    Parameter Name: (Required) Enter Pay Period.
    Description: (Optional)
    Template Parameter: (Required) Select SymbolicPeriod.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional) Enter one of the following symbolic values for the pay period:
    - 1 (Default) = Current Pay Period
    - 0 = Previous Pay Period
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the span of the pay period:
    SymbolicPeriodSpan
    Parameter Name: (Required) Enter Pay Period Span.
    Description: (Optional)
    Template Parameter: (Required) Select SymbolicPeriodSpan.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional)
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Required if CacheBusinessStructure is enabled) Specify the parameter to specify the root node in the business structure:
    BusinessStructureRootName
    Parameter Name: (Required) Enter Business Structure Root.
    Description: (Optional)
    Template Parameter: (Required) Select BusinessStructureRootName.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional) Enter the name of the root node.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Required) CacheEmployeeData must be set to false because no employee data is required in the output file. Do not change this parameter.
    (Required) Specify the parameter to specify the name of the hyperfind query that contains all employees:
    AllEmployeeHyperfindName
    Parameter Name: (Required) Enter All Employee Hyperfind.
    Description: (Optional)
    Template Parameter: (Required) Select AllEmployeeHyperfindName.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional) Enter the name of the hyperfind.
    Caution: Do not enter All Home.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
Click Tap Save.

Install the HCM Accruals Export integration

Virtual Roster HCM Accruals Export integration

Click Tap Create .
Enter an appropriate, unique, and descriptive Integration Name.
(Optional) Enter a Description.
Do not select API Integration.
Complete the SFTP settings:
- In File Access, select one of the following:
  None: Do not select a Connection.
  File Upload
  Source/Output Download
- In Connection, click tap Internal SFTP.
(Optional) To allow the integration access to all APIs in the FAP, and the relevant permissions and data even if the person who runs the integration doesn't have full access, select Execute Integration with System Account.
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
(Optional) Email Notifications
1. Select Yes to send email and control center notifications for integration runs.
2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces: In Progress — The integration run started and has not finished.
  
  Completed — The integration ran successfully without errors.
  
  Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
  
  Completed with Errors — The integration run has errors or could not run.
(Optional, not available for API-based integrations) Select Enhanced Payroll Monitoring to identify whether this integration is part of a payroll process. This setting allows to monitor the integration and sub-processes and help to troubleshoot payroll processes if the integration has errors or fails.
Scheduling Configuration
(Optional)

(Only for file-based integrations) For integrations that will be scheduled to run frequently, configure the behavior if integrations overlap in time. These settings allow frequent integration runs that avoid redundant processing of data and avoid multiple integrations processing the same data.
- In Skip Configuration, select one of the following:
  None (default): Allow multiple integrations to run at the same time or with the same data without restrictions.
  Installed Instance (Recommended): Do not run a scheduled integration if another instance of the same installed integration is in-progress. Only once such integrations finish, this integration can run at the next scheduled time.
  Integration Template: Do not run a scheduled integration if any installed instance of the same integration template is in-progress. Only once such integrations finish, can this integration run at the next scheduled time.
- Only if Installed Instance or Integration Template is selected, select Allow Minute Interval to allow the person who schedules the integration to select the By Minute recurrence to repeat the integration run every 5, 10, 15, 20, 25, or 30 minutes.
Integration template and parameters
1. In Integration Template, select HCMAccrualExport-v1.
2. Click Tap Assign .
3. (Optional) In Integration Parameters, you can override default settings:
  1. Click Tap Create .
  2. (Required) Specify the parameter to select the short names for the accrual codes to export:
    ProcessTheseAccrualCodesOnly
    Parameter Name: (Required) Enter Accrual Codes to Process .
    Description: (Optional)
    Template Parameter: (Required) Select ProcessTheseAccrualCodesOnly.
    Parameter Type: (Required) Select Text.
    Default Value: (Not specified) Can be a single or multiple values separated by commas ( ,) and no spaces.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select whether to include accruals that have a balance of zero:
    Click Tap Create .
    SuppressRecordsWithZeroAccrualBalance
    Parameter Name: (Required) Enter Include Zero Balances.
    Description: (Optional)
    Template Parameter: (Required) Select SuppressRecordsWithZeroAccrualBalance.
    Parameter Type: (Required) Select Boolean.
    Default Value: (Optional)
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to select the pay period:
    Click Tap Create .
    PayPeriod
    Parameter Name: (Required) Enter Pay Period.
    Description: (Optional)
    Template Parameter: (Required) Select PayPeriod.
    Parameter Type: (Required) Select Time period.
    Default Value: (Optional) Enter one of the following pay periods:
    - 0 = Previous pay period
    - 1 = Current pay period
    - 2 = Next pay period
    - 3 = Previous schedule period
    - 4 = Current schedule period
    - 5 = Next schedule period
    - 6 = Week to date
    - 7 = Last week
    - 8 = Yesterday
    - 10 = Range of relative dates
    - 11 = Specific date
    - 12 = Relative specific date
    - 13 = Today
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
    (Optional) Specify the parameter to process data for only a limited number of employees:
    Click Tap Create .
    IncludeEmployees
    Parameter Name: (Required) Enter Include Employees.
    Description: (Optional)
    Template Parameter: (Required) Select IncludeEmployees.
    Parameter Type: (Required) Select Text.
    Default Value: (Optional) Can be a single or multiple values separated by commas (,) and no spaces. Leave blank to process data for all employees.
    User Prompted: To prompt the person who manually runs the integration to set this parameter, select Yes.
    Click Tap Save.
Click Tap Save.

Configure access to the integrations

How to configure access to integrations.

Configure the Generic Data Access Profile (GDAP) to select the integrations that a person can run.

Log in as an administrator.
Click Tap Main Menu > Administration > Application Setup > Access Profiles > Generic Data Access Profiles.
Create, edit, or remove a profile:
- Click Tap New. Enter a Name.
- Select a profile. Click Tap Edit or Duplicate.
- Select a profile. Click Tap Delete. Click Tap OK.
From Setup Category, select Integrations.
From Setup Item, select:
- Integrations
- Integration Sets
Add integrations to the profile. These integrations must be installed in order to be available.
- From Available, select the items and click tap the right arrow . Alternatively, click tap the double right arrow to select all items.
- (Optional) Remove items. From Selected, select the items and click tap the left arrow . Alternatively, click tap the double left arrow to remove all items.
Click Tap Save & Return.
Repeat for the next person.