Choice state for workflow branching using conditional expressions - CloudFlow

A Choice state adds conditional branching to a flow. It evaluates conditions against the input data and routes execution to the first matching branch, similar to a switch-case statement in programming.

How it works

When a flow reaches a Choice state, the system evaluates each branch's condition in order:

If a condition evaluates to true, the flow transitions to the state specified in that branch's Next field.
If no condition evaluates to true, the flow transitions to the state specified in the Default field.

The Default field is required. This ensures the flow always has a valid transition path, even when no branch conditions match.

Important

Choice states do not support the End and Next attributes at the state level. Use the Default attribute to define the fallback transition. Each ChoiceBranch defines its own Next attribute to specify where the flow goes when the condition is met.

Attributes

Attribute	Type	Required	Description	Example
Name	string	Yes	The state name.	my state
Description	string	No	A description of the state.	describe it here
Type	string	Yes	The state type. Set to `Choice`.	Choice
InputConstructor	map[string]any	No	The input constructor. For more information, see Inputs and outputs.	--
Default	string	Yes	The fallback state to transition to when no branch condition evaluates to `true`.	my next task
Branches	ChoiceBranch[]	Yes	An array of choice branches. See the ChoiceBranch table.	--

ChoiceBranch

Each entry in the Branches array contains the following attributes:

Attribute	Type	Required	Description	Example
Condition	string	Yes	A conditional expression that evaluates to `true` or `false`. See Conditional expressions.	`$Input.status=="ready"`
Next	string	Yes	The state to transition to when the condition evaluates to `true`.	my next task

Example

The following flow routes execution based on the value of $Input.data:

If $Input.data equals "ready", the flow transitions to the Pass1 state.
Otherwise, the flow transitions to the default Pass2 state.

Type: StateMachine
Name: MyWorkflow
SpecVersion: v1
StartAt: Choice
States:
  - Type: Choice
    Name: Choice
    Branches:
      - Condition: $Input.data == "ready"
        Next: Pass1
    Default: Pass2
  - Type: Pass
    Name: Pass2
    End: true
  - Type: Pass
    Name: Pass1
    End: true

Conditional expressions

Conditional expressions combine variables, constants, and operators to produce a Boolean result (true or false). Use the $Input variable to reference state input data and the $Context variable to reference flow context data. For more information, see Data passing.

Supported operators

Category	Operators	Applicable types
Comparison	`==`, `!=`, `>`, `>=`, `<`, `<=`	Strings, numbers
Logical	`&&` (AND), `\|\|` (OR)	Boolean expressions
Prefix	`!` (NOT), `-` (negation)	Boolean expressions, numbers
Inclusion	`in`	Arrays (check if a value exists), objects (check if a key exists)

Supported constants

Type	Syntax	Examples
String	Double quotes (`"`) or backticks (`)	`"foobar"`, `foobar`
Numeric	Integer or decimal	`1`, `12.5`
Boolean	Lowercase keywords	`true`, `false`

Expression examples

Given the following $Input data, the tables below show how different expressions evaluate:

{
  "a": 1,
  "b": {
    "b1": true,
    "b2": "ready"
  },
  "c": [1, 2, 3],
  "d": 1,
  "e": 1,
  "f": {
    "f1": false,
    "f2": "inprogress"
  }
}

Numeric comparisons

Expression	Result	Description
`$Input.a==1`	true	Equal to a literal value
`$Input.a==2`	false	Not equal to the literal value
`$Input.a>0`	true	Greater than
`0<$Input.a`	true	Literal on the left side
`$Input.a>=1`	true	Greater than or equal to
`$Input.a!=2`	true	Not equal to

Boolean comparisons

Expression	Result	Description
`$Input.b.b1`	true	Direct Boolean reference
`$Input.b.b1==true`	true	Explicit comparison to `true`
`$Input.b.b1==false`	false	Explicit comparison to `false`

String comparisons

Expression	Result	Description
`$Input.b.b2=="ready"`	true	String equality
`$Input.b.b2=="inprogress"`	false	String inequality

Compound expressions

Expression	Result	Description
`$Input.a==1 && $Input.b.b1`	true	Both conditions are true
`$Input.a==2 && $Input.b.b1`	false	First condition is false

Array and variable-to-variable comparisons

Expression	Result	Description
`$Input.c[0]==1`	true	Access array element by index
`$Input.c[0]==$Input.a`	true	Compare two variables

Inclusion checks

Expression	Result	Description
`"f1" in $Input.f`	true	Key exists in the object
`"f3" in $Input.f`	false	Key does not exist
`1 in $Input.c`	true	Value exists in the array