All outbound Integrations in Integration Studio source data from one of the available HCM Anywhere APIs, such as the Employee Bulk or the Analytics Data Connector (Dayforce Reports). Additionally, inbound integrations can use an external API as a source.
Review the following topics before you configure an API sourced integration:
API Parameters limit what data is returned when the API is called. Common parameters include Pay Period Start and End Dates and Employee or Pay Group Reference Codes.
The following are best practices for populating parameters for common HCM Anywhere APIs in Integration Studio:
Employee Bulk API
The Export Period controls the scope of information pulled. The options are outlined on the Dayforce Developer’s Network. It is recommended that you review the options carefully, and run a test to confirm that the data is returned as expected.
Filters can also be applied to restrict the data included in mapping when reporting data from Employee Bulk. However, it is advised that you select the Export Period which most restricts the data pulled from the API, while also including all relevant information. For example, instead of using an Export Period of Full History and filtering for records currently effective, you should use Current as the Export Period.
Analytics Data Connector API (Dayforce Report)
Filters and parameters should be configured on the report to limit the data pulled from Dayforce as much as possible. If modification to these filters and parameters is required when using the report for an integration but should not impact the results when a user runs the report through Dayforce Reporting, it can be done as part of Source Setup within Integration Studio.
Before working with an API in Integrations, it is considered best practice to understand the following about the API response, which will be the source record for your integration.
What context is the data in?
The context of a data set is how the information is organized and what one full record represents. For example, the GET Time Data or Quick Entry API is in the context of time entry records or quick entries and each record in the response represents one time entry record or one quick entry. Obversely, the Employee Bulk and the Ongoing Benefit Carrier Exports are in the context of an employee so each record in the response represents one employee.
What is the main array?
Some APIs, like the Ongoing Benefit Carrier Exports, include a Header array and an EmployeeRecords array. The Header array includes basic information, such as the plan start date and the client ID. The EmployeeRecords array includes all of the employee, plan, dependent/beneficiary information, etc. so, the main array would be EmployeeRecords.
Other APIs, such as the Employee Bulk, have a single array, which is Data. Data includes all of the base employee, direct deposit, work assignment information, etc. so, the main array is Data.
What is the full path to the field I need to map?
Using the Employee Bulk API as an example source, if a user needs to map the EffectiveStart of an employee’s work assignment. Since EffectiveStart is a very common field name, knowing the full path helps you to select the correct one. The full path references the structure of the source file itself, such as Data > WorkAssignments > Items > EffectiveStart. Data is the top-level array in the source data, followed by WorkAssignments, Items, then the field itself. This is similar to comparing file paths to find the correct copy of a file named “Annual Review”, if two files were saved in different folders on the same computer.
What is nesting?
Many API responses, such as the Employee Bulk, use a nested structure to represent related data. Similar to folders on a computer, each array is a “folder” which contains files (fields) and possibly, more folders (arrays). In the example above, Data is a folder containing employee information in individual files (fields) as well as additional folders (arrays) which include data specific to WorkAssignments, EarningElections, EmployeeProperties, etc. Other API responses, such as the Analytics and Data Connector, has no nesting, and there is only one array (Data) with a set of files (the fields in the API response).