Manage AWS Step Functions Executions as an Integrated Service - AWS Step Functions
Configuring IAM permissions for nested state machines

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.

How the Optimized Step Functions integration is different than the Step Functions AWS SDK integration

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:

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.