Resolve transformation mapping conflicts and errors in Jitterbit Integration Studio

Introduction

Transformation mappings must be valid for a transformation to be valid. This page describes how to identify invalid mappings and view the validation errors associated with them. It also explains how to resolve validation errors.

To prevent validation issues, see Test and validate transformations.

Validation errors

Transformations are treated the same as other project components when identifying component validity on a project scale. You can identify invalid transformations on the design canvas and in the project pane, as described in Component validity. Validation errors within a mapping are included in the validation of transformations.

For a transformation to be valid, it must not have any validation errors within the transformation itself. To be considered valid, a transformation must meet these rules:

• A mapping cannot contain references to non-existent fields or variables.
• A mapping cannot contain data-type conflicts.
• A mapping must use valid script syntax.
• A target loop node cannot have multiple sources.
• A schema must be provided for an adjacent source or target activity.

In addition, certain target fields may require a mapping, or may not allow a mapping. For example, a child table's joined fields cannot be mapped to. Additional details are provided under Validation rules later on this page.

To resolve validation errors, you can identify errors within the transformation itself and make adjustments accordingly. Invalid mappings are displayed either for an entire target field block, or for individual mapped objects within a target field block.

Entire target field

When an entire target field mapping is invalid, a red vertical line appears along the left of the target field block. A warning icon is displayed in the top right of the target field. When you hover over the warning icon, the reason for the mapping being invalid is listed.

This type of invalid mapping may result from mapping of fields that cannot be mapped. For example, this error occurs when you attempt to map to a unique object ID on a Salesforce Insert activity used as a target.

When an entire target field mapping is potentially invalid, an orange vertical line appears along the left of the target field block. When you hover over the field, the reason for the mapping potentially being invalid is listed.

This type of invalid mapping may result from the absence of a mapping that may be required. For example, this error occurs when a primary key is not mapped on a Database Insert activity used as a target.

Invalid or potentially invalid mappings may also result from multiple objects (such as more than one source object or variable) being mapped to a target field without any logic specifying how to process those objects.

To resolve invalid mappings, either remove the mapping, or open the field's script to add processing logic. Potentially invalid mappings are intended to flag a potential problem but can be left as is if you have determined the mapping is valid.

To remove a mapping, hover on the target field and use the Remove mapping icon.

To add processing logic to a field with an invalid mapping, hover on the target field and click the Edit icon.

Individual mapped object

When an individual mapped object within a target field is invalid, the mapped object is outlined in red with a warning icon displayed on the right:

Individual mappings may be invalid if a mapped source object is no longer present after editing a schema, if there is a required/optional mismatch with the cardinality of a target field, or if source and target fields have incompatible data types.

The mapping of source and target fields with potentially incompatible data types is flagged for all schemas regardless of whether they have defined data types, such as those defined from a Salesforce or Database activity. This flagging also occurs for schemas that have data type labels only, such as those defined from a sample file or that have been manually defined. For these types of schemas, all fields are handled as strings regardless of whether they have data type labels.

A data type mismatch does not necessarily indicate there is a problem with the mapping. For example, if a source field with an integer data type is mapped to a target field with a string data type, the resulting data is a string that contains a numerical value. Source fields with any data type can be mapped to a target field with a string data type, so these mappings are not flagged.

However, if the reverse is true, and a source field with a string or other data type is mapped to a mismatched target data type, such mappings may be flagged as potentially incompatible. Mapped fields with data types that are potentially incompatible are displayed with an orange border:

When you hover over the field, the reason for the potential incompatibility is listed. To remove the mapping, click the Remove mapping icon.

The indication of a potential data type mismatch appears only for simple mappings of a source object to a target field, and is not displayed if the target field contains scripting logic.

For target fields that are mapped using scripting logic, after the script is processed and the resulting output is evaluated, the value is converted to the data type of the target field it is being mapped to. You are expected to know, based on the output being converted to the target field data type, whether this final output is the desired result.

As an example, consider a target field with a double data type. Regardless of the type of data in the script, after the script is processed, the final output for the mapping is converted to a double. This is illustrated with the transformation script examples below.

<trans>
1 + "string"
</trans>

The script above evaluates to a value of "1string" with a string data type. Then, during processing of the transformation mapping, this output is converted to a double data type. Because the output begins with a digit, any beginning digit(s) carry over to the final mapping output, as numbers are valid for a double. The final output for the mapping is a value of 1 with a double data type.

<trans>
"string" + 1
</trans>

The second script, above, evaluates to a value of "string1" with a string data type. During processing of the transformation mapping, this output is converted to a double data type. In this case, because a non-digit value, which is not valid for a double, is at the beginning of the returned value, no value is carried over. Instead, the target field takes the default value for a number. The final output for the mapping is a value of 0 with a double data type.

In some cases, you may want to override the data type of the target field and actually carry over output using a different data type. For these situations, you can use the Format or FormatDate functions within the target field mapping script. Make sure that the function is in the last statement of the script, as the returned value of the script always comes from the final line.

Validation rules

For a transformation to be valid, it must be configured properly. The error messages described below are displayed when viewing the validation errors associated with the transformation as a component from the design canvas or project pane, as described in Component validity.

If a transformation has not been configured or is misconfigured, this validation error message is returned:

Transformation is not configured properly.

This message most commonly appears when you have added a new transformation to an operation and it has not been configured yet. To resolve this error, open the transformation configuration screen, then configure the transformation accordingly. It is not required for a transformation to contain mappings if its target schema consists of only nodes without fields. If the target schema contains fields, at least one mapping must be present for the transformation to be configured properly.

In addition, for a transformation to be valid, it must not have any validation errors within the transformation itself. To be considered valid, a transformation must meet these rules:

• A mapping cannot contain references to non-existent fields or variables.
• A mapping cannot contain data-type conflicts.
• A mapping must use valid script syntax.
• A target loop node cannot have multiple sources.
• A schema must be provided for an adjacent source or target activity.

In addition, certain target fields may require a mapping, or may not allow a mapping. For example, a child table's joined fields cannot be mapped to. Invalid mappings are visually indicated within the transformation configuration screen, as described under Validation errors earlier on this page.

Depending on the error, the appropriate variation of these possible error messages is returned if this rule is not met:

Mapping refers to a non-existent [source / target / variable] field $[path].

Potential data type conflict in mapping.

Target field $[node.name] [must be mapped / cannot be mapped].

Target field $[node.name] is linked to [database joins] of its parent. You cannot map a value to this element.

records: Error on line [#]: [Script validation syntax error].

Mappings of a target loop node depend on more than one source loop node.

[Source / Target] schema must be provided.

To resolve these errors, try these troubleshooting tips:

• If you have references to non-existent fields, data-type conflicts, or other invalid mappings, either find the invalid mapping and unmap it or check the schema to make sure all fields are accounted for and have compatible data types. If you have references to non-existent variables, check to make sure the variable exists.
• If you have script validation errors, check the mapping and make adjustments within the script. Validation messages are also displayed below each script reported on a line-by-line basis. After resolving an error on one line, additional syntax errors to resolve may be reported for subsequent lines. Continue making changes until the message indicates the script is valid.
• If you have source or target activities adjacent to the transformation, make sure you provide a schema for each one. You can provide schemas from within the activity itself during its configuration (see documentation for each connector), or by defining a schema from directly within the transformation.

In addition, if a transformation is invalid for some other reason that cannot be readily determined, this error message is returned:

Transformation is invalid.

For more information about prevention and troubleshooting, see the following resources:

• Test and validate transformations to catch issues early.
• Data structures in Key concepts for proper structure.
• Schema processing for data conversion rules.