Skip to main content

Activity Operations

View Markdown

This section covers the following:

Activity Operations are deliberate actions you perform on a specific Activity Execution, as opposed to lifecycle behaviors like retries and timeouts which happen automatically.

You can perform Activity Operations through the CLI, the UI, or directly via the gRPC API. They apply to Workflow Activities and to Standalone Activities. They don't apply to Local Activities.

Public Preview

Activity Operations are in Public Preview, except for Standalone Activity commands: Request Cancel, Terminate, Delete which are GA.

For Workflow Activities, Pause, Unpause, and Reset are available in Server v1.28.0+. Self-hosted UI requires v2.47.0+. For Standalone Activities, Pause, Unpause, Reset, and Update Options are available in Server v1.32.0+.

Activity Operations aren't available as SDK client methods. They're operational controls designed for the CLI, UI, and gRPC API - they are not for programmatic use in Workflow or Activity code.

Operations summary​

OperationWhat it doesWorkflow ActivityStandalone ActivityCLI
PauseStops retries. In-flight execution continues unless the Activity uses Heartbeat.YesYestemporal activity pause
UnpauseResumes a Paused Activity. The next execution starts immediately.YesYestemporal activity unpause
ResetClears retry state (attempts, backoff) and schedules a new execution.YesYestemporal activity reset
Update OptionsChanges timeouts, Retry Policy, or Task Queue without restarting the Activity.YesYestemporal activity update-options
Request CancelRequests that an execution close gracefully, letting your code clean up.Through the WorkflowYestemporal activity cancel
TerminateForcefully closes an execution with no opportunity for your code to clean up.NoYestemporal activity terminate
DeleteTerminates the execution if it's running, then deletes it asynchronously.NoYestemporal activity delete

A Workflow Activity can't be cancelled directly. It receives a cancellation request as a result of its Workflow being cancelled, and from that point behaves the same way a Standalone Activity does.

What an operation guarantees​

Every operation does two things, and they succeed independently.

Server-side state changes immediately. Terminate closes the execution. Request Cancel closes it immediately when no attempt is running. This doesn't depend on the Activity Heartbeating.

Interrupting an already-running attempt is best-effort. Request Cancel, Terminate, Reset, and Pause all attempt it, by the same mechanism: the request reaches your code through the Activity's Heartbeat. An Activity that doesn't Heartbeat isn't interrupted mid-attempt.

Because interruption is best-effort, a Request Cancel, Reset, or Pause request can succeed without the operation taking effect. When an attempt is running, your code may complete or fail non-retryably instead of honoring the request. Only Terminate and Delete discard Activity progress unconditionally. A successful response means the request was accepted, not that the Activity stopped.

Successive operations​

When operations conflict, precedence is Request Cancel, then Reset, then Pause. A higher-precedence request wins over a pending lower-precedence one.

Requests that can't apply to the Activity's current state return an error rather than being queued:

  • FailedPrecondition when the Activity exists but isn't in a state that accepts the operation.
  • NotFound when the Activity or its run can't be found.

Pause and Unpause interact with timers in a way worth knowing before you use them together:

  • Timers keep running while an Activity is Paused. Pausing doesn't stop the Schedule-To-Close Timeout.
  • No new attempt is scheduled while Paused.
  • On Unpause, a retry that's already past due starts immediately.
  • Before the first attempt, Unpause honors the Activity's original Start Delay deadline. If that deadline has passed, the Activity is dispatched immediately. Start Delay isn't restarted from the Unpause time, and it doesn't apply to retry attempts.

Batch operations​

You can apply some operations to many Activities at once with a --query List Filter instead of a single Activity Id.

Standalone Activities currently only support batch operations for Request Cancel, Terminate, and Delete:

temporal activity terminate \
  --query 'ActivityType="ProcessImage" AND ExecutionStatus="Running"' \
  --reason "Bad input batch"

For Workflow Activities, --query applies to Reset, Unpause, and Update Options.

Use --jitter to stagger a batch so a recovering downstream service isn't hit by every retry at once.

Billable Actions​

In Temporal Cloud, Pause, Reset, and Update Options each count as one Action. Unpause is free.

Observability​

Activity Operations have a limited audit trail because they are not recorded in a Workflow's Event History. However, you can use the CLI and the UI to check Activity state and find Paused Activities for running Workflows.

Check Activity state​

temporal workflow describe shows the current state of each pending Activity, including whether it's Paused, its current attempt count, and last failure. The UI shows who performed an operation, when, and why (if a --reason was provided).

Find Paused Activities​

The TemporalPauseInfo Search Attribute is filterable within a Workflow.

There's no Namespace-wide query to find all Paused Activities across Workflows. You must know the Workflow Id.

Audit trail​

Activity Operations don't produce Event History events. There is no record of a Pause, Reset, or option change in the Workflow's Event History. Nothing that reads the Event History - Workflow code, Replays, or external tooling - will see that an Operation occurred.

Evidence of an Operation is gone when the Activity completes or the Workflow closes. There's no persistent record that an Activity was Paused, Reset, or had its options changed.

The only way to confirm the current state of an Activity is temporal workflow describe or the UI.