Task workflow state
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, or by invoking a third-party API, such as Stripe.
The Amazon States Language 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 third-party API endpoint. The following Task state definition invokes a Lambda function named
.HelloFunction
"Lambda Invoke": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2
:123456789012
:function:HelloFunction
:$LATEST"
},
"End": true
}
Task types
Step Functions supports the following task types that you can specify in a Task state definition:
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 third-party API, use the following syntax. For information about syntax of the HTTP Task, see Call third-party APIs in Step Functions workflows.
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 commonlyaws
. -
service
indicates the AWS service used to execute the task, and can be one of the following values:-
states
for an activity. -
lambda
for a Lambda function. If you integrate with other AWS services, for example, Amazon SNS or Amazon DynamoDB, usesns
ordynamodb
.
-
-
region
is the AWS Region code 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. -
function
– A Lambda function. -
– The name of a supported connected service (see Integrating services with Step Functions).servicename
-
-
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, API action, or the Step Functions
console
For more information about creating an activity and implementing workers, see Activities.
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.
Depending on the type of integration (Optimized integration or AWS SDK integration) you use for specifying a Lambda function, the syntax of your Lambda function's Resource
field varies.
The following Resource
field syntax is an example of an optimized integration with a Lambda function.
"arn:aws:states:::lambda:invoke"
The following Resource
field syntax is an example of an AWS SDK integration with a Lambda function.
"arn:aws:states:::aws-sdk:lambda:invoke"
The following Task
state definition shows an example of an optimized integration with a Lambda function named
.HelloWorld
"LambdaState": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"OutputPath": "$.Payload",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-1:function:HelloWorld:$LATEST
"
},
"Next": "NextState"
}
After the Lambda function specified in the Resource
field completes,
its output is sent to the state identified in the Next
field
("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
: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.
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, Task
states have the following fields.
-
Resource
(Required) -
A URI, especially an ARN that uniquely identifies the specific task to execute.
-
Parameters
(Optional) -
Used to pass information to the API actions of connected resources. The parameters can use a mix of static JSON and JsonPath
. For more information, see Passing parameters to a service API in Step Functions. 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 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. 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.Note
This field is supported by the Task types that use Lambda functions and a supported AWS service.
-
ResultPath
(Optional) -
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 theOutputPath
field (if present) before being used as the state's output. For more information, see Input and Output Processing. -
ResultSelector
(Optional) -
Pass a collection of key value pairs, where the values are static or selected from the result. For more information, see 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 using Catch.
-
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.
-
TimeoutSeconds
(Optional) -
Specifies the maximum time an activity or a task can run before it times out with the States.Timeout error and fails. The timeout value must be positive, non-zero integer. The default value is
99999999
.The timeout count begins after a task starts, for example, when
ActivityStarted
orLambdaFunctionStarted
events are logged in the execution event history. For Activities, the count begins whenGetActivityTask
receives a token andActivityStarted
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.Note
HTTP task timeout has a maximum of 60 seconds, even if
TimeoutSeconds
exceeds that limit. See Quotas related to HTTP Task -
TimeoutSecondsPath
(Optional) -
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.Note
A
Task
state cannot include bothTimeoutSeconds
andTimeoutSecondsPath
. HTTP task timeout has a maximum of 60 seconds, even if theTimeoutSecondsPath
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 theTimeoutSeconds
field value. The default value is99999999
. If more time than the specified seconds elapses between heartbeats from the task, the Task state fails with a States.Timeout error.For Activities, the count begins when
GetActivityTask
receives a token andActivityStarted
is logged in the execution event history. -
HeartbeatSecondsPath
(Optional) -
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.Note
A
Task
state cannot include bothHeartbeatSeconds
andHeartbeatSecondsPath
.
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.
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:us-east-1: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 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)"
},
...
}
}
}