Map source record fields to destination

Data mapping allows you to define how integrator.io formats the source application’s data to fit the schema of the destination application. integrator.io applies your data mapping rules to link and transfer each field value in the source data to its corresponding field in the destination application record schema. 

Contents

• Define response mapping
• Advanced data mapping
  • Standard
  • Hard-coded
  • Lookup
    • Dynamic search
    • Static: Value to value
  • Multi-field
• Field mapping type indicators

Edit mapping

Use the Edit mapping panel to configure how the source application’s export data will match what is expected by the destination application.

To edit an import mapping, click the integration tile on your homepage, open the flow that contains the data you want to map, and click the Field mapping icon. 

Note: If you don't see the mapping icon, click + in the flow step to reveal the option.

The Edit mapping panel opens.

The Export field column lists the source application data fields, and the Import field lists the import destination application data fields.

These fields are drop-down lists that reveal the available data record fields for each application. For standard mapping, select a data field in the Export field drop-down menu to match one of the fields on the Import field column.

If your field names and field types have a 1:1 correspondence, and you want to accept the default error handling, click Save & close. Otherwise, continue with advanced data mapping. 

Advanced data mapping

To set up advanced mappings, click the gear icon on a row to open the Settings panel and explore advanced options for configuring data mapping.

Data type: Select the type of data that the destination application expects for this field.

You can choose one of the following options:

• Boolean
• Date
• Number
• Number array
• String
• String array

The purpose of the Data type is to prepare the field for import. For example, data exported from the source application as a number (12) can be defined as a string data type ("12") on the Export field column. Then if its corresponding import destination application field also expects a number data type (12) as a value, set the Data type of the Import field to Number.

Discard if empty: Specify the action to take when the source application’s export record data field contains no data.

• If unchecked, integrator.io keeps the data field and maps the empty value to the import application
• If checked, the import record will not even contain the field that was empty in the export record

Immutable (advanced): Check to always import records, even if they generate errors from the destination application. By default, if a record fails to import into an application, integrator.io will parse the error message from the import application. If a specific field can be identified in the error message as the root cause for the import’s failure, then that field will be removed and the import will be retried again automatically. For most fields, this behavior is intended, so that single fields do not halt entire records from importing. However, there are some fields where it is imperative that the field always gets set. For those fields, check Immutable to tell integrator.io not to remove the field for an automatic retry.

For example, if during the import process the destination application responds with a business rule violation (“Phone number is not in a valid format”), then integrator.io removes the problem field from the record being imported and retries the import for that record. In the first attempt the record being sent to the import application might look like this:

{
  "Name": "Mary"
  "Age": 45
  "Phone": "650-485-3937"
}

Assuming the phone number is in an unacceptable format with hyphens, integrator.io receives an error returned by the destination application. If Immutable is unchecked, integrator.io removes "Phone" from the record and retries the import. The record sent in the second attempt looks like this:

{
  "Name": "Mary"
  "Age": 45
}

Assuming this record is now accepted by the destination application, the flow continues to transfer the data until the transfer is complete or another error occurs.

In some cases, dropping the field from the record is not ideal – such as for email, ID, or any other critical required field. In such cases, mark the field as immutable to disable the retry functionality. If checked, integrator.io will not retry the record transfer, and the record will fail to be imported. 

Standard field mapping

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

Occasionally a required import data field may be missing from the exported source data, or the source data field is there but it’s empty, set to null, or undefined. In such cases, integrator.io interprets the value as “not found.” The import generates an error unless you define which action you’d like the integration to take.

• Use empty string as default value: Set the data field on the import destination application to empty and delete the error-generating data in that field
• Use null as default Value: Set the data field on the import destination application to null and delete the error-generating data in that field
• Use custom default value: Populate the data field on the import destination application with the value you enter and delete the error-generating data in that field

Hard-coded field mapping

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.

• Use empty string as hard-coded value: Populates an empty string ('') into this field
• Use null as hard-coded value: Populates a null data type into this field
• Use custom value: Populates the string that you enter (below for Enter default value) into the mapped field

Lookup field mapping

Use this option to retrieve information from an alternate location to populate fields. Lookups can either be dynamic or static.

Dynamic search

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

A dynamic lookup can search the destination application data records to find a match to the exported source application data field value. For example, the lookup could match records by email address or user ID from the exported source data. You can specify a data field in a particular location of the destination application’s database for the dynamic lookup to search for a matching record. If the lookup finds a match, the secondary data is identified and written to the configured data field on the destination application record.

For example, if the export field is Email and you want to find the corresponding record match in the import application, you can use the value in the exported source application’s Email field to search the destination application for a record with that same email address to match the record.

In the Mappings panel, for Export field column, define the field in the source data record that you want to use to identify a matching record in the destination application, such as Email. For the Import field column, define which field in the destination application you want dynamic lookup data to be written.

Click the gear icon next to the field and set the Relative URI for pinging the destination application API to request the search. For example,
     /customers/search?email={{export.email}}

Define the HTTP method (GET or POST).

Define the Resource identifier path, which is the path the dynamic lookup uses to locate the unknown data in the request response. For example,
     searchResults[0].name

This dynamic lookup might return:

{
  "count": 1,
  "searchResult": [
    {
      "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 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 the default behavior by defining the action integrator.io takes if a unique match is not found. The actions available are the same as those for standard mapping.

Static: Value to value

If you already know how a specific field in the source application data should map to a corresponding field in the destination application, then you can use a static lookup to define the value pair.

For example, if the source application’s export record has a field named “state” that should be mapped to the field “State” on the destination application’s import record. You can define these fields in the Mappings panel.

Open the Settings panel for that field to set up a Static lookup table. For each value pair, define the possible options for the exported data (CA, ID, AK) and the corresponding import value for each option (California, Idaho, Alaska).

Action to take if value not found: If a required import data field is missing from the exported source data, or the source data field is there but it’s empty, set to null, or undefined, integrator.io interprets the value as “not found.” The import generates an error unless you define the action that you’d like the integration to take.

• Fail record: This option (selected by default) excludes the record from import and flags the record as failed.
• Use empty string as default value: Set the data field on the import destination application to empty and delete the error-generating data in that field.
• Use null as default value: Set the data field on the import destination application to null and delete the error-generating data in that field.
• Use custom default value: Populate the data field on the import destination application with the value you entered and delete the error-generating data in that field.

Multi-field field mapping

Use multi-field mapping to merge multiple fields from a source application’s export data into a single field on the destination application’s import data. You can also use multi-field mapping to append data to existing field data or extract a certain number of characters from a source application’s export field to use in a destination application’s import field.

Multi-field mapping relies on handlebars expressions. You enter the handlebars expression in the Expression field, or use the Function and Field drop-down menus to create the expression framework. 

For example, if your source application's export data has multiple address fields like billing address, mailing address, and business address, but your destination app only has a billing address field. You can configure Flow Builder to write all of the values for all of the address fields from your export record into the billing address field in your destination app.

Function: Select helper methods like AND, ADD, or AVG, that let you transform your field values.

Field: Select the fields from your source application’s export data. (The options in this drop-down menu vary according to the function selected.)

Expression: The text of the handlebars expression automatically populates according to the selected function and field. You can modify the default expression from this text box.

Action to take if value not found: If a required import data field is missing from the exported source data, or the source data field is there but it’s empty, set to null, or undefined, integrator.io interprets the value as “not found.” The import generates an error unless you define which action you’d like the integration to take.

• Use empty string as default value: Set the data field on the import destination application to empty and delete the error-generating data in that field
• Use null as default value: Set the data field on the import destination application to null and delete the error-generating data in that field
• Use custom default value: Populate the data field on the import destination application with the value you entered and delete the error-generating data in that field

Field mapping type indicators

Letters next to mapped values indicate the field mapping type.

• H - Hard-coded: City is a hard-coded mapping value.
• L - Lookup: Country is a lookup mapping value.
• M - Multi-field: Transaction_date is a multi-field mapping value.
• none - Standard: Product is a standard mapping value.

For information about response mapping, see Response mapping for flows with multiple destination applications.