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 data relates to your import destination record data. You can also use Mapper 2.0 (beta) to configure import mappings. This article only describes Mapper 1.0 processes.
- Results mapping defines how data returned from a lookup step should be merged back into your source data.
- Response mapping defines how API responses from an import step should be merged back into your source data.
You should be familiar with the data fields in your sources and destination applications when working with mappings. Don't confuse results mapping and response mapping. See results mapping vs. response mapping for more information on the difference between the two mapping types.
Contents
- Auto-map fields BETA
- Import mapping
- Results mapping
- Response mapping
- Advanced data mapping
- Field mapping type indicators
To edit the mappings on a flow step, click the integration tile on your homepage, open the flow that contains the data you want to map, and click the mapping (
) button on the flow step that you want to configure mappings for. With mappings, you can define how your data is handled as it passes from one flow step to the next. Each mapping screen contains two columns of drop-down lists that allow you to select the fields available for you to map.
Tip: If you don’t see the mapping () button in Flow Builder, click + in the flow step to reveal the option.
Check the Auto-preview box to automatically generate your mapping results in the Output screen.
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 data relates to your import destination record data. You can also use Mapper 2.0 (beta) to configure import mappings. This article only describes Mapper 1.0 processes.
Rate this feature
Included in the Feb. 2022 release
Click the mapping () button in the middle of the flow step to open the Edit mapping panel. The Source record field column on the left allows you to select fields from the incoming source data, and the Destination record field column on the right allows you to select the corresponding fields that will store the source data as it passes into the import step.
Use the Source record field drop-down list to select a field, then select a corresponding Destination record field to map the source 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 the results data returned from a lookup into the source data, so that the new data can be used in steps later on in the flow. Click the mapping () button to the right of the flow step to open the Edit results mapping panel. The Lookup response field column on the left allows you to select fields from the lookup results data, and the Source record field on the right allows you to select the corresponding fields in the source data that will be added or replaced by the lookup results data.
The lookup results contain data, error information from the lookup application, status codes, and other information returned by the lookup step. You can merge your lookup results 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.
Response mappings
For an import step that has additional import steps later in the flow, click the mapping () button to the right of the flow step to open the Edit response mapping panel. The Import response field column on the left allows you to select elements returned by the response after the import, and the Source record field on the right allows you to select the corresponding fields in the source data that will be added or replaced by the import response data.
For flows that have multiple imports, response mapping lets you merge the response returned by an import application back into your source data. 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.
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 Settings (
) button 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 Settings () button 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.
Comments
0 comments
Please sign in to leave a comment.