diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index 12d163654..73d98ffc7 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -4134,6 +4134,51 @@ ] } }, + "/api/v1/namespaces/{namespace}/workflows/{execution.workflowId}/result": { + "post": { + "summary": "GetWorkflowExecutionResult returns the state of a workflow execution, which may be still running,\ncompleted, or failed. It can optionally register new callbacks to be invoked when Workflow reaches\na terminal state.\nIf the workflow is completed, it returns the result of the completed workflow.\nNOTE: This has to be a POST since we're optionally attaching callbacks to the running workflow, which mutates it.", + "operationId": "GetWorkflowExecutionResult2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetWorkflowExecutionResultResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "execution.workflowId", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceGetWorkflowExecutionResultBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/api/v1/namespaces/{namespace}/workflows/{execution.workflowId}/trigger-rule": { "post": { "summary": "TriggerWorkflowRule allows to:\n * trigger existing rule for a specific workflow execution;\n * trigger rule for a specific workflow execution without creating a rule;\nThis is useful for one-off operations.", @@ -9609,6 +9654,51 @@ ] } }, + "/namespaces/{namespace}/workflows/{execution.workflowId}/result": { + "post": { + "summary": "GetWorkflowExecutionResult returns the state of a workflow execution, which may be still running,\ncompleted, or failed. It can optionally register new callbacks to be invoked when Workflow reaches\na terminal state.\nIf the workflow is completed, it returns the result of the completed workflow.\nNOTE: This has to be a POST since we're optionally attaching callbacks to the running workflow, which mutates it.", + "operationId": "GetWorkflowExecutionResult", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetWorkflowExecutionResultResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "execution.workflowId", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceGetWorkflowExecutionResultBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/namespaces/{namespace}/workflows/{execution.workflowId}/trigger-rule": { "post": { "summary": "TriggerWorkflowRule allows to:\n * trigger existing rule for a specific workflow execution;\n * trigger rule for a specific workflow execution without creating a rule;\nThis is useful for one-off operations.", @@ -10706,6 +10796,25 @@ }, "description": "Target a worker polling on a Nexus task queue in a specific namespace." }, + "GetWorkflowExecutionResultResponseFailed": { + "type": "object", + "properties": { + "failure": { + "$ref": "#/definitions/v1Failure" + } + } + }, + "GetWorkflowExecutionResultResponseRunning": { + "type": "object" + }, + "GetWorkflowExecutionResultResponseSuccess": { + "type": "object", + "properties": { + "result": { + "$ref": "#/definitions/v1Payloads" + } + } + }, "LinkActivity": { "type": "object", "properties": { @@ -11212,6 +11321,44 @@ } } }, + "WorkflowServiceGetWorkflowExecutionResultBody": { + "type": "object", + "properties": { + "execution": { + "type": "object", + "properties": { + "runId": { + "type": "string" + } + }, + "description": "For now, server will always provide the result of the latest run of the workflow_id\nprovided even if the run_id is set here. We use WorkflowExecution message for forward\ncompatibility if we want to enable getting the result of a specific run_id in the future." + }, + "requestId": { + "type": "string", + "description": "A unique identifier for this request for idempotence. Typically UUIDv4." + }, + "identity": { + "type": "string", + "description": "The identity of the client who initiated this request." + }, + "completionCallbacks": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Callback" + }, + "description": "Callbacks to be called by the server when this worflow reaches a terminal state,\nin the case when we're getting the result of a running workflow.\nCallback addresses must be allowlisted in the server's dynamic configuration." + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/apiCommonV1Link" + }, + "description": "Links to be associated with this request. Note that completion_callbacks may also have\nassociated links; links already included with a callback should not be duplicated here." + } + } + }, "WorkflowServicePatchScheduleBody": { "type": "object", "properties": { @@ -15655,6 +15802,32 @@ } } }, + "v1GetWorkflowExecutionResultResponse": { + "type": "object", + "properties": { + "execution": { + "$ref": "#/definitions/v1WorkflowExecution", + "description": "Information about the workflow execution, including the runID that this result is associated to." + }, + "links": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Link" + }, + "title": "Link to the relevant history event:\n- completion event, if the workflow has finished\n- options-updated event, if callbacks were registered on a running workflow" + }, + "running": { + "$ref": "#/definitions/GetWorkflowExecutionResultResponseRunning" + }, + "success": { + "$ref": "#/definitions/GetWorkflowExecutionResultResponseSuccess" + }, + "failed": { + "$ref": "#/definitions/GetWorkflowExecutionResultResponseFailed" + } + } + }, "v1Header": { "type": "object", "properties": { diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 14a6a130c..9edcbd240 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -3714,6 +3714,47 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/workflows/{execution.workflow_id}/result: + post: + tags: + - WorkflowService + description: |- + GetWorkflowExecutionResult returns the state of a workflow execution, which may be still running, + completed, or failed. It can optionally register new callbacks to be invoked when Workflow reaches + a terminal state. + If the workflow is completed, it returns the result of the completed workflow. + NOTE: This has to be a POST since we're optionally attaching callbacks to the running workflow, which mutates it. + operationId: GetWorkflowExecutionResult + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.workflow_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetWorkflowExecutionResultRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetWorkflowExecutionResultResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/workflows/{execution.workflow_id}/trigger-rule: post: tags: @@ -8659,6 +8700,47 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/workflows/{execution.workflow_id}/result: + post: + tags: + - WorkflowService + description: |- + GetWorkflowExecutionResult returns the state of a workflow execution, which may be still running, + completed, or failed. It can optionally register new callbacks to be invoked when Workflow reaches + a terminal state. + If the workflow is completed, it returns the result of the completed workflow. + NOTE: This has to be a POST since we're optionally attaching callbacks to the running workflow, which mutates it. + operationId: GetWorkflowExecutionResult + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: execution.workflow_id + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetWorkflowExecutionResultRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetWorkflowExecutionResultResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/workflows/{execution.workflow_id}/trigger-rule: post: tags: @@ -12149,6 +12231,73 @@ components: type: string description: Will be set if there are more history events than were included in this response format: bytes + GetWorkflowExecutionResultRequest: + type: object + properties: + namespace: + type: string + execution: + allOf: + - $ref: '#/components/schemas/WorkflowExecution' + description: |- + For now, server will always provide the result of the latest run of the workflow_id + provided even if the run_id is set here. We use WorkflowExecution message for forward + compatibility if we want to enable getting the result of a specific run_id in the future. + requestId: + type: string + description: A unique identifier for this request for idempotence. Typically UUIDv4. + identity: + type: string + description: The identity of the client who initiated this request. + completionCallbacks: + type: array + items: + $ref: '#/components/schemas/Callback' + description: |- + Callbacks to be called by the server when this worflow reaches a terminal state, + in the case when we're getting the result of a running workflow. + Callback addresses must be allowlisted in the server's dynamic configuration. + links: + type: array + items: + $ref: '#/components/schemas/Link' + description: |- + Links to be associated with this request. Note that completion_callbacks may also have + associated links; links already included with a callback should not be duplicated here. + GetWorkflowExecutionResultResponse: + type: object + properties: + execution: + allOf: + - $ref: '#/components/schemas/WorkflowExecution' + description: Information about the workflow execution, including the runID that this result is associated to. + links: + type: array + items: + $ref: '#/components/schemas/Link' + description: |- + Link to the relevant history event: + - completion event, if the workflow has finished + - options-updated event, if callbacks were registered on a running workflow + running: + $ref: '#/components/schemas/GetWorkflowExecutionResultResponse_Running' + success: + $ref: '#/components/schemas/GetWorkflowExecutionResultResponse_Success' + failed: + $ref: '#/components/schemas/GetWorkflowExecutionResultResponse_Failed' + GetWorkflowExecutionResultResponse_Failed: + type: object + properties: + failure: + $ref: '#/components/schemas/Failure' + GetWorkflowExecutionResultResponse_Running: + type: object + properties: {} + GetWorkflowExecutionResultResponse_Success: + type: object + properties: + result: + $ref: '#/components/schemas/Payloads' GoogleProtobufAny: type: object properties: diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index f4012c73d..8f6707aff 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -1163,6 +1163,52 @@ message DescribeWorkflowExecutionResponse { temporal.api.workflow.v1.WorkflowExecutionExtendedInfo workflow_extended_info = 8; } +message GetWorkflowExecutionResultRequest { + string namespace = 1; + // For now, server will always provide the result of the latest run of the workflow_id + // provided even if the run_id is set here. We use WorkflowExecution message for forward + // compatibility if we want to enable getting the result of a specific run_id in the future. + temporal.api.common.v1.WorkflowExecution execution = 2; + // A unique identifier for this request for idempotence. Typically UUIDv4. + string request_id = 3; + // The identity of the client who initiated this request. + string identity = 4; + // Callbacks to be called by the server when this worflow reaches a terminal state, + // in the case when we're getting the result of a running workflow. + // Callback addresses must be allowlisted in the server's dynamic configuration. + repeated temporal.api.common.v1.Callback completion_callbacks = 5; + // Links to be associated with this request. Note that completion_callbacks may also have + // associated links; links already included with a callback should not be duplicated here. + repeated temporal.api.common.v1.Link links = 6; +} + +message GetWorkflowExecutionResultResponse { + // Information about the workflow execution, including the runID that this result is associated to. + temporal.api.common.v1.WorkflowExecution execution = 1; + + // Link to the relevant history event: + // - completion event, if the workflow has finished + // - options-updated event, if callbacks were registered on a running workflow + repeated temporal.api.common.v1.Link links = 2; + + // Completion status of the workflow, which carries relevant information for the caller. + oneof completion_status { + Running running = 3; + Success success = 4; + Failed failed = 5; + } + + message Running {} + + message Success { + temporal.api.common.v1.Payloads result = 1; + } + + message Failed { + temporal.api.failure.v1.Failure failure = 1; + } +} + // (-- api-linter: core::0203::optional=disabled // aip.dev/not-precedent: field_behavior annotation not available in our gogo fork --) message DescribeTaskQueueRequest { diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 49be10dfb..4649c3ec3 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -2026,4 +2026,24 @@ service WorkflowService { // (-- api-linter: core::0127::http-annotation=disabled // aip.dev/not-precedent: Nexus operation deletion not exposed to HTTP, users should use cancel or terminate. --) rpc DeleteNexusOperationExecution (DeleteNexusOperationExecutionRequest) returns (DeleteNexusOperationExecutionResponse) {} + + // GetWorkflowExecutionResult returns the state of a workflow execution, which may be still running, + // completed, or failed. It can optionally register new callbacks to be invoked when Workflow reaches + // a terminal state. + // If the workflow is completed, it returns the result of the completed workflow. + // NOTE: This has to be a POST since we're optionally attaching callbacks to the running workflow, which mutates it. + rpc GetWorkflowExecutionResult (GetWorkflowExecutionResultRequest) returns (GetWorkflowExecutionResultResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/workflows/{execution.workflow_id}/result" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/workflows/{execution.workflow_id}/result" + body: "*" + } + }; + option (temporal.api.protometa.v1.request_header) = { + header: "temporal-resource-id" + value: "workflow:{execution.workflow_id}" + }; + } }