Custom Mapping Overview

Modified on Fri, 22 May at 2:14 PM

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 Mapping Tool under the Developer Center.

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

The following columns will be visible:

Name – The name of the map
Input Type – The format of the incoming data (e.g., json, edi)
Output Type – The format of the output data (e.g., json)
Description – An optional description for the map
Latest Saved Version – The timestamp of the most recently saved version
Latest Deployed Version – The timestamp of the most recently deployed version
Last Updated By – The user who last modified the map

Each column can be sorted and filtered using the controls in the column headers.

Creating a New Map

From this view, you can create a new map using one of two buttons in the upper right corner:

New Inbound EDI – Creates a new map and an associated inbound EDI flow from a specification and sample file. Use this option when setting up EDI-to-JSON mappings as part of a new flow.
New Standard Mapping – Creates a blank standard map that you can configure manually in the Mapping Editor.

To edit an existing map, click the Edit link in the row for that map. You can also remove a map by clicking Delete.

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.

You can name your map in the top left corner.

The editor is made up of three panels:

JSON Data (upper left panel) – This is where you load your source data. Click Choose File to upload a file from your computer. The panel supports JSON, XML, CSV, and EDI input formats. Once a file is loaded, you can switch between the Original File tab (your raw source data) and the Converted JSON tab (the data after it has been parsed into JSON for use in your expressions).
JSONata Expression (right column) – This is where you write the JSONata expressions that define how your source data is transformed. A JSONata Cheatsheet link is available in the top right of this panel for quick reference. You can also use the AI Assistant (accessible via the ✦ AI Assistant button in the panel header) to get help writing or troubleshooting expression.
Output (bottom left panel) - This panel displays the real-time results of your JSONata expression as you type, allowing you to preview the transformation output immediately. You can set the output format using the type selector (e.g., JSON). Use the Select a Mapping Target dropdown to pre-populate the JSONata Expression pane with a sample structure — you can select from pre-made samples for common Chain.io data types (including logistics-related EDI formats) or upload your own file.

Versioning & Deployment

The Mapping Editor supports saving multiple versions of a map.

Save – Saves the current state of the map as a new version without making it available for use in flows.
Save & Deploy – Saves the current version and deploys it, making it available for selection in flow configurations.

By default, the editor displays the latest map version. If you wish to work on a different version, select it from the All Revisions dropdown at the top of the editor. Check the Only list deployed versions checkbox to filter the list to versions that have been deployed and are available for use in flows.

Click Version Info to view metadata about the currently selected version.

Tip: You can deploy different versions to different flows. This is useful when testing a new version in a QA flow while keeping a stable older version active in your production flow.

Lookup Tables

Lookup tables let you create value mappings between your source data and target output. You can attach a lookup table to a map using the Select a Lookup Table dropdown in the editor toolbar. Click the + button to create a new lookup table directly from the editor.

Reference the lookup table in your JSONata mapping to convert source to destination values.

Managing Flows from the Editor

The Manage Flow button in the top right of the editor provides a shortcut to the flow(s) associated with the current map, making it easy to navigate between your map configuration and the flow settings where it is used.

Using Maps In A Flow

To implement a custom map within a flow:

Navigate to the desired Integration Settings in the Workspace where you created the flow and open the Flow Configuration.
In the Custom Processors and Mappings 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.
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.
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 Name box.

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