Syntax Properties Return Values Examples

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

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

Syntax

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

YAML


Type: AWS::Serverless::StateMachine
Properties:
  AutoPublishAlias: String
  UseAliasAsEventTarget: Boolean
  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 AWS Step Functions Developer Guide.

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

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

Type: String

Required: No

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

UseAliasAsEventTarget

Indicate whether or not to pass the alias, created by using the AutoPublishAlias property, to the events source's target defined with Events.

Specify True to use the alias as the events' target.

Type: Boolean

Required: No

Default: False

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

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.

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 AWS 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, AWS SAM generates the StateMachineVersionArn sub-property value automatically.

Type: DeploymentPreference

Required: No

AWS CloudFormation compatibility: AWS 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

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.

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

AWS 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 AWS Identity and Access Management (IAM) execution role.

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

AWS SAM policy templates.
The ARN of an AWS managed policy or customer managed policy.
The name of an AWS managed policy from the following list.
An inline IAM policy formatted in YAML as a map.

Note

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

Type: String | List | Map

Required: No

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

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

Role

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

Type: String

Required: Conditional

AWS 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

AWS 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

AWS CloudFormation compatibility: This property is similar to the Tags property of an AWS::StepFunctions::StateMachine resource. AWS 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 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 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 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

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

PrimaryKeyObject

EventSource