Custom Mapping Overview

With Chain.io’s Custom Mapping feature, users can create their own data mappings providing more flexibility within their flows, and allowing greater control over how data points are handled. The Custom Mapping feature now offers users the ability to tailor data transformations to meet unique business requirements, enhancing data compatibility and integration flexibility.

This feature utilizes a query and transform language called JSONata to query and transform your data. It is specifically designed for use with JSON data. It comes packed with built-in operators and functions that let you manipulate and combine data effortlessly. You can find more about best practices when using JSONata here.

Getting Started with Custom Mapping

Accessing Custom Maps

To begin using Custom Maps, navigate to Workspace Settings in the Chain.io Portal, and select Custom Mappings under the Developer Center.

This will display the Custom Maps page, where you’ll see a list of existing maps created for your workspace.

From this view, you can either edit an existing map or create a new one. To start a new map, simply click New Mapping. Alternatively, if you would like to edit an existing map, click the Edit button next to a map.

The Mapping Editor

Once you've selected or created a map, you’ll enter the Mapping Editor.

The Chain.io Mapping uses the JSONATA transform language to convert your input data to your preferred output format.

Within the editor, you’ll see three primary panels:

1. JSON Data (Left Column) – This is where you’ll insert your JSON data source. Your source file can be JSON, XML, CSV or EDI formats.
2. JSONata Expression (Right column) – This is the column you would use to write your JSONata expressions for mapping your data. You can refer to our basic expressions article for more information on writing JSONata expressions.
3. Output (Right) - This panel will show you the results of the mapping and the output of writing your expressions. For more information please refer to our guild on mapping data.

As you develop your JSONata expression, the Results section will update in real-time, allowing you to preview the transformation results.

Mapping Targets

You can pre-populate your JSONata Expression pane with a sample structure based on an existing JSON file.  Use the Select a Mapping Target dropdown to either upload a file from your computer or select a pre-made sample for common Chain.io data types including most logistics related EDI formats.

Versioning & Deployment

You can save multiple versions of a map by clicking the Save Version button.  To make a version available to use in a flow, you must deploy it by clicking Deploy as New Version.  

TIP: You can have different versions deployed to different flows which is helpful when you are testing a new version in a QA flow while keeping the older version in your production flow.

By default, the editor displays the latest map version. If you wish to work on a different version, select it from the revision dropdown. To view only active versions (those available for integration use), check the Active Versions Only box.

Lookup Tables

Lookup tables allow you to create value mappings between data in your source and your target.  Learn more here.

Using Maps In A Flow

To implement a custom map within a flow:

1. Navigate to the desired Integration Settings in the Workspace where you created the mapping and open the Flow Configuration.
2. In the Custom Processors section, you’ll find fields labeled Input File Map and Output File Map. These fields allow you to select the appropriate map for your data inputs and outputs.
   
3. After selecting the map from the drop down, you will then be prompted to select a version of the map you would like to use. Select the version you want.
4. By default, Chain.io names each processed file using the following format: {file_name}_{map_name}_{map_version}_{milliseconds}.json, making it easy to identify. However, if you prefer to retain the original filename, check the Preserve File box.

Once you are finished with your custom map configuration, save and deploy the flow to begin taking advantage of your custom map.

Learn more about configuring flows here.

Next: Mapping Data In The Chain.io Mapping Editor