Task

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

All work in your state machine is done by tasks. A task performs work by using an activity or an AWS Lambda function, or by passing parameters to the API actions of other services.

AWS Step Functions can invoke Lambda functions directly from a task state. A Lambda function is a cloud-native task that runs on AWS Lambda. You can write Lambda functions in a variety of programming languages, using the AWS Management Console or by uploading code to Lambda. For more information see Creating a Step Functions state machine that uses Lambda.

Note

Step Functions can coordinate some AWS services directly from a task state. For more information see Working with other services.

An activity consists of program code that waits for an operator to perform an action or to provide input. You can host activities on Amazon EC2, on Amazon ECS, or even on mobile devices. Activities poll Step Functions using the GetActivityTask and SendTaskSuccess, SendTaskFailure, and SendTaskHeartbeat API actions.

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 or Lambda function.

Contents

• Task state fields
• Task state definition examples
  • Task state timeouts and heartbeat intervals
    • Static timeout and heartbeat notification example
    • Dynamic task timeout and heartbeat notification example
  • Task state's Credentials field examples
    • Specifying hard-coded IAM role ARN
    • Specifying JSONPath as IAM role ARN
• Specifying Resource ARNs in Tasks
• Task types
  • Activity
  • Lambda functions
  • A supported AWS service
• Activities
  • Overview
    • APIs Related to Activity Tasks
  • Waiting for an Activity Task to Complete
  • Next Steps
  • Example Activity Worker in Ruby

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 Pass parameters to a service API.

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 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 Tutorial: Accessing cross-account AWS resources.

Note

This field is supported by the Task types that use Lambda functions and a supported AWS service.

Important

Currently, the Credentials field is available in Commercial Regions only.

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 the OutputPath 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 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)

If the task runs longer than the specified seconds, this state fails with a States.Timeout error name. Must be a positive, non-zero integer. If not provided, the default value is 99999999. The count begins after the task has been started, for example, when ActivityStarted or LambdaFunctionStarted are logged in the Execution event history.

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 both TimeoutSeconds and TimeoutSecondsPath

HeartbeatSeconds (Optional)

If more time than the specified seconds elapses between heartbeats from the task, this state fails with a 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. For Activities, the count begins when GetActivityTask receives a token and ActivityStarted 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 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

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 Resource ARNs in Tasks

The Resource field's ARN is specified using the following pattern.

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

In this pattern:

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

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

  • states for an activity.

  • lambda for a Lambda function.

• region is the AWS Region in which the Step Functions activity or 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 is one of the following values:

  • activity – An activity.

  • function – A Lambda function.

  • servicename – The name of a supported connected service (see Optimized integrations for Step Functions).

• 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.

Task types

The following task types are supported:

• Activity

• Lambda functions

• A supported AWS service

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

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

Note

You must create activities 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 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").

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

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 Working with other 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
    }
  }
}