Skip to main content

Update Activity Options

View Markdown

Update Options changes an Activity's runtime configuration without restarting it.

When to Update Options​

  • The Schedule-To-Close Timeout is about to expire on a Paused Activity, and you need to extend it before Unpausing. Extend the Start-To-Close Timeout in the same command if the next attempt also needs more time.
  • An Activity's Retry Policy needs tuning based on observed failure patterns (for example, increasing the backoff interval or maximum attempts).
  • You want to move an Activity to a different Task Queue to route it to a specific set of Workers.
  • You need to restore an Activity's original configuration after a temporary override.

What happens when you Update an Activity's Options​

You can change timeouts (Schedule-To-Close, Start-To-Close, Schedule-To-Start, Heartbeat), Retry Policy (initial interval, maximum interval, backoff coefficient, maximum attempts), Task Queue, and Priority (priority key, fairness key, fairness weight). For a Standalone Activity that hasn't dispatched its first Activity Task yet, you can also change the Start Delay. The CLI doesn't have flags for Priority, so change it through the API.

The request carries a field mask naming the fields to change. Fields the mask names are assigned the value in the request, and fields it doesn't name are left alone. A field the mask names but leaves empty is cleared, not skipped. temporal activity update-options adds a field to the mask only for the flags you pass, so omitting a flag never changes that option. To clear a timeout from the CLI, pass 0s. A cleared timeout doesn't stay empty: the Service derives it again from the other timeouts. See Timeouts are resolved again after every update.

  • If the Activity is waiting for retry (scheduled), the new options take effect immediately. Any pending retry timer is regenerated with the updated configuration.
  • If the Activity is currently running, the new options are stored but take effect on the next execution. The in-flight execution isn't interrupted.
  • If the Activity is Paused, the new options are stored immediately. They take effect when the Activity is Unpaused and the next execution starts.
  • Workflow code has no visibility into Activity Operations. Update Options doesn't produce an Event History event, so the Workflow can't detect or react to it. See Observability.

Update Options is idempotent. Updating an Activity with the same values it already has produces no change. Updating options on an Activity that has already completed returns an error.

Timeouts are resolved again after every update​

Once the new values are merged in, the Service re-runs the Activity timeout rules over the whole set. Changing one timeout can therefore change another.

The Activity's timeouts were already resolved when it was first scheduled, so none of them is unset by the time you update. Changing the Schedule-To-Close Timeout works in one direction only:

  • Lowering it pulls the others down with it. Reduce the Schedule-To-Close Timeout to one hour and a two-hour Start-To-Close Timeout is reduced to one hour as well.
  • Raising it leaves the others where they are. An Activity scheduled with a 24-hour Schedule-To-Close Timeout and no Start-To-Close Timeout stores 24 hours for both. Raise the Schedule-To-Close Timeout to 48 hours and the Start-To-Close Timeout stays at 24 hours, because it's no longer unset.

To give a Paused Activity both more total time and more time per attempt, change the Schedule-To-Close and Start-To-Close Timeouts in the same command.

Updates don't apply the Workflow Run Timeout cap that applies at schedule time. Clearing the Schedule-To-Close Timeout on a Workflow Activity leaves it unbounded rather than falling back to the Workflow Run Timeout.

CLI usage​

temporal activity update-options \
--workflow-id my-workflow \
--activity-id my-activity \
--schedule-to-close-timeout 24h

To target a Standalone Activity, omit --workflow-id:

temporal activity update-options \
--activity-id my-activity \
--schedule-to-close-timeout 24h

See the CLI reference for temporal activity update-options for all options, including Retry Policy and Task Queue.

Important considerations​

  • Changes to a running Activity take effect on the next execution, not the current one. If you need the change to apply immediately, the Activity must finish or fail its current execution first.
  • --restore-original-options is batch-only. This flag only works with --query. It's silently ignored in single-workflow mode. It can't be combined with other option changes in the same command.
  • Restoring original options requires a stored snapshot. For Activities that started before your Temporal Service supported Activity Operations, no snapshot exists and the request is rejected.