Troubleshooting

Integrations can typically fail due to invalid data or malformed configurations. To begin troubleshooting, answer the following questions:

• Where is the integration failing?
• Where does the error message point?

Or you can see some additional information about Common Errors and Possible Resolutions.

Where is the integration failing?

Click the error status in the Integration Studio Home page to load the error log, go to System Admin > Background Jobs and click the Job Logs tab and search for the Integration Processor background job. There are three types of tasks that run for each integration:

If the integration failed during the RetrieveDataTaskStatuses step, the issue lies with the API call or related parameters.

If the integration failed during the ManipulateDataTaskStatuses step, the issue is related to the required manipulation (for example: batching), invalid data, or incorrect configuration.

If the integration failed during the TransmitDataTaskStatuses step, the generated file or payload cannot be sent to its final destination, potentially due to invalid security credentials or routing information, or both when, sending to SFTP or external API endpoint, or invalid Recipient ID when sending through DF Link.

Each task type includes an assortment of tasks which contain more information about the error encountered. More information on the specific error messages you might encounter is described in Common Errors and Possible Resolutions.

You can get more information about integrations that you ran previously by reviewing the information shown under the Integration Response tab in the View Job Information dialog box. You must have the Integrations > Integration Studio > Integration Response Log role feature enabled for your user role to see the Integration Response tab.

Where does the error message point?

Error messages include which task failed as well as a general message about the issue. For example, when an integration fails during the ManipulateDataTaskStatuses step, the error message references a specific task and includes additional information in the body of the error, as illustrated in this screenshot:

The task name and status are clearly labeled, as is the message indicating the issue. In this case, the task that failed is TransformIntegrationPlatformTask, the message includes the MappingSource.idl tag, the error is Path is ambiguous, and the field at issue is EmployeeProperty_XrefCode. More information on how to use the MappingSource.idl tag for troubleshooting is available in View IDL.

RetrieveDataTaskStatuses and TransmitDataTaskStatuses also reference a specific task, but might have fewer details about the issue. For example, the error in the following screenshot includes all relevant details for an error when transmitting a file to an SFTP server: step failed for an integration set to be delivered to an SFTP the error message references a different task:

However, if a request or transmission to an API fails, you can find additional information by clicking the Actions icon and clicking View Log, which opens the Integration Log screen. Click the link in the Status column for the run in question to open the View Job Information dialog, and then click the Integration Response tab.

Common Errors and Possible Resolutions

Path is ambiguous

Integration Studio is unable to determine which source field to evaluate because more than one option exists. This is often a configuration issue which can be traced back to one of two things:

• A field referenced in the integration exists inside a source array and a 'Choose Record' filter is required to select the correct source record.
• One or more fields referenced in the integration should exist under an array parent in the destination structure.

The first is common across all output types, but the second will only apply when the destination structure includes one or more parent fields.

If the field referenced in the error message is assigned once per record (for example, the First Name of the employee or Background Job Log Id for a particular background job) or the error detail includes the word source in the path (as in the screen shot below), the field you are referencing must exist within a parent array.

More information on configuring your destination fields, and what it means to reference data from within an array, is available in the following topics, respectively:

• Map Fields from a Source to a Destination
• The Importance of Understanding Your Data Structure

Condition matched multiple elements in the array

Multiple values were returned by the Choose Record filter. For example, if an employee has two work assignments with the same Job (Position) and the Choose Record condition is matching on the XRefCode of the Job, the integration will error because all Choose Record filters are expected to match on only one instance in the array.

Round

A non-numeric value is mapped to a destination field that is formatted as a number where rounding might be required. For example, mapping the Dayforce Field First Name to a numeric destination field:

There is/are (a) non-unique sort key(s)

This error can occur when a unique record couldn’t be identified based on the ordered list Choose Record configuration on the listed line and column number in the error. For example, a Choose Record configured to return the first work contract in a list of work contracts sorted oldest to newest based on the start date would generate this error if the Source Data included two or more work contracts with the same start date.

Param ‘array’ must have type ArrayValue, BlockValue, but was NilValue

All expression variables are wrapped with a coalesce function, so that if the field or array parameter value is missing in the source, Integration Studio assumes a nil (or unknown) value. For field parameters, this works without issue. However, referencing arrays that are then filtered or otherwise manipulated in the expressions can cause this error when the array is missing in the source. For example, the following expression and parameter configuration generate the preceding error when the Data > Contacts array is missing in the source.

concat(
                Contacts |> filter(ci => ci.ContactInformationType.XRefCode =~ "BusinessEmail"), 
                Contacts |> filter(ci => ci.ContactInformationType.XRefCode =~ "PersonalEmail")
                )
                |> map(ci => ci.ElectronicAddress)
                |> then(emails => if length(emails) > 0 { first(emails) } else { 
            omit() })

The expression can be modified to use an empty array when it doesn’t exist in the source:

concat(
                (Contacts ?? []) |> filter(ci => ci.ContactInformationType.XRefCode =~ "BusinessEmail"), 
                (Contacts ?? []) |> filter(ci => ci.ContactInformationType.XRefCode =~ "PersonalEmail")
                )
                |> map(ci => ci.ElectronicAddress)
                |> then(emails => if length(emails) > 0 { first(emails) } else { 
            omit() })

Failed to Transmit Data

If the file cannot be transmitted, it’s typically due to invalid credentials, authentication and authorization problems, or because of a poorly formed request. This information can only be viewed in the Integration Log, in the Integration Response tab. More information is available in the topic Integration Log

There are several types of responses.

Failed to Connect.

Integration Studio can’t connect to the SFTP server using the connection parameters provided. There are several possible error messages: