# 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)"
},
...
}
}
}
```