Basic concepts and examples of the Choice state - CloudFlow

A Choice state directs a flow into different branches based on conditional logic. This topic describes the basic concepts of the Choice state, provides usage examples, and explains how to use conditional expressions for flow control.

Overview

A Choice state is a node in a flow that executes different states based on specified conditions. It contains multiple choices and a default option. Each choice has a conditional expression (Condition) and a transition instruction (Next). Similar to a switch-case statement in a programming language, a Choice state uses conditional expressions to determine the execution path of the flow.

When a flow proceeds to a Choice state, the system evaluates whether the conditional expressions of the choice branches return True in the defined sequence.

If the conditional expression of a choice returns True, the flow executes the state and transition defined for that choice.
If no conditional expressions return True, the flow executes the state and transition defined in the default option.

The following table describes the attributes that a Choice state contains.

Attribute	Type	Required	Description	Example
Name	string	Yes	The name of the state.	my state
Description	string	No	The description of the state.	describe it here
Type	string	Yes	The type of the state.	Choice
InputConstructor	map[string]any	No	The input constructor.	For more information, see Inputs and Outputs.
Default	string	Yes	The default branch.	my next task
Branches	ChoiceBranch	Yes	The choice branches.	See ChoiceBranch.

ChoiceBranch

Attribute	Type	Required	Description	Example
Condition	string	Yes	A conditional expression. For more information, see Expression examples.	$Input.status=="ready"
Next	string	Yes	The name of the next state that the workflow transits to if the condition is met.	my next task

Important

Choice states do not support the End and Next attributes. The Default attribute of Choice states specifies the state that the workflow transits to by default when no condition in Choice branches is met. The feature of the Default attribute is the same as the feature of the Next attribute. ChoiceBranch can contain the Next attribute.

Example

The following sample flow contains a Choice state.

If the input status value is ready, the Pass2 state of the first choice is executed.
If the input status value is not ready, the default option Pass1 is executed.

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

The conditional expressions supported by the system consist of the following operations and variables. You can determine whether the conditions specified by a conditional expression are met based on the Boolean value returned by the expression.

Comparison operations: >, >=, <, <=, ==, and !=. These operations apply to strings and numbers.
Logical operations: || and &&.
String constants: A string constant is enclosed in double quotation marks (") or grave accents (`). Examples: "foobar" or `foobar`.
Numeric constants: 1 and 12.5.
Boolean constants: true and false.
Prefixes: ! and -.
Inclusion: in. This is used to determine whether an array contains a value or an object contains a key.

Sample expression

The following table shows the results of different conditional expressions based on the sample state input $Input. You can use the $Context and $Input variables in a conditional expression. For more information, see Data passing.

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

Conditional expression	Execution results
`$Input.a==1`	true
`$Input.a==2`	false
`$Input.a>0`	true
`0<$Input.a`	true
`$Input.a>=1`	true
`$Input.a!=2`	true
`$Input.b.b1`	true
`$Input.b.b1==true`	true
`$Input.b.b1==false`	false
`$Input.b.b2=="ready"`	true
`$Input.b.b2=="inprogress"`	false
`$Input.a==1 && $Input.b.b1`	true
`$Input.a==2 && $Input.b.b1`	false
`$Input.c[0]==1`	true
`$Input.c[0]==$Input.a`	true
`"f1" in $Input.f`	true
`"f3" in $Input.f`	false
`1 in $Input.c`	true