Parallel state for concurrent branch execution - CloudFlow

A Parallel state runs multiple branches at the same time. Use it to split a workflow into concurrent paths -- for example, fetching data from several sources simultaneously or sending notifications through different channels in parallel.

How it works

A Parallel state contains one or more branches, and each branch holds its own sequence of child states. At runtime:

The Parallel state starts all branches concurrently.
Each branch runs its child states independently.
After all branches complete, the Parallel state collects the results into a single map[string]any output. Each branch's result is stored under a key named Branch<Index> (for example, Branch0, Branch1).
If an OutputConstructor is defined, the Parallel state applies it to transform the combined output before passing the result to the next state.

Limits

Maximum number of branches per Parallel state: 50

Attributes

Parallel state attributes

Attribute	Type	Required	Description
`Name`	string	Yes	State name.
`Description`	string	No	State description.
`Type`	string	Yes	State type. Set to `Parallel`.
`InputConstructor`	map[string]any	No	Transforms the input before passing it to the branches. See Inputs and outputs.
`Branches`	ParallelBranch[]	Yes	Branches to run in parallel. See ParallelBranch.
`OutputConstructor`	map[string]any	No	Transforms the combined branch results before passing them to the next state. See State OutputConstructor in "Inputs and outputs".
`Next`	string	No	Next state to run after the Parallel state completes. Not required if `End` is `true`.
`End`	bool	No	Whether to end the current scope after the Parallel state completes.
`Retry`	Retry	No	Retry policy. See Error handling.
`Catch`	Catch	No	Catch policy. See Error handling.

ParallelBranch

ParallelBranch attributes

Attribute	Type	Required	Description
`States`	array	Yes	Array of states in the branch.
`StartAt`	string	Yes	Name of the first state to run in the branch.

Example

The following workflow defines a Parallel state named Parallel1 with two branches. Each branch contains a single Pass state that produces a static output.

Type: StateMachine
Name: my-wkfl
SpecVersion: v1
StartAt: Parallel1
States:
  - Type: Parallel
    Name: Parallel1
    End: true
    Branches:
      - StartAt: Pass1
        States:
          - Type: Pass
            Name: Pass1
            End: true
            OutputConstructor:
              FieldA: 123
      - StartAt: Pass2
        States:
          - Type: Pass
            InputConstructor:
              FieldA: 321
            Name: Pass2
            End: true

Branch output

Each branch produces its own output independently:

Pass1 output (Branch0):
```
  {
      "FieldA": 123
  }
```
Pass2 output (Branch1):
```
  {
      "FieldA": 321
  }
```

Combined Parallel state output

The Parallel state merges all branch outputs into a single map. Each branch is assigned a default key in the format Branch<Index>:

{
    "Branch0": {
        "FieldA": 123
    },
    "Branch1": {
        "FieldA": 321
    }
}

What's next

Inputs and outputs: Transform data flowing through states with InputConstructor and OutputConstructor.
Error handling: Configure Retry and Catch policies to handle branch failures.