Once you’ve created a custom unified field, you need to define the “mapping” for each of the integration you want this field to be enabled and usable for.
Adding an integration field mapping is done via the integration-level mapping tab after selecting a specific custom unified field.
Only integrations configured and enabled on the integrations page can be mapped.

​
Configuring the mapping

Although it’s possible to map without using an underlying linked account, it’s always advised to use a connected linked account (eg. a sandbox account) to have the most realistic view of what type of properties and fields may be available on the underlying integration.

​
Preview & Test

  1. Preview Fields: (optional)
    • Select a source from the dropdown list to pull a sample set of field data.
    • Click on “Request” to preview the data.
    • Example preview JSON response: 
      {
  "employees": [
    {
      "id": "5",
      "firstName": "Anna",
      "lastName": "Skywalker",
      "terminationDate": "2024-05-28"
    }
  ]
}
  2. Field Mapping Steps:
    • Step 1: Select the source field you want to map from the integration.
    • Step 2: Enter the target custom field name.
    • Step 3: Use the expression language syntax to point to the relevant integration field
      • Example: $.employees.output.data.terminationDate

​
Tips & Tricks

​
Mapping array values

Some origin data will return a list of resources instead of a single resource (eg: all the documents instead of a specific document). In this case, you should make sure to use one of the provided default variables (eg: id) to find the element in the array that matches the ID.

​
Expression language

Custom unified fields can be mapped using the StackOne’s expression language. This language supports JSON path syntax, JEXL expressions for more complex use cases or simple string interpolation. For more information about all the expression language capabilities please refer to the Expression language syntax documentation.

​
Additional Features:

  • Typecasting: Values will be automatically typecasted to the defined variable type when possible (eg: if the variable type is a string but the underlying integration returns a number the number will be return as a string and vice-versa).
  • Viewing Mappings: : once an integration mapping is configured, the source will be visible directly in the integration-level mapping list:

​
Using a Custom Unified Field

Once you have configured an integration custom field mapping you will need to make sure the field is enabled:
You can retrieving the data via any GET or LIST API request for the model you created the field on: The unified custom field will be embedded in an property called unified_custom_fields.
When using SDKs (ie: Typescript SDK) the property may be camel cased instead (ie: unifiedCustomFields). The SDK will not have types for the individual properties contained in this object given it is fully customizable.