Start a new AWS 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.
How the Optimized Step Functions integration is different than the Step Functions AWS SDK 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 the Task Token integration patterns.
For more information, see the following:
Supported Step Functions APIs and syntax:
-
-
Supported Parameters
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.