AWS::Serverless::StateMachine - Amazon Serverless Application Model
SyntaxPropertiesReturn ValuesExamples
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

AWS::Serverless::StateMachine

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

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

Note

When you deploy to Amazon CloudFormation, Amazon SAM transforms your Amazon SAM resources into Amazon CloudFormation resources. For more information, see Generated Amazon CloudFormation resources.

Syntax

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

YAML

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

Properties

AutoPublishAlias

The name of the state machine alias. To learn more about using Step Functions state machine aliases, see Manage continuous deployments with versions and aliases in the Amazon Step Functions Developer Guide.

Use DeploymentPreference to configure deployment preferences for your alias. If you don’t specify DeploymentPreference, Amazon SAM will configure traffic to shift to the newer state machine version all at once.

Amazon SAM sets the version’s DeletionPolicy and UpdateReplacePolicy to Retain by default. Previous versions will not be deleted automatically.

Type: String

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the Name property of an AWS::StepFunctions::StateMachineAlias resource.

Definition

The state machine definition is an object, where the format of the object matches the format of your Amazon 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

Amazon CloudFormation compatibility: This property is unique to Amazon SAM and doesn't have an Amazon 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

Amazon 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, Amazon 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 Amazon SAM CLI.

You must provide either a Definition or a DefinitionUri.

Type: String | S3Location

Required: Conditional

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

DeploymentPreference

The settings that enable and configure gradual state machine deployments. To learn more about Step Functions gradual deployments, see Manage continuous deployments with versions and aliases in the Amazon Step Functions Developer Guide.

Specify AutoPublishAlias before configuring this property. Your DeploymentPreference settings will be applied to the alias specified with AutoPublishAlias.

When you specify DeploymentPreference, Amazon SAM generates the StateMachineVersionArn sub-property value automatically.

Type: DeploymentPreference

Required: No

Amazon CloudFormation compatibility: Amazon SAM generates and attaches the StateMachineVersionArn property value to DeploymentPreference and passes DeploymentPreference to the DeploymentPreference property of an AWS::StepFunctions::StateMachineAlias 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

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

Logging

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

Type: LoggingConfiguration

Required: No

Amazon 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

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

PermissionsBoundary

The ARN of a permissions boundary to use for this state machine's execution role. This property only works if the role is generated for you.

Type: String

Required: No

Amazon CloudFormation compatibility: This property is passed directly to the PermissionsBoundary property of an AWS::IAM::Role resource.

Policies

Permission policies for this state machine. Policies will be appended to the state machine's default Amazon Identity and Access Management (IAM) execution role.

This property accepts a single value or list of values. Allowed values include:

Note

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

Type: String | List | Map

Required: No

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

PropagateTags

Indicate whether or not to pass tags from the Tags property to your AWS::Serverless::StateMachine generated resources. Specify True to propagate tags in your generated resources.

Type: Boolean

Required: No

Default: False

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

Role

The ARN of an IAM role to use as this state machine's execution role.

Type: String

Required: Conditional

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

RolePath

The path to the state machine's IAM execution role.

Use this property when the role is generated for you. Do not use when the role is specified with the Role property.

Type: String

Required: Conditional

Amazon CloudFormation compatibility: This property is passed directly to the Path property of an AWS::IAM::Role resource.

Tags

A string-to-string map that specifies the tags added to the state machine and the corresponding execution role. For information about valid keys and values for tags, see the Tags property of an AWS::StepFunctions::StateMachine resource.

Type: Map

Required: No

Amazon CloudFormation compatibility: This property is similar to the Tags property of an AWS::StepFunctions::StateMachine resource. Amazon SAM automatically adds a stateMachine:createdBy:SAM tag to this resource, and to the default role that is generated for it.

Tracing

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

Type: TracingConfiguration

Required: No

Amazon 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

Amazon 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 Amazon 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 Amazon 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 an inline state machine definition that allows a lambda function to invoke state machine. Note that this example expects the Role property to configure proper policy to allow invocation. 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 Amazon 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 Amazon 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 Amazon 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