state_machines

Creates, updates, deletes, gets or lists a state_machines resource.

Overview

Name	`state_machines`
Type	Resource
Id	`aws.stepfunctions.state_machines`

Fields

The following fields are returned by SELECT queries:

describe_state_machine
list_state_machines

Name	Datatype	Description
`name`	`string`	The name of the state machine. A name must not contain: white space brackets < > { } [ ] wildcard characters ? * special characters " # % \ ^ \| ~ ` $ & , ; : / control characters (U+0000-001F, U+007F-009F, U+FFFE-FFFF) surrogates (U+D800-DFFF) invalid characters ( U+10FFFF) To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.
`creation_date`	`string (date-time)`	The date the state machine is created. For a state machine version, creationDate is the date the version was created.
`definition`	`string`	The Amazon States Language definition of the state machine. See Amazon States Language. If called with includedData = METADATA_ONLY, the returned definition will be {}.
`description`	`string`	The description of the state machine version.
`encryption_configuration`	`object`	Settings to configure server-side encryption.
`label`	`string`	A user-defined or an auto-generated string that identifies a Map state. This parameter is present only if the stateMachineArn specified in input is a qualified state machine ARN.
`logging_configuration`	`object`	The LoggingConfiguration data type is used to set CloudWatch Logs options.
`revision_id`	`string`	The revision identifier for the state machine. Use the revisionId parameter to compare between versions of a state machine configuration used for executions without performing a diff of the properties, such as definition and roleArn.
`role_arn`	`string`	The Amazon Resource Name (ARN) of the IAM role used when creating this state machine. (The IAM role maintains security by granting Step Functions access to Amazon Web Services resources.)
`state_machine_arn`	`string`	The Amazon Resource Name (ARN) that identifies the state machine. If you specified a state machine version ARN in your request, the API returns the version ARN. The version ARN is a combination of state machine ARN and the version number separated by a colon (:). For example, stateMachineARN:1.
`status`	`string`	The current status of the state machine. (ACTIVE, DELETING)
`tracing_configuration`	`object`	Selects whether X-Ray tracing is enabled.
`type_`	`string`	The type of the state machine (STANDARD or EXPRESS). (STANDARD, EXPRESS)
`variable_references`	`object`	A map of state name to a list of variables referenced by that state. States that do not use variable references will not be shown in the response.

Name	Datatype	Description
`name`	`string`	The name of the state machine. A name must not contain: white space brackets < > { } [ ] wildcard characters ? * special characters " # % \ ^ \| ~ ` $ & , ; : / control characters (U+0000-001F, U+007F-009F, U+FFFE-FFFF) surrogates (U+D800-DFFF) invalid characters ( U+10FFFF) To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.
`creation_date`	`string (date-time)`	The date the state machine is created.
`state_machine_arn`	`string`	The Amazon Resource Name (ARN) that identifies the state machine.
`type_`	`string`	(STANDARD, EXPRESS)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Description
`describe_state_machine`	`select`	`region`	Provides information about a state machine's definition, its IAM role Amazon Resource Name (ARN), and configuration. A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN. The following are some examples of qualified and unqualified state machine ARNs: The following qualified state machine ARN refers to a Distributed Map state with a label mapStateLabel in a state machine named myStateMachine. arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel If you provide a qualified state machine ARN that refers to a Distributed Map state, the request fails with ValidationException. The following qualified state machine ARN refers to an alias named PROD. arn:`<partition>`:states:`<region>`:`<account-id>`:stateMachine:`<myStateMachine:PROD>` If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias. The following unqualified state machine ARN refers to a state machine named myStateMachine. arn:`<partition>`:states:`<region>`:`<account-id>`:stateMachine:`<myStateMachine>` This API action returns the details for a state machine version if the stateMachineArn you specify is a state machine version ARN. This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.
`list_state_machines`	`select`	`region`	Lists the existing state machines. If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error. This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.
`create_state_machine`	`insert`	`region`, `name`, `definition`, `roleArn`	Creates a state machine. A state machine consists of a collection of states that can do work (Task states), determine to which states to transition next (Choice states), stop an execution with an error (Fail states), and so on. State machines are specified using a JSON-based, structured language. For more information, see Amazon States Language in the Step Functions User Guide. If you set the publish parameter of this API action to true, it publishes version 1 as the first revision of the state machine. For additional control over security, you can encrypt your data using a customer-managed key for Step Functions state machines. You can configure a symmetric KMS key and data key reuse period when creating or updating a State Machine. The execution history and state machine definition will be encrypted with the key applied to the State Machine. This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes. CreateStateMachine is an idempotent API. Subsequent requests won’t create a duplicate resource if it was already created. CreateStateMachine's idempotency check is based on the state machine name, definition, type, LoggingConfiguration, TracingConfiguration, and EncryptionConfiguration The check is also based on the publish and versionDescription parameters. If a following request has a different roleArn or tags, Step Functions will ignore these differences and treat it as an idempotent request of the previous. In this case, roleArn and tags will not be updated, even if they are different.
`update_state_machine`	`update`	`region`, `stateMachineArn`	Updates an existing state machine by modifying its definition, roleArn, loggingConfiguration, or EncryptionConfiguration. Running executions will continue to use the previous definition and roleArn. You must include at least one of definition or roleArn or you will receive a MissingRequiredParameter error. A qualified state machine ARN refers to a Distributed Map state defined within a state machine. For example, the qualified state machine ARN arn:partition:states:region:account-id:stateMachine:stateMachineName/mapStateLabel refers to a Distributed Map state with a label mapStateLabel in the state machine named stateMachineName. A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN. The following are some examples of qualified and unqualified state machine ARNs: The following qualified state machine ARN refers to a Distributed Map state with a label mapStateLabel in a state machine named myStateMachine. arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel If you provide a qualified state machine ARN that refers to a Distributed Map state, the request fails with ValidationException. The following qualified state machine ARN refers to an alias named PROD. arn:`<partition>`:states:`<region>`:`<account-id>`:stateMachine:`<myStateMachine:PROD>` If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias. The following unqualified state machine ARN refers to a state machine named myStateMachine. arn:`<partition>`:states:`<region>`:`<account-id>`:stateMachine:`<myStateMachine>` After you update your state machine, you can set the publish parameter to true in the same action to publish a new version. This way, you can opt-in to strict versioning of your state machine. Step Functions assigns monotonically increasing integers for state machine versions, starting at version number 1. All StartExecution calls within a few seconds use the updated definition and roleArn. Executions started immediately after you call UpdateStateMachine may use the previous state machine definition and roleArn.
`delete_state_machine`	`delete`	`region`	Deletes a state machine. This is an asynchronous operation. It sets the state machine's status to DELETING and begins the deletion process. A state machine is deleted only when all its executions are completed. On the next state transition, the state machine's executions are terminated. A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN. The following are some examples of qualified and unqualified state machine ARNs: The following qualified state machine ARN refers to a Distributed Map state with a label mapStateLabel in a state machine named myStateMachine. arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel If you provide a qualified state machine ARN that refers to a Distributed Map state, the request fails with ValidationException. The following unqualified state machine ARN refers to a state machine named myStateMachine. arn:partition:states:region:account-id:stateMachine:myStateMachine This API action also deletes all versions and aliases associated with a state machine. For EXPRESS state machines, the deletion happens eventually (usually in less than a minute). Running executions may emit logs after DeleteStateMachine API is called.
`publish_state_machine_version`	`exec`	`region`, `stateMachineArn`	Creates a version from the current revision of a state machine. Use versions to create immutable snapshots of your state machine. You can start executions from versions either directly or with an alias. To create an alias, use CreateStateMachineAlias. You can publish up to 1000 versions for each state machine. You must manually delete unused versions using the DeleteStateMachineVersion API action. PublishStateMachineVersion is an idempotent API. It doesn't create a duplicate state machine version if it already exists for the current revision. Step Functions bases PublishStateMachineVersion's idempotency check on the stateMachineArn, name, and revisionId parameters. Requests with the same parameters return a successful idempotent response. If you don't specify a revisionId, Step Functions checks for a previously published version of the state machine's current revision. Related operations: DeleteStateMachineVersion ListStateMachineVersions
`start_sync_execution`	`exec`	`region`, `stateMachineArn`	Starts a Synchronous Express state machine execution. StartSyncExecution is not available for STANDARD workflows. StartSyncExecution will return a 200 OK response, even if your execution fails, because the status code in the API response doesn't reflect function errors. Error codes are reserved for errors that prevent your execution from running, such as permissions errors, limit errors, or issues with your state machine code and configuration. This API action isn't logged in CloudTrail.
`validate_state_machine_definition`	`exec`	`region`, `definition`	Validates the syntax of a state machine definition specified in Amazon States Language (ASL), a JSON-based, structured language. You can validate that a state machine definition is correct without creating a state machine resource. Suggested uses for ValidateStateMachineDefinition: Integrate automated checks into your code review or Continuous Integration (CI) process to check state machine definitions before starting deployments. Run validation from a Git pre-commit hook to verify the definition before committing to your source repository. Validation will look for problems in your state machine definition and return a result and a list of diagnostic elements. The result value will be OK when your workflow definition can be successfully created or updated. Note the result can be OK even when diagnostic warnings are present in the response. The result value will be FAIL when the workflow definition contains errors that would prevent you from creating or updating your state machine. The list of ValidateStateMachineDefinitionDiagnostic data elements can contain zero or more WARNING and/or ERROR elements. The ValidateStateMachineDefinition API might add new diagnostics in the future, adjust diagnostic codes, or change the message wording. Your automated processes should only rely on the value of the result field value (OK, FAIL). Do not rely on the exact order, count, or wording of diagnostic messages.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`region`	`string`	AWS region (default: us-east-1)

`SELECT` examples

describe_state_machine
list_state_machines

Provides information about a state machine's definition, its IAM role Amazon Resource Name (ARN), and configuration. A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN. The following are some examples of qualified and unqualified state machine ARNs: The following qualified state machine ARN refers to a Distributed Map state with a label mapStateLabel in a state machine named myStateMachine. arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel If you provide a qualified state machine ARN that refers to a Distributed Map state, the request fails with ValidationException. The following qualified state machine ARN refers to an alias named PROD. arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD> If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias. The following unqualified state machine ARN refers to a state machine named myStateMachine. arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine> This API action returns the details for a state machine version if the stateMachineArn you specify is a state machine version ARN. This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.

SELECT
name,
creation_date,
definition,
description,
encryption_configuration,
label,
logging_configuration,
revision_id,
role_arn,
state_machine_arn,
status,
tracing_configuration,
type_,
variable_references
FROM aws.stepfunctions.state_machines
WHERE region = '{{ region }}' -- required
;

Lists the existing state machines. If nextToken is returned, there are more results available. The value of nextToken is a unique pagination token for each page. Make the call again using the returned token to retrieve the next page. Keep all other arguments unchanged. Each pagination token expires after 24 hours. Using an expired pagination token will return an HTTP 400 InvalidToken error. This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes.

SELECT
name,
creation_date,
state_machine_arn,
type_
FROM aws.stepfunctions.state_machines
WHERE region = '{{ region }}' -- required
;

`INSERT` examples

create_state_machine
Manifest

Creates a state machine. A state machine consists of a collection of states that can do work (Task states), determine to which states to transition next (Choice states), stop an execution with an error (Fail states), and so on. State machines are specified using a JSON-based, structured language. For more information, see Amazon States Language in the Step Functions User Guide. If you set the publish parameter of this API action to true, it publishes version 1 as the first revision of the state machine. For additional control over security, you can encrypt your data using a customer-managed key for Step Functions state machines. You can configure a symmetric KMS key and data key reuse period when creating or updating a State Machine. The execution history and state machine definition will be encrypted with the key applied to the State Machine. This operation is eventually consistent. The results are best effort and may not reflect very recent updates and changes. CreateStateMachine is an idempotent API. Subsequent requests won’t create a duplicate resource if it was already created. CreateStateMachine's idempotency check is based on the state machine name, definition, type, LoggingConfiguration, TracingConfiguration, and EncryptionConfiguration The check is also based on the publish and versionDescription parameters. If a following request has a different roleArn or tags, Step Functions will ignore these differences and treat it as an idempotent request of the previous. In this case, roleArn and tags will not be updated, even if they are different.

INSERT INTO aws.stepfunctions.state_machines (
name,
definition,
roleArn,
type,
loggingConfiguration,
tags,
tracingConfiguration,
publish,
versionDescription,
encryptionConfiguration,
region
)
SELECT 
'{{ name }}' /* required */,
'{{ definition }}' /* required */,
'{{ roleArn }}' /* required */,
'{{ type }}',
'{{ loggingConfiguration }}',
'{{ tags }}',
'{{ tracingConfiguration }}',
{{ publish }},
'{{ versionDescription }}',
'{{ encryptionConfiguration }}',
'{{ region }}'
RETURNING
creation_date,
state_machine_arn,
state_machine_version_arn
;

# Description fields are for documentation purposes
- name: state_machines
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the state_machines resource.
  - name: name
    value: "{{ name }}"
    description: |
      The name of the state machine. A name must not contain: white space brackets < > { } [ ] wildcard characters ? * special characters " # %  ^ | ~ ` $ & , ; : / control characters (U+0000-001F, U+007F-009F, U+FFFE-FFFF) surrogates (U+D800-DFFF) invalid characters ( U+10FFFF) To enable logging with CloudWatch Logs, the name should only contain 0-9, A-Z, a-z, - and _.
  - name: definition
    value: "{{ definition }}"
    description: |
      The Amazon States Language definition of the state machine. See Amazon States Language.
  - name: roleArn
    value: "{{ roleArn }}"
    description: |
      The Amazon Resource Name (ARN) of the IAM role to use for this state machine.
  - name: type
    value: "{{ type }}"
    description: |
      Determines whether a Standard or Express state machine is created. The default is STANDARD. You cannot update the type of a state machine once it has been created.
    valid_values: ['STANDARD', 'EXPRESS']
  - name: loggingConfiguration
    description: |
      Defines what execution history events are logged and where they are logged. By default, the level is set to OFF. For more information see Log Levels in the Step Functions User Guide.
    value:
      level: "{{ level }}"
      includeExecutionData: {{ includeExecutionData }}
      destinations:
        - cloudWatchLogsLogGroup:
            logGroupArn: "{{ logGroupArn }}"
  - name: tags
    description: |
      Tags to be added when creating a state machine. An array of key-value pairs. For more information, see Using Cost Allocation Tags in the Amazon Web Services Billing and Cost Management User Guide, and Controlling Access Using IAM Tags. Tags may only contain Unicode letters, digits, white space, or these symbols: _ . : / = + - @.
    value:
      - key: "{{ key }}"
        value: "{{ value }}"
  - name: tracingConfiguration
    description: |
      Selects whether X-Ray tracing is enabled.
    value:
      enabled: {{ enabled }}
  - name: publish
    value: {{ publish }}
    description: |
      Set to true to publish the first version of the state machine during creation. The default is false.
  - name: versionDescription
    value: "{{ versionDescription }}"
    description: |
      Sets description about the state machine version. You can only set the description if the publish parameter is set to true. Otherwise, if you set versionDescription, but publish to false, this API action throws ValidationException.
  - name: encryptionConfiguration
    description: |
      Settings to configure server-side encryption.
    value:
      kmsKeyId: "{{ kmsKeyId }}"
      kmsDataKeyReusePeriodSeconds: {{ kmsDataKeyReusePeriodSeconds }}
      type_: "{{ type_ }}"

`UPDATE` examples

update_state_machine

Updates an existing state machine by modifying its definition, roleArn, loggingConfiguration, or EncryptionConfiguration. Running executions will continue to use the previous definition and roleArn. You must include at least one of definition or roleArn or you will receive a MissingRequiredParameter error. A qualified state machine ARN refers to a Distributed Map state defined within a state machine. For example, the qualified state machine ARN arn:partition:states:region:account-id:stateMachine:stateMachineName/mapStateLabel refers to a Distributed Map state with a label mapStateLabel in the state machine named stateMachineName. A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN. The following are some examples of qualified and unqualified state machine ARNs: The following qualified state machine ARN refers to a Distributed Map state with a label mapStateLabel in a state machine named myStateMachine. arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel If you provide a qualified state machine ARN that refers to a Distributed Map state, the request fails with ValidationException. The following qualified state machine ARN refers to an alias named PROD. arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine:PROD> If you provide a qualified state machine ARN that refers to a version ARN or an alias ARN, the request starts execution for that version or alias. The following unqualified state machine ARN refers to a state machine named myStateMachine. arn:<partition>:states:<region>:<account-id>:stateMachine:<myStateMachine> After you update your state machine, you can set the publish parameter to true in the same action to publish a new version. This way, you can opt-in to strict versioning of your state machine. Step Functions assigns monotonically increasing integers for state machine versions, starting at version number 1. All StartExecution calls within a few seconds use the updated definition and roleArn. Executions started immediately after you call UpdateStateMachine may use the previous state machine definition and roleArn.

UPDATE aws.stepfunctions.state_machines
SET 
stateMachineArn = '{{ stateMachineArn }}',
definition = '{{ definition }}',
roleArn = '{{ roleArn }}',
loggingConfiguration = '{{ loggingConfiguration }}',
tracingConfiguration = '{{ tracingConfiguration }}',
publish = {{ publish }},
versionDescription = '{{ versionDescription }}',
encryptionConfiguration = '{{ encryptionConfiguration }}'
WHERE 
region = '{{ region }}' --required
AND stateMachineArn = '{{ stateMachineArn }}' --required
RETURNING
revision_id,
state_machine_version_arn,
update_date;

`DELETE` examples

delete_state_machine

Deletes a state machine. This is an asynchronous operation. It sets the state machine's status to DELETING and begins the deletion process. A state machine is deleted only when all its executions are completed. On the next state transition, the state machine's executions are terminated. A qualified state machine ARN can either refer to a Distributed Map state defined within a state machine, a version ARN, or an alias ARN. The following are some examples of qualified and unqualified state machine ARNs: The following qualified state machine ARN refers to a Distributed Map state with a label mapStateLabel in a state machine named myStateMachine. arn:partition:states:region:account-id:stateMachine:myStateMachine/mapStateLabel If you provide a qualified state machine ARN that refers to a Distributed Map state, the request fails with ValidationException. The following unqualified state machine ARN refers to a state machine named myStateMachine. arn:partition:states:region:account-id:stateMachine:myStateMachine This API action also deletes all versions and aliases associated with a state machine. For EXPRESS state machines, the deletion happens eventually (usually in less than a minute). Running executions may emit logs after DeleteStateMachine API is called.

DELETE FROM aws.stepfunctions.state_machines
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

publish_state_machine_version
start_sync_execution
validate_state_machine_definition

Creates a version from the current revision of a state machine. Use versions to create immutable snapshots of your state machine. You can start executions from versions either directly or with an alias. To create an alias, use CreateStateMachineAlias. You can publish up to 1000 versions for each state machine. You must manually delete unused versions using the DeleteStateMachineVersion API action. PublishStateMachineVersion is an idempotent API. It doesn't create a duplicate state machine version if it already exists for the current revision. Step Functions bases PublishStateMachineVersion's idempotency check on the stateMachineArn, name, and revisionId parameters. Requests with the same parameters return a successful idempotent response. If you don't specify a revisionId, Step Functions checks for a previously published version of the state machine's current revision. Related operations: DeleteStateMachineVersion ListStateMachineVersions

EXEC aws.stepfunctions.state_machines.publish_state_machine_version 
@region='{{ region }}' --required 
@@json=
'{
"stateMachineArn": "{{ stateMachineArn }}", 
"revisionId": "{{ revisionId }}", 
"description": "{{ description }}"
}'
;

Starts a Synchronous Express state machine execution. StartSyncExecution is not available for STANDARD workflows. StartSyncExecution will return a 200 OK response, even if your execution fails, because the status code in the API response doesn't reflect function errors. Error codes are reserved for errors that prevent your execution from running, such as permissions errors, limit errors, or issues with your state machine code and configuration. This API action isn't logged in CloudTrail.

EXEC aws.stepfunctions.state_machines.start_sync_execution 
@region='{{ region }}' --required 
@@json=
'{
"stateMachineArn": "{{ stateMachineArn }}", 
"name": "{{ name }}", 
"input": "{{ input }}", 
"traceHeader": "{{ traceHeader }}", 
"includedData": "{{ includedData }}"
}'
;

Validates the syntax of a state machine definition specified in Amazon States Language (ASL), a JSON-based, structured language. You can validate that a state machine definition is correct without creating a state machine resource. Suggested uses for ValidateStateMachineDefinition: Integrate automated checks into your code review or Continuous Integration (CI) process to check state machine definitions before starting deployments. Run validation from a Git pre-commit hook to verify the definition before committing to your source repository. Validation will look for problems in your state machine definition and return a result and a list of diagnostic elements. The result value will be OK when your workflow definition can be successfully created or updated. Note the result can be OK even when diagnostic warnings are present in the response. The result value will be FAIL when the workflow definition contains errors that would prevent you from creating or updating your state machine. The list of ValidateStateMachineDefinitionDiagnostic data elements can contain zero or more WARNING and/or ERROR elements. The ValidateStateMachineDefinition API might add new diagnostics in the future, adjust diagnostic codes, or change the message wording. Your automated processes should only rely on the value of the result field value (OK, FAIL). Do not rely on the exact order, count, or wording of diagnostic messages.

EXEC aws.stepfunctions.state_machines.validate_state_machine_definition 
@region='{{ region }}' --required 
@@json=
'{
"definition": "{{ definition }}", 
"type": "{{ type }}", 
"severity": "{{ severity }}", 
"maxResults": {{ maxResults }}
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​