Skip to main content

Activity Execution

This page discusses the following:

What is an Activity Execution?​

An Activity Execution is the full chain of Activity Task Executions.

info
Activity Execution

Activity Execution

You can customize Activity Execution timeouts and retry policies.

If an Activity Execution fails (because it exhausted all retries, threw a non-retryable error, or was canceled), the error is returned to the Workflow, which decides how to handle it.

note

Temporal guarantees that an Activity Task either runs or timeouts. There are multiple failure scenarios when an Activity Task is lost. It can be lost during delivery to a Worker or after the Activity Function is called and the Worker crashed.

Temporal doesn't detect task loss directly. It relies on Start-To-Close timeout. If the Activity Task times out, the Activity Execution will be retried according to the Activity Execution Retry Policy.

In scenarios where the Activity Execution Retry Policy is set to 1 and a Timeout occurs, the Activity Execution will not be tried.

Cancellation​

Activity Cancellation:

  • lets the Activity know it doesn't need to keep doing work, and
  • gives the Activity time to clean up any resources it has created.

Activities must heartbeat to receive cancellations from a Temporal Service.

An Activity may receive Cancellation if:

  • The Activity was requested to be Cancelled. This can often cascade from Workflow Cancellation, but not always—SDKs have ways to stop Cancellation from cascading.
  • The Activity was considered failed by the Server because any of the Activity timeouts have triggered (for example, the Server didn't receive a heartbeat within the Activity's Heartbeat timeout). The Cancelled Failure that the Activity receives will have message: 'TIMED_OUT'.
  • The Workflow Run reached a Closed state, in which case the Cancelled Failure will have message: 'NOT_FOUND'.
  • In some SDKs:
    • The Worker is shutting down.
    • An Activity sends a Heartbeat but the Heartbeat details can't be converted by the Worker's configured Data Converter. This fails the Activity Task Execution with an Application Failure.
    • The Activity timed out on the Worker side and is not Heartbeating or the Temporal Service hasn't relayed a Cancellation.

There are different ways to receive Cancellation depending on the SDK. An Activity may accept or ignore Cancellation:

  • To allow Cancellation to happen, let the Cancellation Failure propagate.
  • To ignore Cancellation, catch it and continue executing.

Some SDKs have ways to shield tasks from being stopped while still letting the Cancellation propagate.

The Workflow can also decide if it wants to wait for the Activity Cancellation to be accepted or to proceed without waiting.

Cancellation can only be requested a single time. If you try to cancel your Activity Execution more than once, it will not receive more than one Cancellation request.

What is an Activity Id?​

The identifier for an Activity Execution. The identifier can be generated by the system, or it can be provided by the Workflow code that spawns the Activity Execution. The identifier is unique among the open Activity Executions of a Workflow Run. (A single Workflow Run may reuse an Activity Id if an earlier Activity Execution with the same Id has closed.)

An Activity Id can be used to complete the Activity asynchronously.

What is Asynchronous Activity Completion?​

Asynchronous Activity Completion is a feature that enables an Activity Function to return without causing the Activity Execution to complete. The Temporal Client can then be used from anywhere to both Heartbeat Activity Execution progress and eventually complete the Activity Execution and provide a result.

How to complete an Activity Asynchronously in:

When to use Async Completion​

When an external system has the final result of a computation that is started by an Activity, there are three main ways of getting the result to the Workflow:

  1. The external system uses Async Completion to complete the Activity with the result.
  2. The Activity completes normally, without the result. Later, the external system sends a Signal to the Workflow with the result.
  3. A subsequent Activity polls the external system for the result.

If you don't have control over the external system—that is, you can't add Async Completion or a Signal to its code—then

  • you can poll (#3), or
  • if the external system can reliably call a webhook (and retry calling in the case of failure), you can write a webhook handler that sends a Signal to the Workflow (#2).

The decision between using #1 vs #2 involves a few factors. Use Async Completion if

  • the external system is unreliable and might fail to Signal, or
  • you want the external process to Heartbeat or receive Cancellation.

Otherwise, if the external system can reliably be trusted to do the task and Signal back with the result, and it doesn't need to Heartbeat or receive Cancellation, then you may want to use Signals.

The benefit to using Signals has to do with the timing of failure retries. For example, consider an external process that is waiting for a human to review something and respond, and they could take up to a week to do so. If you use Async Completion (#1), you would

  • set a Start-To-Close Timeout of one week on the Activity,
  • in the Activity, notify the external process you need the human review, and
  • have the external process Asynchronously Complete the Activity when the human responds.

If the Activity fails on the second step to notify the external system and doesn't throw an error (for example, if the Worker dies), then the Activity won't be retried for a week, when the Start-To-Close Timeout is hit.

If you use Signals, you would:

  • set a Start-To-Close Timeout of one minute on the Activity,
  • in the Activity, notify the external process you need the human review,
  • complete the Activity without the result, and
  • have the external process Signal the Workflow when the human responds.

If the Activity fails on the second step to notify the external system and doesn't throw an error, then the Activity will be retried in a minute.

In the second scenario, the failure is retried sooner. This is particularly helpful in scenarios like this in which the external process might take a long time.

What is a Task Token?​

A Task Token is a unique identifier for an Activity Task Execution.

Asynchronous Activity Completion calls take either of the following as arguments: