Skip to content

Conversation

@awln-temporal
Copy link
Contributor

@awln-temporal awln-temporal commented Dec 10, 2025

What changed?

Add batch workflow refresh tasks Admin API.

Add tdbg commands to invoke StartAdminBatchOperation.

Details

AdminBatchOperations are executed in the Batched System Worker, similar to existing Frontend BatchOperations. The worker activity will fetch pages of workflow executions to perform operations on, and periodically heartbeat its results. For RefreshWorkflowTasks, each individual Refresh call will go through the admin handler.

Refreshing Workflow Tasks regenerates all pending tasks of an execution given its mutable state.

CLI usage

tdbg workflow batch-refresh-tasks \
  --namespace <ns> \
  --query "WorkflowType='MyType'" \
  --reason "fixing stuck workflows" \
  [--job-id <optional-job-id>] \
  [--archetype <optional-archetype>]

Why?

Unblock new Matcher migration and allow for general use case batch Admin calls. Currently, only supports BatchOperationRefreshWorkflowTasks.

How did you test it?

  • built
  • run locally and tested manually
  • covered by existing tests
  • added new unit test(s)
  • added new functional test(s)

@awln-temporal awln-temporal requested review from a team as code owners December 10, 2025 16:48
@awln-temporal awln-temporal requested a review from yycptt December 10, 2025 16:48
@awln-temporal awln-temporal force-pushed the admin-batch-refresh-workflows branch from bfd3e1b to 32e6d5e Compare December 10, 2025 17:14
@awln-temporal awln-temporal force-pushed the admin-batch-refresh-workflows branch from 32e6d5e to 94f9a55 Compare December 10, 2025 18:22
@yycptt
Copy link
Member

yycptt commented Dec 10, 2025

Haven't review the actual changes yet but for the tdbg experience, let’s match what we have in the temporal CLI. so something like `tdbg workflow refresh-tasks -q '' means to start a batch operation. and if -q is not specified and --wid is specified, then it's not a batch op, but only operating on that single workflow.

string namespace = 1;

// Visibility query defines the group of workflows to apply the batch operation.
// This field and `executions` are mutually exclusive.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we will want to support a list of executions as well, that can be quite useful during incident mitigation, but can be done as a follow up item.


// BatchOperationRefreshWorkflowTasks refreshes workflow tasks for batch workflows.
// This regenerates all pending tasks for each workflow.
message BatchOperationRefreshWorkflowTasks {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plz remove Workflow from the names

Comment on lines +642 to +643
// Archetype to use for the refresh operation. If not specified, defaults to workflow archetype.
string archetype = 2;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm why do we need this? I mean the visibility records contain the archetype information.

// The request to start the batch operation.
temporal.api.workflowservice.v1.StartBatchOperationRequest request = 7;

// The request to start an admin batch operation.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plz comment that this field and request are mutually exclusive.
plz also add a comment for batch_type and say that it only applies to request

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants