What is a Transformation Mapping?

A transformation mapping is a fundamental piece of the Graphite Connect Transformation Engine. Combining the Transformation Engine with Transformation Mappings will allow you to implement more complex business logic into you Public API response, such as character limits, source to target value mapping, visibility conditionals and much more.

Transformation Mapping Document

Transformation Mappings are defined in an Excel document, with a tab named Transformation Mapping. The columns of the document are defined in the Transformation Mapping Specification.

Anatomy:

Transformation Document:

A Transformation Document defines all of the Transformation Mappings owned by a given entity. Whenever the transformation document gets loaded into Graphite Connect, all existing mappings will be synchronized, all new mappings will be added and all missing mappings will be removed.

Mapping Group

A mapping group is a group of several individual Transformation Mappings. By utilizing Mapping Groups, you are able to inline mapping expressionsto split complex expressions and utilize the inline transformation key to better organize large and complex objects. Mapping Groups are defined by using the Mapping Name key in (see specification for more details.)

Transformation Mapping (Fields)

A Transformation Mapping (also called a field) specifies an individual row in the transformation mapping document. A transformation mapping owns all of the logic that will determine the value and the visibility of the row for a given connection. Please view the Transformation Mappings Specification for more details on required fields.

Loading the Mapping Document

Transformation Mappings are Environment Specific

When you load your transformation mapping, it will only be loaded into the environment you are in. Don't forget to load this document into higher environments when you are finished with your testing!

To load the transformation document into Graphite Connect, please visit the Loader documentation for more information.

Transformation Mapping Specification

Title	Description
Owner	The Graphite Connect Public ID owns this mapping. Required: Yes
Mapping Name	The name of the Mapping Group that this mapping is assigned to. See Mapping Group for more information. Required: Yes
Field Name	The name of the Mapping within a Mapping Group. See Transformation Mapping for more information. Required: Yes
Source Expression	The value that the transformation mapping will return. The syntax uses the Source Expression Language to dynamically set the value for a given connection. For more complex source expressions, see inlining mapping expression . Required: Yes if Default is omitted
Default Value	The default value that the transformation mapping will return. If the Source Expression field evaluates to `undefined`, the value of the mapping will evaluate to this. The syntax uses the Source Expression Language to dynamically set the value for a given connection. Required: Yes if Source Expression is omitted
Mapping Condition	A boolean Source Expression that determines whether the transformation mapping will appear in the API Response. If this evaluates to `true` OR no mapping condition is provided, then the transformation mapping will appear. Required: No
Translation Table	The name of the Translation Table to do source to target value mapping. The translation table converts the value AFTER all of the other expressions that modify the resulting value are evaluated. If the value is not found within the translation table, the value will be set to the `Translation Table Fallback` specification if provided, otherwise will be set to its original value. Required: No
Character Limit	A number for the maximum amount of characters that should be returned by the expression. This will substring the resulting value if it is greater than the limit provided. Required: No
Date Format	For date fields, the format that the date should be provided in. This value gets passed into the `format` function of MomentJs. Syntax of the format string is defined in MomentJs Documentation. Required: No
Translation Table Fallback	The value which should be returned if the mapping value is not found within the Translation Table. The syntax uses the Source Expression Language to dynamically set the value for a given connection. Required: No
Default Empty String	By default, if the final result of the expression is `""`, `null`, or `undefined`, the mapping field will be omitted in the response. Set this to `yes` to send `""` instead of omitting. Required: No

Inline Mapping Expressions

In the Source Expression column of a Transformation Mapping, you can reference other mappings values by utilizing the source expression key syntax.

If the field exists within the same mapping group, you can reference other fields by simply using <fieldName> (replace fieldName with the fieldName you are trying to reference)

If it exists in another mapping group, the other field must be specified by using the syntax <mappingGroupName.fieldName> (replacing mappingGroupName with the mapping group that the field exists in and fieldName with the name of the field you are trying to reference)