Complex Extraction Transformation

Overview

The complex extraction transformation is used to extract values from within the contained JSON structure into separate schema fields.

Use Cases

The complex extraction can be used to accomplish the following:

• Unpack or flatten arbitrary JSON data to be consumed by a gateway or in Plus
• Make value from within arbitrary JSON data available for use in other transformations
• Used in conjunction with a Complex Insertion transformation for two-way complex value mapping

Prerequisites

A complex field.

Contribution

This transformation adds an additional field containing the selected JSON data.

Configuration

The complex extraction transformation requires the following by way of configuration:

Attribute	Description
Direction	The direction that the transformation will be applied in. Incoming will apply the transformation to connector entity changes. Outgoing will apply the transformation to changes from gateways or Plus links.
Source Field	The complex schema field to extract values from.
Extractions	A set of extraction instructions. These will be executed in the configured order.

Insertion Configuration

Attribute	Description
Value Path	The JSON path to the value to extract. See below for details on supported JSON path syntax and how this affects extraction.
Target Field	Name of a schema field that the extracted value will be assigned to. For Incoming transformations, this will be a new field that will be added to the schema. For Outgoing transformations, the choice is limited to an existing schema field.
Target Value Type	The type of the new schema field for Incoming transformations. It should match the values extracted from the JSON data. This is not needed for Outgoing transformations because the existing schema field's value type is already known.
Ignore Invalid Array Types	If the target value type is a multi-value type and the targeted value is an array, any elements of that array which cannot be converted to the selected type will be ignored instead of erroring.
Null if Unresolved	Assign NULL to the target field if the specified value path cannot resolve to a value in the Complex values data structure. If unchecked, an unresolved value path will error and interrupt the reflection process.

Change Processing

During the change detection process, a change will be flagged for an entity if the Source field has been updated.

Value Path

Value paths are JSON paths that specifies the location of a value within a complex value structure to be extracted.

Only a subset of all JSON path syntax is supported; that which allows the direct targeting of a specific location. This includes:

• dictionary child section .name
• array member selection [3] (positive indexes only):

TIP

As JSON paths used in the Complex extraction transformation are always treated as relative to the top-level dictionary, the JSON path root node identifier ($.field) is not required, and this and other node selectors are not supported.

The following examples show the results of different value paths.

Complex value

// Complex value: 
{
  "a": "one",
  "b": [100, 102, 140],
  "c": { 
    "d": "two"
  },
  "e": [
    [
      {
        "f": "three"
      }
    ]
  ]
} 

// ValuePath: "a" 
"one" 

// ValuePath: "b[1]" 
102 

// ValuePath: "c.d"
"two" 

// ValuePath: "e[0][0].f"
"three"