Articles in this section

Transformation 2.0 field settings

Each output field in a Rules 2.0 transformation has settings in two places. The data type selectors on the field's row set the output and input data types. Transform settings sets where the output value comes from and what happens when the input has no value. This reference describes every setting in both places.

Data types

You set data types on the field's row, not in Transform settings. Select the data type selector (T ▾) in the Output column or the Input column, and then select a type.

Output data type — The data type of the output field: String, Number, Boolean, String array, Number array, Boolean array, or Date. To make the output field an object, select Object or Object array under Convert to. Changing the output data type changes the transformation types available. If the input and output data types can't be converted, an error displays and you can't save the field. For valid combinations, see Data type validation.

Input data type — The data type of the input value: String, Number, Boolean, Object, String array, Number array, Boolean array, or Object array. It's set automatically when you select an existing input field. If you enter a new input path, select its data type.

Input field — The JSONPath of the input value, entered in the row's Input column. Paths are case-sensitive.

Open Transform settings

Transform settings opens when you select Settings on a field's row. For the steps, see Configure field settings.

Field transformation type

Field transformation type — Where the output value comes from. The following table shows the types available for each output data type.

Output data type Standard Hard-coded Handlebars expression Lookup
String, Number, Boolean Yes Yes Yes Yes
String array, Number array, Boolean array Yes Yes Yes No
Object Copy as-is or create in the transformation Yes Yes, when copying as-is No
Object array Copy as-is or create in the transformation Yes Yes, at the extract level only No

For an Object or Object array field, Transform settings first asks Copy an object from the source as-is?:

  • Select Yes to copy an input object, including all its child fields, to the output field. Field transformation type then offers None, Standard, Hard-coded, and Handlebars expression.
  • Select No to define the object's child fields one by one in the transformation.

None clears the selected type. When you select Confirm, the field reverts to Standard and copies the input object as-is.

Standard

A Standard field copies the value of the input field to the output field, one to one. Standard is the default transformation type.

If the input field is a string that contains JSON, a Standard Object field with Copy an object from the source as-is? set to Yes converts the string into an object. For an example, see Transformation 2.0 examples.

Hard-coded

A Hard-coded field writes the same value to the output field for every record, regardless of the input.

How would you like to hard-code the value? — Choose the value to write:

  • Use custom default value — Writes the value you enter in Custom value.
  • Use empty string as default value — Writes an empty string.
  • Use null as default value — Writes null.

Custom value — The value to write. This field displays only when you select Use custom default value.

Hard-coded object and object array values

You can hard-code a static JSON object for an Object field, or a JSON array of objects for an Object array field, on exports and lookups. For Copy an object from the source as-is?, select Yes, and then select Hard-coded. Enter the JSON directly.

Rules 2.0 validates the value and shows a preview before you save.

  • An empty string becomes {} for an Object field and [] for an Object array field.
  • null stays null for both types.
  • If you enter a single object for an Object array field, such as {"id": 1, "label": "Primary"}, Rules 2.0 wraps it in an array: [{"id": 1, "label": "Primary"}].
  • A hard-coded value can't be combined with another mapping approach on the same field. You can't hard-code an Object field and also map its child fields. You can't hard-code an Object array field and also build its items from input data. Saving a field with both configured returns an error.

Handlebars expression

A Handlebars expression field builds the output value from a handlebars template. It's available for every output data type, with these limits:

  • Object — Handlebars is available only when you copy the object as-is.
  • Object array — Handlebars applies only at the extract level, which selects the source array. Child fields in the array use JSONPath.
  • String array, Number array, Boolean array — When the expression returns an array, Rules 2.0 uses the array as-is. It doesn't split it on commas the way it splits a plain-text value.

Handlebars expression — The expression that builds the output value.

Action to take if handlebars expression returns an empty value — Choose what to write when the expression returns nothing:

  • Do nothing (default) — Omits the field from the output.
  • Use custom default value — Writes the value you enter.
  • Use empty string as default value — Writes an empty string.
  • Use null as default value — Writes null.

Lookup

A Lookup field replaces input values with output values before they reach the next step. Choose a static lookup that you define in the field, or a lookup cache.

Static lookup

Edit mapping — Opens the value table. Each row pairs an Input field value with the Output field value that replaces it. In Input field value, you can enter handlebars expressions or several values separated by commas. A new empty row appears each time you add a value. Select Delete to remove a row.

Lookup name — A unique name for the lookup. Required. You can reuse a named static lookup in other flows by selecting it here.

If lookup fails — What happens when an input value has no match in the table:

  • Fail record (default) — Marks the record as failed. integrator.io doesn't pass the record to the next step.
  • Do nothing — Omits the field from the output.
  • Use empty string as default value — Writes an empty string.
  • Use null as default value — Writes null.
  • Use custom default value — Writes the value you enter.

Lookup cache

Lookup cache name — Enter part or all of a name to find an existing lookup cache, or enter a new unique name to create one.

Lookup cache value field — The JSON path of the value to write to the output field, found by matching the lookup cache key.

If lookup fails — What happens when an input value has no match in the lookup cache. The options are the same as for a static lookup: Fail record (default), Do nothing, Use empty string as default value, Use null as default value, and Use custom default value.

Date fields

When you set the output data type to Date, Transform settings shows "Your destination field is using Date data type." Select Edit date format setting to open Date format setting, which has these settings:

  • Input field date format — The date format of the input value.
  • Input field date time zone — The time zone of the input value.
  • Output field date format — The date format to write.
  • Output field date time zone — The time zone to write.

Action to take if input field has no value

Action to take if input field has no value — What Rules 2.0 writes when the input field is missing or empty. Do nothing is the default for every data type. The options and their results depend on the output data type.

Output data type Use empty string as default value Use null as default value Use custom default value Do nothing (default) Cause record to fail
String Writes "" Writes null Writes your string Omits the field Fails the record
Number Writes 0 Writes null Writes your number Omits the field Fails the record
Boolean Not available Writes false Writes true or false Omits the field Fails the record
String array Writes [] Writes null Writes your values as an array, for example ["a", "b"] Omits the field Fails the record
Number array Writes [] Writes null Writes your values as an array, for example [1, 2] Omits the field Fails the record
Boolean array Writes [] Writes null Writes your values as an array, for example [true, false] Omits the field Fails the record
Object Not available Writes null Not available Omits the field Fails the record
Object array Not available Writes null Not available Omits the field Fails the record

Add description

Add description — An optional note that explains why the field is configured the way it is.