Each field row in Mapper 2.0 has settings that control how integrator.io produces the destination value and what it does when the source has no value. This reference is for builders who configure imports in Mapper 2.0. It lists the mapping types, the settings for each type, and the actions integrator.io takes for empty values and failed lookups.
Open field settings
- In the field row, select Settings
.
You must select a destination field before you can open its settings. The available settings depend on the field's data type and the Field mapping type you choose.
Field mapping types by data type
The destination data type determines which field mapping types you can use. For the data types, see Data type validation reference and Work with JSON and file output.
| Destination data type | Standard | Hard-coded | Handlebars expression | Lookup (dynamic) | Lookup (static) | Lookup cache |
|---|---|---|---|---|---|---|
| String, Number, Boolean | Yes | Yes | Yes | Yes | Yes | Yes |
| String array, Number array, Boolean array | Yes | Yes | Yes | No | No | No |
| Object | Copy as-is, or create the object in the mapping | Yes | Copy as-is only | No | No | No |
| Object array | Copy as-is, or create the object array in the mapping | Yes | Extract only. Child mappings use JSONPath. | No | No | No |
Date supports the same mapping types as String and adds an Edit date format setting button in the field's settings.
To convert a source value to an object or object array, set the destination data type to Convert to > Object or Object array. For primitive arrays, see Convert primitive arrays to object arrays in Mapper 2.0.
Standard
Sends the value of the source field to the destination field. This is the default.
| Setting | Description |
|---|---|
| Action to take if source field has no value | Sets what happens when the source field is empty. See Actions for empty values. |
| Add description | An optional note about the mapping. |
Hard-coded
Writes the same value to the destination field for every record. Enter the value in double quotes. Without quotes, Mapper 2.0 reads the value as a handlebars expression.
| Setting | Description |
|---|---|
| How would you like to hard-code the value? | Use empty string as default value, Use null as default value, or Use custom default value. |
| Custom value | The value to send. Appears only when you select Use custom default value. |
| Add description | An optional note about the mapping. |
Hard-code an object or object array
- Open the settings of the object or object array field.
- Set Copy an object from the source as-is? (object) or Copy an array from the source as-is? (object array) to Yes.
- Set Field mapping type to Hard-coded.
- In the destination field, enter the value, for example
{"status": "active", "region": "US"}for an object or[{"id": 1, "label": "Primary"}, {"id": 2, "label": "Secondary"}]for an object array.
Mapper 2.0 validates the value and shows a preview before you save. Keep these rules in mind:
- An empty string resolves to
{}for an object field and[]for an object array field. A null value stays null. - If you enter a single object for an object array field, Mapper 2.0 wraps it in a one-element array.
- You can't combine hard-coded with copy as-is or with Create object in mapping on the same field. Mapper 2.0 rejects the save.
Handlebars expression
Builds the destination value from a handlebars expression. Mapper 2.0 reads any value that isn't a JSONPath or a hard-coded value in double quotes as a handlebars expression. See Handlebars expressions and the Handlebars expression reference.
| Setting | Description |
|---|---|
| Handlebars expression | Enter an expression, or open the advanced field editor to build one. |
| Action to take if handlebars expression returns an empty value | Do nothing (default) skips the field. Other options insert an empty string, a null value, or a custom value. |
| Add description | An optional note about the mapping. |
- For object fields, handlebars works in copy-as-is mode only.
- For object array fields, handlebars applies at the extract level only. Child mappings keep using JSONPath.
- For string, number, and Boolean array fields, an array that the expression returns is used as is. Plain-text values are split at commas.
Lookup
Select a Lookup type: Dynamic, Static, or Lookup cache. Dynamic and static lookups work as described in Add a lookup to an import mapping, with these Mapper 2.0 differences:
| Mapper 2.0 label | Where it differs |
|---|---|
| Lookup name | Names the dynamic or static lookup. Mapper 1.0 labels it Name. To reuse a lookup, select a dynamic or static lookup that another flow uses with the same destination application. |
| Source field value and Destination field value | The value pair columns of a static lookup. Mapper 1.0 labels them Export field value and Import field value. |
| If lookup fails | Sets the result when no unique match is found. Mapper 1.0 labels it Action to take if unique match not found. Mapper 2.0 adds Do nothing, which skips the field name and value. The other options match those in Add a lookup to an import mapping. |
| Relative URI | Dynamic lookups on HTTP imports. The URI is appended to the address shown below the field. Select the AFE icon to open the handlebars editor. |
| Static lookup values | A new empty line appears each time you add a value. Select Delete at the right of a line to remove it. |
| Add description | An optional note about the mapping. Available for every lookup type. |
Lookup cache
Retrieves a value from a lookup cache. For how to create and manage caches, see Lookup caches overview.
| Setting | Description |
|---|---|
| Lookup cache name | The cache to use. |
| Lookup cache value field | The path to the value to write to the destination field. integrator.io retrieves it when the source field matches the cache key. |
| If lookup fails | Sets the result when no match is found. The default is Fail record. |
| Source data type | Set automatically when you select a source field. Select it manually if the source field isn't in the loaded sample data. |
| Add description | An optional note about the mapping. |
Actions for empty values
Action to take if source field has no value applies to Standard mappings. Options vary by data type.
| Option | Result in Mapper 2.0 |
|---|---|
| Do nothing (default) | Removes the field name and value. |
| Use empty string as default value | String: inserts an empty string. Not available for Number or Boolean. |
| Use empty value as default value | Arrays only: inserts an empty array. |
| Use null as default value | Inserts a null value. For arrays and objects, the null has no array or object formatting. |
| Use custom default value | String: inserts the custom string. Number: inserts the custom number. Boolean: you select true or false. Arrays: inserts the custom values as an array, for example ["a", "b", "c"] or [1, 2, 3]. |
| Cause record to fail | The record fails. |
Object and object array fields offer only Do nothing, Use null as default value, and Cause record to fail.
Mapper 1.0 behaves differently. It inserts 0 for a Number field and false for a Boolean field, and an empty array for array fields, whichever option you select. Mapper 2.0 removes the field or inserts the value you choose.
Advanced settings for HTTP composite methods
For HTTP imports that use composite methods, set Only perform mapping when to apply the mapping to one operation:
- Creating a record: the mapping applies only to new records in the destination application.
- Updating a record: the mapping applies only to existing records.
The setting appears in the Advanced section of the field settings.
Related articles
- Map data with Mapper 2.0
- Mapping types and versions
- Mapper 1.0 field mapping settings
- Build a destination object array in Mapper 2.0
- Work with JSON and file output