Custom Mapping Tool

Created by Brian Glick, Modified on Wed, 5 Nov at 5:26 AM by Brian Glick

In this article:

Overview
- Best Practices
- Additional Resources
Accessing the Custom Mapping Tool
Creating a New Mapping
Editing a Mapping
Adding a Lookup Table
Versioning and Deployment
Deleting a Mapping
Using a Custom Mapping in a Flow

Overview

Chain.io's Custom Mapping Tool turns complex data transformation into a fast, flexible task. Use the Custom Mapping Tool to have more integration flexibility and customization of your data mappings within your Flows. The JSONata Expression panel provides greater control over how data points are handled between uploading an input file and producing a customizable output file. Finally, the vast selection of file output formats offers you the opportunity to instantaneously tailor data transformations and guarantee data compatibility when exchanging information between suppliers, freight forwarders, customers, customs authorities, and financial institutions.

Best Practices

To ensure successful data translations with your mappings and Flows:

Test the Flow with sample data before going live.
Document your mapping decisions for future reference.
Use descriptive names for your mappings.

Additional Resources

This article explores the general usage and functionality of the Custom Mapping Tool.

For more information on the Custom Mapping Tool functionality, watch our Custom Mapping Tool Overview video.
For more information on mapping EDI files, refer to the Mapping EDI Files in the Custom Mapping Tool support article.
For more information on mapping XML files, refer to the Mapping XML Files in the Custom Mapping Tool support article.

Accessing the Custom Mapping Tool

To utilize Chain.io's Custom Mapping tool, first sign in to your Chain.io portal account at https://portal.chain.io/.

At the top menu bar, click Workspaces and select the desired Workspace.
At the top right of the screen, click Workspace Settings from the hamburger menu.
Navigate to the Developer Center subsection.
Click Custom Mapping Tool.

Use the Custom Mapping tool to create, edit, and manage your data mappings. If you have an existing mapping, it will appear in the table on the Workspace Maps page.

Click edit on the row of an existing mapping to edit it in the Custom Mapping tool or create a new mapping.

The Custom Mapping tool displays three columns:

- Input (1st/left column) - Input your source data in this column either by uploading a file or copying and pasting your data directly into the column. Accepted formats are JSON, XML, CSV, or EDI.
- JSONata Expression (2nd/middle column) - Your JSONata transformation logic template will appear automatically in this column after you select an output file type in the third panel on the right. Write your JSONata expressions for mapping your data in this column. Refer to our Guide to JSONata Mapping Expressions for more information on how to craft JSONata expressions.
- Output (3rd/right column) - The results of your mapping and adjustments to your JSONata expression will appear in this column in real-time.

Creating a New Mapping

Create a new mapping by clicking the blue New Mapping button in the bottom right corner of the Custom Mapping Tool page.
You can edit the mapping's name by clicking the pencil icon. For the purposes of this example, we are using a simple naming convention; however, it is helpful to provide a descriptive name for your mapping so it is easily identifiable in your Flow configurations.
Next, select Choose File to upload a file.
Within the Output panel on the right, you can select the output file type. The options are JSON, CSV, and XML
For the output file, you can select a Mapping Target from a list of common logistics file formats, like EDI or JSON.

You can pre-populate your JSONata Expression panel with a sample structure based on an existing JSON file. You can also use choose a file type from the the Select a Mapping Target dropdown list.

Editing a Mapping

To edit an existing mapping, begin at the Custom Mapping Tool page.

Find the name of the mapping that you wish to edit.
Click Edit on the right side of the mapping row.
In the Custom Mapping tool, edit the mapping's name if necessary, by clicking the pencil icon.
Manually edit the JSONata expression if necessary, to customize your solution. The output in the 3rd panel on the right will populate and update in real-time. You will know instantly if your mapping is working and what data is flowing through.

JSONata Cheatsheet

To access a quick reference guide on JSONata, consult this JSONata Cheatsheet. This link is also available on the Custom Mapping Tool page.

Adding a Lookup Table

Lookup Tables are helpful to translate codes. Event codes are an example of types of codes that are commonly translated. Other examples of codes that can be translated include package type, organization, and container type.

Example

CargoWise uses the codes DEP for departure and ARV for arrival, while EDI codes are usually expressed as VD for departure and VA for arrival. To send an event from CargoWise to output an EDI 315, which includes status details, you would upload a Lookup Table that you previously created, or insert the values in the Lookup Table manually within the Custom Mapping tool to convert the DEP to VD.

CargoWise uses the codes DEP for departure and ARV for arrival, while EDI codes are usually expressed as VD for departure and VA for arrival. To send an event file from CargoWise to output as an EDI 315, which includes status details, you can upload a Lookup Table CSV file that you previously created, or insert the values into the Lookup Table manually to convert all instances of DEP to VD and instances of ARV to VA.

To add a Lookup Table, begin in the Mapping Editor.

In the upper right area of the page is the Lookup Tables section. Click the blue “+” on the right to add a Lookup Table.
Assign a Table Name.
If you have not yet uploaded a CSV file, the "key" and "value" columns will be blank. After uploading a CSV file, the table will populate.
In the bottom left corner of the pop-up window, click CSV Upload to upload a file.
In the bottom right corner of the pop-up window, click the blue Save Table button.

Next, the Mapping Editor will refresh for this particular mapping. The Lookup Tables drop-down menu will populate with the most recently added table.

Learn more about Lookup Tables here.

Versioning and Deployment

The Save Revision feature allows for version control of your mapping.

You can save multiple versions of a mapping by clicking the blue Save Revision button above the 3rd column on the right, after each iteration of revisions made to your mapping. Revert to a different version of the mapping by selecting the drop-down list next to "Select Revision."
To make a version available to use in a Flow, deploy it by clicking the blue Deploy as New Version button above the 3rd column on the right.

The pop-up window will confirm that deploying this mapping will lock in the data type that you specified. All future mappings using this revision will be of this file type. If another data type is needed, a new mapping must be created.
Confirm the deployment by clicking the blue Create Version button.
Note that the page will not change, but your deployment is confirmed.

Next, you can navigate to a Flow to update the mapping version associated with the Flow.

Deleting a Mapping

To remove a mapping from your account:

Begin on the Custom Mapping Tool page. Click “delete” on the right of the mapping row.
Confirm the mapping deletion by clicking the red Delete button.

The mapping can be deleted as long as it is not already associated with a Flow.

Deleting a Mapping Currently Used in a Flow

If you attempt to delete a mapping that is currently associated with an enabled Flow, an error message will appear stating "Cannot Delete Mapping." The name of the Flow associated with the mapping you attempted to delete will appear at the bottom of the pop-up window. The mapping must be unassociated with a Flow and the Flow must be disabled in order to delete the mapping.

Click the associated Flow name to edit the Flow details.
Deselect the mapping from the Flow.
Within the menu on the right side of the page, click Save, to save changes to the Flow.
Within the same menu, click Deploy, to activate the changes to the Flow.
Within the same menu click Disable Flow.
At the top right of the screen, click Workspace Settings from the hamburger menu.
Scroll down to Developer Center.
Click Custom Mapping Tool.
Click delete on the right of the mapping row to delete the mapping.

Using a Custom Mapping In A Flow

To implement a custom mapping within a Flow:

At the top menu bar, click Integrations.
If you have existing Integrations, select the desired Integration. Refer to the Integrations article for more information on creating new Integrations.
At the top right of the window, click Workspace Settings from the hamburger menu.
If you have an existing Flow configuration, select the desired Flow.

Refer to the Creating A Basic Flow article for more information on how to configure a Flow within an Integration.
Navigate to the Custom Processors section.
Within the Input File Map and Output File Map fields, select the appropriate mapping to associate with the Flow.

Note: EDI files are not able to be selected in the pre-processor and post-processor fields.
Select the appropriate version of each mapping.
By default, Chain.io names each processed file using the following format: {file_name}_{map_name}_{map_version}_{milliseconds}.json.

If you prefer to retain the original filename, check the Preserve File box.
Click Save to confirm your custom mapping configuration.
Click Deploy to initiate the Flow's employment of the mapping.

Learn more about configuring Flows here.

Next: Mapping Data In The Chain.io Mapping Editor