Data mapping v2

Data mapping assigns values to the Properties that consume or expose data in a Workflow.

Put a mapping on the target Step Parameter, Workflow Return, or required control-flow Return. You usually do not need a separate Step only to select, rename, or reshape fields.

Value and Expression

Each runtime-assigned leaf Property normally has one assignment:

Value supplies a literal scalar, such as a string, number, boolean, or date. It can also supply an array whose items are scalar values.
Expression obtains a value at runtime from a Workflow Parameter, an earlier Step Return, or a mapping function.

Workflow Parameters define the values accepted when the Workflow starts. They cannot map data from inside the Workflow.

In the canvas, select a Property and use the Value and Expression switch to choose its assignment mode. Some types, including objects, arrays, and Streams, are Expression-only when used inside the Workflow.

References

Braces identify a reference:

{.customerId}

This refers to the Workflow Parameter named customerId.

{getCustomer.Customer}

This refers to the Customer Return from the earlier getCustomer Step.

{getCustomer.Customer.address.city}

This refers to a nested field.

A Step can reference Workflow Parameters and data available earlier in its execution scope. It cannot reference a later Step.

Functions are written outside braces. Braces still surround any references passed to the function:

CONCAT({getCustomer.Customer.firstName}, " ", {getCustomer.Customer.lastName})

Use only functions and signatures available in the current designer. Unknown functions are reported in Problems.

Map objects

Use Properties to declare the target object's fields. Map each field by meaning and compatible type.

Customer:
  Type: object
  Expression: "{getCustomer.Customer}"
  Properties:
    id:
      Type: string
      Expression: "{getCustomer.Customer.id}"
    displayName:
      Type: string
      Expression: "{getCustomer.Customer.name}"

The target field names define the object supplied to the consumer. They do not rename the earlier Step's Return.

An object can map child fields without a container Expression when the target contract permits you to construct the object directly.

Map arrays

An array mapping has two parts:

The array's Expression identifies the source collection.
Its nested Properties define and map the target item shape.

Customers:
  Type: array
  Expression: "{listCustomers.Customers}"
  Properties:
    id:
      Type: string
      Expression: "{listCustomers.Customers.id}"
    displayName:
      Type: string
      Expression: "{listCustomers.Customers.name}"

The Runtime evaluates the nested mappings for each item obtained from the source collection. A scalar or object can be promoted to a one-item collection where the target contract expects an array.

An array mapping without a container Expression constructs one item from its nested Properties. Use a container Expression when you intend to project an upstream collection.

Preserve Step Return contracts

An ordinary Step Return describes the output envelope of its selected Node Method. Do not flatten, rename, or move those fields on the producing Step.

Map the required fields when a later Step Parameter or a Workflow Return consumes them. This keeps the producer's contract intact and makes each consumer's required shape explicit.

Mapping is not document parsing

Mapping selects and shapes values that already have a known structure. It does not parse JSON, XML, or flat-file text.

Use an appropriate Document Node when the source is a structured document like a JSON or XML string. Map the object or array returned by the parser into later Properties.

Literal Value does not support objects or arrays containing complex items. Use nested Properties, or parse a literal document when that better represents the input.

Work using a schema

Adding a Node Method as a step in a Workflow will allow you to choose a template. The template will provide as much schema as is available at the time.

Some Node Methods aren't able to statically present a schema and in other cases, the schema that is returned from a Node Method may differ from the template. In these cases, the Infer button (which appears on affected Steps and for the Workflow as a whole) will light up. Clicking it will offer the option of applying the schema that was discovered from the most recent run of the Workflow.

When to add another Step

Add a Step when a Node operation is required, such as parsing a document or calling another system. A separate Step can also be useful when several consumers need the same expensive derived value.

For ordinary selection, field renaming, object shaping, and supported scalar transformations, map directly on the consuming Property.

See Expression syntax and Mapping functions for the authored language, Workflow YAML for the complete Property structure, and Lazy Evaluation and Streaming for how collection consumption affects execution.