Skip to content

Add links and callbacks support for standalone activity #759

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

Open
fretz12 wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Add links and callbacks support for standalone activity #759

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6f68c8a
Add start delay, callbacks, and links to StartActivityExecutionRequest
fretz12 Apr 3, 2026
9c2b18d
Fix proto numbering
fretz12 Apr 7, 2026
24adc68
Update temporal/api/workflowservice/v1/request_response.proto
fretz12 Apr 7, 2026
8f0dabc
Update temporal/api/activity/v1/message.proto
fretz12 Apr 7, 2026
93a57ae
Update openapi
fretz12 Apr 7, 2026
8f2ca2c
Address PR comments
fretz12 Apr 7, 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
54 changes: 54 additions & 0 deletions openapi/openapiv2.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9156,6 +9156,21 @@
},
"description": "Target a worker polling on a Nexus task queue in a specific namespace."
},
"LinkActivity": {
"type": "object",
"properties": {
"namespace": {
"type": "string"
},
"activityId": {
"type": "string"
},
"runId": {
"type": "string"
}
},
"description": "A link to an activity."
},
"LinkBatchJob": {
"type": "object",
"properties": {
Expand Down Expand Up @@ -10437,6 +10452,22 @@
"priority": {
"$ref": "#/definitions/v1Priority",
"description": "Priority metadata."
},
"completionCallbacks": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Callback"
},
"description": "Callbacks to be called by the server when this activity reaches a terminal state.\nCallback addresses must be whitelisted in the server's dynamic configuration."
},
"links": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/apiCommonV1Link"
},
"description": "Links to be associated with the activity. Callbacks may also have associated links;\nlinks already included with a callback should not be duplicated here."
}
}
},
Expand Down Expand Up @@ -11249,6 +11280,14 @@
"canceledReason": {
"type": "string",
"description": "Set if activity cancelation was requested."
},
"links": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1Link"
},
"description": "Links associated with the activity."
}
},
"description": "Information about a standalone activity."
Expand Down Expand Up @@ -12864,6 +12903,14 @@
"type": "string",
"format": "byte",
"description": "Token for follow-on long-poll requests. Absent only if the activity is complete."
},
"callbacks": {
"type": "array",
"items": {
"type": "object",
"$ref": "#/definitions/v1CallbackInfo"
},
"description": "Callbacks attached to this activity execution and their current state."
}
}
},
Expand Down Expand Up @@ -13947,6 +13994,9 @@
},
"batchJob": {
"$ref": "#/definitions/LinkBatchJob"
},
"activity": {
"$ref": "#/definitions/LinkActivity"
}
},
"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."
Expand Down Expand Up @@ -16437,6 +16487,10 @@
"started": {
"type": "boolean",
"description": "If true, a new activity was started."
},
"link": {
"$ref": "#/definitions/v1Link",
"description": "Link to the started activity."
}
}
},
Expand Down
40 changes: 40 additions & 0 deletions openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8236,6 +8236,11 @@ components:
canceledReason:
type: string
description: Set if activity cancelation was requested.
links:
type: array
items:
$ref: '#/components/schemas/Link'
description: Links associated with the activity.
description: Information about a standalone activity.
ActivityExecutionListInfo:
type: object
Expand Down Expand Up @@ -9912,6 +9917,11 @@ components:
type: string
description: Token for follow-on long-poll requests. Absent only if the activity is complete.
format: bytes
callbacks:
type: array
items:
$ref: '#/components/schemas/CallbackInfo'
description: Callbacks attached to this activity execution and their current state.
DescribeBatchOperationResponse:
type: object
properties:
Expand Down Expand Up @@ -10915,11 +10925,23 @@ components:
$ref: '#/components/schemas/Link_WorkflowEvent'
batchJob:
$ref: '#/components/schemas/Link_BatchJob'
activity:
$ref: '#/components/schemas/Link_Activity'
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:
in this case, a history event in workflow A could contain a Link to the workflow started event in
workflow B, and vice-versa.
Link_Activity:
type: object
properties:
namespace:
type: string
activityId:
type: string
runId:
type: string
description: A link to an activity.
Link_BatchJob:
type: object
properties:
Expand Down Expand Up @@ -14280,6 +14302,20 @@ components:
allOf:
- $ref: '#/components/schemas/Priority'
description: Priority metadata.
completionCallbacks:
type: array
items:
$ref: '#/components/schemas/Callback'
description: |-
Callbacks to be called by the server when this activity reaches a terminal state.
Callback addresses must be whitelisted in the server's dynamic configuration.
links:
type: array
items:
$ref: '#/components/schemas/Link'
description: |-
Links to be associated with the activity. Callbacks may also have associated links;
links already included with a callback should not be duplicated here.
StartActivityExecutionResponse:
type: object
properties:
Expand All @@ -14289,6 +14325,10 @@ components:
started:
type: boolean
description: If true, a new activity was started.
link:
allOf:
- $ref: '#/components/schemas/Link'
description: Link to the started activity.
StartBatchOperationRequest:
type: object
properties:
Expand Down
3 changes: 3 additions & 0 deletions temporal/api/activity/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,9 @@ message ActivityExecutionInfo {

// Set if activity cancelation was requested.
string canceled_reason = 32;

// Links associated with the activity.
Copy link
Copy Markdown
Contributor

@dandavison dandavison Apr 9, 2026

Choose a reason for hiding this comment

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

A reader is going to think initially these are links that in some way refer to this activity. However, they're not -- they're links pointing to other entities associated with the activity; typically the entity that started the activity. Let's clarify this for the reader, here and in the workflow counterpart HistoryEvent.links. As an author of a Nexus SDK I found this confusing at first, so there's not much doubt that other users will benefit from some help here.

Suggested change
// Links associated with the activity.
// Links to entities associated with this activity, for example
// to the entity that started this activity.

repeated temporal.api.common.v1.Link links = 33;
}

// Limited activity information returned in the list response.
Expand Down
8 changes: 8 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 @@ -240,9 +240,17 @@ message Link {
string job_id = 1;
}

// A link to an activity.
message Activity {
string namespace = 1;
string activity_id = 2;
string run_id = 3;
}

oneof variant {
WorkflowEvent workflow_event = 1;
BatchJob batch_job = 2;
Activity activity = 3;
}
}

Expand Down
11 changes: 11 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 @@ -2931,13 +2931,21 @@ message StartActivityExecutionRequest {
temporal.api.sdk.v1.UserMetadata user_metadata = 17;
// Priority metadata.
temporal.api.common.v1.Priority priority = 18;
// Callbacks to be called by the server when this activity reaches a terminal state.
// Callback addresses must be whitelisted in the server's dynamic configuration.
repeated temporal.api.common.v1.Callback completion_callbacks = 19;
// Links to be associated with the activity. Callbacks may also have associated links;
// links already included with a callback should not be duplicated here.
repeated temporal.api.common.v1.Link links = 20;
Copy link
Copy Markdown
Contributor

@dandavison dandavison Apr 9, 2026

Choose a reason for hiding this comment

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

The SAA PR only uses links on the callback. Is it necessary/appropriate to add these top-level links in addition to the callback links? If so, could the Nexus team give a refresher on what the respective roles are of the two links (I had it in my head that top-level were deprecated).

}

message StartActivityExecutionResponse {
// The run ID of the activity that was started - or used (via ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING).
string run_id = 1;
// If true, a new activity was started.
bool started = 2;
// Link to the started activity.
temporal.api.common.v1.Link link = 3;
}

message DescribeActivityExecutionRequest {
Expand Down Expand Up @@ -2974,6 +2982,9 @@ message DescribeActivityExecutionResponse {

// Token for follow-on long-poll requests. Absent only if the activity is complete.
bytes long_poll_token = 5;

// Callbacks attached to this activity execution and their current state.
repeated temporal.api.workflow.v1.CallbackInfo callbacks = 6;
Copy link
Copy Markdown
Contributor

@dandavison dandavison Apr 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

This CallbackInfo is currently workflow-specific:

// CallbackInfo contains the state of an attached workflow callback.
message CallbackInfo {
    // Trigger for when the workflow is closed.
    message WorkflowClosed {}

    message Trigger {
        oneof variant {
            WorkflowClosed workflow_closed = 1;
        }
    }

We either need to make it more general, or add an activity-specific CallbackInfo. I'm thinking we'd want the former -- add an ActivityClosed or ExecutionClosed trigger. We're going to want to straighten this out, and it would be a breaking API change to do it later.

}

message PollActivityExecutionRequest {
Expand Down
Loading