Map source record fields to destination

There are three types of mapping: import, results, and response. Mapping data defines how your records are compared, merged, or transformed from one application to another. Import mapping defines how your source record data relates to your destination record data. Results mapping defines how data returned from an application should be merged back into your source data. Response mapping defines how application responses should be merged back into your source data to treat a record based on the import response. You should be familiar with the data fields in your sources and destination applications when working with mappings.

Contents

• Auto-map fields BETA
• Import mappings
• Results mappings
• Response mappings
• Advanced data mapping
  • Standard
  • Hard-coded
  • Lookup
    • Dynamic search
    • Static: Value to value
  • Multi-field
• Field mapping type indicators

Use the Edit mapping panel to configure mappings.To edit a mapping, click the integration tile on your homepage, open the flow that contains the data you want to map, and click the Mapping icon . The Edit mapping panel opens.

Tip: If you don’t see the mapping icon in Flow Builder, click + in the flow step to reveal the option.

With mappings, you can define how your data is handled in both applications. Each mapping screen contains an Input and Output panel, with corresponding dropdown fields, to help you visualize and map your records. Select one input field and one output field to define your mappings. For example, you can match a field from your source record to your destination record in import mapping.

Some responses might not contain all the fields you need to map when configuring your mappings. You can still map the missing fields field manually, assuming the field is returned by the application, or the flow might fail at this step.

Check the Auto-preview box to automatically generate your mapping results in the Output screen. If you’re manually editing a field, click out of the edited field to trigger the auto-preview. If you prefer to manually update the mapping's output use the Preview button instead. If you use the preview button, you’ll need to click it every time you want to review your changes.

Auto-map fields BETA

Rate this feature
Included in the June 2021 release For commonly used applications, integrator.io can automatically suggest destination field mappings that you have not yet added. For example, if firstName has already been mapped in the destination field, then Auto-map will add field mappings for destination fields except for the firstName field. The suggestions are based on common mapping configurations between the two applications and how frequently these field mappings are successfully configured by integrator.io users.

Click Auto-map fields BETA to allow integrator.io to suggest field mappings that have not already been applied to your flow step.

The suggested fields display in the New mappings section underneath any fields you have already mapped manually. Any fields you have manually mapped remain unaffected, but you can also modify or delete any of the new fields.

Import mapping

Import mapping () defines how your source record fields are mapped to your destination record fields. 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.

Rate this feature
Included in the Feb. 2022 release The Source and Destination columns each offer a list that includes the available input for each application. Let’s assume your source application is Amazon Seller Central and your destination application is Acumatica.

Use the Source record drop-down list to select a field, then select a corresponding Destination record field to map the source field. For example, an ItemSKU field in Amazon Seller Central might correspond to an SKU field in Acumatica, and a CustomerID field might correspond to a CustID field.

If your fields have a 1:1 correspondence, you’ve reviewed your mappings, and you are satisfied with the default error handling, click Save & close. Otherwise, continue with advanced data mapping.

Results mappings

Results mappings merge data returned from a lookup into the exported source data, so that the new data can be used in steps later on in the flow. Result mappings always occur at the record level. The Lookup response and Source record field columns each have a drop-down list with the available inputs.

The lookup response consists of data (a record), error information from the lookup application, status codes, and other information. You can merge your lookup response data as a top level field in your source or add it to an existing field.

If your fields have a 1:1 correspondence, you’ve reviewed your mappings, and you are satisfied with the default error handling, click Save & close. Otherwise, continue with advanced data mapping.

Results mappings are different from response mappings.

Response mappings

For flows that have multiple imports, response mapping lets you merge the response returned by an import application back into your source record. This defines actions based on a certain API response from an import application, like an error type. You can only use response mappings in import steps with a subsequent flow step. As an example, you can use response mapping to define an action based on the success or fail value of a field for records sent to an import. The Import application returns the response fields based on the request made by integrator.io (like errors). In this example, you can merge your error field the import response to a field from the source data.

Results mappings are different from response mappings.

If your fields have a 1:1 correspondence, you’ve reviewed your mappings, and you are satisfied with 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,
  "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 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.