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:

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:

• 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.

Special characters in connector-provided JSON schemas

When a transformation uses a JSON schema inherited from an adjacent connector activity, any special characters in a schema field or node name are replaced by underscores (_).

When using the legacy JSON processing (the default for projects created prior to the 11.48 Harmony release), this behavior may cause errors to be returned from the endpoint.

For example, if the activity provides a field name of location_ids[], it is converted to location_ids__, however, the endpoint still expects the original field name of location_ids[] and returns the error, such as "error_message": "{location_ids:expected String to be a Array}",}}.

To resolve this issue, follow these steps:

1. Confirm a JSON schema is being used in the affected activity. Such schemas will have a root node named json:

   

2. Configure the project to use the Preserve JSON names processing by toggling on the Preserve JSON names project setting (agent version 11.48 or later is required).

3. Reconfigure, deploy, and run the operation.

   Important

   When Preserve JSON names is toggled on in a project where it is currently disabled, note that the Preserve JSON names processing will be used only for operations and schemas configured after the setting is enabled. That is, existing operations and schemas will remain using legacy JSON processing. We recommend reconfiguring all existing operations and schemas in such projects, as using both schema processing methods in a single project may cause inconsistencies in the project.

When using the Preserve JSON names processing, you can verify the field or node name being passed to the endpoint by viewing the jsonPropertyName in the activity's input or output data when debug logging is enabled (for cloud agents or for private agents). The value of the jsonPropertyName is the value being sent in the request: