What is an Activity?

An activity is a unit of work that is executed by a worker. It is a specialized function call that can be executed one or more times, and can be cancelled while it is running.

Activity Definitions are executed as normal functions.

In the event of failure, the function begins at its initial state when retried (except when Activity Heartbeats are established).

Therefore, an Activity Definition has no restrictions on the code it contains.

Idempotency

Temporal recommends that Activities be idempotent.

Idempotent means that performing an operation multiple times has the same result as performing it once. In the context of Temporal, Activities should be designed to be safely executed multiple times without causing unexpected or undesired side effects.

An Activity is idempotent if multiple Activity Task Executions do not change the state of the system beyond the first Activity Task Execution.

We recommend using idempotency keys for critical side effects.

The lack of idempotency might affect the correctness of your application but does not affect the Temporal Platform. In other words, lack of idempotency doesn't lead to a platform error.

In some cases, whether something is idempotent doesn't affect the correctness of an application. For example, if you have a monotonically incrementing counter, you might not care that retries increment the counter because you don’t care about the actual value, only that the current value is greater than a previous value.

An Activity Heartbeat is a ping from the Worker Process that is executing the Activity to the Temporal Cluster. Each Heartbeat informs the Temporal Cluster that the Activity Execution is making progress and the Worker has not crashed. If the Cluster does not receive a Heartbeat within a Heartbeat Timeout time period, the Activity will be considered failed and another Activity Task Execution may be scheduled according to the Retry Policy.

Heartbeats may not always be sent to the Cluster—they may be throttled by the Worker.

Activity Cancellations are delivered to Activities from the Cluster when they Heartbeat. Activities that don't Heartbeat can't receive a Cancellation. Heartbeat throttling may lead to Cancellation getting delivered later than expected.

Heartbeats can contain payloads describing the Activity's current progress. If an Activity gets retried, the Activity can access the details from the last Heartbeat that was sent to the Cluster.

ActivityInfo provides information about the currently executing activity.

It can be used for logging, introspection, etc.

A type of exception thrown to a running activity to cancel it due to things happening with the worker, such as a shutdown. This differs from a normal activity cancellation, which uses the cancel function from the async package.

It is very common for an Activity to do things that interact with another Workflow, like using query or signal. This function provides a WorkflowClient that can be used to accomplish that.

The Activity monad provides access to the underlying Temporal client since it is very common for an Activity to interact with other Workflows.

A common use-case is to use signal to signal another Workflow from an Activity.

Using the provided client ensures that a consistent set of interceptors are used for all relevant actions.

A utility function for constructing an ActivityDefinition from a function as well as a KnownActivity value. This is useful for keeping the argument, codec, and result types in sync with each other so that changes to the function are reflected at their use sites.

myActivity :: Activity env ()
myActivity = liftIO $ putStrLn "Hello world!"

myActivityDef :: ActivityDefinition env (Activity env ())
myActivityDef = provideWorkflow
  JSON -- codec for serializing arguments and results
  "myActivity" -- visible name of the workflow
  myActivity -- the workflow function

A Task Token is a unique identifier for a Task. It can be used with the AsyncActivity API to signal activity completion or failure.

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 to both Heartbeat Activity Execution progress and eventually provide a result.

The intended use-case for this feature is when an external system has the final result of a computation, started by an Activity.

Consider using Asynchronous Activities instead of Signals if the external process is unreliable and might fail to send critical status updates through a Signal.

Consider using Signals as an alternative to Asynchronous Activities to return data back to a Workflow Execution if there is a human in the process loop. The reason is that a human in the loop means multiple steps in the process. The first is the Activity Function that stores state in an external system and at least one other step where a human would “complete” the activity. If the first step fails, you want to detect that quickly and retry instead of waiting for the entire process, which could be significantly longer when humans are involved.

Signal to the Temporal worker that the activity will be completed asynchronously (out of band).

In order to complete the activity once it has been moved to async, use complete, fail, or reportCancellation.

Note: Under the hood, this throws a CompleteAsync exception, which is caught and handled by the Temporal worker.

Make sure that your own code does not swallow or rewrap this exception, otherwise the activity will fail instead of signalling that it will be completed asynchronously.

Construct a function type from a list of argument types and a result type.