# Discovering workflow states to use in Step Functions
*States* are elements in your state machine. A state is referred to by its *name*, which can be any string, but which must be unique within the scope of the entire state machine.
States take input from the invocation or a previous state. States can filter the input and then manipulate the output that is sent to the next state.
The following is an example state named `HelloWorld` that invokes an AWS Lambda function.
```
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:HelloFunction",
"Next": "AfterHelloWorldState",
"Comment": "Run the HelloWorld Lambda function"
}
```
Individual states can make decisions based on their input, perform actions from those inputs, and pass output to other states. In AWS Step Functions, you define your workflows in the Amazon States Language (ASL). The Step Functions console provides a graphical representation of your state machine to help visualize your application's logic.
The following screenshot shows some of the most popular **Actions** and the seven **Flow** states from Workflow Studio:
![\[Illustrative screenshot showing popular Actions and Flow states in Workflow Studio\]](http://docs.aws.amazon.com/step-functions/latest/dg/images/wfs-actions-flow-panel.png)
States share many common features:
+ A `Type` field indicating what type of state it is.
+ An optional `Comment` field to hold a human-readable comment about, or description of, the state.
+ Each state (except `Succeed` or `Fail` states) requires a `Next` field that specifies the next state in the workflow. `Choice` states can actually have more than one `Next` within each Choice Rule. Alternatively, a state can become a terminal state by setting the `End` field to true.
Certain state types require additional fields, or may redefine common field usage.
**To access log information for workflows**
+ After you have created and run Standard workflows, you can access information about each state, its input and output, when it was active and for how long, by viewing the Execution Details page in the Step Functions console.
+ After you have created and Express Workflow executions and if logging is enabled, you can see execution history in the Step Functions console or Amazon CloudWatch Logs.
For information about viewing and debugging executions, see [Viewing workflow runs](concepts-view-execution-details.md) and [Using CloudWatch Logs to log execution history in Step Functions](cw-logs.md).
## Reference list of workflow states
States are separated in Workflow Studio into **Actions**, also known as **Task states**, and seven **Flow states**. Using **Task states**, or actions in Workflow Studio, you can call third party services, invoke functions, and use hundreds of AWS service endpoints. With **Flow states**, you can direct and control your workflow. All states take input from the previous state, and many provide input filtering, and filtering/transformation for output that is passed to the next state in your workflow.
+ [Task workflow state](state-task.md): Add a single unit of work to be performed by your state machine.
+ [Choice workflow state](state-choice.md): Add a choice between branches of execution to your workflow.
+ [Parallel workflow state](state-parallel.md): Add parallel branches of execution to your workflow.
+ [Map workflow state](state-map.md): Dynamically iterate steps for each element of an input array. Unlike a `Parallel` flow state, a `Map` state will execute the same steps for multiple entries of an array in the state input.
+ [Pass workflow state](state-pass.md): Pass state input through to the output. Optionally, filter, transform, and add fixed data into the output.
+ [Wait workflow state](state-wait.md): Pause your workflow for a certain amount of time or until a specified time or date.
+ [Succeed workflow state](state-succeed.md): Stops your workflow with a success.
+ [Fail workflow state](state-fail.md): Stops your workflow with a failure.
# Task workflow state
**Managing state and transforming data**
Learn about [Passing data between states with variables](workflow-variables.md) and [Transforming data with JSONata](transforming-data.md).
A `Task` state (`"Type": "Task"`) represents a single unit of work performed by a state machine. A task performs work by using an activity or an AWS Lambda function, by integrating with other [supported AWS services](supported-services-awssdk.md#supported-services-awssdk-list), or by invoking a HTTPS API, such as Stripe.
The [Amazon States Language](concepts-amazon-states-language.md) represents tasks by setting a state's type to `Task` and by providing the task with the Amazon Resource Name (ARN) of the activity, Lambda function, or the HTTPS API endpoint.
**Invoke a function with JSONata Arguments**
The following Task state definition (JSONata) invokes a Lambda function named `priceWatcher`.
Note the use of JSONata expressions to query input data to use in Arguments and the task result in the assign field.
```
"Get Current Price": {
"Type": "Task",
"QueryLanguage" : "JSONata",
"Resource": "arn:aws:states:::lambda:invoke",
"Next": "Check Price",
"Arguments": {
"Payload": {
"product": "{% $states.context.Execution.Input.product %}"
},
"FunctionName": "arn:aws:lambda::account-id:function:priceWatcher:$LATEST"
},
"Assign": {
"currentPrice": "{% $states.result.Payload.current_price %}"
}
}
```
**Invoke a function with JSONPath Parameters**
The following Task state definition (JSONPath) invokes a Lambda function named `HelloFunction`.
```
"Lambda Invoke": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:region:account-id:function:HelloFunction:$LATEST"
},
"End": true
}
```
## Task types
Step Functions supports the following task types that you can specify in a Task state definition:
+ [Activity](#state-task-activity)
+ [Lambda functions](#state-task-lambda)
+ [A supported AWS service](#state-task-connector)
+ [An HTTP Task](call-https-apis.md)
You specify a task type by providing its ARN in the `Resource` field of a Task state definition. The following example shows the syntax of the `Resource` field. All Task types except the one that invokes an HTTPS API, use the following syntax. For information about syntax of the HTTP Task, see [Call HTTPS APIs in Step Functions workflows](call-https-apis.md).
In your Task state definition, replace the italicized text in the following syntax with the AWS resource-specific information.
```
arn:partition:service:region:account:task_type:name
```
The following list explains the individual components in this syntax:
+ `partition` is the AWS Step Functions partition to use, most commonly `aws`.
+ `service` indicates the AWS service used to execute the task, and can be one of the following values:
+ `states` for an [activity](#state-task-activity).
+ `lambda` for a [Lambda function](#state-task-lambda). If you integrate with other AWS services, for example, Amazon SNS or Amazon DynamoDB, use `sns` or `dynamodb`.
+ `region` is the [AWS Region code](https://docs.aws.amazon.com/general/latest/gr/rande.html) in which the Step Functions activity or state machine type, Lambda function, or any other AWS resource has been created.
+ `account` is the AWS account ID in which you've defined the resource.
+ `task_type` is the type of task to run. It can be one of the following values:
+ `activity` – An [activity](#state-task-activity).
+ `function` – A [Lambda function](#state-task-lambda).
+ `servicename` – The name of a supported connected service (see [Integrating services with Step Functions](integrate-optimized.md)).
+ `name` is the registered resource name (activity name, Lambda function name, or service API action).
**Note**
Step Functions doesn't support referencing ARNs across partitions or regions. For example, `aws-cn` can't invoke tasks in the `aws` partition, and the other way around.
The following sections provide more detail about each task type.
### Activity
Activities represent workers (processes or threads), implemented and hosted by you, that perform a specific task. They are supported only by Standard Workflows, not Express Workflows.
Activity `Resource` ARNs use the following syntax.
```
arn:partition:states:region:account:activity:name
```
**Note**
You must create activities with Step Functions (using a [CreateActivity](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateActivity.html), API action, or the [Step Functions console](https://console.aws.amazon.com/states/home?region=us-east-1#/)) before their first use.
For more information about creating an activity and implementing workers, see [Activities](concepts-activities.md).
### Lambda functions
Lambda tasks execute a function using AWS Lambda. To specify a Lambda function, use the ARN of the Lambda function in the `Resource` field.
The form of your Lambda function `Resource` field varies based on the type of integration.
For a standard AWS SDK integration with a Lambda function, the `Resource` field will contain the following value:
```
"arn:aws:states:::aws-sdk:lambda:invoke"
```
We **recommend** using the optimized integration for your Lambda functions, using the following value for the `Resource` field:
```
"arn:aws:states:::lambda:invoke"
```
The following `Task` state definition shows an example of an optimized integration with a Lambda function named `HelloWorld` using JSONata.
```
"Optimized call to Lambda function (JSONata)": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Output": "{% $states.result.Payload %}",
"Arguments": {
"FunctionName": "arn:aws:lambda:region:account-id:function:HelloWorld:$LATEST",
"Payload": {
"key": "{% $states.input.myKey %}"
}
},
"Next": "NextState"
}
```
### A supported AWS service
When you reference a connected resource, Step Functions directly calls the API actions of a supported service. Specify the service and action in the `Resource` field.
Connected service `Resource` ARNs use the following syntax.
```
arn:partition:states:region:account-id:servicename:APIname
```
**Note**
To create a synchronous connection to a connected resource, append `.sync` to the *APIname* entry in the ARN. For more information, see [Integrating services](integrate-services.md).
For example:
```
{
"StartAt": "BATCH_JOB",
"States": {
"BATCH_JOB": {
"Type": "Task",
"Resource": "arn:aws:states:::batch:submitJob.sync",
"Parameters": {
"JobDefinition": "preprocessing",
"JobName": "PreprocessingBatchJob",
"JobQueue": "SecondaryQueue",
"Parameters.$": "$.batchjob.parameters",
"RetryStrategy": {
"attempts": 5
}
},
"End": true
}
}
}
```
## Task state fields
In addition to the [common state fields](statemachine-structure.md#amazon-states-language-common-fields), `Task` states have the following fields.
** `Resource` (Required)**
A URI, especially an ARN that uniquely identifies the specific task to execute.
**`Arguments` (Optional, JSONata only)**
Used to pass information to the API actions of connected resources. Values can include JSONata expressions. For more information, see [Transforming data with JSONata in Step Functions](transforming-data.md).
**`Output` (Optional, JSONata only)**
Used to specify and transform output from the state. When specified, the value overrides the state output default.
The output field accepts any JSON value (object, array, string, number, boolean, null). Any string value, including those inside objects or arrays, will be evaluated as JSONata if surrounded by \$1% %\$1 characters.
Output also accepts a JSONata expression directly, for example: "Output": "\$1% jsonata expression %\$1"
For more information, see [Input and Output Processing](concepts-input-output-filtering.md).
**`Parameters` (Optional, JSONPath only)**
Used to pass information to the API actions of connected resources. The parameters can use a mix of static JSON and [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/). For more information, see [Passing parameters to a service API in Step Functions](connect-parameters.md).
**`Credentials` (Optional)**
Specifies a target role the state machine's execution role must assume before invoking the specified `Resource`. Alternatively, you can also specify a JSONPath value or an [intrinsic function](intrinsic-functions.md) that resolves to an IAM role ARN at runtime based on the execution input. If you specify a JSONPath value, you must prefix it with the `$.` notation.
For examples of using this field in the `Task` state, see [Task state's Credentials field examples](#task-state-example-credentials). For an example of using this field to access a cross-account AWS resource from your state machine, see [Accessing cross-account AWS resources in Step Functions](tutorial-access-cross-acct-resources.md).
This field is supported by the [Task types](#task-types) that use [Lambda functions](#state-task-lambda) and [a supported AWS service](integrate-services.md).
** `ResultPath` (Optional, JSONPath only)**
Specifies where (in the input) to place the results of executing the task that's specified in `Resource`. The input is then filtered as specified by the `OutputPath` field (if present) before being used as the state's output. For more information, see [Input and Output Processing](concepts-input-output-filtering.md).
** `ResultSelector` (Optional, JSONPath only)**
Pass a collection of key value pairs, where the values are static or selected from the result. For more information, see [ResultSelector](input-output-inputpath-params.md#input-output-resultselector).
** `Retry` (Optional)**
An array of objects, called Retriers, that define a retry policy if the state encounters runtime errors. For more information, see [State machine examples using Retry and Catch](concepts-error-handling.md#error-handling-examples).
** `Catch` (Optional)**
An array of objects, called Catchers, that define a fallback state. This state is executed if the state encounters runtime errors and its retry policy is exhausted or isn't defined. For more information, see [Fallback States](concepts-error-handling.md#error-handling-fallback-states).
** `TimeoutSeconds` (Optional)**
Specifies the maximum time an activity or a task can run before it times out with the [States.Timeout](concepts-error-handling.md#statestimeout) error and fails. The timeout value must be positive, non-zero integer. The default value is `99999999`.
The timeout count begins when the start event is executed, such as when `TaskStarted`, `ActivityStarted`, or `LambdaFunctionStarted` events are logged in the execution event history. For Activities, the count begins when `GetActivityTask` receives a token and `ActivityStarted` is logged in the execution event history.
When a task starts, Step Functions waits for a success or failure response from the task or activity worker within the specified `TimeoutSeconds` duration. If the task or activity worker fails to respond within this time, Step Functions marks the workflow execution as failed.
HTTP task timeout has a maximum of 60 seconds, even if `TimeoutSeconds` exceeds that limit. See [Quotas related to HTTP Task](service-quotas.md#service-limits-http-task)
** `TimeoutSecondsPath` (Optional, JSONPath only)**
If you want to provide a timeout value dynamically from the state input using a reference path, use `TimeoutSecondsPath`. When resolved, the reference path must select fields whose values are positive integers.
A `Task` state cannot include both `TimeoutSeconds` and `TimeoutSecondsPath`. HTTP task timeout has a maximum of 60 seconds, even if the `TimeoutSecondsPath` value exceeds that limit.
** `HeartbeatSeconds` (Optional)**
Determines the frequency of heartbeat signals an activity worker sends during the execution of a task. Heartbeats indicate that a task is still running and it needs more time to complete. Heartbeats prevent an activity or task from timing out within the `TimeoutSeconds` duration.
`HeartbeatSeconds` must be a positive, non-zero integer value less than the `TimeoutSeconds` field value. The default value is `99999999`. If more time than the specified seconds elapses between heartbeats from the task, the Task state fails with a [States.Timeout](concepts-error-handling.md#statestimeout) error.
For Activities, the count begins when `GetActivityTask` receives a token and `ActivityStarted` is logged in the execution event history.
** `HeartbeatSecondsPath` (Optional, JSONPath only)**
If you want to provide a heartbeat value dynamically from the state input using a reference path, use `HeartbeatSecondsPath`. When resolved, the reference path must select fields whose values are positive integers.
A `Task` state cannot include both `HeartbeatSeconds` and `HeartbeatSecondsPath`.
A `Task` state must set either the `End` field to `true` if the state ends the execution, or must provide a state in the `Next` field that is run when the `Task` state is complete.
## Task state definition examples
The following examples show how you can specify the Task state definition based on your requirement.
+ [Specifying Task state timeouts and heartbeat intervals](#task-state-example-timeouts)
+ [Static timeout and heartbeat notification example](#task-state-example-static)
+ [Dynamic task timeout and heartbeat notification example](#task-state-example-dynamic)
+ [Using Credentials field](#task-state-example-credentials)
+ [Specifying hard-coded IAM role ARN](#example-credentials-specify-role-arn)
+ [Specifying JSONPath as IAM role ARN](#example-credentials-specify-dynamic-jsonpath)
+ [Specifying an intrinsic function as IAM role ARN](#example-credentials-specify-dynamic-intrinsic-function)
### Task state timeouts and heartbeat intervals
It's a good practice to set a timeout value and a heartbeat interval for long-running activities. This can be done by specifying the timeout and heartbeat values, or by setting them dynamically.
#### Static timeout and heartbeat notification example
When `HelloWorld` completes, the next state (here called `NextState`) will be run.
If this task fails to complete within 300 seconds, or doesn't send heartbeat notifications in intervals of 60 seconds, the task is marked as `failed`.
```
"ActivityState": {
"Type": "Task",
"Resource": "arn:aws:states:region:123456789012:activity:HelloWorld",
"TimeoutSeconds": 300,
"HeartbeatSeconds": 60,
"Next": "NextState"
}
```
#### Dynamic task timeout and heartbeat notification example
In this example, when the AWS Glue job completes, the next state will be run.
If this task fails to complete within the interval set dynamically by the AWS Glue job, the task is marked as `failed`.
```
"GlueJobTask": {
"Type": "Task",
"Resource": "arn:aws:states:::glue:startJobRun.sync",
"Parameters": {
"JobName": "myGlueJob"
},
"TimeoutSecondsPath": "$.params.maxTime",
"Next": "NextState"
}
```
### Task state's Credentials field examples
#### Specifying hard-coded IAM role ARN
The following example specifies a target IAM role that a state machine's execution role must assume to access a cross-account Lambda function named `Echo`. In this example, the target role ARN is specified as a hard-coded value.
```
{
"StartAt": "Cross-account call",
"States": {
"Cross-account call": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Credentials": {
"RoleArn": "arn:aws:iam::111122223333:role/LambdaRole"
},
"Parameters": {
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:Echo"
},
"End": true
}
}
}
```
#### Specifying JSONPath as IAM role ARN
The following example specifies a JSONPath value, which will resolve to an IAM role ARN at runtime.
```
{
"StartAt": "Lambda",
"States": {
"Lambda": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Credentials": {
"RoleArn.$": "$.roleArn"
},
...
}
}
}
```
#### Specifying an intrinsic function as IAM role ARN
The following example uses the [`States.Format`](intrinsic-functions.md#asl-intrsc-func-generic) intrinsic function, which resolves to an IAM role ARN at runtime.
```
{
"StartAt": "Lambda",
"States": {
"Lambda": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Credentials": {
"RoleArn.$": "States.Format('arn:aws:iam::{}:role/ROLENAME', $.accountId)"
},
...
}
}
}
```
# Choice workflow state
**Managing state and transforming data**
Learn about [Passing data between states with variables](workflow-variables.md) and [Transforming data with JSONata](transforming-data.md).
A `Choice` state (`"Type": "Choice"`) adds conditional logic to a state machine.
In addition to most of the [common state fields](statemachine-structure.md#amazon-states-language-common-fields), `Choice` states contains the following additional fields.
**`Choices` (Required)**
An array of [Choice Rules](#state-choice-rules) that determines which state the state machine transitions to next. You must define at least one rule in the `Choice` state.
When a `Choice` state is run, Step Functions evaluates each **Choice Rule** to true or false. Based on the result, Step Functions transitions to the next state in the workflow.
**`Default` (Optional, Recommended)**
The name of the state to transition to if no **Choice Rule** evaluates to true.
**Important**
`Choice` states do not support the `End` field. In addition, they use `Next` only inside their `Choices` field.
If no **Choices** evaluate to true when the workflow runs, and no **Default** is provided, the state machine will throw an **error** due to a *failure to transition out of the state*.
## Choice Rules (JSONata)
A `Choice` state must have a `Choices` field whose value is a non-empty array of Choice Rules, which contain the following fields when using JSONata:
+ **`Condition` field** – a JSONata expression that evaluates to true/false.
+ **`Next` field** – a value that must match a state name in the state machine.
The following example checks whether the numerical value is equal to `1`.
```
{
"Condition": "{% $foo = 1 %}",
"Next": "NumericMatchState"
}
```
The following example checks whether the `type`variable is equal to `local`.
```
{
"Condition": "{% $type = 'local' %}",
"Next": "StringMatchState"
}
```
The following example checks whether the string is greater than `MyStringABC`.
```
{
"Condition": "{% $foo > 'MyStringABC' %}",
"Next": "StringGreaterMatchState"
}
```
The following example checks whether the string is not null.
```
{
"Condition" : "{% $possiblyNullValue != null and $possiblyNullValue = 42 %}",
"Next": "NotNullAnd42"
}
```
## Choice Rules (JSONPath)
A `Choice` state must have a `Choices` field whose value is a non-empty array of Choice Rules, which contain the following fields when using JSONPath:
+ A **comparison** – Two fields that specify an input variable to compare, the type of comparison, and the value to compare the variable to. Choice Rules support comparison between two variables. Within a Choice Rule, the value of variable can be compared with another value from the state input by appending `Path` to name of supported comparison operators. The values of `Variable` and Path fields in a comparison must be valid [Reference Paths](amazon-states-language-paths.md#amazon-states-language-reference-paths).
+ A **`Next` field** – The value of this field must match a state name in the state machine.
The following example checks whether the numerical value is equal to `1`.
```
{
"Variable": "$.foo",
"NumericEquals": 1,
"Next": "FirstMatchState"
}
```
The following example checks whether the string is equal to `MyString`.
```
{
"Variable": "$.foo",
"StringEquals": "MyString",
"Next": "FirstMatchState"
}
```
The following example checks whether the string is greater than `MyStringABC`.
```
{
"Variable": "$.foo",
"StringGreaterThan": "MyStringABC",
"Next": "FirstMatchState"
}
```
The following example checks whether the string is null.
```
{
"Variable": "$.possiblyNullValue",
"IsNull": true
}
```
The following example shows how the StringEquals rule is only evaluated when `$.keyThatMightNotExist` exists because of the preceding `IsPresent` Choice Rule.
```
"And": [
{
"Variable": "$.keyThatMightNotExist",
"IsPresent": true
},
{
"Variable": "$.keyThatMightNotExist",
"StringEquals": "foo"
}
]
```
The following example checks whether a pattern with a wildcard matches.
```
{
"Variable": "$.foo",
"StringMatches": "log-*.txt"
}
```
The following example checks whether the timestamp is equal to `2001-01-01T12:00:00Z`.
```
{
"Variable": "$.foo",
"TimestampEquals": "2001-01-01T12:00:00Z",
"Next": "FirstMatchState"
}
```
The following example compares a variable with another value from the state input.
```
{
"Variable": "$.foo",
"StringEqualsPath": "$.bar"
}
```
Step Functions examines each of the Choice Rules in the order listed in the `Choices` field. Then it transitions to the state specified in the `Next` field of the first Choice Rule in which the variable matches the value according to the comparison operator.
The following comparison operators are supported:
+ `And`
+ `BooleanEquals`,`BooleanEqualsPath`
+ `IsBoolean`
+ `IsNull`
+ `IsNumeric`
+ `IsPresent`
+ `IsString`
+ `IsTimestamp`
+ `Not`
+ `NumericEquals`,`NumericEqualsPath`
+ `NumericGreaterThan`,`NumericGreaterThanPath`
+ `NumericGreaterThanEquals`,`NumericGreaterThanEqualsPath`
+ `NumericLessThan`,`NumericLessThanPath`
+ `NumericLessThanEquals`,`NumericLessThanEqualsPath`
+ `Or`
+ `StringEquals`,`StringEqualsPath`
+ `StringGreaterThan`,`StringGreaterThanPath`
+ `StringGreaterThanEquals`,`StringGreaterThanEqualsPath`
+ `StringLessThan`,`StringLessThanPath`
+ `StringLessThanEquals`,`StringLessThanEqualsPath`
+ `StringMatches`
+ `TimestampEquals`,`TimestampEqualsPath`
+ `TimestampGreaterThan`,`TimestampGreaterThanPath`
+ `TimestampGreaterThanEquals`,`TimestampGreaterThanEqualsPath`
+ `TimestampLessThan`,`TimestampLessThanPath`
+ `TimestampLessThanEquals`,`TimestampLessThanEqualsPath`
For each of these operators, the corresponding value must be of the appropriate type: string, number, Boolean, or timestamp. Step Functions doesn't attempt to match a numeric field to a string value. However, because timestamp fields are logically strings, it's possible that a field considered to be a timestamp can be matched by a `StringEquals` comparator.
**Note**
For interoperability, don't assume that numeric comparisons work with values outside the magnitude or precision that the [IEEE 754-2008 `binary64` data type](https://en.wikipedia.org/wiki/IEEE_754#Basic_and_interchange_formats) represents. In particular, integers outside of the range `[-253+1, 253-1]` might fail to compare in the expected way.
Timestamps (for example, `2016-08-18T17:33:00Z`) must conform to [RFC3339 profile ISO 8601](https://www.ietf.org/rfc/rfc3339.txt), with further restrictions:
An uppercase `T` must separate the date and time portions.
An uppercase `Z` must denote that a numeric time zone offset isn't present.
To understand the behavior of string comparisons, see the [Java `compareTo` documentation](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#compareTo-java.lang.String-).
The values of the `And` and `Or` operators must be non-empty arrays of Choice Rules that must not themselves contain `Next` fields. Likewise, the value of a `Not` operator must be a single Choice Rule that must not contain `Next` fields.
You can create complex, nested Choice Rules using `And`, `Not`, and `Or`. However, the `Next` field can appear only in a top-level Choice Rule.
String comparison against patterns with one or more wildcards (“\$1”) can be performed with the StringMatches comparison operator. The wildcard character is escaped by using the standard `\\ (Ex: “\\*”)`. No characters other than “\$1” have any special meaning during matching.
# Parallel workflow state
**Managing state and transforming data**
Learn about [Passing data between states with variables](workflow-variables.md) and [Transforming data with JSONata](transforming-data.md).
The `Parallel` state (`"Type": "Parallel"`) can be used to add separate branches of execution in your state machine.
In addition to the [common state fields](statemachine-structure.md#amazon-states-language-common-fields), `Parallel` states include these additional fields.
** `Branches` (Required)**
An array of objects that specify state machines to execute in parallel. Each such state machine object must have fields named `States` and `StartAt`, whose meanings are exactly like those in the top level of a state machine.
**`Parameters` (Optional, JSONPath only)**
Used to pass information to the state machines defined in the `Branches` array.
**`Arguments` (Optional, JSONata only)**
Used to pass information to the API actions of connected resources. Values can include JSONata expressions. For more information, see [Transforming data with JSONata in Step Functions](transforming-data.md).
**`Output` (Optional, JSONata only)**
Used to specify and transform output from the state. When specified, the value overrides the state output default.
The output field accepts any JSON value (object, array, string, number, boolean, null). Any string value, including those inside objects or arrays, will be evaluated as JSONata if surrounded by \$1% %\$1 characters.
Output also accepts a JSONata expression directly, for example: "Output": "\$1% jsonata expression %\$1"
For more information, see [Transforming data with JSONata in Step Functions](transforming-data.md).
** `Assign` (Optional)**
Used to store variables. The `Assign` field accepts a JSON object with key/value pairs that define variable names and their assigned values. Any string value, including those inside objects or arrays, will be evaluated as JSONata when surrounded by `{% %}` characters
For more information, see [Passing data between states with variables](workflow-variables.md).
** `ResultPath` (Optional, JSONPath only)**
Specifies where (in the input) to place the output of the branches. The input is then filtered as specified by the `OutputPath` field (if present) before being used as the state's output. For more information, see [Input and Output Processing](concepts-input-output-filtering.md).
** `ResultSelector` (Optional, JSONPath only)**
Pass a collection of key value pairs, where the values are static or selected from the result. For more information, see [ResultSelector](input-output-inputpath-params.md#input-output-resultselector).
** `Retry` (Optional)**
An array of objects, called Retriers, that define a retry policy in case the state encounters runtime errors. For more information, see [State machine examples using Retry and Catch](concepts-error-handling.md#error-handling-examples).
** `Catch` (Optional)**
An array of objects, called Catchers, that define a fallback state that is executed if the state encounters runtime errors and its retry policy is exhausted or isn't defined. For more information, see [Fallback States](concepts-error-handling.md#error-handling-fallback-states).
A `Parallel` state causes AWS Step Functions to execute each branch, starting with the state named in that branch's `StartAt` field, as concurrently as possible, and wait until all branches terminate (reach a terminal state) before processing the `Parallel` state's `Next` field.
## Parallel State Example
```
{
"Comment": "Parallel Example.",
"StartAt": "LookupCustomerInfo",
"States": {
"LookupCustomerInfo": {
"Type": "Parallel",
"End": true,
"Branches": [
{
"StartAt": "LookupAddress",
"States": {
"LookupAddress": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:account-id:function:AddressFinder",
"End": true
}
}
},
{
"StartAt": "LookupPhone",
"States": {
"LookupPhone": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:account-id:function:PhoneFinder",
"End": true
}
}
}
]
}
}
}
```
In this example, the `LookupAddress` and `LookupPhone` branches are executed in parallel. Here is how the visual workflow looks in the Step Functions console.
![\[Visual graph of an example parallel workflow.\]](http://docs.aws.amazon.com/step-functions/latest/dg/images/parallel-state.png)
Each branch must be self-contained. A state in one branch of a `Parallel` state must not have a `Next` field that targets a field outside of that branch, nor can any other state outside the branch transition into that branch.
## Parallel State Input and Output Processing
A `Parallel` state provides each branch with a copy of its own input data (subject to modification by the `InputPath` field). It generates output that is an array with one element for each branch, containing the output from that branch. There is no requirement that all elements be of the same type. The output array can be inserted into the input data (and the whole sent as the `Parallel` state's output) by using a `ResultPath` field in the usual way (see [Input and Output Processing](concepts-input-output-filtering.md)).
```
{
"Comment": "Parallel Example.",
"StartAt": "FunWithMath",
"States": {
"FunWithMath": {
"Type": "Parallel",
"End": true,
"Branches": [
{
"StartAt": "Add",
"States": {
"Add": {
"Type": "Task",
"Resource": "arn:aws:states:region:123456789012:activity:Add",
"End": true
}
}
},
{
"StartAt": "Subtract",
"States": {
"Subtract": {
"Type": "Task",
"Resource": "arn:aws:states:region:123456789012:activity:Subtract",
"End": true
}
}
}
]
}
}
}
```
If the `FunWithMath` state was given the array `[3, 2]` as input, then both the `Add` and `Subtract` states receive that array as input. The output of the `Add` and `Subtract` tasks would be the sum of and difference between the array elements 3 and 2, which is `5` and `1`, while the output of the `Parallel` state would be an array.
```
[ 5, 1 ]
```
**Tip**
If the Parallel or Map state you use in your state machines returns an array of arrays, you can transform them into a flat array with the [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) field. For more information, see [Flattening an array of arrays](input-output-inputpath-params.md#flatten-array-of-arrays-result-selector).
## Error Handling
If any branch fails, because of an unhandled error or by transitioning to a `Fail` state, the entire `Parallel` state is considered to have failed and all its branches are stopped. If the error is not handled by the `Parallel` state itself, Step Functions stops the execution with an error.
**Note**
When a parallel state fails, invoked Lambda functions continue to run and activity workers processing a task token are not stopped.
To stop long-running activities, use heartbeats to detect if its branch has been stopped by Step Functions, and stop workers that are processing tasks. Calling [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html), [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html), or [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) will throw an error if the state has failed. See [Heartbeat Errors](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html#API_SendTaskHeartbeat_Errors).
Running Lambda functions cannot be stopped. If you have implemented a fallback, use a `Wait` state so that cleanup work happens after the Lambda function has finished.
# Map workflow state
Use the `Map` state to run a set of workflow steps for each item in a dataset. The `Map` state's iterations run in parallel, which makes it possible to process a dataset quickly. `Map` states can use a variety of input types, including a JSON array, a list of Amazon S3 objects, or a CSV file.
Step Functions provides two types of processing modes for using the `Map` state in your workflows: *Inline* mode and *Distributed* mode.
**Tip**
To deploy an example of a workflow that uses a `Map` state, see [Processing arrays of data with Choice and Map](https://catalog.workshops.aws/stepfunctions/choice-and-map) in *The AWS Step Functions Workshop*.
## Map state processing modes
Step Functions provides the following processing modes for the `Map` state depending on how you want to process the items in a dataset.
+ **Inline** – Limited-concurrency mode. In this mode, each iteration of the `Map` state runs in the context of the workflow that contains the `Map` state. Step Functions adds the execution history of these iterations to the parent workflow's execution history. By default, `Map` states run in Inline mode.
In this mode, the `Map` state accepts only a JSON array as input. Also, this mode supports up to 40 concurrent iterations.
For more information, see [Using Map state in Inline mode in Step Functions workflows](state-map-inline.md).
+ **Distributed** – High-concurrency mode. In this mode, the `Map` state runs each iteration as a child workflow execution, which enables high concurrency of up to 10,000 parallel child workflow executions. Each child workflow execution has its own, separate execution history from that of the parent workflow.
In this mode, the `Map` state can accept either a JSON array or an Amazon S3 data source, such as a CSV file, as its input.
For more information, see [Distributed mode](state-map-distributed.md).
The mode you should use depends on how you want to process the items in a dataset. Use the `Map` state in Inline mode if your workflow's execution history won't exceed 25,000 entries, or if you don't require more than 40 concurrent iterations.
Use the `Map` state in Distributed mode when you need to orchestrate large-scale parallel workloads that meet any combination of the following conditions:
+ The size of your dataset exceeds 256 KiB.
+ The workflow's execution event history would exceed 25,000 entries.
+ You need a concurrency of more than 40 concurrent iterations.
### Inline mode and Distributed mode differences
The following table highlights the differences between the Inline and Distributed modes.
| Inline mode | Distributed mode |
| --- |--- |
| **Supported data sources** |
| --- |
| Accepts a JSON array passed from a previous step in the workflow as input. | Accepts the following data sources as input: JSON array passed from a previous step in the workflow JSON file in an Amazon S3 bucket that contains an array CSV file in an Amazon S3 bucket Amazon S3 object list Amazon S3 inventory |
| **Map iterations** |
| --- |
| In this mode, each iteration of the `Map` state runs in the context of the workflow that contains the `Map` state. Step Functions adds the execution history of these iterations to the parent workflow's execution history. | In this mode, the `Map` state runs each iteration as a child workflow execution, which enables high concurrency of up to 10,000 parallel child workflow executions. Each child workflow execution has its own, separate execution history from that of the parent workflow. |
| **Maximum concurrency for parallel iterations** |
| --- |
| Lets you run up to 40 iterations as concurrently as possible. | Lets you run up to 10,000 parallel child workflow executions to process millions of data items at one time. |
| **Input payload and event history sizes** |
| --- |
| Enforces a limit of 256 KiB on the input payload size and 25,000 entries in the execution event history. | Lets you overcome the payload size limitation because the `Map` state can read input directly from Amazon S3 data sources. In this mode, you can also overcome execution history limitations because the child workflow executions started by the `Map` state maintain their own, separate execution histories from the parent workflow's execution history. |
| **Monitoring and observability** |
| --- |
| You can review the workflow's execution history from the console or by invoking the `[GetExecutionHistory](https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetExecutionHistory.html)` API action. You can also view the execution history through CloudWatch and X-Ray. | When you run a `Map` state in Distributed mode, Step Functions creates a Map Run resource. A Map Run refers to a set of child workflow executions that a *Distributed Map state* starts. You can view a Map Run in the Step Functions console. You can also invoke the `[DescribeMapRun](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeMapRun.html)` API action. A Map Run also emits metrics to CloudWatch. For more information, see [Viewing a Distributed Map Run execution in Step Functions](concepts-examine-map-run.md). |
# Using Map state in Inline mode in Step Functions workflows
**Managing state and transforming data**
Learn about [Passing data between states with variables](workflow-variables.md) and [Transforming data with JSONata](transforming-data.md).
By default, `Map` states runs in **Inline** mode. In Inline mode, the Map state accepts only a JSON array as input. It receives this array from a previous step in the workflow. In this mode, each iteration of the `Map` state runs in the context of the workflow that contains the `Map` state. Step Functions adds the execution history of these iterations to the parent workflow's execution history.
In this mode, the `Map` state supports up to 40 concurrent iterations.
A `Map` state set to **Inline** is known as an *Inline Map state*. Use the `Map` state in Inline mode if your workflow's execution history won't exceed 25,000 entries, or if you don't require more than 40 concurrent iterations.
For an introduction to using the *Inline Map state*, see the tutorial [Repeat actions with Inline Map](tutorial-map-inline.md).
**Topics**
+ [Key concepts in this topic](#key-concepts-inline-map)
+ [Inline Map state fields](#map-state-inline-additional-fields)
+ [Deprecated fields](#map-state-inline-deprecated-fields)
+ [Inline Map state example (JSONPath)](#inline-map-state-examples)
+ [Inline Map state example with `ItemSelector`](#inline-map-state-example-params)
+ [Inline `Map` state input and output processing](#inline-map-state-output)
## Key concepts in this topic
**Inline mode**
A limited-concurrency mode of the `Map` state. In this mode, each iteration of the `Map` state runs in the context of the workflow that contains the `Map` state. Step Functions adds the execution history of these iterations to the parent workflow's execution history. `Map` states run in the Inline mode by default.
This mode accepts only a JSON array as input and supports up to 40 concurrent iterations.
**Inline Map state**
A `Map` state set to the **Inline** mode.
**Map workflow**
The set of steps that the `Map` state runs for each iteration.
**Map state iteration**
A repetition of the workflow defined inside of the `Map` state.
## Inline Map state fields
To use the *Inline Map state* in your workflows, specify one or more of these fields. You specify these fields in addition to the [common state fields](statemachine-structure.md#amazon-states-language-common-fields).
**`Type` (Required)**
Sets the type of state, such as `Map`.
**`ItemProcessor` (Required)**
Contains the following JSON objects that specify the `Map` state processing mode and definition.
The definition contains the set of steps to repeat for processing each array item.
+ `ProcessorConfig` – An optional JSON object that specifies the processing mode for the `Map` state. This object contains the `Mode` sub-field. This field defaults to `INLINE`, which uses the `Map` state in Inline mode.
In this mode, the failure of any iteration causes the `Map` state to fail. All iterations stop when the `Map` state fails.
+ `StartAt` – Specifies a string that indicates the first state in a workflow. This string is case-sensitive and must match the name of one of the state objects. This state runs first for each item in the dataset. Any execution input that you provide to the `Map` state passes to the `StartAt` state first.
+ `States` – A JSON object containing a comma-delimited set of [states](workflow-states.md). In this object, you define the [Map workflow](#mapwflow).
**Note**
States within the `ItemProcessor` field can only transition to each other. No state outside the `ItemProcessor` field can transition to a state within it.
The `ItemProcessor` field replaces the now deprecated `Iterator` field. Although you can continue to include `Map` states that use the `Iterator` field, we highly recommend that you replace this field with `ItemProcessor`.
[Step Functions Local](sfn-local.md) doesn't currently support the `ItemProcessor` field. We recommend that you use the `Iterator` field with Step Functions Local.
**`Items` (Optional, JSONata only)**
A JSON array or a JSONata expression that must evaluate to an array.
**`ItemsPath` (Optional, JSONPath only)**
Specifies a [reference path](amazon-states-language-paths.md#amazon-states-language-reference-paths) using the [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) syntax. This path selects the JSON node that contains the array of items inside the state input. For more information, see [ItemsPath (Map, JSONPath only)](input-output-itemspath.md).
**`ItemSelector` (Optional)**
Overrides the values of the input array items before they're passed on to each `Map` state iteration.
In this field, you specify a valid JSON that contains a collection of key-value pairs. These pairs can contain any of the following:
+ Static values you define in your state machine definition.
+ Values selected from the state input using a [path](amazon-states-language-paths.md).
+ Values accessed from the [context object](input-output-contextobject.md).
For more information, see [ItemSelector (Map)](input-output-itemselector.md).
The `ItemSelector` field replaces the now deprecated `Parameters` field. Although you can continue to include `Map` states that use the `Parameters` field, we highly recommend that you replace this field with `ItemSelector`.
**`MaxConcurrency` (Optional)**
Specifies an integer value that provides the upper bound on the number of `Map` state iterations that can run in parallel. For example, a `MaxConcurrency` value of 10 limits the `Map` state to 10 concurrent iterations running at one time.
In JSONata states, you can specify a JSONata expression that evaluates to an integer.
Concurrent iterations may be limited. When this occurs, some iterations won't begin until previous iterations are complete. The likelihood of this occurring increases when your input array has more than 40 items.
To achieve a higher concurrency, consider [Distributed mode](state-map-distributed.md).
The default value is `0`, which places no limit on concurrency. Step Functions invokes iterations as concurrently as possible.
A `MaxConcurrency` value of `1` invokes the `ItemProcessor` once for each array element. Items in the array are processed in the order of their appearance in the input. Step Functions doesn't start a new iteration until it completes the previous iteration.
**`MaxConcurrencyPath` (Optional, JSONPath only)**
If you want to provide a maximum concurrency value dynamically from the state input using a reference path, use `MaxConcurrencyPath`. When resolved, the reference path must select a field whose value is a non-negative integer.
A `Map` state cannot include both `MaxConcurrency` and `MaxConcurrencyPath`.
**`ResultPath` (Optional, JSONPath only)**
Specifies where in the input to store the output of the `Map` state's iterations. The Map state then filters the input as specified by the [`OutputPath`](input-output-example.md#input-output-outputpath) field, if specified. Then, it uses the filtered input as the state's output. For more information, see [Input and Output Processing](concepts-input-output-filtering.md).
**`ResultSelector` (Optional, JSONPath only)**
Pass a collection of key value pairs, where the values are either static or selected from the result. For more information, see [ResultSelector](input-output-inputpath-params.md#input-output-resultselector).
If the Parallel or Map state you use in your state machines returns an array of arrays, you can transform them into a flat array with the [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) field. For more information, see [Flattening an array of arrays](input-output-inputpath-params.md#flatten-array-of-arrays-result-selector).
**`Retry` (Optional)**
An array of objects, called Retriers, that define a retry policy. States use a retry policy when they encounter runtime errors. For more information, see [State machine examples using Retry and Catch](concepts-error-handling.md#error-handling-examples).
If you define Retriers for the *Inline Map state*, the retry policy applies to all `Map` state iterations, instead of only failed iterations. For example, your `Map` state contains two successful iterations and one failed iteration. If you have defined the `Retry` field for the `Map` state, the retry policy applies to all three `Map` state iterations instead of only the failed iteration.
**`Catch` (Optional)**
An array of objects, called Catchers, that define a fallback state. States run a catcher if they encounter runtime errors and either don't have a retry policy, or their retry policy is exhausted. For more information, see [Fallback States](concepts-error-handling.md#error-handling-fallback-states).
**`Output` (Optional, JSONata only)**
Used to specify and transform output from the state. When specified, the value overrides the state output default.
The output field accepts any JSON value (object, array, string, number, boolean, null). Any string value, including those inside objects or arrays, will be evaluated as JSONata if surrounded by \$1% %\$1 characters.
Output also accepts a JSONata expression directly, for example: "Output": "\$1% jsonata expression %\$1"
For more information, see [Transforming data with JSONata in Step Functions](transforming-data.md).
** `Assign` (Optional)**
Used to store variables. The `Assign` field accepts a JSON object with key/value pairs that define variable names and their assigned values. Any string value, including those inside objects or arrays, will be evaluated as JSONata when surrounded by `{% %}` characters
For more information, see [Passing data between states with variables](workflow-variables.md).
## Deprecated fields
**Note**
Although you can continue to include `Map` states that use the following fields, we highly recommend that you replace `Iterator` with `ItemProcessor` and `Parameters` with `ItemSelector`.
** `Iterator`**
Specifies a JSON object that defines a set of steps that process each element of the array.
**`Parameters`**
Specifies a collection of key-value pairs, where the values can contain any of the following:
+ Static values that you define in your state machine definition.
+ Values selected from the input using a [path](amazon-states-language-paths.md).
## Inline Map state example (JSONPath)
Consider the following input data for a `Map` state running in **Inline** mode.
```
{
"ship-date": "2016-03-14T01:59:00Z",
"detail": {
"delivery-partner": "UQS",
"shipped": [
{ "prod": "R31", "dest-code": 9511, "quantity": 1344 },
{ "prod": "S39", "dest-code": 9511, "quantity": 40 },
{ "prod": "R31", "dest-code": 9833, "quantity": 12 },
{ "prod": "R40", "dest-code": 9860, "quantity": 887 },
{ "prod": "R40", "dest-code": 9511, "quantity": 1220 }
]
}
}
```
Given the previous input, the `Map` state in the following example invokes an AWS Lambda function named `ship-val` once for each item of the array in the `shipped` field.
```
"Validate All": {
"Type": "Map",
"InputPath": "$.detail",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "Validate",
"States": {
"Validate": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"OutputPath": "$.Payload",
"Parameters": {
"FunctionName": "arn:aws:lambda:us-east-2:account-id:function:ship-val:$LATEST"
},
"End": true
}
}
},
"End": true,
"ResultPath": "$.detail.shipped",
"ItemsPath": "$.shipped"
}
```
Each iteration of the `Map` state sends an item in the array, selected with the [`ItemsPath`](input-output-itemspath.md) field, as input to the `ship-val` Lambda function. The following values are an example of input the `Map` state sends to an invocation of the Lambda function:
```
{
"prod": "R31",
"dest-code": 9511,
"quantity": 1344
}
```
When complete, the output of the `Map` state is a JSON array, where each item is the output of an iteration. In this case, this array contains the output of the `ship-val` Lambda function.
## Inline Map state example with `ItemSelector`
Suppose that the `ship-val` Lambda function in the previous example also needs information about the shipment's courier. This information is in addition to the items in the array for each iteration. You can include information from the input, along with information specific to the current iteration of the `Map` state. Note the `ItemSelector` field in the following example:
```
"Validate-All": {
"Type": "Map",
"InputPath": "$.detail",
"ItemsPath": "$.shipped",
"MaxConcurrency": 0,
"ResultPath": "$.detail.shipped",
"ItemSelector": {
"parcel.$": "$$.Map.Item.Value",
"courier.$": "$.delivery-partner"
},
"ItemProcessor": {
"StartAt": "Validate",
"States": {
"Validate": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:account-id:function:ship-val",
"End": true
}
}
},
"End": true
}
```
The `ItemSelector` block replaces the input to the iterations with a JSON node. This node contains both the current item data from the [Context object](input-output-contextobject.md#contextobject-map) and the courier information from the `Map` state input's `delivery-partner` field. The following is an example of input to a single iteration. The `Map` state passes this input to an invocation of the `ship-val` Lambda function.
```
{
"parcel": {
"prod": "R31",
"dest-code": 9511,
"quantity": 1344
},
"courier": "UQS"
}
```
In the previous *Inline Map state* example, the `ResultPath` field produces output in the same format as the input. However, it overwrites the `detail.shipped` field with an array in which each element is the output of each iteration's `ship-val` Lambda invocation.
For more information about using the *Inline Map state* state and its fields, see the following.
+ [Repeat actions with Inline Map](tutorial-map-inline.md)
+ [Processing input and output in Step Functions](concepts-input-output-filtering.md)
+ [ItemsPath (Map, JSONPath only)](input-output-itemspath.md)
+ [Context object data for Map states](input-output-contextobject.md#contextobject-map)
## Inline `Map` state input and output processing
For a given `Map` state, [`InputPath`](input-output-inputpath-params.md#input-output-inputpath) selects a subset of the state's input.
The input of a `Map` state must include a JSON array. The `Map` state runs the `ItemProcessor` section once for each item in the array. If you specify the [`ItemsPath`](input-output-itemspath.md) field, the `Map` state selects where in the input to find the array to iterate over. If not specified, the value of `ItemsPath` is `$`, and the `ItemProcessor` section expects that the array is the only input. If you specify the `ItemsPath` field, its value must be a [Reference Path](amazon-states-language-paths.md#amazon-states-language-reference-paths). The `Map` state applies this path to the effective input after it applies the `InputPath`. The `ItemsPath` must identify a field whose value is a JSON array.
The input to each iteration, by default, is a single element of the array field identified by the `ItemsPath` value. You can override this value with the `ItemSelector (Map)` field.
When complete, the output of the `Map` state is a JSON array, where each item is the output of an iteration.
For more information about Inline Map state inputs and outputs, see the following:
+ [Repeat actions with Inline Map](tutorial-map-inline.md)
+ [Inline Map state example with `ItemSelector`](#inline-map-state-example-params)
+ [Processing input and output in Step Functions](concepts-input-output-filtering.md)
+ [Context object data for Map states](input-output-contextobject.md#contextobject-map)
+ [Process data from a queue with a Map state in Step Functions](sample-map-state.md)
# Using Map state in Distributed mode for large-scale parallel workloads in Step Functions
**Managing state and transforming data**
Learn about [Passing data between states with variables](workflow-variables.md) and [Transforming data with JSONata](transforming-data.md).
With Step Functions, you can orchestrate large-scale parallel workloads to perform tasks, such as on-demand processing of semi-structured data. These parallel workloads let you concurrently process large-scale data sources stored in Amazon S3. For example, you might process a single JSON or CSV file that contains large amounts of data. Or you might process a large set of Amazon S3 objects.
To set up a large-scale parallel workload in your workflows, include a `Map` state in Distributed mode. The *Map state* processes items in a dataset concurrently. A `Map` state set to **Distributed** is known as a *Distributed Map state*. In *Distributed mode*, the `Map` state allows high-concurrency processing. In Distributed mode, the `Map` state processes the items in the dataset in iterations called *child workflow executions*. You can specify the number of child workflow executions that can run in parallel. Each child workflow execution has its own, separate execution history from that of the parent workflow. If you don't specify, Step Functions runs 10,000 parallel child workflow executions in parallel.
The following illustration explains how you can set up large-scale parallel workloads in your workflows.
![\[Diagram to illustrate the concept of orchestrating large-scale parallel workloads.\]](http://docs.aws.amazon.com/step-functions/latest/dg/images/autobahn-concept.png)
**Learn in a workshop**
Learn how serverless technologies such as Step Functions and Lambda can simplify management and scaling, offload undifferentiated tasks, and address the challenges of large-scale distributed data processing. Along the way, you will work with distributed map for high concurrency processing. The workshop also presents best practices for optimizing your workflows, and practical use cases for claims processing, vulnerability scanning, and Monte Carlo simulation.
**Workshop: [Large-scale Data Processing with Step Functions](https://catalog.workshops.aws/serverless-data-processing)**
**Topics**
+ [Key terms](#dist-map-orchestrate-parallel-workloads-key-terms)
+ [Distributed Map state definition](#use-map-state-dist-mode)
+ [Permissions to run Distributed Map](#dist-map-permissions)
+ [Distributed Map state fields](#map-state-distributed-additional-fields)
+ [Distributed Map failure thresholds](#maprun-fail-threshold)
+ [Learn more about distributed maps](#dist-map-next-steps)
## Key terms
**Distributed mode**
A processing mode of the [Map state](state-map.md). In this mode, each iteration of the `Map` state runs as a child workflow execution that enables high concurrency. Each child workflow execution has its own execution history, which is separate from the parent workflow's execution history. This mode supports reading input from large-scale Amazon S3 data sources.
**Distributed Map state**
A Map state set to **Distributed** [processing mode](state-map.md#concepts-map-process-modes).
**Map workflow**
A set of steps that a `Map` state runs.
**Parent workflow**
A workflow that contains one or more Distributed Map states.
**Child workflow execution**
An iteration of the *Distributed Map state*. A child workflow execution has its own execution history, which is separate from the parent workflow's execution history.
**Map Run**
When you run a `Map` state in Distributed mode, Step Functions creates a Map Run resource. A Map Run refers to a set of child workflow executions that a *Distributed Map state* starts, and the runtime settings that control these executions. Step Functions assigns an Amazon Resource Name (ARN) to your Map Run. You can examine a Map Run in the Step Functions console. You can also invoke the `[DescribeMapRun](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeMapRun.html)` API action.
Child workflow executions of a Map Run emit metrics to CloudWatch;. These metrics will have a labelled State Machine ARN with the following format:
`arn:partition:states:region:account:stateMachine:stateMachineName/MapRunLabel or UUID`
For more information, see [Viewing Map Runs](concepts-examine-map-run.md).
## Distributed Map state definition example (JSONPath)
Use the `Map` state in Distributed mode when you need to orchestrate large-scale parallel workloads that meet any combination of the following conditions:
+ The size of your dataset exceeds 256 KiB.
+ The workflow's execution event history would exceed 25,000 entries.
+ You need a concurrency of more than 40 concurrent iterations.
The following *Distributed Map state* definition example specifies the dataset as a CSV file stored in an Amazon S3 bucket. It also specifies a Lambda function that processes the data in each row of the CSV file. Because this example uses a CSV file, it also specifies the location of the CSV column headers. To view the complete state machine definition of this example, see the tutorial [Copying large-scale CSV data using Distributed Map](tutorial-map-distributed.md).
```
{
"Map": {
"Type": "Map",
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "csv-dataset/ratings.csv"
}
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "DISTRIBUTED",
"ExecutionType": "EXPRESS"
},
"StartAt": "LambdaTask",
"States": {
"LambdaTask": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"OutputPath": "$.Payload",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:account-id:function:processCSVData"
},
"End": true
}
}
},
"Label": "Map",
"End": true,
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
}
```
## Permissions to run Distributed Map
When you include a *Distributed Map state* in your workflows, Step Functions needs appropriate permissions to allow the state machine role to invoke the `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API action for the *Distributed Map state*.
The following IAM policy example grants the least privileges required to your state machine role for running the *Distributed Map state*.
**Note**
Make sure that you replace `stateMachineName` with the name of the state machine in which you're using the *Distributed Map state*. For example, `arn:aws:states:region:account-id:stateMachine:mystateMachine`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"states:StartExecution"
],
"Resource": [
"arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachineName"
]
},
{
"Effect": "Allow",
"Action": [
"states:DescribeExecution"
],
"Resource": "arn:aws:states:us-east-1:123456789012:execution:myStateMachineName:*"
}
]
}
```
In addition, you need to make sure that you have the least privileges necessary to access the AWS resources used in the *Distributed Map state*, such as Amazon S3 buckets. For information, see [IAM policies for using Distributed Map states](iam-policies-eg-dist-map.md).
## Distributed Map state fields
To use the *Distributed Map state* in your workflows, specify one or more of these fields. You specify these fields in addition to the [common state fields](statemachine-structure.md#amazon-states-language-common-fields).
**`Type` (Required)**
Sets the type of state, such as `Map`.
**`ItemProcessor` (Required)**
Contains the following JSON objects that specify the `Map` state processing mode and definition.
+ `ProcessorConfig` – JSON object that specifies the mode for processing items, with the following sub-fields:
+ `Mode` – Set to **DISTRIBUTED** to use the `Map` state in Distributed mode.
**Warning**
Distributed mode is supported in Standard workflows but not supported in Express workflows.
+ `ExecutionType` – Specifies the execution type for the Map workflow as either **STANDARD** or **EXPRESS**. You must provide this field if you specified `DISTRIBUTED` for the `Mode` sub-field. For more information about workflow types, see [Choosing workflow type in Step Functions](choosing-workflow-type.md).
+ `StartAt` – Specifies a string that indicates the first state in a workflow. This string is case-sensitive and must match the name of one of the state objects. This state runs first for each item in the dataset. Any execution input that you provide to the `Map` state passes to the `StartAt` state first.
+ `States` – A JSON object containing a comma-delimited set of [states](workflow-states.md). In this object, you define the [Map workflow](state-map-inline.md#mapwflow).
**`ItemReader`**
Specifies a dataset and its location. The `Map` state receives its input data from the specified dataset.
In Distributed mode, you can use either a JSON payload passed from a previous state or a large-scale Amazon S3 data source as the dataset. For more information, see [ItemReader (Map)](input-output-itemreader.md).
**`Items` (Optional, JSONata only)**
A JSON array, a JSON object, or a JSONata expression that must evaluate to an array or object.
**`ItemsPath` (Optional, JSONPath only)**
Specifies a [reference path](amazon-states-language-paths.md#amazon-states-language-reference-paths) using the [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) syntax to select the JSON node that contains an array of items or an object with key-value pairs inside the state input.
In Distributed mode, you specify this field only when you use a JSON array or object from a previous step as your state input. For more information, see [ItemsPath (Map, JSONPath only)](input-output-itemspath.md).
**`ItemSelector` (Optional, JSONPath only)**
Overrides the values of individual dataset items before they're passed on to each `Map` state iteration.
In this field, you specify a valid JSON input that contains a collection of key-value pairs. These pairs can either be static values that you define in your state machine definition, values selected from the state input using a [path](amazon-states-language-paths.md), or values accessed from the [context object](input-output-contextobject.md). For more information, see [ItemSelector (Map)](input-output-itemselector.md).
**`ItemBatcher` (Optional)**
Specifies to process the dataset items in batches. Each child workflow execution then receives a batch of these items as input. For more information, see [ItemBatcher (Map)](input-output-itembatcher.md).
**`MaxConcurrency` (Optional)**
Specifies the number of child workflow executions that can run in parallel. The interpreter only allows up to the specified number of parallel child workflow executions. If you don't specify a concurrency value or set it to zero, Step Functions doesn't limit concurrency and runs 10,000 parallel child workflow executions. In JSONata states, you can specify a JSONata expression that evaluates to an integer.
While you can specify a higher concurrency limit for parallel child workflow executions, we recommend that you don't exceed the capacity of a downstream AWS service, such as AWS Lambda.
**`MaxConcurrencyPath` (Optional, JSONPath only)**
If you want to provide a maximum concurrency value dynamically from the state input using a reference path, use `MaxConcurrencyPath`. When resolved, the reference path must select a field whose value is a non-negative integer.
A `Map` state cannot include both `MaxConcurrency` and `MaxConcurrencyPath`.
**`ToleratedFailurePercentage` (Optional)**
Defines the percentage of failed items to tolerate in a Map Run. The Map Run automatically fails if it exceeds this percentage. Step Functions calculates the percentage of failed items as the result of the total number of failed or timed out items divided by the total number of items. You must specify a value between zero and 100. For more information, see [Setting failure thresholds for Distributed Map states in Step Functions](#maprun-fail-threshold).
In JSONata states, you can specify a JSONata expression that evaluates to an integer.
**`ToleratedFailurePercentagePath` (Optional, JSONPath only)**
If you want to provide a tolerated failure percentage value dynamically from the state input using a reference path, use `ToleratedFailurePercentagePath`. When resolved, the reference path must select a field whose value is between zero and 100.
**`ToleratedFailureCount` (Optional)**
Defines the number of failed items to tolerate in a Map Run. The Map Run automatically fails if it exceeds this number. For more information, see [Setting failure thresholds for Distributed Map states in Step Functions](#maprun-fail-threshold).
In JSONata states, you can specify a JSONata expression that evaluates to an integer.
**`ToleratedFailureCountPath` (Optional, JSONPath only)**
If you want to provide a tolerated failure count value dynamically from the state input using a reference path, use `ToleratedFailureCountPath`. When resolved, the reference path must select a field whose value is a non-negative integer.
**`Label` (Optional)**
A string that uniquely identifies a `Map` state. For each Map Run, Step Functions adds the label to the Map Run ARN. The following is an example of a Map Run ARN with a custom label named `demoLabel`:
```
arn:aws:states:region:account-id:mapRun:demoWorkflow/demoLabel:3c39a231-69bb-3d89-8607-9e124eddbb0b
```
If you don't specify a label, Step Functions automatically generates a unique label.
Labels can't exceed 40 characters in length, must be unique within a state machine definition, and can't contain any of the following characters:
+ Whitespace
+ Wildcard characters (`? *`)
+ Bracket characters (`< > { } [ ]`)
+ Special characters (`: ; , \ | ^ ~ $ # % & ` "`)
+ Control characters (`\\u0000` - `\\u001f` or `\\u007f` - `\\u009f`).
Step Functions accepts names for state machines, executions, activities, and labels that contain non-ASCII characters. Because such characters will prevent Amazon CloudWatch from logging data, we recommend using only ASCII characters so you can track Step Functions metrics.
**`ResultWriter` (Optional)**
Specifies the Amazon S3 location where Step Functions writes all child workflow execution results.
Step Functions consolidates all child workflow execution data, such as execution input and output, ARN, and execution status. It then exports executions with the same status to their respective files in the specified Amazon S3 location. For more information, see [ResultWriter (Map)](input-output-resultwriter.md).
If you don't export the `Map` state results, it returns an array of all the child workflow execution results. For example:
```
[1, 2, 3, 4, 5]
```
**`ResultPath` (Optional, JSONPath only)**
Specifies where in the input to place the output of the iterations. The input is then filtered as specified by the [`OutputPath`](input-output-example.md#input-output-outputpath) field if present, before it is passed as the state's output. For more information, see [Input and Output Processing](concepts-input-output-filtering.md).
**`ResultSelector` (Optional)**
Pass a collection of key-value pairs, where the values are static or selected from the result. For more information, see [ResultSelector](input-output-inputpath-params.md#input-output-resultselector).
If the Parallel or Map state you use in your state machines returns an array of arrays, you can transform them into a flat array with the [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) field. For more information, see [Flattening an array of arrays](input-output-inputpath-params.md#flatten-array-of-arrays-result-selector).
**`Retry` (Optional)**
An array of objects, called Retriers, that define a retry policy. An execution uses the retry policy if the state encounters runtime errors. For more information, see [State machine examples using Retry and Catch](concepts-error-handling.md#error-handling-examples).
If you define Retriers for the *Distributed Map state*, the retry policy applies to all of the child workflow executions the `Map` state started. For example, imagine your `Map` state started three child workflow executions, out of which one fails. When the failure occurs, the execution uses the `Retry` field, if defined, for the `Map` state. The retry policy applies to all the child workflow executions and not just the failed execution. If one or more child workflow executions fails, the Map Run fails.
When you retry a `Map` state, it creates a new Map Run.
**`Catch` (Optional)**
An array of objects, called Catchers, that define a fallback state. Step Functions uses the Catchers defined in `Catch` if the state encounters runtime errors. When an error occurs, the execution first uses any retriers defined in `Retry`. If the retry policy isn't defined or is exhausted, the execution uses its Catchers, if defined. For more information, see [Fallback States](concepts-error-handling.md#error-handling-fallback-states).
**`Output` (Optional, JSONata only)**
Used to specify and transform output from the state. When specified, the value overrides the state output default.
The output field accepts any JSON value (object, array, string, number, boolean, null). Any string value, including those inside objects or arrays, will be evaluated as JSONata if surrounded by \$1% %\$1 characters.
Output also accepts a JSONata expression directly, for example: "Output": "\$1% jsonata expression %\$1"
For more information, see [Transforming data with JSONata in Step Functions](transforming-data.md).
** `Assign` (Optional)**
Used to store variables. The `Assign` field accepts a JSON object with key/value pairs that define variable names and their assigned values. Any string value, including those inside objects or arrays, will be evaluated as JSONata when surrounded by `{% %}` characters
For more information, see [Passing data between states with variables](workflow-variables.md).
## Setting failure thresholds for Distributed Map states in Step Functions
When you orchestrate large-scale parallel workloads, you can also define a tolerated failure threshold. This value lets you specify the maximum number of, or percentage of, failed items as a failure threshold for a [Map Run](concepts-examine-map-run.md). Depending on which value you specify, your Map Run fails automatically if it exceeds the threshold. If you specify both values, the workflow fails when it exceeds either value.
Specifying a threshold helps you fail a specific number of items before the entire Map Run fails. Step Functions returns a `States.ExceedToleratedFailureThreshold` error when the Map Run fails because the specified threshold is exceeded.
**Note**
Step Functions may continue to run child workflows in a Map Run even after the tolerated failure threshold is exceeded, but before the Map Run fails.
To specify the threshold value in Workflow Studio, select **Set a tolerated failure threshold** in **Additional configuration** under the **Runtime settings** field.
**Tolerated failure percentage**
Defines the percentage of failed items to tolerate. Your Map Run fails if this value is exceeded. Step Functions calculates the percentage of failed items as the result of the total number of failed or timed out items divided by the total number of items. You must specify a value between zero and 100. The default percentage value is zero, which means that the workflow fails if any one of its child workflow executions fails or times out. If you specify the percentage as 100, the workflow won’t fail even if all child workflow executions fail.
Alternatively, you can specify the percentage as a [reference path](amazon-states-language-paths.md#amazon-states-language-reference-paths) to an existing key-value pair in your *Distributed Map state* input. This path must resolve to a positive integer between 0 and 100 at runtime. You specify the reference path in the `ToleratedFailurePercentagePath` sub-field.
For example, given the following input:
```
{
"percentage": 15
}
```
You can specify the percentage using a reference path to that input as follows:
```
{
...
"Map": {
"Type": "Map",
...
"ToleratedFailurePercentagePath": "$.percentage"
...
}
}
```
You can specify either `ToleratedFailurePercentage` or `ToleratedFailurePercentagePath`, but not both in your *Distributed Map state* definition.
**Tolerated failure count**
Defines the number of failed items to tolerate. Your Map Run fails if this value is exceeded.
Alternatively, you can specify the count as a [reference path](amazon-states-language-paths.md#amazon-states-language-reference-paths) to an existing key-value pair in your *Distributed Map state* input. This path must resolve to a positive integer at runtime. You specify the reference path in the `ToleratedFailureCountPath` sub-field.
For example, given the following input:
```
{
"count": 10
}
```
You can specify the number using a reference path to that input as follows:
```
{
...
"Map": {
"Type": "Map",
...
"ToleratedFailureCountPath": "$.count"
...
}
}
```
You can specify either `ToleratedFailureCount` or `ToleratedFailureCountPath`, but not both in your *Distributed Map state* definition.
## Learn more about distributed maps
To continue learning more about *Distributed Map state*, see the following resources:
+
**Input and output processing**
To configure the input that a *Distributed Map state* receives and the output that it generates, Step Functions provides the following fields:
+ [ItemReader (Map)](input-output-itemreader.md)
+ [ItemsPath (Map, JSONPath only)](input-output-itemspath.md)
+ [ItemSelector (Map)](input-output-itemselector.md)
+ [ItemBatcher (Map)](input-output-itembatcher.md)
+ [ResultWriter (Map)](input-output-resultwriter.md)
+ [How Step Functions parses input CSV files](example-csv-parse-dist-map.md)
In addition to these fields, Step Functions also provides you the ability to define a tolerated failure threshold for Distributed Map. This value lets you specify the maximum number of, or percentage of, failed items as a failure threshold for a [Map Run](concepts-examine-map-run.md). For more information about configuring the tolerated failure threshold, see [Setting failure thresholds for Distributed Map states in Step Functions](#maprun-fail-threshold).
+
**Using Distributed Map state**
Refer the following tutorials and sample projects to get started with using *Distributed Map state*.
+ [Copy large-scale CSV using Distributed Map](tutorial-map-distributed.md)
+ [Processing batch data with a Lambda function in Step Functions](tutorial-itembatcher-param-task.md)
+ [Processing individual items with a Lambda function in Step Functions](tutorial-itembatcher-single-item-process.md)
+ [Sample project: Process a CSV file with Distributed Map](sample-dist-map-csv-process.md)
+ [Sample project: Process data in an Amazon S3 bucket with Distributed Map](sample-dist-map-s3data-process.md)
+
**Examine Distributed Map state execution**
The Step Functions console provides a *Map Run Details* page, which displays all the information related to a *Distributed Map state* execution. For information about how to examine the information displayed on this page, see [Viewing Map Runs](concepts-examine-map-run.md).
# Pass workflow state
**Managing state and transforming data**
Learn about [Passing data between states with variables](workflow-variables.md) and [Transforming data with JSONata](transforming-data.md).
A `Pass` state (`"Type": "Pass"`) passes its input to its output, without performing work. `Pass` states are useful when constructing and debugging state machines.
You can also use a `Pass` state to transform JSON state input using filters, and then pass the transformed data to the next state in your workflows. For information about input transformation, see [Manipulate parameters in Step Functions workflows](input-output-inputpath-params.md).
In addition to the [common state fields](statemachine-structure.md#amazon-states-language-common-fields), `Pass` states allow the following fields.
** `Assign` (Optional, JSONata only)**
A collection of key-value pairs to assign data to variables. For more information, see [Passing data between states with variables](workflow-variables.md).
**`Output` (Optional, JSONata only)**
Used to specify and transform output from the state. When specified, the value overrides the state output default.
The output field accepts any JSON value (object, array, string, number, boolean, null). Any string value, including those inside objects or arrays, will be evaluated as JSONata if surrounded by \$1% %\$1 characters.
Output also accepts a JSONata expression directly, for example: "Output": "\$1% jsonata expression %\$1"
For more information, see [Transforming data with JSONata in Step Functions](transforming-data.md).
** `Result` (Optional, JSONPath only)**
Refers to the output of a virtual task that is passed on to the next state. If you include the `ResultPath` field in your state machine definition, `Result` is placed as specified by `ResultPath` and passed on to the next state.
** `ResultPath` (Optional, JSONPath only)**
Specifies where to place the *output* (relative to the input) of the virtual task specified in `Result`. The input is further filtered as specified by the `OutputPath` field (if present) before being used as the state's output. For more information, see [Processing input and output in Step Functions](concepts-input-output-filtering.md).
** `Parameters` (Optional, JSONPath only)**
Creates a collection of key-value pairs that will be passed as input. You can specify `Parameters` as a static value or select from the input using a path. For more information, see [Manipulate parameters in Step Functions workflows](input-output-inputpath-params.md).
## Pass State Example (JSONPath)
Here is an example of a `Pass` state that injects some fixed data into the state machine, probably for testing purposes.
```
"No-op": {
"Type": "Pass",
"Result": {
"x-datum": 0.381018,
"y-datum": 622.2269926397355
},
"ResultPath": "$.coords",
"End": true
}
```
Suppose the input to this state is the following.
```
{
"georefOf": "Home"
}
```
Then the output would be this.
```
{
"georefOf": "Home",
"coords": {
"x-datum": 0.381018,
"y-datum": 622.2269926397355
}
}
```
# Wait workflow state
**Managing state and transforming data**
Learn about [Passing data between states with variables](workflow-variables.md) and [Transforming data with JSONata](transforming-data.md).
A `Wait` state (`"Type": "Wait"`) delays the state machine from continuing for a specified time. You can choose either a relative time, specified in seconds from when the state begins, or an absolute end time, specified as a timestamp.
In addition to the [common state fields](statemachine-structure.md#amazon-states-language-common-fields), `Wait` states have one of the following fields.
** `Seconds` **
A time, in seconds, to wait before beginning the state specified in the `Next` field. You must specify time as an integer value from 0 to 99999999. In JSONata states, you can alternatively specify a JSONata expression which must evaluate to an integer in the stated range.
** `Timestamp` **
An absolute time to wait until beginning the state specified in the `Next` field.
Timestamps must conform to the RFC3339 profile of ISO 8601, with the further restrictions that an uppercase `T` must separate the date and time portions, and an uppercase `Z` must denote that a numeric time zone offset is not present, for example, `2024-08-18T17:33:00Z`.
In JSONata states, you can specify a JSONata expression which results in a string that conforms to the previous requirements.
Currently, if you specify the wait time as a timestamp, Step Functions considers the time value up to seconds and truncates milliseconds.
** `SecondsPath` (Optional, JSONPath only) **
A [path](concepts-input-output-filtering.md) in the states input data to an integer value that specifies the time to wait, in seconds, before proceeding to the next state.
** `TimestampPath` (Optional, JSONPath only) **
A [path](concepts-input-output-filtering.md) in the states input data to an absolute date and time (timestamp) to wait before proceeding to the next state.
**Note**
You must specify exactly one of `Seconds`, `Timestamp`, `SecondsPath`, or `TimestampPath`. In addition, the maximum wait time that you can specify for Standard Workflows and Express workflows is one year and five minutes respectively.
## Wait State Examples
The following `Wait` state introduces a 10-second delay into a state machine.
```
"wait_ten_seconds": {
"Type": "Wait",
"Seconds": 10,
"Next": "NextState"
}
```
In the next example, the `Wait` state waits until an absolute time: March 14, 2024, at 1:59 AM UTC.
```
"wait_until" : {
"Type": "Wait",
"Timestamp": "2024-03-14T01:59:00Z",
"Next": "NextState"
}
```
You don't have to hard-code the wait duration. For example, given the following input data:
```
{
"expirydate": "2024-03-14T01:59:00Z"
}
```
You can select the value of "expirydate" from the input using a reference [path](concepts-input-output-filtering.md) to select it from the input data.
```
"wait_until" : {
"Type": "Wait",
"TimestampPath": "$.expirydate",
"Next": "NextState"
}
```
# Succeed workflow state
A `Succeed` state (`"Type": "Succeed"`) either terminates a state machine successfully, ends a branch of a [Parallel workflow state](state-parallel.md), or ends an iteration of a [Map workflow state](state-map.md). The `Succeed` state is a useful target for `Choice` state branches that don't do anything except terminate the state machine.
Because `Succeed` states are terminal states, they have no `Next` field, and don't need an `End` field, as shown in the following example.
```
"SuccessState": {
"Type": "Succeed"
}
```
**`Output` (Optional, JSONata only)**
In addition to the [common state fields](statemachine-structure.md#amazon-states-language-common-fields), `Succeed` states that use JSONata can include an Output field to specify and transform output from the state. When specified, the `Output` value overrides the state output default.
The output field accepts any JSON value (object, array, string, number, boolean, null). Any string value, including those inside objects or arrays, will be evaluated as JSONata if surrounded by `{% %}` characters.
Output also accepts a JSONata expression directly, for example:
```
"Output" : "{% jsonata expression %}"
```
For more information on JSONata, see [Transforming data with JSONata in Step Functions](transforming-data.md).
# Fail workflow state
**Managing state and transforming data**
Learn about [Passing data between states with variables](workflow-variables.md) and [Transforming data with JSONata](transforming-data.md).
A `Fail` state (`"Type": "Fail"`) stops the execution of the state machine and marks it as a failure, unless it is caught by a `Catch` block.
The `Fail` state only allows the use of `Type` and `Comment` fields from the set of [common state fields](statemachine-structure.md#amazon-states-language-common-fields). In addition, the `Fail` state allows the following fields.
** `Cause` (Optional)**
A custom string that describes the cause of the error. You can specify this field for operational or diagnostic purposes.
In JSONata states, you can also specify a JSONata expression.
** `CausePath` (Optional, JSONPath only) **
If you want to provide a detailed description about the cause of the error dynamically from the state input using a [reference path](amazon-states-language-paths.md#amazon-states-language-reference-paths), use `CausePath`. When resolved, the reference path must select a field that contains a string value.
You can also specify `CausePath` using an [intrinsic function](intrinsic-functions.md) that returns a string. These intrinsics are: [States.Format](intrinsic-functions.md#asl-intrsc-func-generic), [States.JsonToString](intrinsic-functions.md#jsontostring), [States.ArrayGetItem](intrinsic-functions.md#arraygetitem), [States.Base64Encode](intrinsic-functions.md#base64encode), [States.Base64Decode](intrinsic-functions.md#base64decode), [States.Hash](intrinsic-functions.md#asl-intrsc-func-uuid-generate), and [States.UUID](intrinsic-functions.md#statesuuid).
+ You can specify either `Cause` or `CausePath`, but not both in your Fail state definition.
+ As an information security best practice, we recommend that you remove any sensitive information or internal system details from the cause description.
** `Error` (Optional)**
An error name that you can provide to perform error handling using [Retry](concepts-error-handling.md#error-handling-retrying-after-an-error) or [Catch](concepts-error-handling.md#error-handling-fallback-states) fields. You can also provide an error name for operational or diagnostic purposes.
In JSONata states, you can also specify a JSONata expression.
** `ErrorPath` (Optional, JSONPath only) **
If you want to provide a name for the error dynamically from the state input using a [reference path](amazon-states-language-paths.md#amazon-states-language-reference-paths), use `ErrorPath`. When resolved, the reference path must select a field that contains a string value.
You can also specify `ErrorPath` using an [intrinsic function](intrinsic-functions.md) that returns a string. These intrinsics are: [States.Format](intrinsic-functions.md#asl-intrsc-func-generic), [States.JsonToString](intrinsic-functions.md#jsontostring), [States.ArrayGetItem](intrinsic-functions.md#arraygetitem), [States.Base64Encode](intrinsic-functions.md#base64encode), [States.Base64Decode](intrinsic-functions.md#base64decode), [States.Hash](intrinsic-functions.md#asl-intrsc-func-uuid-generate), and [States.UUID](intrinsic-functions.md#statesuuid).
+ You can specify either `Error` or `ErrorPath`, but not both in your Fail state definition.
+ As an information security best practice, we recommend that you remove any sensitive information or internal system details from the error name.
Because `Fail` states always exit the state machine, they have no `Next` field and don't require an `End` field.
## Fail state definition examples
The following Fail state definition example specifies static `Error` and `Cause` field values.
```
"FailState": {
"Type": "Fail",
"Cause": "Invalid response.",
"Error": "ErrorA"
}
```
The following Fail state definition example uses reference paths dynamically to resolve the `Error` and `Cause` field values.
```
"FailState": {
"Type": "Fail",
"CausePath": "$.Cause",
"ErrorPath": "$.Error"
}
```
The following Fail state definition example uses the [States.Format](intrinsic-functions.md#asl-intrsc-func-generic) intrinsic function to specify the `Error` and `Cause` field values dynamically.
```
"FailState": {
"Type": "Fail",
"CausePath": "States.Format('This is a custom error message for {}, caused by {}.', $.Error, $.Cause)",
"ErrorPath": "States.Format('{}', $.Error)"
}
```