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 AWS account, see Module 5 - Choice State and Map State of The AWS Step Functions Workshop.

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 of Variable 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 represents. In particular, integers outside of the range [-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, with further restrictions:

• 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:lambda:us-east-1:123456789012:function:Foo",
  "Next": "NextState"
},

"ValueIsZero": {
  "Type" : "Task",
  "Resource": "arn:aws:lambda:us-east-1:123456789012:function:Zero",
  "Next": "NextState"
},

"ValueInTwenties": {
  "Type" : "Task",
  "Resource": "arn:aws: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.