AWS::Serverless::StateMachine - AWS Serverless Application Model

AWS::Serverless::StateMachine

Creates an AWS Step Functions state machine, which you can use to orchestrate AWS Lambda functions and other AWS resources to form complex and robust workflows.

For more information about Step Functions, see the AWS Step Functions Developer Guide.

Note: To manage AWS SAM templates that contain Step Functions state machines, you must use version 0.52.0 or later of the AWS SAM CLI. To check which version you have, run the command sam --version.

Syntax

To declare this entity in your AWS Serverless Application Model (AWS SAM) template, use the following syntax.

YAML

Type: AWS::Serverless::StateMachine Properties: Definition: Map DefinitionSubstitutions: Map DefinitionUri: String | S3Location Events: EventSource Logging: LoggingConfiguration Name: String Policies: String | List | Map Role: String Tags: Map Tracing: TracingConfiguration Type: String

Properties

Definition

The state machine definition is an object, where the format of the object matches the format of your AWS SAM template file, for example, JSON or YAML. State machine definitions adhere to the Amazon States Language.

For an example of an inline state machine definition, see Examples.

You must provide either a Definition or a DefinitionUri.

Type: Map

Required: Conditional

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

DefinitionSubstitutions

A string-to-string map that specifies the mappings for placeholder variables in the state machine definition. This enables you to inject values obtained at runtime (for example, from intrinsic functions) into the state machine definition.

Type: Map

Required: No

AWS CloudFormation compatibility: This property is similar to the DefinitionSubstitutions property of an AWS::StepFunctions::StateMachine resource. If any intrinsic functions are specified in an inline state machine definition, AWS SAM adds entries to this property to inject them into the state machine definition.

DefinitionUri

The Amazon Simple Storage Service (Amazon S3) URI or local file path of the state machine definition written in the Amazon States Language.

If you provide a local file path, the template must go through the workflow that includes the sam deploy or sam package command to correctly transform the definition. To do this, you must use version 0.52.0 or later of the AWS SAM CLI.

You must provide either a Definition or a DefinitionUri.

Type: String | S3Location

Required: Conditional

AWS CloudFormation compatibility: This property is passed directly to the DefinitionS3Location property of an AWS::StepFunctions::StateMachine resource.

Events

Specifies the events that trigger this state machine. Events consist of a type and a set of properties that depend on the type.

Type: EventSource

Required: No

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

Logging

Defines which execution history events are logged and where they are logged.

Type: LoggingConfiguration

Required: No

AWS CloudFormation compatibility: This property is passed directly to the LoggingConfiguration property of an AWS::StepFunctions::StateMachine resource.

Name

The name of the state machine.

Type: String

Required: No

AWS CloudFormation compatibility: This property is passed directly to the StateMachineName property of an AWS::StepFunctions::StateMachine resource.

Policies

One or more policies that this state machine's execution role needs.

This property accepts a single string or a list of strings. The property can be the name of AWS managed AWS Identity and Access Management (IAM) policies, AWS SAM policy templates, or one or more inline policy documents formatted as a map.

You provide either a Role or Policies.

If the Role property is set, this property is ignored.

Type: String | List | Map

Required: Conditional

AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.

Role

The Amazon Resource Name (ARN) of an IAM role to use as this state machine's execution role.

You must provide either a Role or Policies.

Type: String

Required: Conditional

AWS CloudFormation compatibility: This property is passed directly to the RoleArn property of an AWS::StepFunctions::StateMachine resource.

Tags

A string-to-string map that specifies the tags added to the state machine and the corresponding IAM execution role.

Type: Map

Required: No

AWS CloudFormation compatibility: This property is passed directly to the Tags property of an AWS::StepFunctions::StateMachine resource.

Tracing

Selects whether or not AWS X-Ray is enabled for the state machine. For more information about using X-Ray with Step Functions, see AWS X-Ray and Step Functions in the AWS Step Functions Developer Guide.

Type: TracingConfiguration

Required: No

AWS CloudFormation compatibility: This property is passed directly to the TracingConfiguration property of an AWS::StepFunctions::StateMachine resource.

Type

The type of the state machine.

Valid values: STANDARD or EXPRESS.

Type: String

Required: No

Default: STANDARD

AWS CloudFormation compatibility: This property is passed directly to the StateMachineType property of an AWS::StepFunctions::StateMachine resource.

Return Values

Ref

When you provide the logical ID of this resource to the Ref intrinsic function, Ref returns the Amazon Resource Name (ARN) of the underlying AWS::StepFunctions::StateMachine resource.

For more information about using the Ref function, see Ref in the AWS CloudFormation User Guide.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using Fn::GetAtt, see Fn::GetAtt in the AWS CloudFormation User Guide.

Name

Returns the name of the state machine, such as HelloWorld-StateMachine.

Examples

State Machine Definition File

The following is an example of a state machine defined with a definition file. The my_state_machine.asl.json file must be written in the Amazon States Language.

In this example, the DefinitionSubstitution entries allow the state machine to include resources that are declared in the AWS SAM template file.

YAML

MySampleStateMachine: Type: AWS::Serverless::StateMachine Properties: DefinitionUri: statemachine/my_state_machine.asl.json Role: arn:aws:iam::123456123456:role/service-role/my-sample-role Tracing: Enabled: True DefinitionSubstitutions: MyFunctionArn: !GetAtt MyFunction.Arn MyDDBTable: !Ref TransactionTable

Inline State Machine Definition

The following is an example of an inline state machine definition.

In this example, the AWS SAM template file is written in YAML, so the state machine definition is also in YAML. To declare an inline state machine definition in JSON, write your AWS SAM template file in JSON.

YAML

MySampleStateMachine: Type: AWS::Serverless::StateMachine Properties: Definition: StartAt: MyLambdaState States: MyLambdaState: Type: Task Resource: arn:aws:lambda:us-east-1:123456123456:function:my-sample-lambda-app End: true Role: arn:aws:iam::123456123456:role/service-role/my-sample-role Tracing: Enabled: True