Learn about state machines in Step Functions
Step Functions is based on state machines and tasks. In Step Functions, state machines are called workflows, which are a series of event-driven steps. Each step in a workflow is called a state. For example, a Task state represents a unit of work that another AWS service performs, such as calling another AWS service or API. Instances of running workflows performing tasks are called executions in Step Functions.
Introduction to state machines
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 AWS service API actions from your workflow. For more information, see Integrating services with Step Functions. |
Service integration type |
|
Service integration pattern | When calling an AWS 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 AWS 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 AWS 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 AWS 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: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 AWS 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:
-
AWS 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, AWS 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.
Transitions in Distributed Map state
When you use the Map
state in Distributed mode, you'll be charged one state transition for each child workflow execution that the Distributed Map state starts. When you use the Map
state in Inline mode, you aren't charged a state transition for each iteration of the Inline Map state.
You can optimize cost by using the Map
state in Distributed mode and
include a nested workflow in the Map
state definition. The Distributed Map state also
adds more value when you start child workflow executions of type Express.
Step Functions stores the response and status of the Express child workflow executions, which
reduces the need to store execution data in CloudWatch Logs. You can also get access to flow
controls available with a Distributed Map state, such as defining error thresholds or batching a
group of items. For information about Step Functions pricing, see AWS Step Functions pricing
Read Consistency in Step Functions
State machine updates in AWS 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 AWS Step Functions API Reference -
Update a workflow in Learn how to get started with Step Functions.