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 all 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
120 changes: 120 additions & 0 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8650,9 +8650,21 @@
"properties": {
"workflowClosed": {
"$ref": "#/definitions/CallbackInfoWorkflowClosed"
},
"updateWorkflowExecutionCompleted": {
"$ref": "#/definitions/CallbackInfoUpdateWorkflowExecutionCompleted"
}
}
},
"CallbackInfoUpdateWorkflowExecutionCompleted": {
"type": "object",
"properties": {
"updateId": {
"type": "string"
}
},
"description": "Trigger for when a workflow update is completed."
},
"CallbackInfoWorkflowClosed": {
"type": "object",
"description": "Trigger for when the workflow is closed."
Expand Down Expand Up @@ -8769,6 +8781,24 @@
},
"description": "A link to a built-in batch job.\nBatch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).\nThis link can be put on workflow history events generated by actions taken by a batch job."
},
"LinkWorkflow": {
"type": "object",
"properties": {
"namespace": {
"type": "string"
},
"workflowId": {
"type": "string"
},
"runId": {
"type": "string"
},
"reason": {
"$ref": "#/definitions/v1LinkReason"
}
},
"description": "A link to a workflow execution. This is a more general version of WorkflowEvent that doesn't specify a \nparticular event within the workflow, useful when you want to link to a workflow but there is no particular event to link to,\nsuch as a Query or a Rejected Update."
},
"LinkWorkflowEvent": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -9103,6 +9133,27 @@
},
"description": "RequestIdReference is a indirect reference to a history event through the request ID."
},
"WorkflowExecutionOptionsUpdatedEventAttributesWorkflowUpdateOptionsUpdate": {
"type": "object",
"properties": {
"updateId": {
"type": "string",
"description": "The ID of the workflow update this update options update corresponds to."
},
"attachedRequestId": {
"type": "string",
"title": "Request ID attached to the running workflow update so that subsequent requests with same\nrequest ID will be deduped"
},
"attachedCompletionCallbacks": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
},
"description": "Completion callbacks attached to the running workflow update."
}
}
},
"WorkflowRuleActionActionActivityPause": {
"type": "object"
},
Expand Down Expand Up @@ -10534,6 +10585,26 @@
"description": "The arguments to pass to the named Update handler."
}
}
},
"requestId": {
"type": "string",
"description": "The request ID of the request."
},
"completionCallbacks": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
},
"description": "Callbacks to be called by the server when this update reaches a terminal state."
},
"links": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/apiCommonV1Link"
},
"description": "Links to be associated with this update."
}
},
"description": "The request information that will be delivered all the way down to the\nWorkflow Execution."
Expand Down Expand Up @@ -13303,10 +13374,23 @@
},
"batchJob": {
"$ref": "#/definitions/LinkBatchJob"
},
"workflow": {
"$ref": "#/definitions/LinkWorkflow"
}
},
"description": "Link can be associated with history events. It might contain information about an external entity\nrelated to the history event. For example, workflow A makes a Nexus call that starts workflow B:\nin this case, a history event in workflow A could contain a Link to the workflow started event in\nworkflow B, and vice-versa."
},
"v1LinkReason": {
"type": "string",
"enum": [
"LINK_REASON_UNSPECIFIED",
"LINK_REASON_QUERY",
"LINK_REASON_UPDATE_REJECTED"
],
"default": "LINK_REASON_UNSPECIFIED",
"description": "LinkReason is the reason for linking to a workflow execution."
},
"v1ListActivityExecutionsResponse": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -13744,6 +13828,10 @@
"pollerAutoscaling": {
"type": "boolean",
"title": "True if the namespace supports poller autoscaling"
},
"workflowUpdateCallbacks": {
"type": "boolean",
"title": "True if the namespace supports attaching callbacks on workflow updates"
}
},
"description": "Namespace capability details. Should contain what features are enabled in a namespace."
Expand Down Expand Up @@ -14892,6 +14980,26 @@
},
"input": {
"$ref": "#/definitions/v1Input"
},
"requestId": {
"type": "string",
"description": "The request ID of the request."
},
"completionCallbacks": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
},
"description": "Callbacks to be called by the server when this update reaches a terminal state."
},
"links": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Link"
},
"description": "Links to be associated with this update."
}
},
"description": "The client request that triggers a Workflow Update."
Expand Down Expand Up @@ -16573,6 +16681,10 @@
"stage": {
"$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage",
"description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nUNSPECIFIED will be returned if and only if the server's maximum wait\ntime was reached before the Update reached the stage specified in the\nrequest WaitPolicy, and before the context deadline expired; clients may\nmay then retry the call as needed."
},
"link": {
"$ref": "#/definitions/v1Link",
"description": "Link to the update event. May be null if the update has not yet been accepted."
}
}
},
Expand Down Expand Up @@ -17574,6 +17686,14 @@
"priority": {
"$ref": "#/definitions/v1Priority",
"description": "Priority override upserted in this event. Represents the full priority; not just partial fields.\nIgnored if nil."
},
"workflowUpdateOptions": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/WorkflowExecutionOptionsUpdatedEventAttributesWorkflowUpdateOptionsUpdate"
},
"description": "Updates to workflow updates options."
}
}
},
Expand Down
68 changes: 68 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 @@ -10373,6 +10381,8 @@ components:
$ref: '#/components/schemas/Link_WorkflowEvent'
batchJob:
$ref: '#/components/schemas/Link_BatchJob'
workflow:
$ref: '#/components/schemas/Link_Workflow'
description: |-
Link can be associated with history events. It might contain information about an external entity
related to the history event. For example, workflow A makes a Nexus call that starts workflow B:
Expand All @@ -10387,6 +10397,23 @@ components:
A link to a built-in batch job.
Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).
This link can be put on workflow history events generated by actions taken by a batch job.
Link_Workflow:
type: object
properties:
namespace:
type: string
workflowId:
type: string
runId:
type: string
reason:
enum:
- LINK_REASON_UNSPECIFIED
- LINK_REASON_QUERY
- LINK_REASON_UPDATE_REJECTED
type: string
format: enum
description: "A link to a workflow execution. This is a more general version of WorkflowEvent that doesn't specify a \n particular event within the workflow, useful when you want to link to a workflow but there is no particular event to link to,\n such as a Query or a Rejected Update."
Link_WorkflowEvent:
type: object
properties:
Expand Down Expand Up @@ -10774,6 +10801,9 @@ components:
pollerAutoscaling:
type: boolean
description: True if the namespace supports poller autoscaling
workflowUpdateCallbacks:
type: boolean
description: True if the namespace supports attaching callbacks on workflow updates
description: Namespace capability details. Should contain what features are enabled in a namespace.
NamespaceInfo_Limits:
type: object
Expand Down Expand Up @@ -12082,6 +12112,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 +15082,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 +16356,27 @@ components:
description: |-
Priority override upserted in this event. Represents the full priority; not just partial fields.
Ignored if nil.
workflowUpdateOptions:
type: array
items:
$ref: '#/components/schemas/WorkflowExecutionOptionsUpdatedEventAttributes_WorkflowUpdateOptionsUpdate'
description: Updates to workflow updates options.
WorkflowExecutionOptionsUpdatedEventAttributes_WorkflowUpdateOptionsUpdate:
type: object
properties:
updateId:
type: string
description: The ID of the workflow update this update options update corresponds to.
attachedRequestId:
type: string
description: |-
Request ID attached to the running workflow update so that subsequent requests with same
request ID will be deduped
attachedCompletionCallbacks:
type: array
items:
$ref: '#/components/schemas/Callback'
description: Completion callbacks attached to the running workflow update.
WorkflowExecutionPauseInfo:
type: object
properties:
Expand Down
12 changes: 12 additions & 0 deletions temporal/api/common/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import "google/protobuf/empty.proto";
import "temporal/api/enums/v1/common.proto";
import "temporal/api/enums/v1/event_type.proto";
import "temporal/api/enums/v1/reset.proto";
import "temporal/api/enums/v1/link.proto";

message DataBlob {
temporal.api.enums.v1.EncodingType encoding_type = 1;
Expand Down Expand Up @@ -240,9 +241,20 @@ message Link {
string job_id = 1;
}

// A link to a workflow execution. This is a more general version of WorkflowEvent that doesn't specify a
// particular event within the workflow, useful when you want to link to a workflow but there is no particular event to link to,
// such as a Query or a Rejected Update.
message Workflow {
string namespace = 1;
string workflow_id = 2;
string run_id = 3;
temporal.api.enums.v1.LinkReason reason = 4;
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.

I kinda prefer a string here, it's a bit more overhead but doesn't require translating enums to strings and can flow newer values through older SDK and server versions that don't have up-to-date protos.

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.

I don't have a strong opinion here. I thought enums were just easier to keep consistent across the SDK, Server and UI.

}

oneof variant {
WorkflowEvent workflow_event = 1;
BatchJob batch_job = 2;
Workflow workflow = 3;
}
}

Expand Down
17 changes: 17 additions & 0 deletions temporal/api/enums/v1/link.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
syntax = "proto3";

package temporal.api.enums.v1;

option go_package = "go.temporal.io/api/enums/v1;enums";
option java_package = "io.temporal.api.enums.v1";
option java_multiple_files = true;
option java_outer_classname = "LinkProto";
option ruby_package = "Temporalio::Api::Enums::V1";
option csharp_namespace = "Temporalio.Api.Enums.V1";

// LinkReason is the reason for linking to a workflow execution.
enum LinkReason {
LINK_REASON_UNSPECIFIED = 0;
LINK_REASON_QUERY = 1;
LINK_REASON_UPDATE_REJECTED = 2;
}
11 changes: 11 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,15 @@ message ChildWorkflowExecutionTerminatedEventAttributes {
}

message WorkflowExecutionOptionsUpdatedEventAttributes {
message WorkflowUpdateOptionsUpdate {
// The ID of the workflow update this update options update corresponds to.
string update_id = 1;
// Request ID attached to the running workflow update so that subsequent requests with same
// request ID will be deduped
string attached_request_id = 2;
// Completion callbacks attached to the running workflow update.
repeated temporal.api.common.v1.Callback attached_completion_callbacks = 3;
}
// 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 +882,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;
// Updates to workflow updates options.
repeated WorkflowUpdateOptionsUpdate workflow_update_options = 7;
}

// Not used anywhere. Use case is replaced by WorkflowExecutionOptionsUpdatedEventAttributes
Expand Down
2 changes: 2 additions & 0 deletions temporal/api/namespace/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,8 @@ message NamespaceInfo {
bool worker_poll_complete_on_shutdown = 8;
// True if the namespace supports poller autoscaling
bool poller_autoscaling = 9;
// True if the namespace supports attaching callbacks on workflow updates
bool workflow_update_callbacks = 10;
}

// Namespace configured limits
Expand Down
Loading
Loading