Manage AWS Step Functions Executions as an Integrated Service
Step Functions integrates with its own API as a service integration. This allows 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.
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.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "states:StartExecution" ], "Resource": [ "arn:aws:states:
[[region]]
:[[accountId]]
:stateMachine:[[stateMachineName]]
" ] } ] }
For more information, see IAM permissions for nested workflow executions.