Mapper 2.0

Rate this feature
Included in the Nov. 2022 release 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. 

Contents

• Mapper 2.0 functionality
  • Mapper 2.0 toolbar
  • Mapper 2.0 field mappings
• Switch to Mapper 2.0
• Set record or row structure
• Filter by required fields
• Filter by mapped fields

Mapper 2.0 functionality

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 and Source format (upper right): The full sample data from your source application and identifies the record or row JSON structure type.

• Output and Destination format (lower right): The destination JSON structure you are building and identifies the record or row JSON structure type.

Mapper 2.0 toolbar

1. Edit Mapping: <flow step name>: The name of the import flow step that has your mapping configuration applied.
2. Mapper 2.0 toggle: Allows you to switch between Mapper 1.0 and Mapper 2.0.
3. Destination record or row format selector: This drop-down list allows you to define the destination JSON structure opening and closing characters as records {} or rows [].
4. Refresh fields: Refresh the source fields available for mapping. Click the refresh () button to display recent changes to your source sample data when mapping fields. 
5. Expand all fields: Displays all fields with all subfields expanded.
6. Collapse all fields: Displays only top-level fields with all subfields collapsed.
7. Filter by required or mapped fields: Click the filter ( ) to display only required fields, only mapped fields, or only mapped and required fields. You can’t modify existing mappings or add new fields in filter view. Set the filter to All fields to modify mappings or add new fields.

8. Search destination field names: Click the magnifying glass () to open search mode to find destination fields by name. Mapper 2.0 displays and highlights only destination fields with names that match your search criteria. Adding a new row while in search mode closes search mode.

Note: Empty destination fields will also display in search mode.

9. Auto-populate destination fields or Remove all mappings: If you are 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. You can then map each JSON element to its corresponding source field. Click Remove all mappings if you decide to start over. It will remove all the non-required destination fields from the mappings.

Mapper 2.0 field mappings

1. Drag-and-drop row handle: Click and hold () to move a row to a different position in the JSON hierarchy.
2. Destination field: Enter the name of the destination field you want to build. You can save a destination field without having mapped it to a source field.
3. Destination field data type: Select the data type of the destination field you want to build.
4. Source field: The source field accepts the following values:

   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.

   • The JSON path to the source field: $.user.location
   • A hard-coded value in double-quotes: "testValue". The row displays an next to the source field when the value is interpreted as hard-coded. 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}} expression. Any value that is not in JSONPath notation or hard-coded (surrounded in double-quotes) is interpreted as an expression. The row displays an next to the source field when the value is interpreted as an expression.
     
   • A dynamic lookup. The row displays a next to a source linked to a dynamic lookup.
     
   • A static lookup. The row displays an next to a source linked to a static lookup.
     

5. Source field data type: Select the data type of the source field.
6. Source field selector: Select the source field you want to use to populate the destination field. Your selection is represented in JSONPath syntax. Begin typing the name of the field to filter the list by field name.

7. Destination field settings: Click the Settings () button to configure field settings. The options available change depending on the destination field data type you have selected.
8. Add row: Add a new row to the current hierarchy level of the destination JSON structure. 
9. Delete row: Click the garbage can () to delete the row. This option only displays on hover over the row.

Switch to Mapper 2.0

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 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:
  1. Delete all mappings from the Mapper 2.0 interface.
  2. Verify that the record or row structure is set to Create destination record {} from source record {}/[].
  3. Delete all empty lines from Mapper 2.0.

For instructions on mapping fields with Mapper 1.0, see Map source record fields to destination.

Set record or row structure

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.

• Example 1: Record-to-record mapping
• Example 2: Record-to-row mapping
• Example 3: Row-to-record mapping

Filter by required fields

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. If you used Auto-populate destination fields to generate your destination fields, click the filter ( ), check Required fields, and click Apply to display only required fields.

• A padlock () displays next to all required fields.
• You can’t modify existing mappings or add new fields in filter view.
• Set the filter to All fields to modify mappings or add new fields.

Filter by mapped fields

When working with data structures that contain hundreds of fields it can become difficult for you to find all destination fields that have already been mapped to their source field counterparts. If you used Auto-populate destination fields to generate your destination fields, click the filter ( ), check Mapped fields, and click Apply to display only mapped fields.

• A padlock () displays next to all required fields.
• You can’t modify existing mappings or add new fields in filter view.
• Set the filter to All fields to modify mappings or add new fields.