It is important to have a basic understanding of how Integration Studio works with the standard API data structure response, as well as key considerations when transforming data from one structure to another.
This is especially important when the main record can have multiple assignments of the same data fields, which is called an array.
For example, in Dayforce, an employee record can have multiple addresses on the HR profile, meaning a single employee record can have an array of multiple address objects. When Integration Studio calls the Employee Bulk API to source an outbound integration, the API returns the data in the following way:
Thus, if you map a Destination Field to the Addresses > Address1 Dayforce Field, Integration Studio returns multiple Address1 values, because the employee has both a PrimaryResidence address and a Mailing address in their profile.
If you expect only one value to appear in the final output for the integration (for example, only the PrimaryResidence address), you need to apply a Choose Record filter on your field. For example:
In some cases, you can set multiple conditions for choosing records, illustrated in the following screenshot:
In the Choose Record for <element> dialog, you can see a + icon to the left of each record. Clicking that icon adds a new row of fields for another condition below the preceding row. You can select values for the new condition similar to the first condition. You can also delete any added conditions, but you can’t delete the first condition. You can’t save unless all of the conditions are fully configured.
You might also want to apply a Choose Record on a field nested within multiple arrays, such as when you are mapping a destination field AmountValue to the Deduction Value in the source, but only for deductions in Dayforce that use an Amount parameter and are effective after a certain date. To restrict the Deduction Value results, map the field, and open the associated Choose Record dialog box.
By default, the filter must be applied on the current array in which the mapped field exists. In this case, the mapped field is Value, which exists within the EmployeeDeductionParameter array, which in turn exists within the DeductionElection array. At least one EmployeeDeductionParameter object exists for each DeductionElection object.
Because the current array is EmployeeDeductionParameter the first filter must uniquely identify an EmployeeDeductionParameter object, such as when the Deduction Parameter XrefCode equals AMOUNT.
Because another array exists (DeductionElections) between the current array (EmployeeDeductionParam) and the top-level source array (Data)—the DeductionElection array—another filter must be configured. Instead of Save at the bottom right of the dialog, click Next. Now, the current array is DeductionElections and a filter on the EffectiveStart date can be configured. Once you are finished, click Save.
You can also configure a Choose Record filter to return any record that meets your conditions when multiple records are found. This is done by selecting Return any record from the If multiple records are found that meet the criteria drop-down list. You can select Fail the integration to fail an integration when multiple records are found that meet the conditions in your Choose Record filter.
When clearing and deleting nested Choose Record filters, all subsequent filters are cleared or deleted as well. In the Deduction example above, if the Amount filter was cleared or deleted, the EffectiveStart filter is automatically cleared or deleted too.
Integration Studio selects the instance based on all of the conditions configured in Choose Record, using the AND or the Or conditions similar to Local Filters, and parent filters and then outputs the chosen value in the file.
Note: You might need additional criteria when you are configuring a Choose Record filter so that a specific record from a sorted list is selected. For example, if there are two records that are tied for the same spot, you must provide additional information so that the application can select the proper record. You can add a filter based on an XRefCode, LastModifiedTimestamp, etc to ensure that the proper record is selected.
Handling Arrays with Single Objects
For convenience, Integration Studio doesn’t require you to configure a Choose Record filter when only one object exists in the array for all records returned using the API selected; however, the blue filter icon will still be shown.
For example, if you are using the Employee Bulk API to source your Integration, you might want to restrict the data returned for employees to include only current information, rather than all historical records. You can do this by configuring the Export Period parameter to return current records (by selecting the Current option) instead of returning all historical records (by selecting the Full History option). When you select Current, the API returns only current records, ensuring that data for each employee is returned with a single Employment Status record, effective as-of date that the integration runs. This effectively results in an array with a single object. Integration Studio doesn’t require you to configure a Choose Record filter in cases like this, even though the blue filter icon is still shown.
Similarly, if all employees are only assigned a Primary Residence address in Dayforce, Integration Studio won’t require the configuration of a Choose Record filter, and your integration will run without issues. However, as soon as one employee gets assigned a second address using a Mailing Address record, your integration will fail, and you must configure the Choose Record filter if your output expects a single address value.