Mapper 2.0 (beta)

Rate this feature
Included in the Sept. 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 using Mapper 2.0. Mapper 2.0 (beta) 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
• Switch to Mapper 2.0
• Set record or row structure
• Destination field settings
  • Field mapping types
    • Standard
    • Hard-coded
    • Handlebars expression
    • Lookup
  • Destination field is date field
  • Action to take if source record field has no value
  • Advanced (available only for HTTP composite methods)

Mapper 2.0 functionality

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. 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.

6. Destination field: Enter the name of the destination field you want to build.
7. Destination field data type: Select the data type of the destination field you want to build.
8. Source field selector: Select the source field you want to use to populate the destination field. Your selection is represented in JSONPath syntax.
9. 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.
10. Add field: Add a new field to the current hierarchy level of the destination JSON structure. 
11. Input and Source format: The full sample data from your source application and identifies the record or row JSON structure type.
12. Output and Destination format: The destination JSON structure you are building and identifies the record or row JSON structure type.

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

Destination field settings

Click the Settings () button to the right of the field mapping to configure additional mapping settings.

Destination data type: displays the selected data type for the destination field you are mapping. Select a different value to change the data type.

Field mapping types: Select the type of mapping you want to apply to the destination record field. The field mapping types available change depending on the data type you select.

The following field mapping types are available for each data type.

Note: Objects and object arrays can either be copied directly to the output or constructed using the Mapper 2.0 interface. If you choose Create object in mapping, each field contained in the object or object array can then use the field mapping types available for its data type.

Standard

Send the value of the source field as the value in the destination field. This is the default setting, indicating that data found in a specific field in the export should map to its corollary in the import application (1:1 direct mapping). 

Hard-coded

Set the source field to a defined value for the destination field. Use this setting if you prefer to have the same value written to this imported data field for every record, regardless of the exported value.

How would you like to hard-code the value?: Select one of the following options:

• Use empty string as default value: Inserts empty string
• Use null as default value: Inserts null value
• Use custom default value: Inserts custom string value

Custom value: Enter the value to send to the destination field. This field only displays if you choose Use custom default value from How would you like to hard-code the value?.

Handlebars expression

Build a handlebars expression for the value in the source field to send to the destination field. 

Handlebars expression: Enter a simple handlebars expression in the field, or click the AFE () button to open the Handlebars advanced field editor (AFE).

Lookup

Define a static value-to-value mapping or use the results of a dynamic search to populate the destination field value. 

Lookup (Dynamic)

If your integration requires further information from a secondary source in order to determine which record in the destination application data matches a record of the source application data, you can create a dynamic lookup search to retrieve the information needed to match the records.

Relative URI: Enter the relative URI that will be appended to the address displayed below the field. Using the above example, if you enter  /customers/search?email={{export.email}}, the call to retrieve data for your lookup will be sent to https://us15.api.mailchimp.com/customers/search?email={{export.email}}. The handlebars expression {{export.email}} would be replaced with the email address stored in the source data email field for each call. Click the AFE () button to create a handlebars expression to dynamically populate the relative URI.

HTTP method: Select GET or POST. Consult the lookup destination app developer documentation for which method to choose.

Resource identifier path: Enter the JSON path where the dynamic lookup will locate the lookup data in the request response. For example, if you enter searchResults[0].name, the dynamic lookup might return:

{
  "count": 1,
  "searchResults": [
    {
      "name": "Mary"
      "id": 1234
      "email": "mary@email.com"
    }
  ]
}

In this example, the value mary@email.com in the field email for a record in the source application’s data matched a record in the lookup destination application’s data based on that email address. The positive result instructs integrator.io to locate the name field in the response and write the value Mary to the field name in the destination application’s record.

If a unique match is not found when performing a dynamic lookup search, by default integrator.io marks the record as failed and does not transfer data for that record. You can alter that behavior by selecting an option from the If lookup fails drop-down list.

Lookup name: Give the lookup a unique name so that it can be easily identified for use in other flows. You can select any dynamic lookups used in other flows to this destination app.

If lookup fails: If no match returns from the lookup search, the record fails by default. integrator.io then marks the record as failed and does not transfer any data for that record. You can select one of the following alternatives if needed:

• Do nothing: The record is skipped.
• Fail record (default): integrator.io marks the record as failed and does not transfer any data for that record.
• Use empty string as default value: Inserts empty string.
• Use null as default value: Inserts null value.
• Use custom default value: Inserts any string value you enter in the field provided.

Lookup (Static)

If you already know how a specific field value from the source application data should be replaced before being sent to the destination application, then you can use a static lookup to define how each value should be replaced.

For each Source field value, define the corresponding replacement Destination field value that will be sent to the destination application.

For example, if the source data has a field named state that should be mapped to a corresponding field named Region on the destination application’s import record, but the naming conventions are not the same because the source data references states with the two-letter convention (AL, AK, AZ) and the corresponding import value for each state uses the full name of the state (Alabama, Alaska, Arizona), you could add all 50 states as Source field values using the two-letter convention, and Destination field values as corresponding full state names. This ensures that each two-letter state name in the source data would be replaced by the full state name during import.

Source field value: Enter a value that this field may contain in the source application data.

Destination field value: Enter the corresponding value as it would be replaced when sent to the destination application.

Note: An additional empty line is added to the list with each new value you add, and you can click the Delete () button on the right to delete any line.

Lookup name: Give the lookup a unique name so that it can be easily identified for use in other flows. You can also select any static lookups used in other flows.

If lookup fails: If no match returns from the lookup search, the record fails by default. integrator.io marks the record as failed and does not transfer any data for that record. You can select one of the following alternative options if needed:

• Do nothing: The record is skipped.
• Fail record (default): integrator.io marks the record as failed and does not transfer any data for that record.
• Use empty string as default value: Inserts empty string.
• Use null as default value: Inserts null value.
• Use custom default value: Inserts custom string value.

Destination record field is date field

Check this box if the destination field requires a date format. Additional date field options display if this box is checked.

Date field options

Source record field date format: Select the date format for the source field.

Source record field date time zone: Select the time zone for the source field.

Destination record field date format: Select the date format for the destination field.

Destination record field date time zone: Select the time zone for the destination field.

Action to take if source record field has no value

Select one of the following options when the mappings return an empty value. The options available vary according to data type, and the behavior of each selection varies according to which version (Mapper 1.0 or Mapper 2.0) you use to map your fields. 

Data type	Action to take if source record field has no value	Mapper 1.0	Mapper 2.0
string	Use empty string as default value	Inserts empty string
	Use null as default value	Inserts null value
	Use custom default value	Inserts custom string value
	Do nothing (default)	Removes field name and value
number	Use empty string as default value	Inserts 0
	Use null as default value	Inserts 0	Inserts null value
	Use custom default value	Inserts custom number value
	Do nothing (default)	Inserts 0	Removes field name and value
Boolean	Use empty string as default value	Inserts false	N/A
	Use null as default value	Inserts false
	Use custom default value	Inserts false	Selects true or false
	Do nothing (default)	Inserts false	Removes field name and value
object	Use null as default value	Inserts empty array	Inserts null value without object formatting
	Do nothing (default)	Inserts empty array	Removes field name and value
[string]	Use empty string as default value	Inserts empty array
	Use null as default value	Inserts empty array	Inserts null value without array formatting
	Use custom default value	Inserts empty array	Inserts custom values as array ["a", "b", "c", "d"]
	Do nothing (default)	Inserts empty array	Removes field name and value
[number]	Use empty string as default value	Inserts empty array
	Use custom default value	Inserts empty array	Inserts custom number values as an array [1, 2, 3, 4]
	Use null as default value	Inserts empty array	Inserts null value without array formatting
	Do nothing (default)	Inserts empty array	Removes field name and value
[Boolean]	Use empty string as default value	Inserts empty array
	Use custom default value	Inserts empty array	Inserts custom values as an array [true, false, false]
	Use null as default value	Inserts empty array	Inserts null value without array formatting
	Do nothing (default)	Inserts empty array	Removes field name and value
[object]	Use null as default value	Inserts empty array	Inserts null value without object formatting
	Do nothing (default)	Inserts empty array	Removes field name and value

Description: Enter an optional description of the settings configured for this field.

Advanced (available only for HTTP composite methods)

Advanced options only apply to HTTP imports that use composite methods. Only perform mapping when:

• Creating a record: Choose this option if the mappings you create will apply only to new records you create in the destination application.
• Updating a record: Choose this option if the mappings you create will apply only to existing records in the destination application.