Start a new AWS Step Functions state machine from a running execution - AWS Step Functions
Supported APIsExamplesIAM policies

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.

Key features of Optimized Step Functions integration

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

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:states:[[region]]:[[accountId]]:stateMachine:[[stateMachineName]]"
            ]
        }
    ]
}

For more information, see the following:

Synchronous
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "states:StartExecution"
            ],
            "Resource": [
                "arn:aws:states:[[region]]:[[accountId]]:stateMachine:[[stateMachineName]]"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "states:DescribeExecution",
                "states:StopExecution"
            ],
            "Resource": [
               "arn:aws:states:[[region]]:[[accountId]]:execution:[[stateMachineName]]:*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "events:PutTargets",
                "events:PutRule",
                "events:DescribeRule"
            ],
            "Resource": [
               "arn:aws:events:[[region]]:[[accountId]]:rule/StepFunctionsGetEventsForStepFunctionsExecutionRule"
            ]
        }
    ]
}
Asynchronous
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "states:StartExecution"
            ],
            "Resource": [
                "arn:aws:states:[[region]]:[[accountId]]:stateMachine:[[stateMachineName]]"
            ]
        }
    ]
}

For more information about nested workflow executions, see Start workflow executions from a task state in Step Functions.