Start a new Amazon Step Functions state machine from a running execution
Step Functions integrates with its own API as a service integration. Learn how to use Step Functions to start a new execution of a state machine directly from the task state of a running execution. When building new workflows, use nested workflow executions to reduce the complexity of your main workflows and to reuse common processes.
Key features of Optimized Step Functions integration
The Run a Job (.sync) integration pattern is available.
Note that there are no optimizations for the Request Response or Wait for a Callback with Task Token integration patterns.
For more information, see the following:
Supported Step Functions APIs
-
-
Supported Parameters
Workflow Examples
The following includes a Task
state that starts an execution of another state
machine and waits for it to complete.
{
"Type":"Task",
"Resource":"arn:aws:states:::states:startExecution.sync:2",
"Parameters":{
"Input":{
"Comment": "Hello world!"
},
"StateMachineArn":"arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld",
"Name":"ExecutionName"
},
"End":true
}
The following includes a Task
state that starts an execution of another state
machine.
{
"Type":"Task",
"Resource":"arn:aws:states:::states:startExecution",
"Parameters":{
"Input":{
"Comment": "Hello world!"
},
"StateMachineArn":"arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld",
"Name":"ExecutionName"
},
"End":true
}
The following includes a Task
state that implements the callback service integration pattern.
{
"Type":"Task",
"Resource":"arn:aws:states:::states:startExecution.waitForTaskToken",
"Parameters":{
"Input":{
"Comment": "Hello world!",
"token.$": "$$.Task.Token"
},
"StateMachineArn":"arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld",
"Name":"ExecutionName"
},
"End":true
}
To associate a nested workflow execution with the parent execution that started it, pass a
specially named parameter that includes the execution ID pulled from the Context object. When starting a nested
execution, use a parameter named AWS_STEP_FUNCTIONS_STARTED_BY_EXECUTION_ID
.
Pass the execution ID by appending .$
to the parameter name, and referencing
the ID in the Context object with $$.Execution.Id
. For more information, see
Accessing the Context object.
{
"Type":"Task",
"Resource":"arn:aws:states:::states:startExecution.sync",
"Parameters":{
"Input":{
"Comment": "Hello world!",
"AWS_STEP_FUNCTIONS_STARTED_BY_EXECUTION_ID.$": "$$.Execution.Id"
},
"StateMachineArn":"arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld",
"Name":"ExecutionName"
},
"End":true
}
Nested state machines return the following:
Resource | Output |
---|---|
startExecution.sync | String |
startExecution.sync:2 | JSON |
Both will wait for the nested state machine to complete, but they return different
Output
formats. For example, if you create a Lambda function that returns
the object { "MyKey": "MyValue" }
, you would get the following
responses:
For startExecution.sync:
{
<other fields>
"Output": "{ \"MyKey\": \"MyValue\" }"
}
For startExecution.sync:2:
{
<other fields>
"Output": {
"MyKey": "MyValue"
}
}
Configuring IAM permissions for nested state machines
A parent state machine determines if a child state machine has completed execution using polling and events. Polling requires permission for
states:DescribeExecution
while events sent through EventBridge to Step Functions require permissions for events:PutTargets
, events:PutRule
,
and events:DescribeRule
. If these permissions are missing from your IAM role, there may be a delay before a parent state machine becomes aware of the
completion of the child state machine's execution.
For a state machine that calls StartExecution
for a single nested workflow execution, use an IAM policy that limits permissions to that state
machine.
For more information, see IAM permissions for Step Functions.
IAM policies for calling nested Step Functions workflows
For a state machine that calls StartExecution
for a single nested workflow
execution, use an IAM policy that limits permissions to that state machine.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"states:StartExecution"
],
"Resource": [
"arn:aws-cn:states:[[region]]
:[[accountId]]
:stateMachine:[[stateMachineName]]
"
]
}
]
}
For more information, see the following:
For more information about nested workflow executions, see Start workflow executions from a task state in Step Functions.