Learn about state machines in Step Functions
Step Functions is based on state machines, which are also called workflows. Workflows are comprised of a series of event-driven steps.
You define a workflow using Amazon States Language, also known as ASL. You can optionally use Workflow Studio, a visual workflow designer, to build and edit your workflows.
Each step in a workflow is called a state. There are two types of states: Flow states and Task states:
- Flow states
-
Flow states control the flow of execution of the steps. For example, Choice states provide conditional logic; Wait states pause workflow execution; Map states run child workflows for each item in a dataset; and Parallel states create separate branches in your workflows.
- Task states
-
Task states represent a unit of work that another Amazon service performs, such as calling another Amazon Web Services service or API. Tasks states are also known as Actions. You can choose hundreds of actions to perform work in Amazon and external services. (Note: You can also use workers that run outside of Step Functions to perform tasks. For more info, see Activities.)
Executions and handling errors
When you run your workflows, Step Functions creates a workflow instance called an execution. You can monitor the status of your workflow executions. If an execution experiences an error, the workflow might catch the error. Depending on your use case, you might redrive the execution later to resume the workflow.
Passing data
You can optionally provide input data in the form of JSON text to your workflows. Each step can pass data to subsequent steps using variables and state output. Data stored in variables can be used by later steps. State output becomes the input for the very next step. To learn more about passing data, see Passing data between states with variables.
At the end of workflows, your state machine can optionally produce output, also in the form of JSON.
Transforming data
States and state machines can transform data using a query language. The recommended query language is JSONata; however, state machines created prior to re:Invent 2024 use JSONPath. For backward compatibility, your state machines or individual states must opt-in to using JSONata for their query language.
You can recognize JSONata state machines and individual states by the
QueryLanguage
field set to "JSONata". State machines and states that use
JSONPath, lack the QueryLanguage
field.
States that use JSONPath will have state fields such as InputPath, Parameters,
ResultSelector, ResultPath, and OutputPath. In JSONPath state machine definitions, you will
also see field names that end
in .$
and values prefixed with $.
and $$.
, both of which
represent paths. In the paths, you might see various intrinsic functions, such as
States.MathAdd
. Intrinsic functions are only
used in JSONPath.
JSONata states use Arguments and Output fields. In these optional fields, you might see JSONata expressions that
look like the following: "{% $type = 'local' %}"
. With JSONata, you can use
expressions, operators, and functions. To learn more, see Transforming data with JSONata in Step Functions.
Note
You can use only one query language per state. You cannot mix JSONPath and JSONata within a single step.
Key concepts
The following provides an overview of the key Step Functions terms for context.
Term | Description |
---|---|
Workflow | A sequence of steps that often reflect a business process. |
States |
Individual steps in your state machine that can make decisions based on their input, perform actions from those inputs, and pass output to other states. For more information, see Discovering workflow states to use in Step Functions. |
Workflow Studio |
A visual workflow designer that helps you to prototype and build workflows faster. For more information, see Developing workflows in Step Functions Workflow Studio. |
State machine | A workflow defined using JSON text representing the individual states or steps in the workflow along with fields, such as For more information, see State machine structure in Amazon States Language for Step Functions workflows. |
Amazon States Language |
A JSON-based, structured language used to define your state machines. With ASL, you define a collection of states that can do work (Task state), determine which states to transition to next (Choice state), and stop an execution with an error (Fail state). For more information, see Using Amazon States Language to define Step Functions workflows. |
Input and output configuration |
States in a workflow receive JSON data as input and usually pass JSON data as output to the next state. Step Functions provides filters to control the data flow between states. For more information, see Processing input and output in Step Functions. |
Service integration |
You can call Amazon service API actions from your workflow. For more information, see Integrating services with Step Functions. |
Service integration type |
|
Service integration pattern | When calling an Amazon Web Services service, you use one of the following service integration patterns:
|
Execution |
State machine executions are instances where you run your workflow to perform tasks. For more information, see Starting state machine executions in Step Functions. |
State Machine Data
State machine data takes the following forms:
-
The initial input into a state machine
-
Data passed between states
-
The output from a state machine
This section describes how state machine data is formatted and used in Amazon Step Functions.
Data Format
State machine data is represented by JSON text. You can provide values to a state machine using any data type supported by JSON.
Note
-
Numbers in JSON text format conform to JavaScript semantics. These numbers typically correspond to double-precision IEEE-854
values. -
The following is valid JSON text:
-
Standalone, quote-delimited strings
-
Objects
-
Arrays
-
Numbers
-
Boolean values
-
null
-
-
The output of a state becomes the input for the next state. However, you can restrict states to work on a subset of the input data by using Input and Output Processing.
State Machine Input/Output
You
can give your initial input data to an Amazon Step Functions state machine in one of two ways. You
can pass the data to a
StartExecution
action when you start an execution. You can also
pass the data to the state machine from the Step Functions
consoleStartAt
state. If no input is provided, the default is an empty object
({}
).
The output of the execution is returned by the last state (terminal
).
This output appears as JSON text in the execution's result.
For Standard Workflows, you can retrieve execution results from the execution history
using external callers,
such
as the DescribeExecution
action. You
can view execution results on the Step Functions
console
For Express Workflows, if you enabled logging, you can retrieve results from CloudWatch Logs, or view and debug the executions in the Step Functions console. For more information, see Using CloudWatch Logs to log execution history in Step Functions and Viewing execution details in the Step Functions console.
You should also consider quotas related to your state machine. For more information, see Step Functions service quotas
State Input/Output
Each state's input consists of JSON text from the preceding state or, for the
StartAt
state, the input into the execution. Certain flow-control
states echo their input to their output.
In the following example, the state machine adds two numbers together.
-
Define the Amazon Lambda function.
function Add(input) { var numbers = JSON.parse(input).numbers; var total = numbers.reduce( function(previousValue, currentValue, index, array) { return previousValue + currentValue; }); return JSON.stringify({ result: total }); }
-
Define the state machine.
{ "Comment": "An example that adds two numbers together.", "StartAt": "Add", "Version": "1.0", "TimeoutSeconds": 10, "States": { "Add": { "Type": "Task", "Resource": "arn:aws-cn:lambda:us-east-1:123456789012:function:Add", "End": true } } }
-
Start an execution with the following JSON text.
{ "numbers": [3, 4] }
The
Add
state receives the JSON text and passes it to the Lambda function.The Lambda function returns the result of the calculation to the state.
The state returns the following value in its output.
{ "result": 7 }
Because
Add
is also the final state in the state machine, this value is returned as the state machine's output.If the final state returns no output, then the state machine returns an empty object (
{}
).
For more information, see Processing input and output in Step Functions.
Invoke Amazon Step Functions from other services
You can configure several other services to invoke state machines. Based on the state machine's workflow type,
you can invoke state machines asynchronously or synchronously. To invoke state machines synchronously, use the
StartSyncExecution
API call or Amazon API Gateway
integration with Express Workflows. With asynchronous invocation, Step Functions pauses the workflow execution until a task token is returned. However, waiting for a task token does make the workflow synchronous.
Services that you can configure to invoke Step Functions include:
-
Amazon Lambda, using the
StartExecution
call.
Step Functions invocations are governed by the StartExecution
quota. For more information, see:
Transitions in state machines
When you start a new execution of your state machine, the system begins with the state
referenced in the top-level StartAt
field. This field, given as a string, must
exactly match, including case, the name of a state in the workflow.
After a state runs, Amazon Step Functions uses the value of the Next
field to determine
the next state to advance to.
Next
fields also specify state names as strings. This string is case-sensitive
and must match the name of a state specified in the state machine description exactly
For example, the following state includes a transition to NextState
.
"SomeState" : {
...,
"Next" : "NextState"
}
Most states permit only a single transition rule with the Next
field. However,
certain flow-control states, such as a Choice
state, allow you to specify
multiple transition rules, each with its own Next
field. The Amazon States Language provides details
about each of the state types you can specify, including information about how to specify
transitions.
States can have multiple incoming transitions from other states.
The process repeats until it either reaches a terminal state (a state with "Type":
Succeed
, "Type": Fail
, or "End": true
), or a runtime
error occurs.
When you redrive an execution, it's considered as a state transition. In addition, all states that are rerun in a redrive are also considered as state transitions.
The following rules apply to states within a state machine:
-
States can occur in any order within the enclosing block. However, the order in which they're listed doesn't affect the order in which they're run. That order is determined by the contents of the states.
-
Within a state machine, there can be only one state designated as the
start
state. Thestart
state is defined by the value of theStartAt
field in the top-level structure. -
Depending on your state machine logic — for example, if your state machine has multiple logic branches — you may have more than one
end
state. -
If your state machine consists of only one state, it can be both the start and end state.
Read Consistency in Step Functions
State machine updates in Amazon Step Functions are eventually consistent. All
StartExecution
calls within a few seconds will use the updated definition
and roleArn
(the Amazon Resource Name for the IAM role). Executions started immediately after calling
UpdateStateMachine
might use the previous state machine definition and
roleArn
.
For more information, see the following:
-
UpdateStateMachine
in the Amazon Step Functions API Reference