A lookup field mapping fills a destination field with a value that isn't in your source record. A dynamic lookup searches the destination application, or another service, for the value, and a static lookup translates one value to another from a list you define. This article is for builders who configure HTTP imports and need to match records, translate values, or set defaults. A lookup in a field mapping is different from a lookup step in a flow: for a lookup step, see Configure results mapping.
Before you begin
For an HTTP import, know the JSON or XML request body that the endpoint expects.
Choose a lookup type
| Type | Use it when | Example |
|---|---|---|
| Dynamic search | You must query another resource to find the value. | Search the destination for a customer with the same email address and write back the customer's name. |
| Static: Value to value | You already know how each source value maps to a destination value. | Translate CA, ID, and AK to California, Idaho, and Alaska. |
Create a dynamic lookup
- In the Edit mapping panel, select Settings
on the row you are mapping. To open the panel, see Configure import mapping in Mapper 1.0.
- Set Field mapping type to Lookup, and then select Dynamic search.
- Enter the Relative URI. It's appended to the connection's base URI. To use a source field in the URI, add a handlebars expression, for example
/customers/search?email={{export.email}}. - Select the HTTP method: GET or POST.
- Enter the Resource identifier path, the path to the value in the response, for example
searchResults[0].name. - Enter a unique Name. You use the name to reference the lookup later.
- Set Action to take if unique match not found. See Choose what happens when no match is found.
Suppose the search returns this response:
{
"count": 1,
"searchResults": [
{
"name": "Mary",
"id": 1234,
"email": "mary@email.com"
}
]
}With a Resource identifier path of searchResults[0].name, integrator.io writes Mary to the destination field.
Create a static lookup
- In the Edit mapping panel, select Settings
on the row you are mapping.
- Set Field mapping type to Lookup, and then select Static: Value to value.
- For each pair, enter the Export field value and the matching Import field value. For example, enter
CAandCalifornia. - Enter a unique Name.
- Set Action to take if unique match not found. See Choose what happens when no match is found.
Choose what happens when no match is found
Action to take if unique match not found applies to both lookup types. The default is Fail record.
| Option | Result |
|---|---|
| Fail record | integrator.io doesn't send the record and marks it as failed. This is the default. |
| Use empty string as default value | Sets the destination field to an empty string. |
| Use null as default value | Sets the destination field to null. |
| Use custom default value | Sets the destination field to the value you enter. |
Fail record is available only for lookups. NetSuite imports offer all four options for lookup mappings, plus Use default on multiple matches for dynamic lookups.
Set a default for unmatched values
To map specific source values and send a default for all others, use a static lookup with Use custom default value.
For example, if the gateway is cash, you want the cash payment method, and for any other gateway you want a default payment method:
- Create a static lookup with one pair:
cashand the cash payment method. - Set Action to take if unique match not found to Use custom default value.
- Enter the default payment method as the custom value.
Reference a lookup in a handlebars expression
Use these expressions to reference a lookup's result elsewhere in the mapping.
| Lookup type | Expression | Example |
|---|---|---|
| Dynamic | {{lookup.<lookup name>}} |
{{lookup.typeLookup}} |
| Static | {{lookup '<lookup name>' this.<source field name>}} |
{{lookup 'vendor_status' this.ExportFieldName}} |
For the full syntax, see Handlebars syntax.
Related articles
- Mapper 1.0 field mapping settings
- Configure import mapping in Mapper 1.0
- Configure results mapping
- Mapper 2.0 field settings