Menu
AWS Step Functions
Developer Guide

Task

A Task state ("Type": "Task") represents a single unit of work performed by a state machine.

In addition to the common state fields, Task states have the following fields:

Resource (Required)

A URI, especially an Amazon Resource Name (ARN) that uniquely identifies the specific task to execute.

ResultPath (Optional)

Specifies where (in the input) to place the results of executing the task specified in Resource. The input is then filtered as prescribed by the OutputPath field (if present) before being used as the state's output. For more information, see path.

Retry (Optional)

An array of objects, called Retriers, that define a retry policy in case the state encounters runtime errors. For more information, see Retrying After an Error.

Catch (Optional)

An array of objects, called Catchers, that define a fallback state which is executed in case the state encounters runtime errors and its retry policy has been exhausted or is not defined. For more information, see Fallback States.

TimeoutSeconds (Optional)

If the task runs longer than the specified seconds, then this state fails with a States.Timeout Error Name. Must be a positive, non-zero integer. If not provided, the default value is 99999999.

HeartbeatSeconds (Optional)

If more time than the specified seconds elapses between heartbeats from the task, then this state fails with an States.Timeout Error Name. Must be a positive, non-zero integer less than the number of seconds specified in the TimeoutSeconds field. If not provided, the default value is 99999999.

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 will be run upon completion of the Task state.

Here is an example:

"ActivityState": {
  "Type": "Task",
  "Resource": "arn:aws:states:us-east-1:123456789012:activity:HelloWorld",
  "TimeoutSeconds": 300,
  "HeartbeatSeconds": 60,
  "Next": "NextState"
}

In this example, ActivityState will schedule the HelloWorld activity for execution in the us-east-1 region on the caller's AWS account. When HelloWorld completes, the next state (here called NextState) will be run.

If this task fails to complete within 300 seconds, or does not send heartbeat notifications in intervals of 60 seconds, then the task is marked as failed. It's a good practice to set a timeout value and a heartbeat interval for long-running activities.

Specifying Resource ARNs in Tasks

The Resource field's Amazon Resource Name (ARN) is specified using the following pattern:

arn:partition:service:region:account:task_type:name

Where:

  • partition is the AWS Step Functions partition to use, most commonly aws.

  • service indicates the AWS service used to execute the task, and is either:

  • region is the AWS region in which the Step Functions activity/state machine type or Lambda function has been created.

  • account is your AWS account id.

  • task_type is the type of task to run. It will be one of the following values:

  • name is the registered resource name (activity name or Lambda function name).

Note

Step Functions does not support referencing ARNs across partitions (For example: "aws-cn" cannot invoke tasks in the "aws" partition, and vice versa);

Task Types

The following task types are supported:

The following sections will provide more detail about each type.

Activity

Activities represent workers (processes or threads), implemented and hosted by you, that perform a specific task.

Activity resource ARNs use the following syntax:

arn:partition:states:region:account:activity:name

For more information about these fields, see Specifying Resource ARNs in Tasks.

Note

activities must be created with Step Functions (using a CreateActivity, API action, or the Step Functions console) before their first use.

For more information about creating an activity and implementing workers, see Activities.

Lambda Functions

Lambda functions execute a function using AWS Lambda. To specify a Lambda function, use the ARN of the Lambda function in the Resource field.

Lambda function Resource ARNs use the following syntax:

arn:partition:lambda:region:account:function:function_name

For more information about these fields, see Specifying Resource ARNs in Tasks.

For example:

"LambdaState": {
  "Type": "Task",
  "Resource": "arn:aws:lambda:us-east-1:123456789012:function:HelloWorld",
  "Next": "NextState"
}

Once the Lambda function specified in the Resource field completes, its output is sent to the state identified in the Next field ("NextState").