Operation troubleshooting in Jitterbit Integration Studio

Introduction

If you experience issues executing an operation, the following troubleshooting actions are recommended.

Test the connection

For any operations using connectors, in the connection, click the Test button to ensure the connection is successful.

For Connector SDK-based connectors deployed in operations running on private agents, clicking the Test button ensures the latest version of the connector is downloaded to the agent (unless using the Disable Auto Connector Update organization policy).

Check the operation logs

Check the operation logs for any information written during execution of the operation.

Depending on the agent type, you can do the following to retrieve additional log files and data:

Enable operation debug logging (for cloud agents or for private agents)
Enable connector verbose logging (private agents only)
Check the agent logs (private agents only)

Possible errors in operation logs

The following sections cover errors that may be present in an operation log and their resolution.

Extra subelement warning

An extra subelement warning in the log messages can generally be ignored. This warning indicates a connector's API payload returned more nodes or fields of data than those defined in the response data schema.

Unallowed characters in XML schema mappings

Depending on the connector activity, these characters are invalid and will result in a runtime error:

`\x00` (NULL)	`\x0E` (shift out)
`\x01` (start of heading)	`\x0F` (shift in)
`\x02` (start of text)	`\x1A` (substitute character)
`\x03` (end of text)	`\x1B` (escape)
`\x04` (end of transmission)	`\x1C` (file separator, information separator four)
`\x05` (enquiry)	`\x1D` (file separator, information separator three)
`\x06` (acknowledge)	`\x1E` (file separator, information separator two)
`\x07` (bell)	`\x1F` (file separator, information separator one)
`\x08` (backspace)	`\xD800` to `\xDFFF` (UTF-16 high surrogate characters)
`\x0B` (vertical tab)	`\xFFFE`
`\x0C` (form feed)	`\xFFFF`

When the input or output data being supplied to or returned from a transformation adjacent to an XML-based connector activity contains one of the above characters, a specific error referencing that character is returned at runtime. For example, when the \x1E control character is present in the response transformation for the Epicor Kinetic Get BAQ activity, this error is returned at runtime:

The Exception is Invalid white space character (0x1e) in text to output

Unsupported XML elements when embedded in JSON

Character data (CDATA) sections are not supported with XML embedded in JSON intended to be sent through a transformation. Including CDATA sections can cause the following error to appear in an operation log at runtime:

Transformation failed. Error: The operation "Operation" failed.
Error: Failed to convert XML file to JSON.
org.jitterbit.integration.server.engine.EngineSessionException: org.xml.sax.SAXParseException ...

To work around this, use a Jitterbit script to Replace the &, <, >, ', and " characters of the entire CDATA section, including its definition (<![CDATA[ ... ]]>), with &amp, &lt, &gt, &apos, &quot respectively. If necessary, the entire XML string containing the CDATA section can be replaced if targeting the section does not fit your use case.

The following example is considered invalid without replacements:

{
  "name": "Jitterbit",
  "data": "<xml><content><![CDATA[<greeting>Hello, world!</greeting>]]></content></xml>"
}

Reprocessing of mirrored XML schemas

Due to changes made in Harmony versions 10.25 and 10.27, you may see different behavior in projects created prior to these releases. These changes affect XML schemas that have been mirrored and are most likely to impact mappings that use XML functions that involve namespaces, such as the SelectNodes function. In this case, mappings that were previously valid may now be invalid with an error related to the syntax of the XML function.

Compare the differences between this example mirrored XML schema prior to 10.25 with one created in 10.25 or later:

XML schema annotated

Example XML Schema Prior to 10.25: In projects created prior to 10.25, mirrored XML schemas use the default namespace prefix for XML documents: xsi. As shown highlighted in red above, xmlns:xsi declares the namespace and unmapped fields are displayed in the schema with the attribute xsi:nil="true".
Example XML Schema in 10.25 and Later: In projects created in 10.25 and later and highlighted in green above, mirrored XML schemas use the namespace prefix ns to declare a qualified namespace. Unmapped fields are not displayed in the schema.

In versions 10.25 and 10.26, if you imported a project with a mirrored XML schema that was created prior to 10.25, the schema was reprocessed and changed to use the qualified namespace prefix.

As of version 10.27, imported projects whose mirrored XML schemas were created prior to 10.25 retain the default XML schema namespace prefix so that the schema is identical to that when it was created. This change means that any pre-10.25 projects that are imported into the current version should function as originally designed.

To force a refresh of a pre-10.25 XML schema to use the updated namespace prefix, you can regenerate the schema by refreshing it or reconfiguring the activity that provides the schema.