Map Arrays v2

Map an Array by selecting a source collection on the target Property and declaring the shape of one target item under Properties.

The Parameters: sections below belong to a consuming Step inside the Workflow's Steps list. Replace that Step's Parameters section in Code view. They are not root Workflow Parameters: Workflow inputs cannot contain Expressions. The named source Steps and their Return fields must already exist.

Project a source collection

Set the Array's Expression to the collection, then map child fields in that collection's item scope:

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

The Runtime evaluates the child mappings once for each source item. The child reference must remain in the source collection's scope.

For example, a source collection containing [{"customerId":"C-001","name":"Ada"},{"customerId":"C-002","name":"Grace"}] produces Customers with the value [{"id":"C-001","displayName":"Ada"},{"id":"C-002","displayName":"Grace"}]. The target field names change, while the source records remain unchanged.

Filter rows

Use FILTER as the parent Expression when only matching rows should reach the target:

Parameters:
  OpenOrders:
    Type: array
    Expression: "FILTER({listOrders.Orders}, {listOrders.Orders.status} == \"Open\")"
    Properties:
      id:
        Type: string
        Expression: "{listOrders.Orders.id}"
      total:
        Type: number
        Expression: "{listOrders.Orders.total}"

FILTER requires exactly two arguments. Its source must be a direct Step Return reference, and the predicate must use fields in that source scope.

Select or flatten values

Use the collection functions that match the intended result:

PLUCK({listOrders.Orders.lines.sku}) projects a field and recursively flattens nested Array levels in source order.
FIRST({listOrders.Orders}) and LAST({listOrders.Orders}) select one item for an object mapping.
MAKEARRAY({getCustomer.Customer}) promotes one value to a one-item Array.
GROUPBY groups a direct source collection by one or more unique direct child fields.

For example:

GROUPBY({listOrders.Orders}, {listOrders.Orders.country}, {listOrders.Orders.region})

The grouping keys become scalar fields. Other fields become Arrays for each group and can be projected or aggregated by nested mappings.

Construct one item

An Array with child Properties but no parent Expression constructs one item:

Parameters:
  Customers:
    Type: array
    Properties:
      id:
        Type: string
        Expression: "{.customerId}"
      displayName:
        Type: string
        Expression: "{.customerName}"

A scalar or object can also be promoted to a one-item Array where the target contract accepts it. Use MAKEARRAY when the intent should be explicit.

Aggregate without projecting the entire Array

Use an aggregate on the required field when the target needs one scalar result:

SUM({listOrders.Orders.total})
COUNT(FILTER({listOrders.Orders}, {listOrders.Orders.status} == "Open"))

Do not materialize or copy a large collection merely to calculate one supported aggregate.

Keep lazy data lazy

An Array or deferred source is consumed when a downstream mapping, aggregate, logger, or Node enumerates it. Multiple consumers can require replay and retained data. Prefer one clear consumption path, avoid mapping fields that the target does not need, and pass a Stream directly when the receiving contract supports it.

Use Preview to check the mapped shape, then Debug with a small representative set. Inspect counters and Step timings in Logs before increasing the data volume.