Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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 Amazon Lambda function, or by passing parameters to the API actions of other services.

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

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.

Task state fields

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

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-cn: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 Amazon Glue job completes, the next state will be run.

If this task fails to complete within the interval set dynamically by the Amazon Glue job, the task is marked as failed.

"GlueJobTask": {
  "Type": "Task",
  "Resource": "arn:aws-cn:states:::glue:startJobRun.sync",
  "Parameters": {
    "JobName": "myGlueJob"
  },
  "TimeoutSecondsPath": "$.params.maxTime",
  
  "Next": "NextState"
}

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:

Task types

The following task types are supported:

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.

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

Lambda functions

Lambda tasks execute a function using Amazon 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 Amazon 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-cn:states:::lambda:invoke"

The following Resource field syntax is an example of an Amazon SDK integration with a Lambda function.

"arn:aws-cn: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-cn:states:::lambda:invoke",
  "OutputPath": "$.Payload",
  "Parameters": {
    "Payload.$": "$",
    "FunctionName": "arn:aws-cn: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 Amazon 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

For example:

{
 "StartAt": "BATCH_JOB",
 "States": {
   "BATCH_JOB": {
     "Type": "Task",
     "Resource": "arn:aws-cn:states:::batch:submitJob.sync",
     "Parameters": {  
       "JobDefinition": "preprocessing",
       "JobName": "PreprocessingBatchJob",
       "JobQueue": "SecondaryQueue",
       "Parameters.$": "$.batchjob.parameters",
       "RetryStrategy": {
          "attempts": 5
        }
     },
     "End": true
    }
  }
}