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.
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:
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:
-
Create an activity by using the console, or by using
CreateActivity
. Make a note of the activity ARN. -
Reference that ARN in an activity task state in your state machine definition and set
TimeoutSeconds
. -
Implement an activity worker that polls for work by using
GetActivityTask
, referencing that activity ARN. -
Use
SendTaskHeartbeat
periodically within the time you set inHeartbeatSeconds
in your state machine task definition to keep the task from timing out. -
Start an execution of your state machine.
-
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: