Action Mapping

Once all of the Endpoints are added to the Data Hub, you need to map each Endpoint Action, tying all of your Schema Definitions to the Connectors by mapping how the data needs to flow between systems. Most Connectors utilize JSON or XML language to "talk" to the Common Model; however, the types of maps are dependent on the type of connector data you are mapping to (JSON, XML, SQL, and Delimited Files). The Connector Property field must match the exact naming and language of the Connector.

INFO

When you open the Mapping screen, you will see a black code box on the left, with an open area to add properties on the right. The code box will display the details as you create the Mapping. The Connector data is always shown on the left side in blue text, while the Common Model data (Schema Definitions) is shown on the right side in purple text. The arrows between the Connector and Common Model indicate the direction data will flow. The arrow will always point towards the application receiving the data. Fixed values will always show in orange text.

For example, when a connection is publishing data to the Common Model via JSON protocols, the arrow will point from the Connector to the Common Model. However, when working on the subscribing side, the arrow will point towards the Connector -- since the data is flowing from the Common Model to the Connector.

Advanced Tool

Advanced users can view, and in some cases modify, the underlying configuration that is fed into the engine. To access code view, select the code icon in the top right corner. See Code View for more details.

NOTES

The following instructions for Mapping Endpoint Actions are generically written for JSON protocols; however, each protocol will have its own distinct appearance and follow its own standards (e.g. JSON will present within curly brackets, while XML will present within square brackets).
Additionally, these instructions guide you through the addition of a Simple Property. However, you will select the most applicable Property Type for your protocol and data; then, loosely follow the same instructions.
If a Template was used to configure the Endpoint, some Mapping will be pre-populated; you can edit the Mapping as needed to achieve the desired syncs.
For detailed descriptions of mappable properties for each protocol, see the Mapping Properties of Endpoint Actions per Protocol section below.

Map Endpoint Actions

Edit Endpoint Action Maps

Select Build > Data Hubs from the main menu.
Select the appropriate Data Hub; then, select the appropriate parent Endpoint.
Ensure you are on the Data Source tab, and select the appropriate Event.
Select the menu icon > Edit Maps.
As needed, select + Add Map Group.
NOTE
If the Endpoint was configured using a Template, you will not see this screen as some Mapping will be pre-populated; you can continue to the next step.
Select the top row of the code box on the left side.
NOTE
If you are simply adding a map to the route, then select the top line in the code box. However, when you want to add a map to a specific action (e.g. Saves), select that line in the left pane (specifically, where on the payload you want to add your map).
Select how to map the data via the Add Element selectors and, as needed, toggle ON Make List. Make List allows you to add a list structure instead of an object structure when configuring the mapping payload.
NOTES
- Only mappable options will be displayed based on your configured Endpoints.
- You can add one or more of the Element types to a single Map.
- For detailed descriptions of mappable properties for each protocol, see the Mapping Properties of Endpoint Actions per Protocol section below.
Depending on the method, select a Central Property and/or define the Connector Property. Or, when mapping a File connector, enter a Field Position and Field Width.
NOTE
The Field Position refers to the character position the field starts on; the Field Width refers to how many characters are in the data field you are syncing.
TIP
- To delete a map property, select the delete icon in that row of the code.
- To adjust the order of a Mapping element, select the up or down arrow in that row of the code.
As needed, adapt the data.
NOTE
It is possible to adapt the data as it is published to the Common Model or as an Endpoint subscribes to that data. For additional information and instructions, see the Data Adaptation section.
Repeat the previous steps to construct all of the necessary Mapping.
TIP
While Mapping, select Save as needed; doing so will not close the window.
When finished, select Save; then select Cancel to close the window.

Mapping Properties of Endpoint Actions per Protocol

NOTE

Users should be familiar with XPath to complete Read mapping.

JSON Reads

All JSON Read maps use JSONPath for the Connector Property to tell the mapping engine where on the payload we should map the data from.

Property Type	Description
Property	Maps a single value in a JSON document to a property on your Schema.
Multi-Property	Generally used in tandem with a Transform, it takes multiple values on a JSON document, transforms those values in some way, and then sets the transformed result onto a property on your Schema.
Looping List	Used to bind an array on the connector JSON payload to a list of items on your schema. For example, a Looping List can be used to map the lines of a Sales Order or the Prices of an Item.

JSON Saves

Property Type	Description
Property	Maps a single value on your schema to a property on the connector's JSON input.
Multi-Property	Generally used in tandem with a Transform, it can take multiple properties on your Schema and output a single property on the connector's JSON input.
Nested Property	Used to create a static JSON nested property. Usually used in tandem with another map that is embedded inside of it. For example, in this input: `{ "customerName": { "firstName":"Marc", "lastName":"Johnson"}}`, the nested Property would be "customerName".
Static List	Used to create a static JSON array to insert static items, such as `"itemPrices":[ {"price": 23.12}]`.
Looping List	Used to bind a dynamic list of items on your Schema list to an array of items on the connector's JSON input.

XML Reads

Uses XPath to map the data from the connector to your Schema. It is important to note that the first step in creating an XML Read Mapping is to add the root Element of the XML Document. For example, in a SOAP document, the root is typically <Envelope></Envelope>.

Property Type	Description
Simple Element	Maps a single value in an XML Element or XML Attribute to a property on your Schema. To map the first name value, enter "FirstName." To map from a nested value (e.g. street), enter "Address/Street." For an attribute, enter "Person/@title."
Multi-Element	Generally used in tandem with a Transform, it can take multiple values on an XML document, transform those values in some way, and then sets the transformed result onto a property on your Schema (e.g. to combine a person's first name and last name).
Looping List	Used to map a list of repeating items in the connector XML document to a list of items on your Schema. For example, a Looping List can be used to map the phone numbers into a list on the Schema.

XML Syntax Example

xml

<Person title="Mr.">
  <FirstName>John</FirstName>
  <LastName>Doe</LastName>
  <Address>
    <Street>123 Main St</Street>
  </Address>
  <PhoneNumbers>
    <PhoneNumber type="home">555-1212</PhoneNumber>
    <PhoneNumber type="work">555-2323</PhoneNumber>
  </PhoneNumbers>
</Person>

XML Saves

On an XML Save, your maps will be used to build the XML document that gets sent to the Connector. Every layer of the XML document needs to be built and accounted for in your mapping. You will be mapping both structure and content.

Property Type	Description
Element	Adds an element to the XML with the value selected from the Schema.
Attribute	Attributes can be added to any Element and will map to the value selected in the Schema.
Multi-Element	Generally used in tandem with a Transform, it can take multiple properties on your Schema and output a single Element on the connector's XML input.
Nested Element	Used to create a static XML nested Element. Typically used in tandem with another map that is embedded inside of it. For example, in this input: `<customerName><firstName>Marc</firstName><lastName>Johnson</lastName></customerName>`, the nested Element would be `<customerName>`.
Static List	Used to create a static list of XML items where you can insert static items. For example: `<itemPrices><price>23.12</price></itemPrices>`.
Looping List	Used to bind a dynamic list of items on a list on your Schema, to a list of items on the connector's XML input.

SQL Reads

Property Type	Description
Column	Maps a single value from a database to a property on your Schema.
Multi-Property	Generally used in tandem with a Transform, it can take multiple database columns, transform those values in some way, and then sets the transformed result onto a property on your Schema.

SQL Saves

Property Type	Description
Property	Maps a single value on your Schema to a column on a database.
Multi-Property	Generally used in tandem with a Transform, it can take multiple properties on your Schema and output a single column on the database.

File Reads

Property Type	Description
Column	Maps a single value from a file to a property on your schema.
Multi-Property	Generally used in tandem with a Transform, it can take multiple file columns, transform those values in some way, and then set the transformed result onto a property on your Schema.

File Saves

Property Type	Description
Property	Maps a single value on your Schema to a column on a character delimited file.
Multi-Property	Generally used in tandem with a Transform, it can take multiple properties on your Schema and output a single column on a file.

Fixed-Width Files

Property Type	Description
Property	Maps a fixed character length for each field.

Action Mapping ​

Map Endpoint Actions ​

Mapping Properties of Endpoint Actions per Protocol ​

JSON Reads ​

JSON Saves ​

XML Reads ​

XML Saves ​

SQL Reads ​

SQL Saves ​

File Reads ​

File Saves ​

Fixed-Width Files ​

See Also ​