Skip to content

Add Callbacks and Links to Workflow Update #742

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Quinn-With-Two-Ns wants to merge 10 commits into
base: master
Choose a base branch
from
Draft

Add Callbacks and Links to Workflow Update #742

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bac598d
Update callback support
Quinn-With-Two-Ns Dec 19, 2025
47c2e7f
Add links to request
Quinn-With-Two-Ns Dec 20, 2025
caadbdf
Add back link on UpdateWorkflowExecutionResponse
Quinn-With-Two-Ns Dec 20, 2025
134f733
Add update trigger
Quinn-With-Two-Ns Dec 21, 2025
4e2ba73
Add WorkflowUpdateOptionsUpdate to WorkflowExecutionOptionsUpdatedEve…
Quinn-With-Two-Ns Dec 21, 2025
0b8d676
fix openapi
Quinn-With-Two-Ns Feb 21, 2026
0576ff2
Add request ID
Quinn-With-Two-Ns Feb 21, 2026
7b4cb2b
add attached_request_id
Quinn-With-Two-Ns Feb 21, 2026
6c715c8
Add new link type
Quinn-With-Two-Ns Mar 25, 2026
3472bf7
Respond to PR comments
Quinn-With-Two-Ns Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2,109 changes: 1,839 additions & 270 deletions openapi/openapiv2.json
View file
Open in desktop

Large diffs are not rendered by default.

43 changes: 43 additions & 0 deletions openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8776,6 +8776,14 @@ components:
properties:
workflowClosed:
$ref: '#/components/schemas/CallbackInfo_WorkflowClosed'
updateWorkflowExecutionCompleted:
$ref: '#/components/schemas/CallbackInfo_UpdateWorkflowExecutionCompleted'
CallbackInfo_UpdateWorkflowExecutionCompleted:
type: object
properties:
updateId:
type: string
description: Trigger for when a workflow update is completed.
CallbackInfo_WorkflowClosed:
type: object
properties: {}
Expand Down Expand Up @@ -12082,6 +12090,19 @@ components:
$ref: '#/components/schemas/Meta'
input:
$ref: '#/components/schemas/Input'
requestId:
type: string
description: The request ID of the request.
completionCallbacks:
type: array
items:
$ref: '#/components/schemas/Callback'
description: Callbacks to be called by the server when this update reaches a terminal state.
links:
type: array
items:
$ref: '#/components/schemas/Link'
description: Links to be associated with this update.
description: The client request that triggers a Workflow Update.
RequestCancelActivityExecutionRequest:
type: object
Expand Down Expand Up @@ -15039,6 +15060,10 @@ components:
request WaitPolicy, and before the context deadline expired; clients may
may then retry the call as needed.
format: enum
link:
allOf:
- $ref: '#/components/schemas/Link'
description: Link to the update event. May be null if the update has not yet been accepted.
UpsertWorkflowSearchAttributesEventAttributes:
type: object
properties:
Expand Down Expand Up @@ -16309,6 +16334,17 @@ components:
description: |-
Priority override upserted in this event. Represents the full priority; not just partial fields.
Ignored if nil.
workflowUpdateOptions:
type: object
additionalProperties:
$ref: '#/components/schemas/WorkflowExecutionOptionsUpdatedEventAttributes_WorkflowUpdateOptionsUpdate'
WorkflowExecutionOptionsUpdatedEventAttributes_WorkflowUpdateOptionsUpdate:
type: object
properties:
attachedCompletionCallbacks:
type: array
items:
$ref: '#/components/schemas/Callback'
WorkflowExecutionPauseInfo:
type: object
properties:
Expand Down Expand Up @@ -16666,6 +16702,13 @@ components:
description: |-
The message payload of the original request message that initiated this
update.
completionCallbacks:
type: array
items:
$ref: '#/components/schemas/Callback'
description: |-
Completion callbacks attached when this update was started.
TODO(quinn) maybe not needed
WorkflowExecutionUpdateAdmittedEventAttributes:
type: object
properties:
Expand Down
12 changes: 12 additions & 0 deletions temporal/api/history/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -858,6 +858,13 @@ message ChildWorkflowExecutionTerminatedEventAttributes {
}

message WorkflowExecutionOptionsUpdatedEventAttributes {
message WorkflowUpdateOptionsUpdate {
// Request ID attached to the running workflow update so that subsequent requests with same
// request ID will be deduped
string attached_request_id = 3;
// Completion callbacks attached to the running workflow update.
repeated temporal.api.common.v1.Callback attached_completion_callbacks = 1;
}
// Versioning override upserted in this event.
// Ignored if nil or if unset_versioning_override is true.
temporal.api.workflow.v1.VersioningOverride versioning_override = 1;
Expand All @@ -873,6 +880,8 @@ message WorkflowExecutionOptionsUpdatedEventAttributes {
// Priority override upserted in this event. Represents the full priority; not just partial fields.
// Ignored if nil.
temporal.api.common.v1.Priority priority = 6;

map<string, WorkflowUpdateOptionsUpdate> workflow_update_options = 7;
Copy link
Copy Markdown
Member

@bergundy bergundy Mar 25, 2026

Choose a reason for hiding this comment

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

Is the key here the update ID? I slightly prefer putting the update ID in the WorkflowUpdateOptionsUpdate event so it's clear what the field just by the name. That would turn this field's type to repeated WorkflowUpdateOptionsUpdate.

Copy link
Copy Markdown
Contributor Author

@Quinn-With-Two-Ns Quinn-With-Two-Ns Mar 25, 2026

Choose a reason for hiding this comment

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

Yeah I thought we would need to index into this but we never ended up needing to

}

// Not used anywhere. Use case is replaced by WorkflowExecutionOptionsUpdatedEventAttributes
Expand Down Expand Up @@ -909,6 +918,9 @@ message WorkflowExecutionUpdateAcceptedEventAttributes {
// The message payload of the original request message that initiated this
// update.
temporal.api.update.v1.Request accepted_request = 4;
// Completion callbacks attached when this update was started.
// TODO(quinn) maybe not needed
Copy link
Copy Markdown
Member

@bergundy bergundy Mar 25, 2026

Choose a reason for hiding this comment

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

Looks like it's needed? My only concern is that the event time here is for when the update was accepted but there's no indication of when the callback was received for attachment.

Copy link
Copy Markdown
Contributor Author

@Quinn-With-Two-Ns Quinn-With-Two-Ns Mar 25, 2026

Choose a reason for hiding this comment

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

We currently don't keep any time for when the update was received, so if we don't care about when the update was received I don't think a callback changes that.

Copy link
Copy Markdown
Contributor Author

@Quinn-With-Two-Ns Quinn-With-Two-Ns Mar 25, 2026

Choose a reason for hiding this comment

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

We already attach the callback to the request so we can remove the callback here.

Copy link
Copy Markdown
Member

@bergundy bergundy Mar 27, 2026

Choose a reason for hiding this comment

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

Agree knowing the request time could be useful and is a separate concern.

repeated temporal.api.common.v1.Callback completion_callbacks = 5;
}

message WorkflowExecutionUpdateCompletedEventAttributes {
Expand Down
6 changes: 6 additions & 0 deletions temporal/api/update/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,12 @@ message Input {
message Request {
Meta meta = 1;
Input input = 2;
// The request ID of the request.
string request_id = 3;
// Callbacks to be called by the server when this update reaches a terminal state.
repeated temporal.api.common.v1.Callback completion_callbacks = 4;
// Links to be associated with this update.
repeated temporal.api.common.v1.Link links = 5;
}

// An Update protocol message indicating that a Workflow Update has been rejected.
Expand Down
6 changes: 6 additions & 0 deletions temporal/api/workflow/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,9 +449,15 @@ message CallbackInfo {
// Trigger for when the workflow is closed.
message WorkflowClosed {}

// Trigger for when a workflow update is completed.
message UpdateWorkflowExecutionCompleted {
string update_id = 1;
}

message Trigger {
oneof variant {
WorkflowClosed workflow_closed = 1;
UpdateWorkflowExecutionCompleted update_workflow_execution_completed = 2;
}
}

Expand Down
3 changes: 3 additions & 0 deletions temporal/api/workflowservice/v1/request_response.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1733,6 +1733,9 @@ message UpdateWorkflowExecutionResponse {
// request WaitPolicy, and before the context deadline expired; clients may
// may then retry the call as needed.
temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage stage = 3;

// Link to the update event. May be null if the update has not yet been accepted.
temporal.api.common.v1.Link link = 4;
}

message StartBatchOperationRequest {
Expand Down
Loading