Activities - Amazon Step Functions
OverviewWaiting for an Activity Task to CompleteNext Steps
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).

Activities

Activities are an Amazon Step Functions feature that enables you to have a task in your state machine where the work is performed by a worker that can be hosted on Amazon Elastic Compute Cloud (Amazon EC2), Amazon Elastic Container Service (Amazon ECS), mobile devices—basically anywhere.

Overview

In Amazon Step Functions, activities are a way to associate code running somewhere (known as an activity worker) with a specific task in a state machine. You can create an activity using the Step Functions console, or by calling CreateActivity. This provides an Amazon Resource Name (ARN) for your task state. Use this ARN to poll the task state for work in your activity worker.

Note

Activities are not versioned and are expected to be backward compatible. If you must make a backward-incompatible change to an activity, create a new activity in Step Functions using a unique name.

An activity worker can be an application running on an Amazon EC2 instance, an Amazon Lambda function, a mobile device: any application that can make an HTTP connection, hosted anywhere. When Step Functions reaches an activity task state, the workflow waits for an activity worker to poll for a task. An activity worker polls Step Functions by using GetActivityTask, and sending the ARN for the related activity. GetActivityTask returns a response including input (a string of JSON input for the task) and a taskToken (a unique identifier for the task). After the activity worker completes its work, it can provide a report of its success or failure by using SendTaskSuccess or SendTaskFailure. These two calls use the taskToken provided by GetActivityTask to associate the result with that task.

APIs Related to Activity Tasks

Step Functions provides APIs for creating and listing activities, requesting a task, and for managing the flow of your state machine based on the results of your worker.

The following are the Step Functions APIs that are related to activities:

Note

Polling for activity tasks with GetActivityTask can cause latency in some implementations. See Avoid latency when polling for activity tasks.

Waiting for an Activity Task to Complete

Configure how long a state waits by setting TimeoutSeconds in the task definition. To keep the task active and waiting, periodically send a heartbeat from your activity worker using SendTaskHeartbeat within the time configured in TimeoutSeconds. By configuring a long timeout duration and actively sending a heartbeat, an activity in Step Functions can wait up to a year for an execution to complete.

For example, if you need a workflow that waits for the outcome of a long process, do the following:

  1. Create an activity by using the console, or by using CreateActivity. Make a note of the activity ARN.

  2. Reference that ARN in an activity task state in your state machine definition and set TimeoutSeconds.

  3. Implement an activity worker that polls for work by using GetActivityTask, referencing that activity ARN.

  4. Use SendTaskHeartbeat periodically within the time you set in HeartbeatSeconds in your state machine task definition to keep the task from timing out.

  5. Start an execution of your state machine.

  6. Start your activity worker process.

The execution pauses at the activity task state and waits for your activity worker to poll for a task. Once a taskToken is provided to your activity worker, your workflow will wait for SendTaskSuccess or SendTaskFailure to provide a status. If the execution doesn't receive either of these or a SendTaskHeartbeat call before the time configured in TimeoutSeconds, the execution will fail and the execution history will contain an ExecutionTimedOut event.

Next Steps

For a more detailed look at creating state machines that use an activity workers, see: