Choice workflow state
A Choice
state ("Type": "Choice"
) adds conditional logic to a state machine.
In addition to most of the common state fields, Choice
states contains the following additional fields.
Choices
(Required)-
An array of Choice Rules that determines which state the state machine transitions to next. You use a comparison operator in a Choice Rule to compare an input variable with a specific value. For example, using Choice Rules you can compare if an input variable is greater than or less than 100.
When a
Choice
state is run, it evaluates each Choice Rule to true or false. Based on the result of this evaluation, Step Functions transitions to the next state in the workflow.You must define at least one rule in the
Choice
state. Default
(Optional, Recommended)-
The name of the state to transition to if none of the transitions in
Choices
is taken.
Important
Choice
states don't support the End
field. In addition, they use Next
only inside their Choices
field.
Tip
To deploy an example of a workflow that uses a Choice
state to your Amazon Web Services account, see Module 5 - Choice State and Map State
Choice Rules
A Choice
state must have a Choices
field whose value is a non-empty array. Each element in this array is an object called Choice Rule, which contains the
following:
-
A comparison – Two fields that specify an input variable to compare, the type of comparison, and the value to compare the variable to. Choice Rules support comparison between two variables. Within a Choice Rule, the value of variable can be compared with another value from the state input by appending
Path
to name of supported comparison operators. The values ofVariable
and Path fields in a comparison must be valid Reference Paths. -
A
Next
field – The value of this field must match a state name in the state machine.
The following example checks whether the numerical value is equal to
1
.
{
"Variable": "$.foo",
"NumericEquals": 1,
"Next": "FirstMatchState"
}
The following example checks whether the string is equal to
MyString
.
{
"Variable": "$.foo",
"StringEquals": "MyString",
"Next": "FirstMatchState"
}
The following example checks whether the string is greater than
MyStringABC
.
{
"Variable": "$.foo",
"StringGreaterThan": "MyStringABC",
"Next": "FirstMatchState"
}
The following example checks whether the string is null.
{
"Variable": "$.possiblyNullValue",
"IsNull": true
}
The following example shows how the
StringEquals rule is only evaluated when $.keyThatMightNotExist
exists because of the preceding IsPresent
Choice Rule.
"And": [
{
"Variable": "$.keyThatMightNotExist",
"IsPresent": true
},
{
"Variable": "$.keyThatMightNotExist",
"StringEquals": "foo"
}
]
The following example checks whether a pattern with a wildcard matches.
{ "Variable": "$.foo", "StringMatches": "log-*.txt" }
The following example checks whether the timestamp is equal to
2001-01-01T12:00:00Z
.
{
"Variable": "$.foo",
"TimestampEquals": "2001-01-01T12:00:00Z",
"Next": "FirstMatchState"
}
The following example compares a variable with another value from the state input.
{ "Variable": "$.foo", "StringEqualsPath": "$.bar" }
Step Functions examines each of the Choice Rules in the order listed in the
Choices
field. Then it transitions to the state specified in the
Next
field of the first Choice Rule in which the variable matches the
value according to the comparison operator.
The following comparison operators are supported:
-
And
-
BooleanEquals
,BooleanEqualsPath
-
IsBoolean
-
IsNull
-
IsNumeric
-
IsPresent
-
IsString
-
IsTimestamp
-
Not
-
NumericEquals
,NumericEqualsPath
-
NumericGreaterThan
,NumericGreaterThanPath
-
NumericGreaterThanEquals
,NumericGreaterThanEqualsPath
-
NumericLessThan
,NumericLessThanPath
-
NumericLessThanEquals
,NumericLessThanEqualsPath
-
Or
-
StringEquals
,StringEqualsPath
-
StringGreaterThan
,StringGreaterThanPath
-
StringGreaterThanEquals
,StringGreaterThanEqualsPath
-
StringLessThan
,StringLessThanPath
-
StringLessThanEquals
,StringLessThanEqualsPath
-
StringMatches
-
TimestampEquals
,TimestampEqualsPath
-
TimestampGreaterThan
,TimestampGreaterThanPath
-
TimestampGreaterThanEquals
,TimestampGreaterThanEqualsPath
-
TimestampLessThan
,TimestampLessThanPath
-
TimestampLessThanEquals
,TimestampLessThanEqualsPath
For each of these operators, the corresponding value must be of the appropriate type:
string, number, Boolean, or timestamp. Step Functions doesn't attempt to match a numeric field to
a string value. However, because timestamp fields are logically strings, it's possible
that a field considered to be a timestamp can be matched by a StringEquals
comparator.
Note
For interoperability, don't assume that numeric comparisons work with values
outside the magnitude or precision that the IEEE
754-2008 binary64
data type[-253+1,
253-1]
might fail to compare in the
expected way.
Timestamps (for example, 2016-08-18T17:33:00Z
) must conform to RFC3339 profile ISO 8601
-
An uppercase
T
must separate the date and time portions. -
An uppercase
Z
must denote that a numeric time zone offset isn't present.
To understand the behavior of string comparisons, see the Java compareTo
documentation
The values of the And
and Or
operators must be non-empty
arrays of Choice Rules that must not themselves contain Next
fields.
Likewise, the value of a Not
operator must be a single Choice Rule that
must not contain Next
fields.
You can create complex, nested Choice Rules using And
,
Not
, and Or
. However, the Next
field can
appear only in a top-level Choice Rule.
String comparison against patterns with one or more wildcards (“*”) can be
performed with the StringMatches comparison operator. The wildcard character is
escaped by using the standard \\ (Ex: “\\*”)
. No characters other than
“*” have any special meaning during matching.
Choice State Example
The following is an example of a Choice
state and other states that it
transitions to.
Note
You must specify the $.type
field. If the state input doesn't contain
the $.type
field, the execution fails and an error is displayed in the
execution history. You can only specify a string in the StringEquals
field that matches a literal value. For example, "StringEquals": "Buy"
.
"ChoiceStateX": {
"Type": "Choice",
"Choices": [
{
"Not": {
"Variable": "$.type",
"StringEquals": "Private"
},
"Next": "Public"
},
{
"Variable": "$.value",
"NumericEquals": 0,
"Next": "ValueIsZero"
},
{
"And": [
{
"Variable": "$.value",
"NumericGreaterThanEquals": 20
},
{
"Variable": "$.value",
"NumericLessThan": 30
}
],
"Next": "ValueInTwenties"
}
],
"Default": "DefaultState"
},
"Public": {
"Type" : "Task",
"Resource": "arn:aws-cn:lambda:us-east-1:123456789012:function:Foo",
"Next": "NextState"
},
"ValueIsZero": {
"Type" : "Task",
"Resource": "arn:aws-cn:lambda:us-east-1:123456789012:function:Zero",
"Next": "NextState"
},
"ValueInTwenties": {
"Type" : "Task",
"Resource": "arn:aws-cn:lambda:us-east-1:123456789012:function:Bar",
"Next": "NextState"
},
"DefaultState": {
"Type": "Fail",
"Cause": "No Matches!"
}
In this example, the state machine starts with the following input value.
{
"type": "Private",
"value": 22
}
Step Functions transitions to the ValueInTwenties
state, based on the
value
field.
If there are no matches for the Choice
state's Choices
, the
state provided in the Default
field runs instead. If the
Default
state isn't specified, the execution fails with an
error.