Articles in this section

Add a lookup to an import mapping

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

  1. In the Edit mapping panel, select Settings settings-icon.png on the row you are mapping. To open the panel, see Configure import mapping in Mapper 1.0.
  2. Set Field mapping type to Lookup, and then select Dynamic search.
  3. 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}}.
  4. Select the HTTP method: GET or POST.
  5. Enter the Resource identifier path, the path to the value in the response, for example searchResults[0].name.
  6. Enter a unique Name. You use the name to reference the lookup later.
  7. 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

  1. In the Edit mapping panel, select Settings settings-icon.png on the row you are mapping.
  2. Set Field mapping type to Lookup, and then select Static: Value to value.
  3. For each pair, enter the Export field value and the matching Import field value. For example, enter CA and California.
  4. Enter a unique Name.
  5. 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:

  1. Create a static lookup with one pair: cash and the cash payment method.
  2. Set Action to take if unique match not found to Use custom default value.
  3. 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.