Map State Inline Mode in CloudFlow - CloudFlow

When a workflow needs to apply the same processing logic to every element in an array -- validating a batch of orders, resizing a set of images, or enriching a list of records -- the Map state handles this by iterating over the array and running each element through a sub-flow in parallel, similar to a foreach loop with concurrent execution. Map states run in inline mode by default. The inline mode focuses on a single node and is suitable for scenarios in which each element in a collection requires processing.

How it works

Extract an array from the input using the ItemsPath expression.
Launch an independent sub-flow for each element, running the states defined in Processor.
Run all sub-flows in parallel, up to the MaxConcuccency limit.
After all sub-flows complete, merge results into a map[string]any output under the Items key.

Field reference

Field	Type	Required	Description
Name	string	Yes	State name.
Type	string	Yes	Must be `Map`.
ItemsPath	string	Yes	Expression that extracts the target array from the input. Supports `$Input` and `$Context` variables. See ItemsPath.
Processor	Processor	Yes	Sub-flow definition that runs for each array element. See Processor.
InputConstructor	map[string]any	No	Constructs or reshapes the input before iteration. See Inputs and outputs.
OutputConstructor	map[string]any	No	Reshapes the merged output after all sub-flows complete. See State OutputConstructor.
MaxConcuccency	int	No	Maximum number of parallel sub-flows. Upper limit is 40. See MaxConcuccency.
Next	string	No	State to transition to after completion. Not required if `End` is `true`.
End	bool	No	Marks this as the terminal state of the current scope.
Retry	Retry	No	Error retry policy. See Error handling.
Catch	Catch	No	Error catch policy. See Error handling.
Description	string	No	State description.

Key fields

ItemsPath

An expression that extracts an array from the input. If the expression returns a JSON array, the Map state iterates over each element and passes it to the Processor independently.

Supports the $Input and $Context expression variables:

$Input.FieldA

This extracts the FieldA array from the input. Each element is then processed in a separate parallel sub-flow.

Processor

Defines the sub-flow that runs for each array element.

Field	Type	Required	Description
StartAt	string	Yes	First state to run in the sub-flow.
States	array	Yes	States that make up the sub-flow.

Example:

Processor:
  StartAt: Pass1
  States:
    - Type: Pass
      Name: Pass1
      End: true

MaxConcuccency

Maximum number of sub-flows that run in parallel. The upper limit is 40.

Example

The following flow defines a Map state that iterates over a three-element array. Each element passes through a single Pass state.

Type: StateMachine
Name: my-wkfl
SpecVersion: v1
StartAt: Map1
States:
  - Type: Map
    Name: Map1
    End: true
    InputConstructor:
      FieldA:
        - a: b
        - c: d
        - e: f
    ItemsPath: $Input.FieldA
    Processor:
      StartAt: Pass1
      States:
        - Type: Pass
          Name: Pass1
          End: true

Input

InputConstructor builds the following input:

{
  "FieldA": [
    { "a": "b" },
    { "c": "d" },
    { "e": "f" }
  ]
}

What each iteration receives

ItemsPath extracts the FieldA array. Each sub-flow receives one element as its input. For example, the first iteration receives:

{
  "a": "b"
}

The second iteration receives { "c": "d" }, and the third receives { "e": "f" }. All three sub-flows run in parallel.

Output

After all sub-flows complete, the Map state merges results under the Items key:

{
  "Items": [
    { "a": "b" },
    { "c": "d" },
    { "e": "f" }
  ]
}

To reshape this merged output, use OutputConstructor.