Mapper 2.0 provides a clear visual representation of both source and destination JSON structures, enabling you to reference sample input data from the source app while building the JSON structure to be sent to a destination app. You can easily build complex JSON structures that include nested arrays and make use of data type validation for required fields and incompatible data types. Mapper 2.0 is available for HTTP and REST API-based imports, as well as file transfer imports like FTP, AS2, and Google Drive.
The Mapper 2.0 interface has four general components:
-
Mapper 2.0 toolbar: Navigate data structures and limit the displayed fields to only those that you are currently working with.
-
Mapper 2.0 field mappings: Modify settings to particular field mappings.
-
Input – source records (upper right in the above screenshot): The full sample data from your source application which shows the record or row JSON structure type.
-
Output – destination records (lower right in the above screenshot): The destination JSON structure you are building which shows the record or row JSON structure type.
Click any layout option that works best as you create or edit mappings using Mapper 2.0.
-
Edit Mapping: <flow step name>: The name of the import flow step to provide a context for your mapping configurations.
-
Mapper 2.0 toggle: Allows you to switch between Mapper 1.0 and Mapper 2.0.
-
Expand all fields: Displays all fields with all subfields expanded.
-
Collapse all fields: Displays only top-level fields with all subfields collapsed.
-
JSON structure record or row format selector: This drop-down list allows you to define the destination JSON structure as records {} or rows [].
-
Input context record or envelope selector: This drop-down list enables you to select an object (default) or envelope that shows all the fields that are available during a run. You can use envelope when you want to map fields such as settings, job, or the like from the available metadata.
-
Refresh fields: Refreshes the source fields available for mapping. Click refresh ()
to display recent changes to your source sample data when mapping fields.
-
Filter by required or mapped fields: Click the filter (
) to view and configure or examine your mappings.
-
Search field names: Click the magnifying glass (
) to open search mode to find source or destination fields by name. Mapper 2.0 displays rows with names that match your search criteria. Adding a new row while in search mode closes search mode. You can use Cmd+F on Mac and Ctrl+F to search and find find specific fields
Note
Empty destination fields will also display in search mode.
-
More actions: Click (
) to perform actions, such as automatically populating the destination fields or automatically mapping the destination fields. You can also remove all or non-mandatory mapping by clicking the available options.
-
Source: It represents the source application. The arrow next to the source indicates that the source data will be sent to the destination fields based on the mapping type and other settings you configure.
-
Type of mappings available to associate your source and destination fields. Click Settings (
) to select the mapping type and configure required fields. The letter next to Settings (
-
A standard mapping is typically used when we send the value of the source field to a corresponding value in the destination field.
-
A hard-coded mapping is used when we assign a fixed value to a field in the destination application, which will apply to all records, and the row displays an
Hard-coded values must use double-quotes; otherwise, they will be treated as expression values. You can't use hard-coded values for object or [object] data types.
-
A {{handlebars}} mapping is used when any value that is not in JSONPath notation or hard-coded (surrounded in double-quotes) is to be interpreted as an expression and the row displays
.
-
A lookup mapping is used when we want to dynamically reference related data from external systems or datasets, which can be either Dynamic, Static, or a Lookup Cache.
-
A dynamic lookup . The row displays
.
-
A static lookup . The row displays
.
-
A lookup cache. The row displays
. You can also add a field value path, which is a JSON notation path (for example, address.city or results[0].id) that tells the system exactly which specific piece of data to extract from the stored cache record once a match is found using the key.
-
-
-
Destination: It represents the destination application that's shown next to the heading. For example, HTTP.
-
Destination fields: Enter the name of the destination field you want to build. Begin typing the name of the field to quickly find it from the list.
Note
You can save a destination field without having mapped it to a source field
Datatype
Select the datatype of the destination field you want to build. You can also choose an object or array of objects.
-
Source fields: Select the source field you want to use to populate the destination field. Your selection is represented in JSONPath syntax for example,
$.user.locationor$.recordid.. Begin typing the name of the field to filter the list by field name.Note
You can't save a source field without having mapped it to a destination field. However, you can save a destination field without mapping it to a source field.
Datatype
-
Select any of the datatypes for your source field/data/ A visual cue will show the selection you've made. For example, T will indicated that you've selected a string datatype.
-
-
Drag-and-drop row handle: After selecting a row, click and hold the dotted icon at the start of the row to reorder the rows.
-
Handlebars editor:: Click the Handlebars editor (
to write and review your handlebar expression. If you're not familiar with JSON, then click to open the handlebars editor and use Celigo Ora to easily and quickly create your handlebar expressions.
-
Add row: Add a new row to the current hierarchy level of the destination JSON structure.
-
Delete row: Click the garbage can (
) to delete the row. This option only displays on hover over the row.
Click the mappings () button on an import flow step to open Mapper 2.0.
Click the switch to change your view between Mapper 1.0 and Mapper 2.0.
Consider the following points when switching between Mapper 1.0 and Mapper 2.0
-
Mapper 2.0 is the default for new mappings or imports that do not yet have any mappings saved.
-
Imports that have mapping configurations only in Mapper 1.0 will open in the Mapper 1.0 interface.
-
Imports that have any mapping configurations in Mapper 2.0 will open in the Mapper 2.0 interface (even if Mapper 1.0 contains mapped fields).
-
If you have mapping configurations entered in both Mapper 1.0 and Mapper 2.0, when you click Save all mappings configured in either version are saved. However, the flow will use only the mappings configured in Mapper 2.0 when the flow runs.
-
To use any mappings you create using Mapper 1.0, you must:
-
Delete all mappings from the Mapper 2.0 interface.
-
Verify that the record or row structure is set to Create destination record {} from source record {}/[].
-
Delete all empty lines from Mapper 2.0.
-
For instructions on mapping fields with Mapper 1.0, see Map source record fields to destination.
Click Create destination record {}/[] from source record {}/[] to set the record or row structure to send to the destination API.
integrator.io automatically recognizes the record or row structure of your source data.
The following examples demonstrate how record or row structures change the output data.
Records that result in empty outputs, such as {}, [], [null], are ignored when sent to file providers, databases, warehouses (during bulk or batch insert operations), or HTTP import operations without a postMap script. These empty records are not inserted into the target system or passed downstream. If the import contains a postMap hook, this behavior does not apply, and the records can be handled according to your script logic.
The Input context setting is a a very useful configuration that determines the structure of the incoming data payload and how fields are referenced. There are two primary options: record and envelope.
The record context is simple and limited in scope, focusing only on the raw, core data from the source application. Referencing is direct, with the record as the root (for example, $.field). This option is best suited for straightforward integrations that only require the core business data for processing.
The envelope context is comprehensive. It wraps the core data record with essential runtime metadata and execution details. Because the envelope acts as the root, the core data record is nested (for example, $.record.field). The main advantage of the envelope option is the access it provides to dynamic runtime objects. These include job details ($.job.*), settings ($.settings.*), and query or path parameters ($.queryParams.*, $.pathParams.*).This option is therefore useful for advanced scenarios. It allows for clean, direct JSONPath referencing of both the core data and the crucial metadata, eliminating the need for complex Handlebars expressions to access runtime execution details.
When working with data structures that contain hundreds of fields it can become difficult for you to find all required fields throughout your destination data structure. For example, if you use Auto-populate destination fields to generate your destination fields, click the filter (), check the Required fields box, and click Apply to examine the values in the required fields. You can also check the Mapped fields box, and click Apply to view the already mapped fields and if the fields aren't mapped, you can use Auto-map destination fields
If you're mapping fields from an HTTP/REST-based connector or using a file transfer import with sample file configured, click Auto-populate destination fields to automatically generate the destination JSON structure with the destination app's expected field names. Click Auto-map destination fields to automatically map each JSON element to its corresponding source field. Click Remove all mappings if you decide to start over. Click Remove all non-mandatory fields to remove all the non-required destination fields from the mappings.
When you configure mappings, you need not provide prompts. In Mapper 2.0, after the destination fields are populated, you can select one or more fields and click to auto-map the destination fields.
You can either choose to auto-map all fields, a single specific field, or multiple specific fields. When you select a parent-level field, all the fields below that parent are automatically selected. Auto-map doesn’t overwrite the mapping values that already exist or are entered manually. After you select the fields, click Auto-map selected destination fields. For more information, see Auto-map destination fields using Celigo AI.
It auto-maps all selected un-mapped destination fields, that is the ones that do not have the source field added. When auto-map is clicked, all options that modify the existing destination structure will be disabled. Close auto-map to go back to mappings.
Note
The option is enabled only when you add new mappings/fields. After the fields are mapped, the auto-map destination fields option is disabled.