Skip to content

[Workflow Pause] Proto changes #653

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

Merged
gow merged 14 commits into from
Nov 18, 2025
Merged

[Workflow Pause] Proto changes #653

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
7efd5cb
[Workflow Pause] Proto changes
gow Oct 22, 2025
fbd9785
make proto
gow Oct 22, 2025
b076f2a
Add attributes to oneoff and add docs
gow Oct 23, 2025
e261a75
make proto
gow Oct 23, 2025
414ead2
Added WorkflowExecutionPauseInfo and addressed comments
gow Oct 24, 2025
1892424
make proto
gow Oct 24, 2025
6a5e637
Inline worklfow_id & run_id
gow Oct 31, 2025
cef26c1
Use Id instead of workflow_id
gow Oct 31, 2025
16af4ae
Removed reference to pause event ID from WorkflowExecutionUnpausedEve…
gow Nov 4, 2025
b2a5959
Revert "Use Id instead of workflow_id"
gow Nov 6, 2025
5d8eed6
make proto
gow Nov 6, 2025
9a804df
Revert "Inline worklfow_id & run_id"
gow Nov 6, 2025
51d85ac
Merge branch 'master' of github.com:temporalio/api into cg/wf_pause_1
gow Nov 14, 2025
6159855
Reapply "Inline worklfow_id & run_id"
gow Nov 14, 2025
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
221 changes: 217 additions & 4 deletions openapi/openapiv2.json
View file
Open in desktop

Large diffs are not rendered by default.

204 changes: 203 additions & 1 deletion openapi/openapiv3.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6204,6 +6204,52 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/Status'
/namespaces/{namespace}/workflows/{workflowId}/pause:
post:
tags:
- WorkflowService
description: |-
Note: This is an experimental API and the behavior may change in a future release.
PauseWorkflowExecution pauses the workflow execution specified in the request. Pausing a workflow execution results in
- The workflow execution status changes to `PAUSED` and a new WORKFLOW_EXECUTION_PAUSED event is added to the history
- No new workflow tasks or activity tasks are dispatched.
- Any workflow task currently executing on the worker will be allowed to complete.
- Any activity task currently executing will be paused.
- All server-side events will continue to be processed by the server.
- Queries & Updates on a paused workflow will be rejected.
operationId: PauseWorkflowExecution
parameters:
- name: namespace
in: path
description: Namespace of the workflow to pause.
required: true
schema:
type: string
- name: workflowId
in: path
description: ID of the workflow execution to be paused. Required.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PauseWorkflowExecutionRequest'
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PauseWorkflowExecutionResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/namespaces/{namespace}/workflows/{workflowId}/signal-with-start/{signalName}:
post:
tags:
Expand Down Expand Up @@ -6258,6 +6304,49 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/Status'
/namespaces/{namespace}/workflows/{workflowId}/unpause:
post:
tags:
- WorkflowService
description: |-
Note: This is an experimental API and the behavior may change in a future release.
UnpauseWorkflowExecution unpauses a previously paused workflow execution specified in the request.
Unpausing a workflow execution results in
- The workflow execution status changes to `RUNNING` and a new WORKFLOW_EXECUTION_UNPAUSED event is added to the history
- Workflow tasks and activity tasks are resumed.
operationId: UnpauseWorkflowExecution
parameters:
- name: namespace
in: path
description: Namespace of the workflow to unpause.
required: true
schema:
type: string
- name: workflowId
in: path
description: ID of the workflow execution to be paused. Required.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UnpauseWorkflowExecutionRequest'
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UnpauseWorkflowExecutionResponse'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/namespaces/{namespace}/workflows/{workflow_execution.workflow_id}/cancel:
post:
tags:
Expand Down Expand Up @@ -8670,6 +8759,8 @@ components:
- EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
- EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
- EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
type: string
format: enum
version:
Expand Down Expand Up @@ -8820,6 +8911,10 @@ components:
$ref: '#/components/schemas/NexusOperationCancelRequestCompletedEventAttributes'
nexusOperationCancelRequestFailedEventAttributes:
$ref: '#/components/schemas/NexusOperationCancelRequestFailedEventAttributes'
workflowExecutionPausedEventAttributes:
$ref: '#/components/schemas/WorkflowExecutionPausedEventAttributes'
workflowExecutionUnpausedEventAttributes:
$ref: '#/components/schemas/WorkflowExecutionUnpausedEventAttributes'
description: |-
History events are the method by which Temporal SDKs advance (or recreate) workflow state.
See the `EventType` enum for more info about what each event is for.
Expand Down Expand Up @@ -9664,6 +9759,32 @@ components:
reason:
type: string
description: Reason why rule was created. Populated from rule description.
PauseWorkflowExecutionRequest:
type: object
properties:
namespace:
type: string
description: Namespace of the workflow to pause.
workflowId:
type: string
description: ID of the workflow execution to be paused. Required.
runId:
type: string
description: Run ID of the workflow execution to be paused. Optional. If not provided, the current run of the workflow will be paused.
identity:
type: string
description: The identity of the client who initiated this request.
reason:
type: string
description: Reason to pause the workflow execution.
requestId:
type: string
description: A unique identifier for this pause request for idempotence. Typically UUIDv4.
description: Request to pause a workflow execution.
PauseWorkflowExecutionResponse:
type: object
properties: {}
description: Response to a successful PauseWorkflowExecution request.
Payload:
description: |-
Represents some binary (byte array) data (ex: activity input parameters or workflow result) with
Expand Down Expand Up @@ -10202,6 +10323,7 @@ components:
- WORKFLOW_EXECUTION_STATUS_TERMINATED
- WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW
- WORKFLOW_EXECUTION_STATUS_TIMED_OUT
- WORKFLOW_EXECUTION_STATUS_PAUSED
type: string
format: enum
QueryWorkflowRequest:
Expand Down Expand Up @@ -10576,6 +10698,8 @@ components:
- EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
- EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
- EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
type: string
description: The event type of the history event generated by the request.
format: enum
Expand Down Expand Up @@ -11134,6 +11258,7 @@ components:
- WORKFLOW_EXECUTION_STATUS_TERMINATED
- WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW
- WORKFLOW_EXECUTION_STATUS_TIMED_OUT
- WORKFLOW_EXECUTION_STATUS_PAUSED
type: string
description: |-
If the action was start_workflow, this field will reflect an
Expand Down Expand Up @@ -12213,6 +12338,7 @@ components:
- WORKFLOW_EXECUTION_STATUS_TERMINATED
- WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW
- WORKFLOW_EXECUTION_STATUS_TIMED_OUT
- WORKFLOW_EXECUTION_STATUS_PAUSED
type: string
description: |-
Current execution status of the workflow. Typically remains WORKFLOW_EXECUTION_STATUS_RUNNING
Expand Down Expand Up @@ -12719,6 +12845,31 @@ components:
UnpauseActivityResponse:
type: object
properties: {}
UnpauseWorkflowExecutionRequest:
type: object
properties:
namespace:
type: string
description: Namespace of the workflow to unpause.
workflowId:
type: string
description: ID of the workflow execution to be paused. Required.
runId:
type: string
description: Run ID of the workflow execution to be paused. Optional. If not provided, the current run of the workflow will be paused.
identity:
type: string
description: The identity of the client who initiated this request.
reason:
type: string
description: Reason to unpause the workflow execution.
requestId:
type: string
description: A unique identifier for this unpause request for idempotence. Typically UUIDv4.
UnpauseWorkflowExecutionResponse:
type: object
properties: {}
description: Response to a successful UnpauseWorkflowExecution request.
UpdateActivityOptionsRequest:
type: object
properties:
Expand Down Expand Up @@ -13867,6 +14018,8 @@ components:
- EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
- EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
- EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
type: string
format: enum
description: EventReference is a direct reference to a history event through the event ID.
Expand Down Expand Up @@ -13935,6 +14088,8 @@ components:
- EVENT_TYPE_WORKFLOW_EXECUTION_OPTIONS_UPDATED
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED
- EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED
- EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED
- EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED
type: string
format: enum
description: RequestIdReference is a indirect reference to a history event through the request ID.
Expand Down Expand Up @@ -14152,6 +14307,7 @@ components:
- WORKFLOW_EXECUTION_STATUS_TERMINATED
- WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW
- WORKFLOW_EXECUTION_STATUS_TIMED_OUT
- WORKFLOW_EXECUTION_STATUS_PAUSED
type: string
format: enum
historyLength:
Expand Down Expand Up @@ -14249,6 +14405,10 @@ components:
allOf:
- $ref: '#/components/schemas/Priority'
description: Priority metadata
pauseInfo:
allOf:
- $ref: '#/components/schemas/WorkflowExecutionPauseInfo'
description: Information about the workflow execution pause operation.
description: |-
Hold basic information about a workflow execution.
This structure is a part of visibility, and thus contain a limited subset of information.
Expand Down Expand Up @@ -14284,6 +14444,33 @@ components:
identity:
type: string
description: Optional. The identity of the client who initiated the request that created this event.
WorkflowExecutionPauseInfo:
type: object
properties:
identity:
type: string
description: The identity of the client who paused the workflow execution.
pausedTime:
type: string
description: The time when the workflow execution was paused.
format: date-time
reason:
type: string
description: The reason for pausing the workflow execution.
description: WorkflowExecutionPauseInfo contains the information about a workflow execution pause.
WorkflowExecutionPausedEventAttributes:
type: object
properties:
identity:
type: string
description: The identity of the client who paused the workflow execution.
reason:
type: string
description: The reason for pausing the workflow execution.
requestId:
type: string
description: The request ID of the request that paused the workflow execution.
description: Attributes for an event marking that a workflow execution was paused.
WorkflowExecutionSignaledEventAttributes:
type: object
properties:
Expand Down Expand Up @@ -14538,6 +14725,19 @@ components:
newExecutionRunId:
type: string
description: If another run is started by cron or retry, this contains the new run id.
WorkflowExecutionUnpausedEventAttributes:
type: object
properties:
identity:
type: string
description: The identity of the client who unpaused the workflow execution.
reason:
type: string
description: The reason for unpausing the workflow execution.
requestId:
type: string
description: The request ID of the request that unpaused the workflow execution.
description: Attributes for an event marking that a workflow execution was unpaused.
WorkflowExecutionUpdateAcceptedEventAttributes:
type: object
properties:
Expand Down Expand Up @@ -15043,7 +15243,9 @@ components:
description: The failure details
identity:
type: string
description: "If a worker explicitly failed this task, this field contains the worker's identity. \n When the server generates the failure internally this field is set as 'history-service'."
description: |-
If a worker explicitly failed this task, this field contains the worker's identity.
When the server generates the failure internally this field is set as 'history-service'.
baseRunId:
type: string
description: The original run id of the workflow. For reset workflow.
Expand Down
4 changes: 4 additions & 0 deletions temporal/api/enums/v1/event_type.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,4 +169,8 @@ enum EventType {
EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_COMPLETED = 56;
// A cancellation request for a Nexus operation resulted in an error.
EVENT_TYPE_NEXUS_OPERATION_CANCEL_REQUEST_FAILED = 57;
// An event that indicates that the workflow execution has been paused.
EVENT_TYPE_WORKFLOW_EXECUTION_PAUSED = 58;
// An event that indicates that the previously paused workflow execution has been unpaused.
EVENT_TYPE_WORKFLOW_EXECUTION_UNPAUSED = 59;
}
1 change: 1 addition & 0 deletions temporal/api/enums/v1/workflow.proto
View file
Open in desktop
Copy link
Member

@cretz cretz Nov 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@gow - don't you have to update WorkflowIdConflictPolicy comment to no longer talk about "running" but instead "running and not paused" or "open" or something? And StartWorkflowExecutionRequest.workflow_id_conflict_policy and so on?

Also, you may want to create a side issue to come back and update any API docs (and ask docs team to update all docs and ask SDK team to update all SDKs and maybe UI) to update anything that is now affected by our backwards-incompatible reclassification of what running means (went from non-closed to non-closed-non-paused).

Copy link
Contributor Author

@gow gow Nov 18, 2025

Choose a reason for hiding this comment

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

Yes. I'll create tasks to track the documentation changes.

Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@ enum WorkflowExecutionStatus {
WORKFLOW_EXECUTION_STATUS_TERMINATED = 5;
WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW = 6;
WORKFLOW_EXECUTION_STATUS_TIMED_OUT = 7;
WORKFLOW_EXECUTION_STATUS_PAUSED = 8;
Copy link
Member

@bergundy bergundy Oct 30, 2025

Choose a reason for hiding this comment

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

Verifying that we have consensus for adding this new status... this is fine with me FTR.

Copy link
Member

@cretz cretz Oct 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I think I am the only holdout. I still think it breaks Temporal expectation that a workflow is either running or closed, and that running has nothing to do with whether tasks are being processed (or signals or activities or timers). Having said that, I think unfortunately people are wanting to break these expectations.

I also think it's confusing to assume the entire workflow is in a paused status just because some things are paused. When a user asks us to support, say, pausing only signals/updates, it's gonna look real strange that we chose to treat pause as a status instead of what it truly is - a collection of paused aspects.

Copy link
Contributor Author

@gow gow Oct 31, 2025

Choose a reason for hiding this comment

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

We had the consensus in the internal discussion about this. The reasoning was that pausing a workflow would set an expectation that the workflow status to change to PAUSED. Otherwise "workflow pause" operation appears broken.
If (and when) we support pausing of individual aspects we would have individual status for them to make it clear that only certain aspects are paused.

Copy link
Member

@cretz cretz Oct 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

We had the consensus in the internal discussion about this

👍

The reasoning was that pausing a workflow would set an expectation that the workflow status to change to PAUSED

I don't think this is true that it would set this expectation any more than "cancel" would set an expectation of a workflow status changing to "cancel requested". Basically, there is no such thing as pausing a workflow, just pausing certain parts. I want to warn about user confusion by marking what Temporal deems to be a started/running workflow as not running.

If (and when) we support pausing of individual aspects we would have individual status for them to make it clear that only certain aspects are paused.

To clarify here, you mean the workflow status would remain running if we only paused signals, updates, etc? Or we would set it to paused even if some of it is paused? That's what we're doing with this change, e.g. the timers are not paused, but we are acting as if the whole workflow is paused when it is not.

Copy link
Contributor Author

@gow gow Nov 3, 2025

Choose a reason for hiding this comment

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

I'm actually not completely sure. It depends on how we support these.
If pausing these individual aspects is a top level operation then it would have a separate status (like activity pause). If it is an option to workflow pause then the workflow status would be changed.
I'm also not sure if we will support pausing just the individual aspects without pausing the workflow tasks.

Copy link
Member

@cretz cretz Nov 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I'm also not sure if we will support pausing just the individual aspects without pausing the workflow tasks.

Note, you are making a permanent "can't take back" change here for something you may not be sure about in successive phases. But if we are defining status "paused" as "workflow tasks are paused" and not some general definition of "pause", ok (even if I do disagree with the premise).

Copy link
Contributor Author

@gow gow Nov 14, 2025

Choose a reason for hiding this comment

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

Yes. In all cases when a workflow status is set to paused, workflow tasks would remain paused. Other aspects are TBD. So, "paused" status is consistent with workflow task pause.

Copy link
Member

@cretz cretz Nov 14, 2025

Choose a reason for hiding this comment

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

I'm not necessarily convinced that will always be the case (e.g. user wanting to pause interactions like update but still process activity completions), but if we think so, ok.

}

enum PendingActivityState {
Expand Down
24 changes: 23 additions & 1 deletion temporal/api/history/v1/message.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,7 @@ message WorkflowTaskFailedEventAttributes {
temporal.api.enums.v1.WorkflowTaskFailedCause cause = 3;
// The failure details
temporal.api.failure.v1.Failure failure = 4;
// If a worker explicitly failed this task, this field contains the worker's identity.
// If a worker explicitly failed this task, this field contains the worker's identity.
// When the server generates the failure internally this field is set as 'history-service'.
string identity = 5;
// The original run id of the workflow. For reset workflow.
Expand Down Expand Up @@ -885,6 +885,26 @@ message WorkflowExecutionUpdateAdmittedEventAttributes {
temporal.api.enums.v1.UpdateAdmittedEventOrigin origin = 2;
}

// Attributes for an event marking that a workflow execution was paused.
message WorkflowExecutionPausedEventAttributes {
// The identity of the client who paused the workflow execution.
string identity = 1;
// The reason for pausing the workflow execution.
string reason = 2;
// The request ID of the request that paused the workflow execution.
string request_id = 3;
}

// Attributes for an event marking that a workflow execution was unpaused.
message WorkflowExecutionUnpausedEventAttributes {
Comment on lines +889 to +899
Copy link
Member

@cretz cretz Oct 22, 2025

Choose a reason for hiding this comment

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

I think you forgot to add these to the actual oneof below

Copy link
Contributor Author

@gow gow Oct 23, 2025

Choose a reason for hiding this comment

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

Yes. I had forgotten them. Added now.

Copy link
Member

@cretz cretz Oct 24, 2025

Choose a reason for hiding this comment

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

I think we might want to wait to merge this until the implementation is present so we can confirm these types of things work with the code

Copy link
Contributor Author

@gow gow Oct 24, 2025

Choose a reason for hiding this comment

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

Yes. I will not merge until the corresponding server PR using this is not ready.

// The identity of the client who unpaused the workflow execution.
string identity = 1;
// The reason for unpausing the workflow execution.
string reason = 2;
// The request ID of the request that unpaused the workflow execution.
string request_id = 3;
}

// Event marking that an operation was scheduled by a workflow via the ScheduleNexusOperation command.
message NexusOperationScheduledEventAttributes {
// Endpoint name, must exist in the endpoint registry.
Expand Down Expand Up @@ -1103,6 +1123,8 @@ message HistoryEvent {
WorkflowExecutionOptionsUpdatedEventAttributes workflow_execution_options_updated_event_attributes = 60;
NexusOperationCancelRequestCompletedEventAttributes nexus_operation_cancel_request_completed_event_attributes = 61;
NexusOperationCancelRequestFailedEventAttributes nexus_operation_cancel_request_failed_event_attributes = 62;
WorkflowExecutionPausedEventAttributes workflow_execution_paused_event_attributes = 63;
WorkflowExecutionUnpausedEventAttributes workflow_execution_unpaused_event_attributes = 64;
}
}

Expand Down
Loading
Loading