Define the parameters of this integration

Integration parameters are broken up into the following sections:

• Source
• Output Format
• Mapper Options

Depending on which connector you select, you will see some, or all of these sections.

Source

For outbound integrations, Integration Studio retrieves the Dayforce data by calling the Dayforce HCM Anywhere APIs. Therefore, you must select an appropriate HCM Anywhere API to source each integration. When you select an API source, you are prompted to fill out the respective API parameters for that API source in the Source section. For example, if the API Source is set to Dayforce Report, users will be prompted to select a report to use for the integration. When you run the integration, Integration Studio calls the Analytic Data Connector API to request the data.

Note: Reports that use the grouping, totaling, or pivoting functionality cannot be used in Integration Studio.

Because outbound integration data is sourced from the HCM Anywhere APIs, make sure to review the content and structure of the data offered via the Dayforce Developers Network at https://developers.dayforce.com/.

Available Data Sources

The following Dayforce HCM Anywhere APIs and Events are available to be used as a source of outbound integrations in Integration Studio. For more information, please see the Dayforce Developers Network at https://developers.dayforce.com/.

Common:

• Bulk Employee HR API
• Event Driven HR Changes Connector (Event and Payroll Election Events)
• Dayforce Report (V1 or V2 Reports via Analytics Data Connector API)

Other:

• BackgroundJobLogs
• BenefitEnrollmmentData
• CandidateApplicationStatuses
• Certifications
• ClientPayrollCountry
• Courses
• DataPrivacy
• DeductionDefinition
• EarningDefinition
• EmployeeBalancePeriods
• EmployeeBalanceTransactions
• EmployeePayAdjustments
• EmployeePaySummaries
• EmployeePaySummariesRetro
• EmployeePunches
• EmployeeRawPunches
• EmployeeSchedules
• JobPostingQuestionnaires
• JobPostings
• KpiData
• LaborCosts
• LaborDemands
• LegacyLaborMetric
• LocationAddresses
• Payee
• PayGroupCalendar
• Payroll/DataEntry
• Payroll/EmployeeGLSplits
• Payroll/PayrollElection
• Payroll/PayrollPayEntryImportHistory
• Payroll/WorkLocationOverride
• PayRunStatus*
• PlanTargets
• Projects
• ReportMetadata
• Skills
• TaxAuthorityInstanceDetails
• TrainingPrograms

* Pay run data/Payroll Export data isn’t currently an available source of data in Integration Studio.

Connectors will already have the source configured, because they’re specific to a particular data set.

Relative Dates and Report Parameters

Integration Studio offers several dynamic date options for Source parameter and report filter dates. The following examples assume that the integration is run on November 22, 2022 at 15:25:45 UTC.

Parameters

The parameters shown in the connector depend on the selected data source. See the following table for common Dayforce API sources related parameters:

For more information about Employee API parameters, see the Dayforce Developers Network at https://developers.dayforce.com/.

Report Filters

When Dayforce Report is the source, the Report Filters section appears between Source and Output Format.

The Report Filters section is optional and allows you to override the prepopulated filters that are set in the configuration of the report in Reporting and Analytics > Reporting and Analytics Home > Reporting.

It is generally recommended to configure the required filters directly in the report configuration, rather than rely on the overrides in Integration Studio.

By default, the Override checkbox is cleared for all report filters in Integration Studio. Report filters in this section correspond with the filters for the selected report in Reporting & Analytics > Reporting and Analytics Home > Reporting. When the Override checkbox is cleared, Integration Studio uses the values configured in Reporting & Analytics > Reporting and Analytics Home > Reporting for the selected report.

Select the Override checkbox to configure an override for the corresponding filter, illustrated in the following screenshot:

Output Format

You must determine the format of the generated file or payload in the Output Format section.

The first setting is Output Type, which controls the overall layout of the file. Options include:

• Character-Separated Values/Delimited Text File
• XML
• JSON
• Segmented Character-Separated Values/Delimited Text File
• Fixed Width Text File
• Segmented Fixed Width File

The Formatted Output switch is turned off by default to ensure that XML and JSON size is minimized. When you click it to turn it on, the output includes line breaks, indentation and spacing between fields, which significantly increases the file or payload size.

You can enter a number into the Batch Size field that specifies the number of records that each batch contains. For example, if the data includes 1,000 records and you enter the number 10 into the Batch Size field, the data is split into 100 batches that contain 10 records each.

You can select the Do not transmit if there is no data checkbox to ensure that an empty file doesn’t get transmitted to your vendor if there is no data to be transmitted, regardless of the output type. This checkbox is unchecked by default.

You can use the following checkboxes to modify the output of your data. The “Checkbox options in relation to output types” table in this section outlines which checkbox options are available for each output type:

• Output in Uppercase: Select this checkbox to convert characters in a text file to uppercase characters.
• Convert Supported non-ASCII Character to ASCII: Select this checkbox to convert non-ASCII characters in a text file to ASCII characters.
• Do not transmit if there is no data: Select this checkbox to ensure that an empty file doesn’t get transmitted to your vendor if there is no data to be transmitted. This checkbox is available for all output types and is cleared by default.

Important: If you need the generated file to include a file extension, specify the extension in the file name. For example: 401kContributions_Monthly.xml instead of 401kContributions_Monthly.

Mapper Options

The Mapper Options section contains the Enable Strict Paths switch, which ensures that the application shows an error message when an expression references a variable or a path that isn't found in the source. The Enable Strict Paths switch is on, by default.

Character-Separated Values/Delimited Text

This is a flat file format, frequently referred to as CSV and formerly known in Integration Studio as Separated Values/Delimited Text. When this output type is selected, the following fields are shown:

Note that, when using commas as the delimiters in Separated Values/Delimited Text Files, the output format looks like this:

1,Darzi,Aresh,Product,P&T,Toronto,Canada,FullTime
  2,Jones,Amanda,Product,P&T,Toronto,Canada,FullTime

Similar to hierarchical output structures (XML, JSON), Character Separated Values/Delimited Text files are configured using hierarchy in Integration Studio to allow the return of multiple records in the destination. For example, you might want the output file to contain a row for each Direct Deposit account that is linked to an employee in Dayforce. To do this, you can add a parent field that is configured as an array, and then create the child fields under the parent field. If the fields already exist, click the Action icon beside a field and then click Edit in the menu that opens. In the Edit <Field Name> Element dialog box, select the parent field you created from the Parent drop-down list.

To filter the returned records so that only a specific record from the array is sent to your vendor, you must click the Choose Record icon beside a field in the mapping step. In the Choose Record For <Field Name> dialog box, define a filter for the specific record that you need.

Unlike XML and JSON output types, related fields might or might not be shown side-by-side in the output file. To define the order that the fields are shown in the output file, you must click Define Field Order in the mapping step. In the Define Field Order screen, drag and drop the fields so that they are in your preferred order and then click Save. To ensure that you can locate the correct field or fields, the name of each field is shown as well as the name of the parent field and the field’s display name. For your reference, the column number is shown on the left side of each field.

Segmented Character-Separated Values/Delimited Text

Similar to traditional Character-Separated Values/Delimited Text files, this is also a flat file format that allows hierarchy; however, this output type uses a hierarchical structure to allow for looping over a segment of records, which may or may not span multiple lines. Some vendors and some types of integrations require a file format that loops through records, outputting several rows of data per record before moving onto the next. The most common example of this is the Benefit Enrollment 834 format, an industry wide standard for benefit integrations.

In earlier versions of Integration Studio, this output type was named Block Separated Values/Delimited Text.

1,Darzi,Areshn~

This output type requires a particular file structure to ensure that the data is pulled correctly. Each loop (a series of fields that repeat), contains a separate piece, or linked pieces, of data. The following example illustrates the output format for a Block Separated Values/Delimited Text File:

For example, if you are configuring an HR Data integration with three lines for each employee, Personal Information, Key Dates on the second line, and Phone Number on the third, you could define your structure as illustrated in the following screenshot:

For each record, Integration Studio generates a line for each group of data fields. The parent records such as Personal and Dates don’t appear in the final file because they represent a loop of data, or a series of fields that repeat.

Fixed Width Text

Fixed-width text files are arranged with a specific column and row structure, and each column has a fixed width. These files are commonly used by applications for financial reporting or data analysis, where the information contained must align perfectly at all times. This rigid structure is one advantage of fixed-width files: they can be easily read and processed by software applications because the data is organized in a predictable format.

These files might require a header and a footer, as well as the data in the body. By default, the first parent field in an integration that is configured to use the Fixed Width Text output type is the header. The second parent field is the body, and the third parent field is the footer. When you configure headers and footers in your integration, they must be the same total width as the body.

When you select this output type, you must define the width value, padding character, and padding alignment for each field. You also have the ability to import a CSV file that contains the following field properties:

• Data Type
• Data Format
• Description
• Custom Padding Character
• Padding Alignment
• Field Required

This is achieved by clicking Import in the mapping step.

Important: If the source data exceeds the width value provided, Integration Studio truncates the data and ignores characters beyond the specified width.

Segmented Fixed Width File

Similar to Fixed Width text files, data in Segmented Fixed Width files are arranged with a specific column and row structure, and each column has a fixed width. In addition, these files show employee data in segmented data blocks that do not use a delimiter, which is similar to Segmented-Character Separated Values/Delimited text files.

XML

XML, an abbreviation of eXtensible Markup Language, is used for storing and transporting data similar to HTML (HyperText Markup Language). XML is designed to be both human-readable and machine-readable, and is commonly used for exchanging data between different systems and applications. Data is organized into a hierarchical structure. When adding fields in Step 3 of the configuration, you can define the field as a parent or as a data element and the parent element under which the new field appears.

When you select XML File as the output type, you can import an XSD file that defines the destination fields and their structure. When you import an XSD file, the Required Field checkbox in the Add Element dialog box and the Include Null/Empty Values in the Output toggle that is available when your integration is not configured to use the Character-Separated Values/Delmited Text File output type, are updated by the MinOccurs field and the Nillable field in the XSD file.

Fields are designated as required and null or empty fields are included in the output file when the MinOccurs field is greater than 0 and the Nillable field is set to false, respectively. In addition, fields are not designated as required and do not include null or empty fields when the value for the MinOccurs field is set to 0 and the value for the Nillable field is set to true. Otherwise, fields are not marked as required. However, null or empty fields are included in the output file.

Important: If the format of your file is hierarchical, and any set of fields repeats in the final output file, the fields must share a parent element designated as an array. For example, to return all direct deposit records, all destination fields mapped to the Direct Deposit collection in Dayforce must have the same parent with the Is Array box selected.

JSON

JSON, an abbreviation of JavaScript Object Notation, serves as a lightweight data interchange format that is easy for humans to read and write and is easy for machines to parse and generate. JSON is often used for exchanging data between web applications and APIs and is widely supported by programming languages and frameworks. JSON data is represented as key-value pairs, with values that can be strings, numbers, arrays, or other objects. JSON data can also be organized in a hierarchical structure, and when you are adding fields in Step 3 of the configuration, you can define the field as a parent or as a data element, and you can define under which parent the new field appears.

Important: If the format of your file is hierarchical, and any set of fields repeats in the final output file, the fields must share a parent element designated as an array. For example, to return all direct deposit records, all destination fields mapped to the Direct Deposit collection in Dayforce must have the same parent with the Is Array box selected.