Field Configuration

Create Custom Tokens

Tokens let you to use system and user defined values in the mapping step of an integration. Currently, you can select configurable and system tokens in the mapping step for all integrations. Custom tokens, instead are unique to a specific integration because they are user defined and dependent on the selected source.

To create a new custom token:

1. Open an existing integration.
2. Click Map fields from Dayforce to <Vendor> to expand the step.
3. Click Manage Tokens.
4. Click Custom Tokens to expand the section.
5. Click Create New Custom Token.
6. Define the Token Details:
   1. Name: Enter a name for your custom token.
   2. Data Type: Select the data type for your custom token. For example, a custom token that is configured to use the Date/Time data type can only be mapped to a Date/Time destination field. Similarly, an array custom token can only be used as a parameter to an expression, or as the Comparison Value of a Criteria in Local Filters, Choose Record, or Conditional Mapping when you use the IN and NOT IN operators.
   3. Description: Enter a description for your custom token. You can use this field to add additional information about your custom token, if needed.
7. Define the parameters in the Parameters section and write the required IDL expression
8. Click Save.

You can view a custom token in the Manage Integration Token screen. Additionally, you can edit and map a custom token to a destination field.

Note: You can disable or delete tokens that are not mapped. Disabled or deleted tokens are not shown as options in the mapping step. You can re-enable a token that you previously disabled at any time; however, deleted tokens cannot be recovered. Only custom tokens can be deleted.

Source and Source Details

Field Configuration

Each field must have a source, which defines where to get the data for a particular destination field:

• Source Vendor Field
• Source Array
• Flattened Array
• User Defined Value
• Mapping
• Conditional Mapping
• Token
• Transformation
• Expression
• Aggregation

Some of the source options listed in the Source drop-down list require you to select an option from the Source Details drop-down list, while others don’t. If a selection is required, the Source Details drop-down list is shown.

Note, if you selected Dayforce Report in the step Define the parameters of this integration, the Auto-fill from Report button is shown to the right of the Add button. Integration Studio populates the name, description, and data type of each field from the report in Step 3, in the same order as the report.

Source Vendor Field

This is a direct, one-to-one relationship: one <Source Vendor> field linked directly to one Destination Vendor field. For example, in outbound integrations, if the vendor field EmployeeFirstName is the same as the Dayforce field FirstName, Source can be set to Dayforce Field, and Source Details can be set to Data > FirstName.

You can use the type-ahead search to find the source field you need, because some Source HCM Anywhere APIs offer a large list of fields to select from. For example, if you are using the Bulk Employee API, enter xrefcode paytype employmentstatus in the Source Details drop-down list to filter the list of possible fields to select when you are mapping to the employee’s Pay Type XrefCode value. If you’re not sure which field you need, start with the most general term (for example, xrefcode) and get more specific to reduce the overall number of results returned.

If the selected source field could have more than one assignment per employee, such as a Global Property in an outbound integration, a filter icon will appear to the right of the drop-down. Click the icon to restrict the returned data to a single value. After the filter has been applied, the icon turns blue. More information on this topic is available in The Importance of Understanding Your Data Structure.

Source Array

You can explicitly select a source array that defines the structure of a destination array. This ensures that Integration Studio uses the correct source array, if the auto-generated array results in an unexpected output.

The Source Array option is available in the Source Details drop-down list for fields that are configured to use Parent as the Type and the Is Array checkbox is selected for an element. When this criterion is met, the Source field is set to Source Array, which can’t be edited. The Source Details drop-down list is set to Auto-Generate for integrations that don’t have a filter.

If needed, you can select a different source array from the Source Details drop-down list.

Flattened Array

You can flatten your data in Integration Studio by selecting Flattened Array in the Source drop-down list for an array root element or for the topmost array parent field.

You can select only one sub-array field in the main data array to map data from the sub-array to be flattened, in the Source Details drop-down list.

This functionality is useful in situations where your source data is organized hierarchically, but the vendor's required data structure isn't. For example, you can send pay summary data that is flattened to the employee, or HR data that contains elections that is flattened to the employee.

Note: Flattened arrays can’t be used in combination with grouping or parent level expressions.

User Defined Value

This is a static value provided by the user. Manually enter a value or leave the field blank if the field should always be empty. For example, if the first field in every XML integration should be the company name, the Source of the first field can be set to User Defined Value, and the user can type the company name into the Source Details text box.

Acceptable user defined values vary based on the Data Type of the destination field. If the data type is Date/Time, only Date/Time values are allowed. Similarly, if the data type is Number, only integer and decimal values are accepted.

Mapping

The Mapping option is used when source values need to be mapped to destination values. The source assumes that there is a direct relationship between a <Source Vendor> field and a Destination Vendor field. However, the values contained within might vary between systems.

For example, if the vendor field Status is derived via the Dayforce field EmploymentStatus > Xrefcode, the Source can be set to Mapping. Source Details can be set to EmploymentStatus > Xrefcode, and, after you click Edit, you can import the list of required status codes in Dayforce and their relative values in the receiving system (for example, ACTIVE in Dayforce to 01 in the target system, and so forth). The Else clause is used when the Dayforce field is missing or the value is not included in the list of mapped values.

Before you can link source values with Destination Vendor values, you must define the Destination Vendor values in Dayforce. After you select the Source, click Edit, and then click either Edit Vendor Values to add them one by one, or click Import to import them all at once. The best practice is to import, because that will create the vendor values and also streamline the assignment of Dayforce values to vendor values. If you’ve already manually configured required vendor values in one integration, and you need the same set for another integration, click Export to get the full list.

Important: If the field to be mapped has a Data Type of Boolean, importing vendor values isn’t supported.

If the selected Dayforce field to be mapped can have more than one assignment per employee, such as a Global Property in an outbound integration, a filter icon will appear to the right of the drop-down. Click the icon to restrict the returned data to a single value. After the filter has been applied, the icon turns blue. More information on this topic is available in The Importance of Understanding Your Data Structure.

Conditional Mapping

The Conditional Mapping option offers logic that allows for the evaluation of multiple criteria sets to determine the output for a given field. There is no Source Details selection for this option, so once Conditional Mapping is selected as the Source, click Edit.

For example, the vendor field PayClass could be one of several values, depending on the country that an employee lives and works in. You can set the Source to Conditional Mapping, click Edit, and then define one or more criteria sets.

Each numbered criteria set can return one Result and each set is made up of one or more conditional statements. If none of the criteria sets evaluate to true, the Else clause will be used.

For each condition, you must define the Criteria Field (field used for comparison), Operator (type of comparison), and Comparison Value (value compared to Criteria Field). The Criteria Field and Comparison Value each also contain source selector drop-down lists, which allow you to compare a source field to another source field, a user defined value, a token, or the result of a transformation of Dayforce fields.

If any selected source field could have more than one assignment per employee, such as a Global Property in an outbound integration, a filter icon is shown to the right of the drop-down. Click the icon to restrict the returned data to a single value. After the filter has been applied, the icon turns blue. Additional information is available in The Importance of Understanding Your Data Structure.

To add additional criteria sets, click Add Criteria Set. To copy an existing criteria set, click the Copy icon at the top right of the criteria set box.

Note: You can use the search bar above the criteria sets to search for user-defined fields, transformation names, token names, source field names, and paths. This is useful for integrations where many criteria sets are configured.

Criteria sets are evaluated in order. Use the Up and Down icons at the top right of the criteria box to rearrange the order of the criteria sets, to ensure that they are evaluated in the appropriate order.

To remove extra criteria sets, click the Trashcan icon in the upper right-hand corner of the criteria set. Also note that each conditional statement has an action icon (three vertical dots) to the right that opens a list of actions available for the corresponding entry. To add or remove a conditional statement, click the action icon and click either Add or Delete.

Important: All conditional statements within a criteria set must evaluate to true in order for the configured result to generate.

Token

The following types of tokens are available in Integration Studio:

• System Tokens - values cannot be edited.
• Configurable Tokens - values change based on the integration run.
• Custom Tokens - values are defined using an IDL expression.

Currently, the following pre-defined tokens are supported:

By default, the LAST_SUCCESSFUL_RUN_DATE tokens listed above are not updated during ad-hoc runs, so that data can be resent without impacting the data this is already included in the next scheduled run. To update the tokens during an ad-hoc run, select the Update Last Successful Run Time checkbox in the Run <Integration> dialog box, and then click Run.

Source Details selection for Tokens is limited by destination field data type.

You can manage tokens used in your integration by clicking Manage Tokens in the mapping step. In the Manage Integration Tokens screen that opens, you can reset the value of a system token in the Configurable Tokens section, if needed. Only system tokens can be reset, such as the INTEGRATION_RUN_COUNT system token and the value you enter must be an integer that is greater than 0.

You can manage all other system tokens in the Static Tokens section.

Transformation

Transformations allow you to manipulate one or more source fields before mapping to a destination field, the Result of a criteria set, or the Else clause in Conditional Mapping. Similarly, a transformation can be used as a Criteria Field or Comparison Value within Conditional Mapping.

There is no Source Details selection, so after you select Transformation as the Source, click Edit, select the appropriate transformation, and populate the required fields.

For example, if the destination vendor field Assignment is a combination of two underscore separated source fields, Position and Department, Source can be set to Transformation and when you click Edit, select the Combine Multiple Fields transformation, give the transformation a sensible name, select Underscore as the separator, and select the appropriate source fields to combine.

If a selected source field in the Transformation configuration can have more than one assignment per employee, such as a Global Property, a filter icon is shown at the right of the drop-down. Click the icon to restrict the returned data to a single value. After you have applied filter, the icon turns blue. More information on this topic is available in The Importance of Understanding Your Data Structure.

Transformation options are limited by data type. For example, to map using Combine Multiple Fields, the destination field Data Type must be set to String. Similarly, to use Add (+) or Subtract (-) Time as a Comparison Value in Conditional Mapping, the configured Criteria Field must have a data type of Date/Time.

Saved transformations can be reused in other field mappings, as well as custom tokens in the File Name and API URL for Event Driven integrations. To reuse a transformation, open the Transformation page and instead of selecting Configure New <Transformation Name>, select the appropriate Saved <Transformation Name>. If a transformation is no longer needed for the integration, delete it by clicking the trash can to the right of the transformation and confirm deletion.

If you delete a saved transformation by clicking the trash can icon to the right of the Transformation drop-down list, it is removed from all fields. To change the loaded transformation, select a different option.

See the “Options in the Transformation drop-down list” table for a full list of available transformations. Multiple instances of the same transformation can be created or differentiated by the transformation name. By default, the transformation options are as shown preceded by “Configure New”. However, once the transformation is saved, the user-defined name is shown in the list preceded by “Saved”. For example, “Configure New Combine Multiple Fields” versus “Saved Combine First, Middle, and Last Name”.

Expression

Expressions allow complex field configuration as well as use of functions not yet available elsewhere in Integration Studio using Integration Description Language (or IDL). For more information about IDL, see Reference: Integration Description Language.

By default, the IDL Expression Editor includes an example of a field level expression. The example expression is removed when you type in the editor. To streamline writing expressions, configure the field manually as much as possible. In Step 3, click View IDL, copy the IDL, and paste it into an expression sourced field. Configure required parameters and update all references to source fields with the newly created parameter names.

Information about IDL syntax and semantics is available in the topic Reference: Integration Description Language.

A full list of IDL functions is available in Functions.

More information about generated IDL is available in the topic View IDL.

Key Topics for Expressions

Key topics for Expressions in this topic are:

• Example Expressions
• Parameters
• Functions
• Configure Parent Level Expressions
• Common Expression Errors

Example Expressions

In general, an expression is a snippet of IDL code which returns a specific value, or in the case of parent level expressions, specific values. Below are examples of simple IDL expressions, abstracted from any particular source, which could be combined to create more complex expressions:

Coalesce Expressions are used to handle values which may be missing in the source. If the value represented by the “possibly_nil_or_missing_value” parameter is missing or nil in the source, the destination will use the provided alternative, “DEFAULT_STRING”.

possibly_nil_or_missing_value ?? "DEFAULT_STRING" 

Boolean Expressions determine whether a given condition is true or false. The example below returns the boolean value false (note that AND has higher precedence than OR):

true && false || true

Mathematical Expressions are used to compute a numeric result:

1 + 2 * 3 - 4 

Returns the value 3. Note that PEMDAS/BODMAS is respected.

Function Call Expressions manipulate data using a function from the IDL function library:

string_concat("test", "ing")

Returns the string "testing".

Function Pipeline Expressions allow chaining of function calls:

date(2024, 3, 18) |> date_add(1, "day")

Returns the computed date 2024-03-19 from the date function call fed into the date_add function call.

If Expressions return a value from one of the defined branches. For example, the expression below will return true as 5 is greater than 4.

if 2 + 3 > 4 { 

    true 

} else { 

    false 

} 

Array Expressions define arrays of data, such as the array of blocks below:

[ 

    { foo = 111; bar = 222; }, 

    { foo = 333; bar = 444; }, 

    { foo = 555; bar = 666; }, 

] 

Block Expressions defines a block (also known as “record” or “object”), composed of key/value pairs. Block expressions can only be configured when the integration has been converted to full IDL.

{ foo = 111; bar = 111 * 222; } --> { foo = 123; bar = 24642; } 

Invalid Expressions are syntactically incorrect, such as when configuring a block expression in a field level or parent level expression, instead of converting the integration to full IDL:

test { 

    item = 123; 

} 

This expression is invalid because it ends in a semi-colon:

    2 + 3; 

This is invalid as a field level expression; however, this is the appropriate format for a destination field titled “test” within a parent level expression:

    test = 1 + 2 * 3; 

Parameters

Before writing an expression, you must define one or more parameter names, select a source, and then map it. The sources include:

• <Source Vendor> Field
• <Source Vendor> Array
• Token
• User Defined Date
• User Defined String
• User Defined Number

Parameters are used to streamline expression configuration; they remove the need to type out the full source field path, and allow for testing. You should refer to them in your expression using the name that you’ve created. After your expression is configured, you can provide test values and click Run IDL with Test Values to see the results in real time.

Note: Run IDL with Test Values is disabled when at least one array parameter is present. For more information about arrays and their importance in your data, see The Importance of Understanding Your Data Structure.

The <Source Vendor> Field and <Source Vendor> Array parameters reference fields or arrays in the source. When a value exists inside the top-level array, such as the XrefCode for an employee in the HR Bulk API, that value can be referenced using a parameter with the <Source Vendor> Field as the source, and the XrefCode field selected in the detail drop-down.

On the other hand, you must use an array parameter to reference a field that is within a sub-array of the source. For example, the Deduction Election array is a sub-array of the employee data top-level array. To reference the XrefCode of the Deduction object within the Deduction Election array, you could configure an array parameter called deds. You would write out the path to the Deduction XrefCode in the expression as deds.Deduction.XrefCode. This is illustrated in the following screenshot:

.

Functions

Functions take inputs, or arguments, and use them to perform specific tasks. Individually the tasks seem simple, such as calculating the difference in days between two dates (DateDiff) or checking to see if something exists (IsMaterial), but expressions allow nesting functions within functions to perform more complex operations. The Expression Editor also exposes mathematical functions, such as addition, subtraction, multiplication, and division.

Note: Mathematical operations follow standard operator precedence (PEMDAS/BODMAS).

Values used as inputs to functions fall into one of the following categories: known, unknown, or missing. In an outbound integration with the HR Bulk API as the source, a known value would be the XrefCode of the employee. This is a required field in Dayforce and will always be present in the source for an employee. By default, the only values included in Dayforce sourced data are known values.

If a field used in the integration is missing in the source, Integration Studio treats it as unknown, or nil. Fields configured without the use of expressions can treat unknown and missing values the same because all references to source data are wrapped in a coalesce function by default. Expressions are built from scratch by the user, and unknown values must be handled explicitly, either by wrapping the parameter in a coalesce function or ensuring the data set used for the integration is present at all times.

Handling missing values is critical to ensuring reliable integrations, because missing values are considered viral. If a field is referenced in configuration without a coalesce function, and it is missing from the source, it is considered missing. As a result, the value on the generated file will be missing, whether the field references a single source value (as with a direct mapping), or several values (such as when concatenating multiple source fields). If any source field referenced in the expression isn’t wrapped in a coalesce function but is missing from the source data when the integration runs, the value on the generated file will also be missing.

Some IDL functions require you to use array parameters to iterate over data, such as:

• Find: Returns a single value from an array of data. For example, returning only Work Assignments that are listed as Is Primary.
• Length: Returns the total number of items in a given array. For example, determine how many direct deposits exist for a given employee and omit records if more exist than can be consumed by the vendor system.
• Min/Max: Returns the smallest/largest value from an array of data. For example, determine whether the Employee or Pay Group setting is smaller or larger for an Earning Election. Or, whether the Hire Date occurred earlier or later than the Rehire Date.

A simple expression on one of the footer or summary fields might sum all of the amounts in a report of earning quick entries. Assuming the parameters defined in Step 2 limit the payroll data to earnings, and an array parameter is defined referencing the top-level source array, src, the following expression would return a running total of all earning amounts reported in the file:

sum(src, qe => qe.Amount)

Alternately, sums might be reported per earning. For example, one field might report the total amount paid of Regular, another Overtime, and yet another Annual Bonus. To accomplish this, each field needs the same source array parameter, src, and a filter prior to the sum:

filter(src, prdata => prdata.CodeName =~ "Regular")
            |> sum(qe => qe.Amount)

Officially, the sum function requires an array as an input, or argument, which you can see in the first of the two preceding example, but not the second, though both are valid expressions. Function pipelines allow the result of one function to serve as the input of another function, without nesting them together. In the second example, the filter function returns an array of items that match the specified criteria (all of the records in the source that have a CodeName of Regular), and that array is fed into the sum function as the first argument via the pipeline |>.

Another important component to functions is the lambda, or anonymous function. Lambdas take the form of arg => expression and are generally required within functions that control or restrict the data returned, such as any, filter, find, map, sum, and so forth. In the example above, the filter function accepts an array as input and uses a lambda to define the filter criteria:

prdata => prdata.CodeName =~ “Regular”

Similarly, the sum function accepts an array as input and uses the lambda to define the field to be summed.

qe => qe.AmountA

Some functions in Integration Studio might look interchangeable, such as is_material and is_nil, but they aren’t. These IDL functions are both intended to check for particular states of data within an expression, such as whether a field has a value of null in the source, or whether an array contains any records. The validation performed by each function is different.

For example, a field in the source is_material if it exists and has a value in the source, but is not null. An array in the source is_material if it includes at least one record. In addition, a field is_nil only when it has a value of null in the source.

is_material(“test”) // ==> true

is_material(“”) // ==> false

is_nil(“”) // ==> false

is_nil(nil) // ==> true

Note: In Integration Studio, nil and null represent the same state. When a field is null in the source, it is nil when being evaluated in IDL.

Configure Parent Level Expressions

Parent Level Expressions allow maximum flexibility in mapping data from source to destination by allowing any number of source arrays to be referenced and mapped to the same set of child fields in the destination. Additionally, otherwise basic configuration with nuance, such as the use of functions and filters for specific fields which cannot be configured in the UI, are possible with parent level expressions.

Some aspects of expression configuration are shared between parent and child fields

• Parameter types are consistent.
• Source Fields must be referenced by way of parameter.
• Source fields within an array must be referenced by way of an array parameter.

Parent level expressions also have unique aspects:

• Child fields must exist before you configure a parent level expression.
• Configuration on child fields occur within the expression on the parent.
• Testing parent-level expressions requires running the integration end to end.

A key use for parent level expressions is the merging of source arrays so that users can reference fields from multiple source collections within the same destination array. For example, to reference values contained in both the Earning and Deduction arrays from the Employee Bulk API in the same set of destination fields, add all of the required child fields under the parent, then edit the parent field to enable “Configure Expression on Parent”. When enabled, any configuration present on the child fields is wiped out and an Edit button appears to the right of the parent field.

By default, a sample expression with each child field listed is shown until you start typing. The final expression must contain the same opening and closing curly braces and each child field under the parent must have a valid IDL mapping. Given three destination fields, XrefCode, Value, and Type, all three would need valid mappings encased in the curly braces to save the expression.

Arrays at the same depth in the source, such as the Earning and Deduction arrays in the Employee Bulk, can be merged using the concat function, then mapped using the map function. For example, the parent level expression below concatenates the mappings for the Deduction Array, deds, and the Earnings array, earns, into the same set of destination fields.

concat(    
                map(deds, ded => {
                XrefCode = (ded.Deduction.XRefCode ?? nil);
                Type = (ded.Deduction.CalculationType.XRefCode ?? nil);
                Value = (ded.EmployeeDeductionParameters.Items.Value ?? nil);
                }),
                map(earns, earn => {
                XrefCode = (earn.Earning.XRefCode ?? nil);
                Type = (earn.Earning.CalculationType.XRefCode ?? nil);
                Value = (earn.EmployeeEarningParameters.Items.Value ?? nil);
            }))

This expression could also be written using function pipelines, first mapping the Deduction array and concatenating it to the mapped Earning array.

map(deds, ded => {...see above example...}
                |> concat(
            map(earns, earn => {...see above example...}))

Arrays of differing depths in the source can be concatenated and mapped in a parent level expression, but only after the required source fields are organized via the flat map function.

The following expression first flat maps the top-level source array, src, with the DeductionElections array and creates a new array composed of the Employee Number and the Election information. This new array is fed as input to the map function, which include the mappings for each child field.

flat_map(src, Employee =>
                map(Employee.DeductionElections.Items, DeductionElection => {
                Election = DeductionElection;
                EmpNumber = Employee.EmployeeNumber;
                })
                )
                |> map(deds => {
                EmployeeNumber = (deds.EmpNumber ?? nil);
                ElectionXRefCode = (deds.Election.Deduction.XRefCode ?? nil);
                ElectionValue = (deds.Election.EmployeeDeductionParameters.Items.Value ?? nil);
            }) 

Note: Nested flat maps can be needed, if the record being reported is more than one layer deep, as in the preceding example.

More information about arrays and their importance in your data is available in the topic The Importance of Understanding Your Data Structure.

Common Expression Errors

This section describes some common expression errors in Integration Studio.

Not an expression

The IDL expression provided isn’t valid. This can happen for a variety of reasons, including but not limited to:

• Unmatched parenthesis
• Inclusion of non-standard named blocks
• Missing semi-colons at the end of a block
• Expression ending with a semi-colon
• General syntax errors
• Unfinished binary operations (for example: 2 +)

Path or variable does not exist: <Variable>

The specified value is undefined, most often caused by a discrepancy between a parameter name as defined and as used in the expression, an undefined parameter used in the expression, or incorrectly entered IDL keywords. 

Wrong return type

The result of the expression is of a different data type than the one defined for the field. Review your expression to determine what the data type of the result is and confirm it matches the fields settings in Step 3.

Cannot apply operator

An operator used in the expression is incompatible with the data types of one or more of the referenced fields. Review your expression for the specified operator with the specified data types and update as appropriate.

Aggregation

Aggregation allows you to count the volume of specific elements processed and report the total in the generated file or payload. This is most commonly used in 834 benefit integrations to report the number of employees, dependents, and the sum of both, included in the file.

Aggregations are configured on numeric child fields, within a hierarchical structure, to count parent fields, or elements, within the configuration. For example, the following integration includes information about an employee’s work assignment, direct deposits, as well as a footer which will show the total volume of employees included in the integration. Each non-root parent (Employee, WorkAssignment, Direct Deposit, Footer) is an element that can be counted.

There is no selection in the Source Details drop-down list, so after Aggregation is selected in the Source drop-down list, click Edit. There is only one Aggregation Type available: Count. Select the element or elements (parent field) to be counted and click Save.