Help Center

SynchUP Academy

Mapping & Translations

SynchUP Mapping - Translation Engine

The SynchUP Translation engine provides users with a straightforward method for modifying basic mappings and configuring default values. Here we outline the necessary requirements and highlight the various features available for this purpose.

Overview

Each SynchUP Job includes a Translation Engine schema. Within each Job, there is an entity that is associated with a default schema. The default schema performs a direct copy of each property on the Job, maintaining a one-to-one mapping. However, users have the flexibility to modify these mappings or establish default values. Additionally, a schema encompasses translation rules and relationships.

Anatomy of a schema

A SynchUP Translation Engine schema is created using XML. The root XML node of a translation schema should be named 'translationSchemas'. As a child of the translationSchemas root node, there should be a node named 'rootSchema'. This serves as the entry point for the translation schema when a SynchUP Job is executed.

<translationSchemas>
    <rootSchema>

    </rootSchema>
</translationSchemas>

Afterwards, you may place your translation rules as children of the rootSchema node in the XML. When SynchUP processes your translation rules it will process them in order of first to last. So, if you have multiple rules targeting the same properties, you may only see the result of the last rule.

<translationSchemas>
    <rootSchema>
        <translate action='copy' from='Id' to='Id' />
        <translate action='copy' from='ExternalId' to='ExternalId' />
    </rootSchema>
</translationSchemas>

Translation Engine - Translate Rules

There are two different types of translation rules that can be written:

translate
- This allows you to map, or copy, a value from one location to another
- It also allows you to set default values and override data points that came from another system
relationship
- These are additional child schemas that allow you to map complex child objects in your MCO

Each of these child XML nodes must be labeled as either 'translate' or 'relationship'. Additionally, these XML nodes can contain various XML attributes that alter the functionality of the rules. In the following sections, we will delve into the details of these attributes.

Translate XML Attributes

XML Attributes for the translate rule include:

action
- The possible values for this attribute are 'copy' and 'default'.
from
- The specific MCO property or attribute from which you would like to copy the value.
to
- the specific MCO property or attribute to which you want to copy the value
fromIsAttribute
- This field is optional, and its default value is false when not specified. If the 'from' property represents a concrete MCO value, the value should be set to false. However, if the 'from' property refers to an attribute on the MCO, the value should be set to true.
toIsAttribute
- This field is optional, and its default value is false when not specified. If the 'to' property represents a concrete MCO value, the value should be set to false. However, if the 'to' property refers to an attribute on the MCO, the value should be set to true.

value
- When the 'action' property is set to 'default', this value will be used to set the MCO property specified in the 'from' property.

Translate Rule Examples

1. Copy Action

When utilizing a default translation schema, each concrete property on the MCO is automatically configured with a 'copy' rule that performs a one-to-one copy from the puller system to the pusher system. In the example below, two copy rules are implemented to extract the Id value from the origin system and copy it to the Id field in the destination system. The same process applies to the ItemNumber field.

<translate action='copy' from='Id' to='Id' />
<translate action='copy' from='ItemNumber' to='ItemNumber' />

If you have a scenario where you need the Id from the origin system to be transformed into the ItemNumber in the destination system, you can customize the rules mentioned above. It is important to retain the first rule to ensure that the Id is copied over. By replacing 'ItemNumber' in the 'from' attribute of the second rule with 'Id', you can change the mapping so that the Id is displayed as the Item Number in the destination system.

<translate action='copy' from='Id' to='Id' />
<translate action='copy' from='Id' to='ItemNumber' />

2. Default Action

If you prefer to have a default value present in the destination system, regardless of the data pulled from the origin system, you can modify the translate rule action to 'default'. This will ensure that the specified property on the MCO always contains the desired value.

In the example below, we set the Status property to always be "Pending". When using the default translate action, you need to provide the 'to' and 'value' XML attributes. The 'to' XML attribute represents the property on the MCO that you want to populate, and the 'value' XML attribute is the default value that you want that property to have.

<translate action='default' to='Status' value='Pending' />

Using Attributes with Translation Rules

MCO Attributes are present at every level of every Entity on the MCO. Attributes serve as a means to transfer additional data from one system to another, such as custom data, scripted data, or extraneous data. If you are using a system that includes this type of data, you may want to map it to or from attributes.

When using the 'from' or 'to' property on a copy or default translate action, the SynchUP translation engine assumes that you are referring to a concrete property on the MCO. If what is specified in a 'from' or 'to' XML attribute does not exist as a concrete property on the MCO, a validation error will occur, and you will not be able to enable your Job. If the field you are trying to reference in your 'from' or 'to' field is actually an attribute on the MCO, you must define it as such using the 'fromIsAttribute' or 'toIsAttribute' XML attributes. These attributes are boolean fields that default to false when not specified in your translation schema. However, you can add them to any translate rule.

In the provided example, we have created a custom field named Addressee in the origin system. This field is represented as an attribute on the MCO called 'Addressee'. Our objective is to display the value of this field in the 'FirstName' field of the destination system.

<translate action='copy' from='Addressee' fromIsAttribute='true' to='FirstName' />

Take note that we only need to include 'fromIsAttribute=true' since 'from' comes from an attribute on the MCO. On the other hand, 'to' does not require 'toIsAttribute' as it is a concrete property on the MCO and is already assumed to be false.

Tip: The SynchUP Translation Engine automatically copies attributes over without any translation rules necessary. Any attribute present on the Puller MCO will be present on the Pusher MCO. That means while the following rule is possible, it is redundant and unnecessary:

<translate action='copy' from='Addressee' fromIsAttribute='true' to='Addressee' toIsAttribute='true' />

Translation Engine - Relationship Rules & Schemas

Translation rules outlined above are able to copy simple properties on the MCO or set default values. However, every MCO Entity in SynchUP contains properties that are arrays or are complex objects. In that event, we must use a Translation Engine Rule called a Relationship and relate that to a defined Schema.

Setting up child Schemas for complex objects

You have the flexibility to create multiple schema XML nodes within the translationSchemas of your Translation Schema. These nodes serve as a collection of translation rules that can be associated with complex properties on the MCO. Each schema node must have a unique id, which can be chosen according to your preference. It is recommended to use a descriptive id for better understanding.

<translationSchemas>
  <rootSchema>

  </rootSchema>
  <schema id='AddressSchema'>
    <translate action='copy' from='AddressLine1' to='AddressLine1' />
    <translate action='copy' from='AddressLine2' to='AddressLine2' />
  </schema>
</translationSchemas>

You may have as many schemas as you'd like. They all must appear under the rootSchema node in the XML.

Note: schemas may not be nested within another schema. All schemas should appear as a child node under the translationSchemas node. rootSchema must be present as the first child node under translationSchemas.

An example of a Translation Schema with multiple child schemas:

<translationSchemas>
  <rootSchema>

  </rootSchema>
  <schema id='DefaultAddressSchema'>
    <translate action='copy' from='AddressLine1' to='AddressLine1' />
    <translate action='copy' from='AddressLine2' to='AddressLine2' />
  </schema>
  <schema id='CompanyAddressSchema'>
    <translate action='default' to='AddressLine1' value='123 Awesome St' />
    <translate action='copy' from='ScriptedAdd2' fromIsAttribute='true' to='AddressLine2' />
  </schema>
</translationSchemas>

Relationship XML Attributes

XML Attributes for the relationship rule include:

schemaId
- the name of a schema present in the Translation Schema
from
- The specific complex MCO property from which you would like to associate the defined schema.
to
- The specific complex MCO property to which you would like to associate the defined schema.

Relationship Rule Examples

1. Simple Relationship

When utilizing a default translation schema, each complex property on the MCO is automatically configured with a 'relationship' rule that relates a schema. In the example below, we have a customer Entity with a child billing address address associated to the customer.

<translationSchemas>
  <rootSchema>
    <translate action='copy' from='FirstName' to='FirstName' />
    <translate action='copy' from='LastName' to='LastName' />
    <relationship schemaId='AddressSchema' from='BillingAddress' to='BillingAddress' />
  </rootSchema>
  <schema id='AddressSchema'>
    <translate action='copy' from='AddressLine1' to='AddressLine1' />
    <translate action='copy' from='AddressLine2' to='AddressLine2' />
  </schema>
</translationSchemas>

2. Many-to-one Relationships

Schemas can be associated with multiple complex objects of the same type. For example, if you have a customer object with both a billing address and a shipping address, you only need to create one schema and associate it with both properties.

<translationSchemas>
  <rootSchema>
    <translate action='copy' from='FirstName' to='FirstName' />
    <translate action='copy' from='LastName' to='LastName' />
    <relationship schemaId='AddressSchema' from='BillingAddress' to='BillingAddress' />
    <relationship schemaId='AddressSchema' from='ShippingAddress' to='ShippingAddress' />
  </rootSchema>
  <schema id='AddressSchema'>
    <translate action='copy' from='AddressLine1' to='AddressLine1' />
    <translate action='copy' from='AddressLine2' to='AddressLine2' />
  </schema>
</translationSchemas>

3. Multiple Schemas for Same Child Type

If you encounter different mapping scenarios for two properties of the same type, you have the option to create separate schemas. By using the relationship schemaId, you can specify the appropriate schema for each property.

<translationSchemas>
  <rootSchema>
    <translate action='copy' from='FirstName' to='FirstName' />
    <translate action='copy' from='LastName' to='LastName' />
    <relationship schemaId='AddressSchema' from='BillingAddress' to='BillingAddress' />
    <relationship schemaId='SpecialAddressSchema' from='ShippingAddress' to='ShippingAddress' />
  </rootSchema>
  <schema id='AddressSchema'>
    <translate action='copy' from='AddressLine1' to='AddressLine1' />
    <translate action='copy' from='AddressLine2' to='AddressLine2' />
  </schema>
  <schema id='SpecialAddressSchema'>
    <translate action='default' to='AddressLine1' value='123 Awesome St' />
    <translate action='copy' from='ScriptedAdd2' fromIsAttribute='true' to='AddressLine2' />
  </schema>
</translationSchemas>