diff --git a/openapi/openapiv2.json b/openapi/openapiv2.json index c0d6b230c..d0a13c3b3 100644 --- a/openapi/openapiv2.json +++ b/openapi/openapiv2.json @@ -157,6 +157,60 @@ ] } }, + "/api/v1/namespaces/{namespace}/activities": { + "get": { + "summary": "ListActivityExecutions is a visibility API to list activity executions in a specific namespace.", + "operationId": "ListActivityExecutions2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListActivityExecutionsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "pageSize", + "description": "Max number of executions to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token returned in ListActivityExecutionsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, "/api/v1/namespaces/{namespace}/activities/cancel": { "post": { "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", @@ -199,7 +253,7 @@ }, "/api/v1/namespaces/{namespace}/activities/cancel-by-id": { "post": { - "summary": "See `RecordActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "summary": "See `RespondActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", "operationId": "RespondActivityTaskCanceledById2", "responses": { "200": { @@ -279,7 +333,7 @@ }, "/api/v1/namespaces/{namespace}/activities/complete-by-id": { "post": { - "summary": "See `RecordActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", + "summary": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", "operationId": "RespondActivityTaskCompletedById2", "responses": { "200": { @@ -480,7 +534,7 @@ "/api/v1/namespaces/{namespace}/activities/pause": { "post": { "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", - "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", + "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and\nstructured to work well for standalone activities.", "operationId": "PauseActivity2", "responses": { "200": { @@ -521,7 +575,7 @@ "/api/v1/namespaces/{namespace}/activities/reset": { "post": { "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", - "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.", + "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.\nThis API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and\nstructured to work well for standalone activities.", "operationId": "ResetActivity2", "responses": { "200": { @@ -562,7 +616,7 @@ "/api/v1/namespaces/{namespace}/activities/unpause": { "post": { "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", - "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", + "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and\nstructured to work well for standalone activities.", "operationId": "UnpauseActivity2", "responses": { "200": { @@ -602,7 +656,7 @@ }, "/api/v1/namespaces/{namespace}/activities/update-options": { "post": { - "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.", + "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.\nThis API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and\nstructured to work well for standalone activities.", "operationId": "UpdateActivityOptions2", "responses": { "200": { @@ -640,15 +694,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/archived-workflows": { + "/api/v1/namespaces/{namespace}/activities/{activityId}": { "get": { - "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", - "operationId": "ListArchivedWorkflowExecutions2", + "summary": "DescribeActivityExecution returns information about an activity execution.\nSupported use cases include:\n- Get current activity info without waiting\n- Long-poll for next state change and return new activity info\nResponse can optionally include activity input or outcome (if the activity has completed).", + "operationId": "DescribeActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" + "$ref": "#/definitions/v1DescribeActivityExecutionResponse" } }, "default": { @@ -666,68 +720,35 @@ "type": "string" }, { - "name": "pageSize", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" + "name": "activityId", + "in": "path", + "required": true, + "type": "string" }, { - "name": "nextPageToken", + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", "in": "query", "required": false, - "type": "string", - "format": "byte" + "type": "string" }, { - "name": "query", + "name": "includeInput", + "description": "Include the input field in the response.", "in": "query", "required": false, - "type": "string" - } - ], - "tags": [ - "WorkflowService" - ] - } - }, - "/api/v1/namespaces/{namespace}/batch-operations": { - "get": { - "summary": "ListBatchOperations returns a list of batch operations", - "operationId": "ListBatchOperations2", - "responses": { - "200": { - "description": "A successful response.", - "schema": { - "$ref": "#/definitions/v1ListBatchOperationsResponse" - } - }, - "default": { - "description": "An unexpected error response.", - "schema": { - "$ref": "#/definitions/rpcStatus" - } - } - }, - "parameters": [ - { - "name": "namespace", - "description": "Namespace that contains the batch operation", - "in": "path", - "required": true, - "type": "string" + "type": "boolean" }, { - "name": "pageSize", - "description": "List page size", + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the activity has completed.", "in": "query", "required": false, - "type": "integer", - "format": "int32" + "type": "boolean" }, { - "name": "nextPageToken", - "description": "Next page token", + "name": "longPollToken", + "description": "Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that activity state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", "in": "query", "required": false, "type": "string", @@ -737,17 +758,16 @@ "tags": [ "WorkflowService" ] - } - }, - "/api/v1/namespaces/{namespace}/batch-operations/{jobId}": { - "get": { - "summary": "DescribeBatchOperation returns the information about a batch operation", - "operationId": "DescribeBatchOperation2", + }, + "post": { + "summary": "StartActivityExecution starts a new activity execution.", + "description": "Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace\nunless permitted by the specified ID conflict policy.", + "operationId": "StartActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeBatchOperationResponse" + "$ref": "#/definitions/v1StartActivityExecutionResponse" } }, "default": { @@ -760,31 +780,40 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "activityId", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartActivityExecutionBody" + } } ], "tags": [ "WorkflowService" ] - }, + } + }, + "/api/v1/namespaces/{namespace}/activities/{activityId}/cancel": { "post": { - "summary": "StartBatchOperation starts a new batch operation", - "operationId": "StartBatchOperation2", + "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", + "description": "Requesting to cancel an activity does not automatically transition the activity to canceled status. If the\nactivity has a currently running attempt, the activity will only transition to canceled status if the current\nattempt is unsuccessful.\nTODO: Clarify what happens if there are no more allowed retries after the current attempt.\n\nIt returns success if the requested activity is already closed.\nTODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior?", + "operationId": "RequestCancelActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartBatchOperationResponse" + "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" } }, "default": { @@ -797,14 +826,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Job ID defines the unique ID for the batch job", + "name": "activityId", "in": "path", "required": true, "type": "string" @@ -814,7 +841,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" } } ], @@ -823,15 +850,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/batch-operations/{jobId}/stop": { - "post": { - "summary": "StopBatchOperation stops a batch operation", - "operationId": "StopBatchOperation2", + "/api/v1/namespaces/{namespace}/activities/{activityId}/outcome": { + "get": { + "summary": "GetActivityExecutionOutcome long-polls for an activity execution to complete and returns\nthe outcome (result or failure).", + "operationId": "GetActivityExecutionOutcome2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StopBatchOperationResponse" + "$ref": "#/definitions/v1GetActivityExecutionOutcomeResponse" } }, "default": { @@ -844,25 +871,22 @@ "parameters": [ { "name": "namespace", - "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "jobId", - "description": "Batch job id", + "name": "activityId", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" - } + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -870,15 +894,16 @@ ] } }, - "/api/v1/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { + "/api/v1/namespaces/{namespace}/activities/{activityId}/terminate": { "post": { - "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `SetWorkerDeploymentCurrentVersion`.", - "operationId": "SetCurrentDeployment2", + "summary": "TerminateActivityExecution terminates an existing activity execution immediately.", + "description": "Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a\nrunning attempt and will be requested to be canceled by the server when it heartbeats.", + "operationId": "TerminateActivityExecution2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SetCurrentDeploymentResponse" + "$ref": "#/definitions/v1TerminateActivityExecutionResponse" } }, "default": { @@ -896,8 +921,7 @@ "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", + "name": "activityId", "in": "path", "required": true, "type": "string" @@ -907,7 +931,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" + "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" } } ], @@ -916,15 +940,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/current-deployment/{seriesName}": { + "/api/v1/namespaces/{namespace}/activity-count": { "get": { - "summary": "Returns the current deployment (and its info) for a given deployment series.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `current_version` returned by `DescribeWorkerDeployment`.", - "operationId": "GetCurrentDeployment2", + "summary": "CountActivityExecutions is a visibility API to count of activity executions in a specific namespace.", + "operationId": "CountActivityExecutions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetCurrentDeploymentResponse" + "$ref": "#/definitions/v1CountActivityExecutionsResponse" } }, "default": { @@ -942,9 +966,10 @@ "type": "string" }, { - "name": "seriesName", - "in": "path", - "required": true, + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, "type": "string" } ], @@ -953,15 +978,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/deployments": { + "/api/v1/namespaces/{namespace}/archived-workflows": { "get": { - "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `ListWorkerDeployments`.", - "operationId": "ListDeployments2", + "summary": "ListArchivedWorkflowExecutions is a visibility API to list archived workflow executions in a specific namespace.", + "operationId": "ListArchivedWorkflowExecutions2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListDeploymentsResponse" + "$ref": "#/definitions/v1ListArchivedWorkflowExecutionsResponse" } }, "default": { @@ -993,8 +1018,7 @@ "format": "byte" }, { - "name": "seriesName", - "description": "Optional. Use to filter based on exact series name match.", + "name": "query", "in": "query", "required": false, "type": "string" @@ -1005,15 +1029,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { + "/api/v1/namespaces/{namespace}/batch-operations": { "get": { - "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DescribeWorkerDeploymentVersion`.", - "operationId": "DescribeDeployment2", + "summary": "ListBatchOperations returns a list of batch operations", + "operationId": "ListBatchOperations2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeDeploymentResponse" + "$ref": "#/definitions/v1ListBatchOperationsResponse" } }, "default": { @@ -1026,23 +1050,26 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", - "in": "path", - "required": true, - "type": "string" + "name": "pageSize", + "description": "List page size", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" }, { - "name": "deployment.buildId", - "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", - "in": "path", - "required": true, - "type": "string" + "name": "nextPageToken", + "description": "Next page token", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ @@ -1050,15 +1077,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}/reachability": { + "/api/v1/namespaces/{namespace}/batch-operations/{jobId}": { "get": { - "summary": "Returns the reachability level of a worker deployment to help users decide when it is time\nto decommission a deployment. Reachability level is calculated based on the deployment's\n`status` and existing workflows that depend on the given deployment for their execution.\nCalculating reachability is relatively expensive. Therefore, server might return a recently\ncached value. In such a case, the `last_update_time` will inform you about the actual\nreachability calculation time.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DrainageInfo` returned by `DescribeWorkerDeploymentVersion`.", - "operationId": "GetDeploymentReachability2", + "summary": "DescribeBatchOperation returns the information about a batch operation", + "operationId": "DescribeBatchOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" + "$ref": "#/definitions/v1DescribeBatchOperationResponse" } }, "default": { @@ -1071,20 +1098,14 @@ "parameters": [ { "name": "namespace", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "deployment.seriesName", - "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "deployment.buildId", - "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "name": "jobId", + "description": "Batch job id", "in": "path", "required": true, "type": "string" @@ -1093,17 +1114,15 @@ "tags": [ "WorkflowService" ] - } - }, - "/api/v1/namespaces/{namespace}/schedules": { - "get": { - "summary": "List all schedules in a namespace.", - "operationId": "ListSchedules2", + }, + "post": { + "summary": "StartBatchOperation starts a new batch operation", + "operationId": "StartBatchOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSchedulesResponse" + "$ref": "#/definitions/v1StartBatchOperationResponse" } }, "default": { @@ -1116,33 +1135,25 @@ "parameters": [ { "name": "namespace", - "description": "The namespace to list schedules in.", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "maximumPageSize", - "description": "How many to return at once.", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" + "name": "jobId", + "description": "Job ID defines the unique ID for the batch job", + "in": "path", + "required": true, + "type": "string" }, { - "name": "nextPageToken", - "description": "Token to get the next page of results.", - "in": "query", - "required": false, - "type": "string", - "format": "byte" - }, - { - "name": "query", - "description": "Query to filter schedules.", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartBatchOperationBody" + } } ], "tags": [ @@ -1150,15 +1161,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}": { - "get": { - "summary": "Returns the schedule description and current state of an existing schedule.", - "operationId": "DescribeSchedule2", + "/api/v1/namespaces/{namespace}/batch-operations/{jobId}/stop": { + "post": { + "summary": "StopBatchOperation stops a batch operation", + "operationId": "StopBatchOperation2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeScheduleResponse" + "$ref": "#/definitions/v1StopBatchOperationResponse" } }, "default": { @@ -1171,31 +1182,41 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to describe.", + "description": "Namespace that contains the batch operation", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to describe.", + "name": "jobId", + "description": "Batch job id", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStopBatchOperationBody" + } } ], "tags": [ "WorkflowService" ] - }, - "delete": { - "summary": "Deletes a schedule, removing it from the system.", - "operationId": "DeleteSchedule2", + } + }, + "/api/v1/namespaces/{namespace}/current-deployment/{deployment.seriesName}": { + "post": { + "summary": "Sets a deployment as the current deployment for its deployment series. Can optionally update\nthe metadata of the deployment as well.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `SetWorkerDeploymentCurrentVersion`.", + "operationId": "SetCurrentDeployment2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteScheduleResponse" + "$ref": "#/definitions/v1SetCurrentDeploymentResponse" } }, "default": { @@ -1208,38 +1229,40 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to delete.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to delete.", + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", "in": "path", "required": true, "type": "string" }, { - "name": "identity", - "description": "The identity of the client who initiated this request.", - "in": "query", - "required": false, - "type": "string" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSetCurrentDeploymentBody" + } } ], "tags": [ "WorkflowService" ] - }, - "post": { - "summary": "Creates a new schedule.", - "operationId": "CreateSchedule2", + } + }, + "/api/v1/namespaces/{namespace}/current-deployment/{seriesName}": { + "get": { + "summary": "Returns the current deployment (and its info) for a given deployment series.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced by `current_version` returned by `DescribeWorkerDeployment`.", + "operationId": "GetCurrentDeployment2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CreateScheduleResponse" + "$ref": "#/definitions/v1GetCurrentDeploymentResponse" } }, "default": { @@ -1252,25 +1275,15 @@ "parameters": [ { "name": "namespace", - "description": "The namespace the schedule should be created in.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the new schedule.", + "name": "seriesName", "in": "path", "required": true, "type": "string" - }, - { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceCreateScheduleBody" - } } ], "tags": [ @@ -1278,15 +1291,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/matching-times": { + "/api/v1/namespaces/{namespace}/deployments": { "get": { - "summary": "Lists matching times within a range.", - "operationId": "ListScheduleMatchingTimes2", + "summary": "Lists worker deployments in the namespace. Optionally can filter based on deployment series\nname.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `ListWorkerDeployments`.", + "operationId": "ListDeployments2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListScheduleMatchingTimesResponse" + "$ref": "#/definitions/v1ListDeploymentsResponse" } }, "default": { @@ -1299,32 +1312,30 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to query.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to query.", - "in": "path", - "required": true, - "type": "string" + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" }, { - "name": "startTime", - "description": "Time range to query.", + "name": "nextPageToken", "in": "query", "required": false, "type": "string", - "format": "date-time" + "format": "byte" }, { - "name": "endTime", + "name": "seriesName", + "description": "Optional. Use to filter based on exact series name match.", "in": "query", "required": false, - "type": "string", - "format": "date-time" + "type": "string" } ], "tags": [ @@ -1332,15 +1343,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/patch": { - "post": { - "summary": "Makes a specific change to a schedule or triggers an immediate action.", - "operationId": "PatchSchedule2", + "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}": { + "get": { + "summary": "Describes a worker deployment.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DescribeWorkerDeploymentVersion`.", + "operationId": "DescribeDeployment2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PatchScheduleResponse" + "$ref": "#/definitions/v1DescribeDeploymentResponse" } }, "default": { @@ -1353,25 +1364,23 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to patch.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to patch.", + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServicePatchScheduleBody" - } + "type": "string" } ], "tags": [ @@ -1379,15 +1388,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/update": { - "post": { - "summary": "Changes the configuration or state of an existing schedule.", - "operationId": "UpdateSchedule2", + "/api/v1/namespaces/{namespace}/deployments/{deployment.seriesName}/{deployment.buildId}/reachability": { + "get": { + "summary": "Returns the reachability level of a worker deployment to help users decide when it is time\nto decommission a deployment. Reachability level is calculated based on the deployment's\n`status` and existing workflows that depend on the given deployment for their execution.\nCalculating reachability is relatively expensive. Therefore, server might return a recently\ncached value. In such a case, the `last_update_time` will inform you about the actual\nreachability calculation time.\nExperimental. This API might significantly change or be removed in a future release.\nDeprecated. Replaced with `DrainageInfo` returned by `DescribeWorkerDeploymentVersion`.", + "operationId": "GetDeploymentReachability2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateScheduleResponse" + "$ref": "#/definitions/v1GetDeploymentReachabilityResponse" } }, "default": { @@ -1400,25 +1409,23 @@ "parameters": [ { "name": "namespace", - "description": "The namespace of the schedule to update.", "in": "path", "required": true, "type": "string" }, { - "name": "scheduleId", - "description": "The id of the schedule to update.", + "name": "deployment.seriesName", + "description": "Different versions of the same worker service/application are related together by having a\nshared series name.\nOut of all deployments of a series, one can be designated as the current deployment, which\nreceives new workflow executions and new tasks of workflows with\n`VERSIONING_BEHAVIOR_AUTO_UPGRADE` versioning behavior.", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "deployment.buildId", + "description": "Build ID changes with each version of the worker when the worker program code and/or config\nchanges.", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateScheduleBody" - } + "type": "string" } ], "tags": [ @@ -1426,15 +1433,15 @@ ] } }, - "/api/v1/namespaces/{namespace}/search-attributes": { + "/api/v1/namespaces/{namespace}/schedules": { "get": { - "summary": "ListSearchAttributes returns comprehensive information about search attributes.", - "operationId": "ListSearchAttributes2", + "summary": "List all schedules in a namespace.", + "operationId": "ListSchedules2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSearchAttributesResponse" + "$ref": "#/definitions/v1ListSchedulesResponse" } }, "default": { @@ -1447,25 +1454,49 @@ "parameters": [ { "name": "namespace", + "description": "The namespace to list schedules in.", "in": "path", "required": true, "type": "string" + }, + { + "name": "maximumPageSize", + "description": "How many to return at once.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token to get the next page of results.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Query to filter schedules.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/api/v1/namespaces/{namespace}/task-queues/{taskQueue.name}": { + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}": { "get": { - "summary": "DescribeTaskQueue returns the following information about the target task queue, broken down by Build ID:\n - List of pollers\n - Workflow Reachability status\n - Backlog info for Workflow and/or Activity tasks", - "operationId": "DescribeTaskQueue2", + "summary": "Returns the schedule description and current state of an existing schedule.", + "operationId": "DescribeSchedule2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeTaskQueueResponse" + "$ref": "#/definitions/v1DescribeScheduleResponse" } }, "default": { @@ -1478,31 +1509,338 @@ "parameters": [ { "name": "namespace", + "description": "The namespace of the schedule to describe.", "in": "path", "required": true, "type": "string" }, { - "name": "taskQueue.name", + "name": "scheduleId", + "description": "The id of the schedule to describe.", "in": "path", "required": true, "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "delete": { + "summary": "Deletes a schedule, removing it from the system.", + "operationId": "DeleteSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DeleteScheduleResponse" + } }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ { - "name": "taskQueue.kind", - "description": "Default: TASK_QUEUE_KIND_NORMAL.\n\n - TASK_QUEUE_KIND_UNSPECIFIED: Tasks from any non workflow task may be unspecified.\n\nTask queue kind is used to differentiate whether a workflow task queue is sticky or \nnormal. If a task is not a workflow task, Task queue kind will sometimes be \nunspecified.\n - TASK_QUEUE_KIND_NORMAL: Tasks from a normal workflow task queue always include complete workflow history\n\nThe task queue specified by the user is always a normal task queue. There can be as many\nworkers as desired for a single normal task queue. All those workers may pick up tasks from\nthat queue.\n - TASK_QUEUE_KIND_STICKY: A sticky queue only includes new history since the last workflow task, and they are\nper-worker.\n\nSticky queues are created dynamically by each worker during their start up. They only exist\nfor the lifetime of the worker process. Tasks in a sticky task queue are only available to\nthe worker that created the sticky queue.\n\nSticky queues are only for workflow tasks. There are no sticky task queues for activities.", - "in": "query", - "required": false, - "type": "string", - "enum": [ - "TASK_QUEUE_KIND_UNSPECIFIED", - "TASK_QUEUE_KIND_NORMAL", - "TASK_QUEUE_KIND_STICKY" - ], - "default": "TASK_QUEUE_KIND_UNSPECIFIED" - }, - { - "name": "taskQueue.normalName", + "name": "namespace", + "description": "The namespace of the schedule to delete.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to delete.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "identity", + "description": "The identity of the client who initiated this request.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "WorkflowService" + ] + }, + "post": { + "summary": "Creates a new schedule.", + "operationId": "CreateSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1CreateScheduleResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace the schedule should be created in.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the new schedule.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceCreateScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/matching-times": { + "get": { + "summary": "Lists matching times within a range.", + "operationId": "ListScheduleMatchingTimes2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListScheduleMatchingTimesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to query.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to query.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "startTime", + "description": "Time range to query.", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + }, + { + "name": "endTime", + "in": "query", + "required": false, + "type": "string", + "format": "date-time" + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/patch": { + "post": { + "summary": "Makes a specific change to a schedule or triggers an immediate action.", + "operationId": "PatchSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1PatchScheduleResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to patch.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to patch.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServicePatchScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/schedules/{scheduleId}/update": { + "post": { + "summary": "Changes the configuration or state of an existing schedule.", + "operationId": "UpdateSchedule2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1UpdateScheduleResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "description": "The namespace of the schedule to update.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "scheduleId", + "description": "The id of the schedule to update.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceUpdateScheduleBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/search-attributes": { + "get": { + "summary": "ListSearchAttributes returns comprehensive information about search attributes.", + "operationId": "ListSearchAttributes2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListSearchAttributesResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "OperatorService" + ] + } + }, + "/api/v1/namespaces/{namespace}/task-queues/{taskQueue.name}": { + "get": { + "summary": "DescribeTaskQueue returns the following information about the target task queue, broken down by Build ID:\n - List of pollers\n - Workflow Reachability status\n - Backlog info for Workflow and/or Activity tasks", + "operationId": "DescribeTaskQueue2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DescribeTaskQueueResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "taskQueue.name", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "taskQueue.kind", + "description": "Default: TASK_QUEUE_KIND_NORMAL.\n\n - TASK_QUEUE_KIND_UNSPECIFIED: Tasks from any non workflow task may be unspecified.\n\nTask queue kind is used to differentiate whether a workflow task queue is sticky or \nnormal. If a task is not a workflow task, Task queue kind will sometimes be \nunspecified.\n - TASK_QUEUE_KIND_NORMAL: Tasks from a normal workflow task queue always include complete workflow history\n\nThe task queue specified by the user is always a normal task queue. There can be as many\nworkers as desired for a single normal task queue. All those workers may pick up tasks from\nthat queue.\n - TASK_QUEUE_KIND_STICKY: A sticky queue only includes new history since the last workflow task, and they are\nper-worker.\n\nSticky queues are created dynamically by each worker during their start up. They only exist\nfor the lifetime of the worker process. Tasks in a sticky task queue are only available to\nthe worker that created the sticky queue.\n\nSticky queues are only for workflow tasks. There are no sticky task queues for activities.", + "in": "query", + "required": false, + "type": "string", + "enum": [ + "TASK_QUEUE_KIND_UNSPECIFIED", + "TASK_QUEUE_KIND_NORMAL", + "TASK_QUEUE_KIND_STICKY" + ], + "default": "TASK_QUEUE_KIND_UNSPECIFIED" + }, + { + "name": "taskQueue.normalName", "description": "Iff kind == TASK_QUEUE_KIND_STICKY, then this field contains the name of\nthe normal task queue that the sticky worker is running on.", "in": "query", "required": false, @@ -3342,20 +3680,266 @@ } ], "tags": [ - "WorkflowService" + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/workflows/{workflowId}": { + "post": { + "summary": "StartWorkflowExecution starts a new workflow execution.", + "description": "It will create the execution with a `WORKFLOW_EXECUTION_STARTED` event in its history and\nalso schedule the first workflow task. Returns `WorkflowExecutionAlreadyStarted`, if an\ninstance already exists with same workflow id.", + "operationId": "StartWorkflowExecution2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1StartWorkflowExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "workflowId", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceStartWorkflowExecutionBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/namespaces/{namespace}/workflows/{workflowId}/signal-with-start/{signalName}": { + "post": { + "summary": "SignalWithStartWorkflowExecution is used to ensure a signal is sent to a workflow, even if\nit isn't yet started.", + "description": "If the workflow is running, a `WORKFLOW_EXECUTION_SIGNALED` event is recorded in the history\nand a workflow task is generated.\n\nIf the workflow is not running or not found, then the workflow is created with\n`WORKFLOW_EXECUTION_STARTED` and `WORKFLOW_EXECUTION_SIGNALED` events in its history, and a\nworkflow task is generated.", + "operationId": "SignalWithStartWorkflowExecution2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1SignalWithStartWorkflowExecutionResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "namespace", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "workflowId", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "signalName", + "description": "The workflow author-defined name of the signal to send to the workflow", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceSignalWithStartWorkflowExecutionBody" + } + } + ], + "tags": [ + "WorkflowService" + ] + } + }, + "/api/v1/nexus/endpoints": { + "get": { + "summary": "List all Nexus endpoints for the cluster, sorted by ID in ascending order. Set page_token in the request to the\nnext_page_token field of the previous response to get the next page of results. An empty next_page_token\nindicates that there are no more results. During pagination, a newly added service with an ID lexicographically\nearlier than the previous page's last endpoint's ID may be missed.", + "operationId": "ListNexusEndpoints2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1ListNexusEndpointsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "To get the next page, pass in `ListNexusEndpointsResponse.next_page_token` from the previous page's\nresponse, the token will be empty if there's no other page.\nNote: the last page may be empty if the total number of endpoints registered is a multiple of the page size.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "name", + "description": "Name of the incoming endpoint to filter on - optional. Specifying this will result in zero or one results.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "OperatorService" + ] + }, + "post": { + "summary": "Create a Nexus endpoint. This will fail if an endpoint with the same name is already registered with a status of\nALREADY_EXISTS.\nReturns the created endpoint with its initial version. You may use this version for subsequent updates.", + "operationId": "CreateNexusEndpoint2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1CreateNexusEndpointResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/v1CreateNexusEndpointRequest" + } + } + ], + "tags": [ + "OperatorService" + ] + } + }, + "/api/v1/nexus/endpoints/{id}": { + "get": { + "summary": "Get a registered Nexus endpoint by ID. The returned version can be used for optimistic updates.", + "operationId": "GetNexusEndpoint2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetNexusEndpointResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "id", + "description": "Server-generated unique endpoint ID.", + "in": "path", + "required": true, + "type": "string" + } + ], + "tags": [ + "OperatorService" + ] + }, + "delete": { + "summary": "Delete an incoming Nexus service by ID.", + "operationId": "DeleteNexusEndpoint2", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1DeleteNexusEndpointResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "id", + "description": "Server-generated unique endpoint ID.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "version", + "description": "Data version for this endpoint. Must match current version.", + "in": "query", + "required": false, + "type": "string", + "format": "int64" + } + ], + "tags": [ + "OperatorService" ] } }, - "/api/v1/namespaces/{namespace}/workflows/{workflowId}": { + "/api/v1/nexus/endpoints/{id}/update": { "post": { - "summary": "StartWorkflowExecution starts a new workflow execution.", - "description": "It will create the execution with a `WORKFLOW_EXECUTION_STARTED` event in its history and\nalso schedule the first workflow task. Returns `WorkflowExecutionAlreadyStarted`, if an\ninstance already exists with same workflow id.", - "operationId": "StartWorkflowExecution2", + "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", + "operationId": "UpdateNexusEndpoint2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1StartWorkflowExecutionResponse" + "$ref": "#/definitions/v1UpdateNexusEndpointResponse" } }, "default": { @@ -3367,13 +3951,8 @@ }, "parameters": [ { - "name": "namespace", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "workflowId", + "name": "id", + "description": "Server-generated unique endpoint ID.", "in": "path", "required": true, "type": "string" @@ -3383,25 +3962,24 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceStartWorkflowExecutionBody" + "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" } } ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/api/v1/namespaces/{namespace}/workflows/{workflowId}/signal-with-start/{signalName}": { - "post": { - "summary": "SignalWithStartWorkflowExecution is used to ensure a signal is sent to a workflow, even if\nit isn't yet started.", - "description": "If the workflow is running, a `WORKFLOW_EXECUTION_SIGNALED` event is recorded in the history\nand a workflow task is generated.\n\nIf the workflow is not running or not found, then the workflow is created with\n`WORKFLOW_EXECUTION_STARTED` and `WORKFLOW_EXECUTION_SIGNALED` events in its history, and a\nworkflow task is generated.", - "operationId": "SignalWithStartWorkflowExecution2", + "/api/v1/system-info": { + "get": { + "summary": "GetSystemInfo returns information about the system.", + "operationId": "GetSystemInfo2", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1SignalWithStartWorkflowExecutionResponse" + "$ref": "#/definitions/v1GetSystemInfoResponse" } }, "default": { @@ -3411,49 +3989,43 @@ } } }, - "parameters": [ - { - "name": "namespace", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "workflowId", - "in": "path", - "required": true, - "type": "string" - }, - { - "name": "signalName", - "description": "The workflow author-defined name of the signal to send to the workflow", - "in": "path", - "required": true, - "type": "string" + "tags": [ + "WorkflowService" + ] + } + }, + "/cluster": { + "get": { + "summary": "GetClusterInfo returns information about temporal cluster", + "operationId": "GetClusterInfo", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1GetClusterInfoResponse" + } }, - { - "name": "body", - "in": "body", - "required": true, + "default": { + "description": "An unexpected error response.", "schema": { - "$ref": "#/definitions/WorkflowServiceSignalWithStartWorkflowExecutionBody" + "$ref": "#/definitions/rpcStatus" } } - ], + }, "tags": [ "WorkflowService" ] } }, - "/api/v1/nexus/endpoints": { + "/cluster/namespaces": { "get": { - "summary": "List all Nexus endpoints for the cluster, sorted by ID in ascending order. Set page_token in the request to the\nnext_page_token field of the previous response to get the next page of results. An empty next_page_token\nindicates that there are no more results. During pagination, a newly added service with an ID lexicographically\nearlier than the previous page's last endpoint's ID may be missed.", - "operationId": "ListNexusEndpoints2", + "summary": "ListNamespaces returns the information and configuration for all namespaces.", + "operationId": "ListNamespaces", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListNexusEndpointsResponse" + "$ref": "#/definitions/v1ListNamespacesResponse" } }, "default": { @@ -3473,32 +4045,32 @@ }, { "name": "nextPageToken", - "description": "To get the next page, pass in `ListNexusEndpointsResponse.next_page_token` from the previous page's\nresponse, the token will be empty if there's no other page.\nNote: the last page may be empty if the total number of endpoints registered is a multiple of the page size.", "in": "query", "required": false, "type": "string", "format": "byte" }, { - "name": "name", - "description": "Name of the incoming endpoint to filter on - optional. Specifying this will result in zero or one results.", + "name": "namespaceFilter.includeDeleted", + "description": "By default namespaces in NAMESPACE_STATE_DELETED state are not included.\nSetting include_deleted to true will include deleted namespaces.\nNote: Namespace is in NAMESPACE_STATE_DELETED state when it was deleted from the system but associated data is not deleted yet.", "in": "query", "required": false, - "type": "string" + "type": "boolean" } ], "tags": [ - "OperatorService" + "WorkflowService" ] }, "post": { - "summary": "Create a Nexus endpoint. This will fail if an endpoint with the same name is already registered with a status of\nALREADY_EXISTS.\nReturns the created endpoint with its initial version. You may use this version for subsequent updates.", - "operationId": "CreateNexusEndpoint2", + "summary": "RegisterNamespace creates a new namespace which can be used as a container for all resources.", + "description": "A Namespace is a top level entity within Temporal, and is used as a container for resources\nlike workflow executions, task queues, etc. A Namespace acts as a sandbox and provides\nisolation for all resources within the namespace. All resources belongs to exactly one\nnamespace.", + "operationId": "RegisterNamespace", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1CreateNexusEndpointResponse" + "$ref": "#/definitions/v1RegisterNamespaceResponse" } }, "default": { @@ -3514,24 +4086,24 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/v1CreateNexusEndpointRequest" + "$ref": "#/definitions/v1RegisterNamespaceRequest" } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/api/v1/nexus/endpoints/{id}": { + "/cluster/namespaces/{namespace}": { "get": { - "summary": "Get a registered Nexus endpoint by ID. The returned version can be used for optimistic updates.", - "operationId": "GetNexusEndpoint2", + "summary": "DescribeNamespace returns the information and configuration for a registered namespace.", + "operationId": "DescribeNamespace", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetNexusEndpointResponse" + "$ref": "#/definitions/v1DescribeNamespaceResponse" } }, "default": { @@ -3543,25 +4115,32 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", "in": "path", "required": true, "type": "string" + }, + { + "name": "id", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ - "OperatorService" + "WorkflowService" ] - }, - "delete": { - "summary": "Delete an incoming Nexus service by ID.", - "operationId": "DeleteNexusEndpoint2", + } + }, + "/cluster/namespaces/{namespace}/search-attributes": { + "get": { + "summary": "ListSearchAttributes returns comprehensive information about search attributes.", + "operationId": "ListSearchAttributes", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteNexusEndpointResponse" + "$ref": "#/definitions/v1ListSearchAttributesResponse" } }, "default": { @@ -3573,19 +4152,10 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", "in": "path", "required": true, "type": "string" - }, - { - "name": "version", - "description": "Data version for this endpoint. Must match current version.", - "in": "query", - "required": false, - "type": "string", - "format": "int64" } ], "tags": [ @@ -3593,15 +4163,15 @@ ] } }, - "/api/v1/nexus/endpoints/{id}/update": { + "/cluster/namespaces/{namespace}/update": { "post": { - "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", - "operationId": "UpdateNexusEndpoint2", + "summary": "UpdateNamespace is used to update the information and configuration of a registered\nnamespace.", + "operationId": "UpdateNamespace", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateNexusEndpointResponse" + "$ref": "#/definitions/v1UpdateNamespaceResponse" } }, "default": { @@ -3613,8 +4183,7 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", "in": "path", "required": true, "type": "string" @@ -3624,24 +4193,69 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" + "$ref": "#/definitions/WorkflowServiceUpdateNamespaceBody" } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/api/v1/system-info": { + "/cluster/nexus/endpoints": { "get": { - "summary": "GetSystemInfo returns information about the system.", - "operationId": "GetSystemInfo2", + "summary": "List all Nexus endpoints for the cluster, sorted by ID in ascending order. Set page_token in the request to the\nnext_page_token field of the previous response to get the next page of results. An empty next_page_token\nindicates that there are no more results. During pagination, a newly added service with an ID lexicographically\nearlier than the previous page's last endpoint's ID may be missed.", + "operationId": "ListNexusEndpoints", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetSystemInfoResponse" + "$ref": "#/definitions/v1ListNexusEndpointsResponse" + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/rpcStatus" + } + } + }, + "parameters": [ + { + "name": "pageSize", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "To get the next page, pass in `ListNexusEndpointsResponse.next_page_token` from the previous page's\nresponse, the token will be empty if there's no other page.\nNote: the last page may be empty if the total number of endpoints registered is a multiple of the page size.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "name", + "description": "Name of the incoming endpoint to filter on - optional. Specifying this will result in zero or one results.", + "in": "query", + "required": false, + "type": "string" + } + ], + "tags": [ + "OperatorService" + ] + }, + "post": { + "summary": "Create a Nexus endpoint. This will fail if an endpoint with the same name is already registered with a status of\nALREADY_EXISTS.\nReturns the created endpoint with its initial version. You may use this version for subsequent updates.", + "operationId": "CreateNexusEndpoint", + "responses": { + "200": { + "description": "A successful response.", + "schema": { + "$ref": "#/definitions/v1CreateNexusEndpointResponse" } }, "default": { @@ -3651,20 +4265,30 @@ } } }, + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/v1CreateNexusEndpointRequest" + } + } + ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/cluster": { + "/cluster/nexus/endpoints/{id}": { "get": { - "summary": "GetClusterInfo returns information about temporal cluster", - "operationId": "GetClusterInfo", + "summary": "Get a registered Nexus endpoint by ID. The returned version can be used for optimistic updates.", + "operationId": "GetNexusEndpoint", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetClusterInfoResponse" + "$ref": "#/definitions/v1GetNexusEndpointResponse" } }, "default": { @@ -3674,20 +4298,27 @@ } } }, + "parameters": [ + { + "name": "id", + "description": "Server-generated unique endpoint ID.", + "in": "path", + "required": true, + "type": "string" + } + ], "tags": [ - "WorkflowService" + "OperatorService" ] - } - }, - "/cluster/namespaces": { - "get": { - "summary": "ListNamespaces returns the information and configuration for all namespaces.", - "operationId": "ListNamespaces", + }, + "delete": { + "summary": "Delete an incoming Nexus service by ID.", + "operationId": "DeleteNexusEndpoint", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListNamespacesResponse" + "$ref": "#/definitions/v1DeleteNexusEndpointResponse" } }, "default": { @@ -3699,40 +4330,35 @@ }, "parameters": [ { - "name": "pageSize", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" + "name": "id", + "description": "Server-generated unique endpoint ID.", + "in": "path", + "required": true, + "type": "string" }, { - "name": "nextPageToken", + "name": "version", + "description": "Data version for this endpoint. Must match current version.", "in": "query", "required": false, "type": "string", - "format": "byte" - }, - { - "name": "namespaceFilter.includeDeleted", - "description": "By default namespaces in NAMESPACE_STATE_DELETED state are not included.\nSetting include_deleted to true will include deleted namespaces.\nNote: Namespace is in NAMESPACE_STATE_DELETED state when it was deleted from the system but associated data is not deleted yet.", - "in": "query", - "required": false, - "type": "boolean" + "format": "int64" } ], "tags": [ - "WorkflowService" + "OperatorService" ] - }, + } + }, + "/cluster/nexus/endpoints/{id}/update": { "post": { - "summary": "RegisterNamespace creates a new namespace which can be used as a container for all resources.", - "description": "A Namespace is a top level entity within Temporal, and is used as a container for resources\nlike workflow executions, task queues, etc. A Namespace acts as a sandbox and provides\nisolation for all resources within the namespace. All resources belongs to exactly one\nnamespace.", - "operationId": "RegisterNamespace", + "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", + "operationId": "UpdateNexusEndpoint", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RegisterNamespaceResponse" + "$ref": "#/definitions/v1UpdateNexusEndpointResponse" } }, "default": { @@ -3743,29 +4369,36 @@ } }, "parameters": [ + { + "name": "id", + "description": "Server-generated unique endpoint ID.", + "in": "path", + "required": true, + "type": "string" + }, { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/v1RegisterNamespaceRequest" + "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" } } ], "tags": [ - "WorkflowService" + "OperatorService" ] } }, - "/cluster/namespaces/{namespace}": { + "/namespaces/{namespace}/activities": { "get": { - "summary": "DescribeNamespace returns the information and configuration for a registered namespace.", - "operationId": "DescribeNamespace", + "summary": "ListActivityExecutions is a visibility API to list activity executions in a specific namespace.", + "operationId": "ListActivityExecutions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DescribeNamespaceResponse" + "$ref": "#/definitions/v1ListActivityExecutionsResponse" } }, "default": { @@ -3783,7 +4416,24 @@ "type": "string" }, { - "name": "id", + "name": "pageSize", + "description": "Max number of executions to return per page.", + "in": "query", + "required": false, + "type": "integer", + "format": "int32" + }, + { + "name": "nextPageToken", + "description": "Token returned in ListActivityExecutionsResponse.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" + }, + { + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", "in": "query", "required": false, "type": "string" @@ -3794,15 +4444,16 @@ ] } }, - "/cluster/namespaces/{namespace}/search-attributes": { - "get": { - "summary": "ListSearchAttributes returns comprehensive information about search attributes.", - "operationId": "ListSearchAttributes", + "/namespaces/{namespace}/activities/cancel": { + "post": { + "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", + "description": "This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCanceled", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListSearchAttributesResponse" + "$ref": "#/definitions/v1RespondActivityTaskCanceledResponse" } }, "default": { @@ -3818,22 +4469,30 @@ "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/cluster/namespaces/{namespace}/update": { + "/namespaces/{namespace}/activities/cancel-by-id": { "post": { - "summary": "UpdateNamespace is used to update the information and configuration of a registered\nnamespace.", - "operationId": "UpdateNamespace", + "summary": "See `RespondActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCanceledById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateNamespaceResponse" + "$ref": "#/definitions/v1RespondActivityTaskCanceledByIdResponse" } }, "default": { @@ -3846,6 +4505,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -3855,7 +4515,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateNamespaceBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" } } ], @@ -3864,15 +4524,16 @@ ] } }, - "/cluster/nexus/endpoints": { - "get": { - "summary": "List all Nexus endpoints for the cluster, sorted by ID in ascending order. Set page_token in the request to the\nnext_page_token field of the previous response to get the next page of results. An empty next_page_token\nindicates that there are no more results. During pagination, a newly added service with an ID lexicographically\nearlier than the previous page's last endpoint's ID may be missed.", - "operationId": "ListNexusEndpoints", + "/namespaces/{namespace}/activities/complete": { + "post": { + "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", + "description": "This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskCompleted", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ListNexusEndpointsResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" } }, "default": { @@ -3884,73 +4545,34 @@ }, "parameters": [ { - "name": "pageSize", - "in": "query", - "required": false, - "type": "integer", - "format": "int32" - }, - { - "name": "nextPageToken", - "description": "To get the next page, pass in `ListNexusEndpointsResponse.next_page_token` from the previous page's\nresponse, the token will be empty if there's no other page.\nNote: the last page may be empty if the total number of endpoints registered is a multiple of the page size.", - "in": "query", - "required": false, - "type": "string", - "format": "byte" - }, - { - "name": "name", - "description": "Name of the incoming endpoint to filter on - optional. Specifying this will result in zero or one results.", - "in": "query", - "required": false, + "name": "namespace", + "in": "path", + "required": true, "type": "string" - } - ], - "tags": [ - "OperatorService" - ] - }, - "post": { - "summary": "Create a Nexus endpoint. This will fail if an endpoint with the same name is already registered with a status of\nALREADY_EXISTS.\nReturns the created endpoint with its initial version. You may use this version for subsequent updates.", - "operationId": "CreateNexusEndpoint", - "responses": { - "200": { - "description": "A successful response.", - "schema": { - "$ref": "#/definitions/v1CreateNexusEndpointResponse" - } }, - "default": { - "description": "An unexpected error response.", - "schema": { - "$ref": "#/definitions/rpcStatus" - } - } - }, - "parameters": [ { "name": "body", "in": "body", "required": true, "schema": { - "$ref": "#/definitions/v1CreateNexusEndpointRequest" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/cluster/nexus/endpoints/{id}": { - "get": { - "summary": "Get a registered Nexus endpoint by ID. The returned version can be used for optimistic updates.", - "operationId": "GetNexusEndpoint", + "/namespaces/{namespace}/activities/complete-by-id": { + "post": { + "summary": "See `RespondActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskCompletedById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1GetNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" } }, "default": { @@ -3962,25 +4584,36 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" + }, + { + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] - }, - "delete": { - "summary": "Delete an incoming Nexus service by ID.", - "operationId": "DeleteNexusEndpoint", + } + }, + "/namespaces/{namespace}/activities/fail": { + "post": { + "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", + "description": "This results in a new `ACTIVITY_TASK_FAILED` event being written to the workflow history and\na new workflow task created for the workflow. Fails with `NotFound` if the task token is no\nlonger valid due to activity timeout, already being completed, or never having existed.", + "operationId": "RespondActivityTaskFailed", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1DeleteNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" } }, "default": { @@ -3992,35 +4625,34 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", "in": "path", "required": true, "type": "string" }, { - "name": "version", - "description": "Data version for this endpoint. Must match current version.", - "in": "query", - "required": false, - "type": "string", - "format": "int64" + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/cluster/nexus/endpoints/{id}/update": { + "/namespaces/{namespace}/activities/fail-by-id": { "post": { - "summary": "Optimistically update a Nexus endpoint based on provided version as obtained via the `GetNexusEndpoint` or\n`ListNexusEndpointResponse` APIs. This will fail with a status of FAILED_PRECONDITION if the version does not\nmatch.\nReturns the updated endpoint with its updated version. You may use this version for subsequent updates. You don't\nneed to increment the version yourself. The server will increment the version for you after each update.", - "operationId": "UpdateNexusEndpoint", + "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RespondActivityTaskFailedById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateNexusEndpointResponse" + "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" } }, "default": { @@ -4032,8 +4664,8 @@ }, "parameters": [ { - "name": "id", - "description": "Server-generated unique endpoint ID.", + "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" @@ -4043,25 +4675,25 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/OperatorServiceUpdateNexusEndpointBody" + "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" } } ], "tags": [ - "OperatorService" + "WorkflowService" ] } }, - "/namespaces/{namespace}/activities/cancel": { + "/namespaces/{namespace}/activities/heartbeat": { "post": { - "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", - "description": "This results in a new `ACTIVITY_TASK_CANCELED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCanceled", + "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", + "description": "If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to\nthe workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in\nsuch situations, in that event, the SDK should request cancellation of the activity.", + "operationId": "RecordActivityTaskHeartbeat", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCanceledResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" } }, "default": { @@ -4083,7 +4715,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" } } ], @@ -4092,15 +4724,15 @@ ] } }, - "/namespaces/{namespace}/activities/cancel-by-id": { + "/namespaces/{namespace}/activities/heartbeat-by-id": { "post": { - "summary": "See `RecordActivityTaskCanceled`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCanceledById", + "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", + "operationId": "RecordActivityTaskHeartbeatById", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCanceledByIdResponse" + "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" } }, "default": { @@ -4123,7 +4755,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCanceledByIdBody" + "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" } } ], @@ -4132,16 +4764,16 @@ ] } }, - "/namespaces/{namespace}/activities/complete": { + "/namespaces/{namespace}/activities/pause": { "post": { - "summary": "RespondActivityTaskCompleted is called by workers when they successfully complete an activity\ntask.", - "description": "This results in a new `ACTIVITY_TASK_COMPLETED` event being written to the workflow history\nand a new workflow task created for the workflow. Fails with `NotFound` if the task token is\nno longer valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskCompleted", + "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", + "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "PauseActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedResponse" + "$ref": "#/definitions/v1PauseActivityResponse" } }, "default": { @@ -4154,6 +4786,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4163,7 +4796,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedBody" + "$ref": "#/definitions/WorkflowServicePauseActivityBody" } } ], @@ -4172,15 +4805,16 @@ ] } }, - "/namespaces/{namespace}/activities/complete-by-id": { + "/namespaces/{namespace}/activities/reset": { "post": { - "summary": "See `RecordActivityTaskCompleted`. This version allows clients to record completions by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskCompletedById", + "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", + "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.\nThis API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "ResetActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskCompletedByIdResponse" + "$ref": "#/definitions/v1ResetActivityResponse" } }, "default": { @@ -4193,7 +4827,7 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4203,7 +4837,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskCompletedByIdBody" + "$ref": "#/definitions/WorkflowServiceResetActivityBody" } } ], @@ -4212,16 +4846,16 @@ ] } }, - "/namespaces/{namespace}/activities/fail": { + "/namespaces/{namespace}/activities/unpause": { "post": { - "summary": "RespondActivityTaskFailed is called by workers when processing an activity task fails.", - "description": "This results in a new `ACTIVITY_TASK_FAILED` event being written to the workflow history and\na new workflow task created for the workflow. Fails with `NotFound` if the task token is no\nlonger valid due to activity timeout, already being completed, or never having existed.", - "operationId": "RespondActivityTaskFailed", + "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", + "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type\nThis API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and\nstructured to work well for standalone activities.", + "operationId": "UnpauseActivity", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedResponse" + "$ref": "#/definitions/v1UnpauseActivityResponse" } }, "default": { @@ -4234,6 +4868,7 @@ "parameters": [ { "name": "namespace", + "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" @@ -4243,7 +4878,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedBody" + "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" } } ], @@ -4252,15 +4887,15 @@ ] } }, - "/namespaces/{namespace}/activities/fail-by-id": { + "/namespaces/{namespace}/activities/update-options": { "post": { - "summary": "See `RecordActivityTaskFailed`. This version allows clients to record failures by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RespondActivityTaskFailedById", + "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.\nThis API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and\nstructured to work well for standalone activities.", + "operationId": "UpdateActivityOptions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RespondActivityTaskFailedByIdResponse" + "$ref": "#/definitions/v1UpdateActivityOptionsResponse" } }, "default": { @@ -4283,7 +4918,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRespondActivityTaskFailedByIdBody" + "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" } } ], @@ -4292,16 +4927,15 @@ ] } }, - "/namespaces/{namespace}/activities/heartbeat": { - "post": { - "summary": "RecordActivityTaskHeartbeat is optionally called by workers while they execute activities.", - "description": "If worker fails to heartbeat within the `heartbeat_timeout` interval for the activity task,\nthen it will be marked as timed out and an `ACTIVITY_TASK_TIMED_OUT` event will be written to\nthe workflow history. Calling `RecordActivityTaskHeartbeat` will fail with `NotFound` in\nsuch situations, in that event, the SDK should request cancellation of the activity.", - "operationId": "RecordActivityTaskHeartbeat", + "/namespaces/{namespace}/activities/{activityId}": { + "get": { + "summary": "DescribeActivityExecution returns information about an activity execution.\nSupported use cases include:\n- Get current activity info without waiting\n- Long-poll for next state change and return new activity info\nResponse can optionally include activity input or outcome (if the activity has completed).", + "operationId": "DescribeActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatResponse" + "$ref": "#/definitions/v1DescribeActivityExecutionResponse" } }, "default": { @@ -4319,28 +4953,54 @@ "type": "string" }, { - "name": "body", - "in": "body", + "name": "activityId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatBody" - } + "type": "string" + }, + { + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" + }, + { + "name": "includeInput", + "description": "Include the input field in the response.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "includeOutcome", + "description": "Include the outcome (result/failure) in the response if the activity has completed.", + "in": "query", + "required": false, + "type": "boolean" + }, + { + "name": "longPollToken", + "description": "Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity\nstate changes from the state encoded in this token. If absent, return current state immediately.\nIf present, run_id must also be present.\nNote that activity state may change multiple times between requests, therefore it is not\nguaranteed that a client making a sequence of long-poll requests will see a complete\nsequence of state changes.", + "in": "query", + "required": false, + "type": "string", + "format": "byte" } ], "tags": [ "WorkflowService" ] - } - }, - "/namespaces/{namespace}/activities/heartbeat-by-id": { + }, "post": { - "summary": "See `RecordActivityTaskHeartbeat`. This version allows clients to record heartbeats by\nnamespace/workflow id/activity id instead of task token.", - "operationId": "RecordActivityTaskHeartbeatById", + "summary": "StartActivityExecution starts a new activity execution.", + "description": "Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace\nunless permitted by the specified ID conflict policy.", + "operationId": "StartActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1RecordActivityTaskHeartbeatByIdResponse" + "$ref": "#/definitions/v1StartActivityExecutionResponse" } }, "default": { @@ -4353,7 +5013,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "activityId", "in": "path", "required": true, "type": "string" @@ -4363,7 +5028,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceRecordActivityTaskHeartbeatByIdBody" + "$ref": "#/definitions/WorkflowServiceStartActivityExecutionBody" } } ], @@ -4372,16 +5037,16 @@ ] } }, - "/namespaces/{namespace}/activities/pause": { + "/namespaces/{namespace}/activities/{activityId}/cancel": { "post": { - "summary": "PauseActivity pauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be paused", - "description": "Pausing an activity means:\n- If the activity is currently waiting for a retry or is running and subsequently fails,\n it will not be rescheduled until it is unpaused.\n- If the activity is already paused, calling this method will have no effect.\n- If the activity is running and finishes successfully, the activity will be completed.\n- If the activity is running and finishes with failure:\n * if there is no retry left - the activity will be completed.\n * if there are more retries left - the activity will be paused.\nFor long-running activities:\n- activities in paused state will send a cancellation with \"activity_paused\" set to 'true' in response to 'RecordActivityTaskHeartbeat'.\n- The activity should respond to the cancellation accordingly.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", - "operationId": "PauseActivity", + "summary": "RequestCancelActivityExecution requests cancellation of an activity execution.", + "description": "Requesting to cancel an activity does not automatically transition the activity to canceled status. If the\nactivity has a currently running attempt, the activity will only transition to canceled status if the current\nattempt is unsuccessful.\nTODO: Clarify what happens if there are no more allowed retries after the current attempt.\n\nIt returns success if the requested activity is already closed.\nTODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior?", + "operationId": "RequestCancelActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1PauseActivityResponse" + "$ref": "#/definitions/v1RequestCancelActivityExecutionResponse" } }, "default": { @@ -4394,7 +5059,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "activityId", "in": "path", "required": true, "type": "string" @@ -4404,7 +5074,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServicePauseActivityBody" + "$ref": "#/definitions/WorkflowServiceRequestCancelActivityExecutionBody" } } ], @@ -4413,16 +5083,15 @@ ] } }, - "/namespaces/{namespace}/activities/reset": { - "post": { - "summary": "ResetActivity resets the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be reset.", - "description": "Resetting an activity means:\n* number of attempts will be reset to 0.\n* activity timeouts will be reset.\n* if the activity is waiting for retry, and it is not paused or 'keep_paused' is not provided:\n it will be scheduled immediately (* see 'jitter' flag),\n\nFlags:\n\n'jitter': the activity will be scheduled at a random time within the jitter duration.\nIf the activity currently paused it will be unpaused, unless 'keep_paused' flag is provided.\n'reset_heartbeats': the activity heartbeat timer and heartbeats will be reset.\n'keep_paused': if the activity is paused, it will remain paused.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type.", - "operationId": "ResetActivity", + "/namespaces/{namespace}/activities/{activityId}/outcome": { + "get": { + "summary": "GetActivityExecutionOutcome long-polls for an activity execution to complete and returns\nthe outcome (result or failure).", + "operationId": "GetActivityExecutionOutcome", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1ResetActivityResponse" + "$ref": "#/definitions/v1GetActivityExecutionOutcomeResponse" } }, "default": { @@ -4435,18 +5104,22 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", + "name": "activityId", + "in": "path", "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceResetActivityBody" - } + "type": "string" + }, + { + "name": "runId", + "description": "Activity run ID. If empty the request targets the latest run.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -4454,16 +5127,16 @@ ] } }, - "/namespaces/{namespace}/activities/unpause": { + "/namespaces/{namespace}/activities/{activityId}/terminate": { "post": { - "summary": "UnpauseActivity unpauses the execution of an activity specified by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be unpaused.", - "description": "If activity is not paused, this call will have no effect.\nIf the activity was paused while waiting for retry, it will be scheduled immediately (* see 'jitter' flag).\nOnce the activity is unpaused, all timeout timers will be regenerated.\n\nFlags:\n'jitter': the activity will be scheduled at a random time within the jitter duration.\n'reset_attempts': the number of attempts will be reset.\n'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset.\n\nReturns a `NotFound` error if there is no pending activity with the provided ID or type", - "operationId": "UnpauseActivity", + "summary": "TerminateActivityExecution terminates an existing activity execution immediately.", + "description": "Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a\nrunning attempt and will be requested to be canceled by the server when it heartbeats.", + "operationId": "TerminateActivityExecution", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UnpauseActivityResponse" + "$ref": "#/definitions/v1TerminateActivityExecutionResponse" } }, "default": { @@ -4476,7 +5149,12 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity.", + "in": "path", + "required": true, + "type": "string" + }, + { + "name": "activityId", "in": "path", "required": true, "type": "string" @@ -4486,7 +5164,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/WorkflowServiceUnpauseActivityBody" + "$ref": "#/definitions/WorkflowServiceTerminateActivityExecutionBody" } } ], @@ -4495,15 +5173,15 @@ ] } }, - "/namespaces/{namespace}/activities/update-options": { - "post": { - "summary": "UpdateActivityOptions is called by the client to update the options of an activity by its ID or type.\nIf there are multiple pending activities of the provided type - all of them will be updated.", - "operationId": "UpdateActivityOptions", + "/namespaces/{namespace}/activity-count": { + "get": { + "summary": "CountActivityExecutions is a visibility API to count of activity executions in a specific namespace.", + "operationId": "CountActivityExecutions", "responses": { "200": { "description": "A successful response.", "schema": { - "$ref": "#/definitions/v1UpdateActivityOptionsResponse" + "$ref": "#/definitions/v1CountActivityExecutionsResponse" } }, "default": { @@ -4516,18 +5194,16 @@ "parameters": [ { "name": "namespace", - "description": "Namespace of the workflow which scheduled this activity", "in": "path", "required": true, "type": "string" }, { - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/WorkflowServiceUpdateActivityOptionsBody" - } + "name": "query", + "description": "Visibility query, see https://docs.temporal.io/list-filter for the syntax.", + "in": "query", + "required": false, + "type": "string" } ], "tags": [ @@ -7428,22 +8104,6 @@ } } }, - "CountWorkflowExecutionsResponseAggregationGroup": { - "type": "object", - "properties": { - "groupValues": { - "type": "array", - "items": { - "type": "object", - "$ref": "#/definitions/v1Payload" - } - }, - "count": { - "type": "string", - "format": "int64" - } - } - }, "DeploymentInfoTaskQueueInfo": { "type": "object", "properties": { @@ -7533,6 +8193,21 @@ } } }, + "LinkActivity": { + "type": "object", + "properties": { + "namespace": { + "type": "string" + }, + "activityId": { + "type": "string" + }, + "runId": { + "type": "string" + } + }, + "description": "A link to an activity." + }, "LinkBatchJob": { "type": "object", "properties": { @@ -8223,11 +8898,11 @@ "properties": { "workflowId": { "type": "string", - "title": "Id of the workflow which scheduled this activity" + "title": "Id of the workflow which scheduled this activity, leave empty to target a standalone activity" }, "runId": { "type": "string", - "title": "Run Id of the workflow which scheduled this activity" + "description": "For a workflow activity - the run ID of the workflow which scheduled this activity.\nFor a standalone activity - the run ID of the activity." }, "activityId": { "type": "string", @@ -8259,6 +8934,27 @@ } } }, + "WorkflowServiceRequestCancelActivityExecutionBody": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "Activity run ID, targets the latest run if run_id is empty." + }, + "identity": { + "type": "string", + "description": "The identity of the worker/client." + }, + "requestId": { + "type": "string", + "description": "Used to de-dupe cancellation requests." + }, + "reason": { + "type": "string", + "description": "Reason for requesting the cancellation, recorded and available via the PollActivityExecution API.\nNot propagated to a worker if an activity attempt is currently running." + } + } + }, "WorkflowServiceRequestCancelWorkflowExecutionBody": { "type": "object", "properties": { @@ -8424,11 +9120,11 @@ "properties": { "workflowId": { "type": "string", - "title": "Id of the workflow which scheduled this activity" + "title": "Id of the workflow which scheduled this activity, leave empty to target a standalone activity" }, "runId": { "type": "string", - "title": "Run Id of the workflow which scheduled this activity" + "description": "For a workflow activity - the run ID of the workflow which scheduled this activity.\nFor a standalone activity - the run ID of the activity." }, "activityId": { "type": "string", @@ -8483,11 +9179,11 @@ "properties": { "workflowId": { "type": "string", - "title": "Id of the workflow which scheduled this activity" + "title": "Id of the workflow which scheduled this activity, leave empty to target a standalone activity" }, "runId": { "type": "string", - "title": "Run Id of the workflow which scheduled this activity" + "description": "For a workflow activity - the run ID of the workflow which scheduled this activity.\nFor a standalone activity - the run ID of the activity." }, "activityId": { "type": "string", @@ -8542,11 +9238,11 @@ "properties": { "workflowId": { "type": "string", - "title": "Id of the workflow which scheduled this activity" + "title": "Id of the workflow which scheduled this activity, leave empty to target a standalone activity" }, "runId": { "type": "string", - "title": "Run Id of the workflow which scheduled this activity" + "description": "For a workflow activity - the run ID of the workflow which scheduled this activity.\nFor a standalone activity - the run ID of the activity." }, "activityId": { "type": "string", @@ -8816,6 +9512,74 @@ }, "description": "Keep the parameters in sync with:\n - temporal.api.batch.v1.BatchOperationSignal.\n - temporal.api.workflow.v1.PostResetOperation.SignalWorkflow." }, + "WorkflowServiceStartActivityExecutionBody": { + "type": "object", + "properties": { + "identity": { + "type": "string", + "title": "The identity of the client who initiated this request" + }, + "requestId": { + "type": "string", + "description": "A unique identifier for this start request. Typically UUIDv4." + }, + "activityType": { + "$ref": "#/definitions/v1ActivityType" + }, + "taskQueue": { + "$ref": "#/definitions/v1TaskQueue", + "description": "Task queue to schedule this activity on." + }, + "scheduleToCloseTimeout": { + "type": "string", + "description": "Indicates how long the caller is willing to wait for an activity completion. Limits how long\nretries will be attempted. Either this or `start_to_close_timeout` must be specified.\n" + }, + "scheduleToStartTimeout": { + "type": "string", + "description": "Limits time an activity task can stay in a task queue before a worker picks it up. This\ntimeout is always non retryable, as all a retry would achieve is to put it back into the same\nqueue. Defaults to `schedule_to_close_timeout` if not specified.\n" + }, + "startToCloseTimeout": { + "type": "string", + "description": "Maximum time an activity is allowed to execute after being picked up by a worker. This\ntimeout is always retryable. Either this or `schedule_to_close_timeout` must be\nspecified.\n" + }, + "heartbeatTimeout": { + "type": "string", + "description": "Maximum permitted time between successful worker heartbeats." + }, + "retryPolicy": { + "$ref": "#/definitions/v1RetryPolicy", + "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`." + }, + "input": { + "$ref": "#/definitions/v1Payloads", + "description": "Serialized arguments to the activity. These are passed as arguments to the activity function." + }, + "idReusePolicy": { + "$ref": "#/definitions/v1ActivityIdReusePolicy", + "description": "Defines whether to allow re-using the activity id from a previously *closed* activity.\nThe default policy is ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE." + }, + "idConflictPolicy": { + "$ref": "#/definitions/v1ActivityIdConflictPolicy", + "description": "Defines how to resolve an activity id conflict with a *running* activity.\nThe default policy is ACTIVITY_ID_CONFLICT_POLICY_FAIL." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes for indexing." + }, + "header": { + "$ref": "#/definitions/v1Header", + "description": "Header for context propagation and tracing purposes." + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity." + }, + "priority": { + "$ref": "#/definitions/v1Priority", + "description": "Priority metadata." + } + } + }, "WorkflowServiceStartBatchOperationBody": { "type": "object", "properties": { @@ -8980,16 +9744,33 @@ } } }, - "WorkflowServiceStopBatchOperationBody": { + "WorkflowServiceStopBatchOperationBody": { + "type": "object", + "properties": { + "reason": { + "type": "string", + "title": "Reason to stop a batch operation" + }, + "identity": { + "type": "string", + "title": "Identity of the operator" + } + } + }, + "WorkflowServiceTerminateActivityExecutionBody": { "type": "object", "properties": { + "runId": { + "type": "string", + "description": "Activity run ID, targets the latest run if run_id is empty." + }, "reason": { "type": "string", - "title": "Reason to stop a batch operation" + "description": "Reason for requesting the termination, recorded in in the activity's result failure outcome." }, "identity": { "type": "string", - "title": "Identity of the operator" + "description": "The identity of the worker/client." } } }, @@ -9374,6 +10155,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." @@ -9544,6 +10328,188 @@ } } }, + "v1ActivityExecutionInfo": { + "type": "object", + "properties": { + "activityId": { + "type": "string", + "description": "Unique identifier of this activity within its namespace along with run ID (below)." + }, + "runId": { + "type": "string" + }, + "activityType": { + "$ref": "#/definitions/v1ActivityType", + "description": "The type of the activity, a string that maps to a registered activity on a worker." + }, + "status": { + "$ref": "#/definitions/v1ActivityExecutionStatus", + "description": "A general status for this activity, indicates whether it is currently running or in one of the terminal statuses." + }, + "runState": { + "$ref": "#/definitions/v1PendingActivityState", + "description": "More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING." + }, + "heartbeatDetails": { + "$ref": "#/definitions/v1Payloads", + "description": "Details provided in the last recorded activity heartbeat." + }, + "lastHeartbeatTime": { + "type": "string", + "format": "date-time", + "description": "Time the last heartbeat was recorded." + }, + "lastStartedTime": { + "type": "string", + "format": "date-time", + "description": "Time the last attempt was started." + }, + "attempt": { + "type": "integer", + "format": "int32", + "description": "The attempt this activity is currently on.\nIncremented each time a new attempt is started.\nTODO(dandavison): Confirm if this is on scheduled or started." + }, + "maximumAttempts": { + "type": "integer", + "format": "int32" + }, + "scheduledTime": { + "type": "string", + "format": "date-time", + "description": "Time the activity was originally scheduled via a StartActivityExecution request." + }, + "expirationTime": { + "type": "string", + "format": "date-time", + "description": "Scheduled time + schedule to close timeout." + }, + "lastFailure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "Failure details from the last failed attempt." + }, + "lastWorkerIdentity": { + "type": "string" + }, + "currentRetryInterval": { + "type": "string", + "description": "Time from the last attempt failure to the next activity retry.\nIf the activity is currently running, this represents the next retry interval in case the attempt fails.\nIf activity is currently backing off between attempt, this represents the current retry interval.\nIf there is no next retry allowed, this field will be null.\nThis interval is typically calculated from the specified retry policy, but may be modified if an activity fails\nwith a retryable application failure specifying a retry delay." + }, + "lastAttemptCompleteTime": { + "type": "string", + "format": "date-time", + "description": "The time when the last activity attempt completed. If activity has not been completed yet, it will be null." + }, + "nextAttemptScheduleTime": { + "type": "string", + "format": "date-time", + "description": "The time when the next activity attempt will be scheduled.\nIf activity is currently scheduled or started, this field will be null." + }, + "lastDeploymentVersion": { + "$ref": "#/definitions/v1WorkerDeploymentVersion", + "description": "The Worker Deployment Version this activity was dispatched to most recently.\nIf nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker." + }, + "priority": { + "$ref": "#/definitions/v1Priority", + "description": "Priority metadata." + }, + "activityOptions": { + "$ref": "#/definitions/v1ActivityOptions", + "description": "Current activity options. May be different from the one used to start the activity." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Incremented each time the activity's state is mutated in persistence." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes" + }, + "header": { + "$ref": "#/definitions/v1Header" + }, + "userMetadata": { + "$ref": "#/definitions/v1UserMetadata", + "description": "Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity." + }, + "canceledReason": { + "type": "string", + "description": "Set if activity cancelation was requested." + } + }, + "description": "Information about a standalone activity." + }, + "v1ActivityExecutionListInfo": { + "type": "object", + "properties": { + "activityId": { + "type": "string", + "description": "For standalone activity - a unique identifier of this activity within its namespace along with run ID (below)." + }, + "runId": { + "type": "string", + "description": "The run ID of the workflow or standalone activity." + }, + "workflowId": { + "type": "string", + "description": "Workflow that contains this activity - only present for workflow activity." + }, + "activityType": { + "$ref": "#/definitions/v1ActivityType", + "description": "The type of the activity, a string that maps to a registered activity on a worker." + }, + "scheduledTime": { + "type": "string", + "format": "date-time", + "title": "Time the activity was originally scheduled via a StartActivityExecution request.\nTODO: Workflows call this schedule_time but it's scheduled_time in PendingActivityInfo, what should we choose for\nconsistency?" + }, + "closeTime": { + "type": "string", + "format": "date-time", + "description": "If the activity is in a terminal status, this field represents the time the activity transitioned to that status." + }, + "status": { + "$ref": "#/definitions/v1ActivityExecutionStatus", + "description": "Only scheduled and terminal statuses appear here. More detailed information in PendingActivityInfo but not\navailable in the list response." + }, + "searchAttributes": { + "$ref": "#/definitions/v1SearchAttributes", + "description": "Search attributes from the start request." + }, + "taskQueue": { + "type": "string", + "description": "The task queue this activity was scheduled on when it was originally started, updated on activity options update." + }, + "stateTransitionCount": { + "type": "string", + "format": "int64", + "description": "Updated on terminal status." + }, + "stateSizeBytes": { + "type": "string", + "format": "int64", + "description": "Updated once on scheduled and once on terminal status." + }, + "executionDuration": { + "type": "string", + "description": "The difference between close time and scheduled time.\nThis field is only populated if the activity is closed." + } + }, + "description": "Limited activity information returned in the list response.\nWhen adding fields here, ensure that it is also present in ActivityExecutionInfo (note that it\nmay already be present in ActivityExecutionInfo but not at the top-level)." + }, + "v1ActivityExecutionStatus": { + "type": "string", + "enum": [ + "ACTIVITY_EXECUTION_STATUS_UNSPECIFIED", + "ACTIVITY_EXECUTION_STATUS_RUNNING", + "ACTIVITY_EXECUTION_STATUS_COMPLETED", + "ACTIVITY_EXECUTION_STATUS_FAILED", + "ACTIVITY_EXECUTION_STATUS_CANCELED", + "ACTIVITY_EXECUTION_STATUS_TERMINATED", + "ACTIVITY_EXECUTION_STATUS_TIMED_OUT" + ], + "default": "ACTIVITY_EXECUTION_STATUS_UNSPECIFIED", + "description": "Status of a standalone activity.\nThe status is updated once, when the activity is originally scheduled, and again when the activity reaches a terminal\nstatus.\nTODO: Should this be a common execution status? Seems like the other archetypes will share this status.\n\n - ACTIVITY_EXECUTION_STATUS_RUNNING: The activity is not in a terminal status. This does not necessarily mean that there is a currently running\nattempt. The activity may be backing off between attempts or waiting for a worker to pick it up.\n - ACTIVITY_EXECUTION_STATUS_COMPLETED: The activity completed successfully.\n - ACTIVITY_EXECUTION_STATUS_FAILED: The activity completed with failure.\n - ACTIVITY_EXECUTION_STATUS_CANCELED: The activity completed as canceled.\nRequesting to cancel an activity does not automatically transition the activity to canceled status. If the\nactivity has a currently running attempt, the activity will only transition to canceled status if the current\nattempt is unsuccessful.\nTODO: Clarify what happens if there are no more allowed retries after the current attempt.\n - ACTIVITY_EXECUTION_STATUS_TERMINATED: The activity was terminated. Termination does not reach the worker and the activity code cannot react to it.\nA terminated activity may have a running attempt and will be requested to be canceled by the server when it\nheartbeats.\n - ACTIVITY_EXECUTION_STATUS_TIMED_OUT: The activity has timed out by reaching the specified shedule-to-start or schedule-to-close timeouts.\nTODO: Clarify if there are other conditions where the activity can end up in timed out status." + }, "v1ActivityFailureInfo": { "type": "object", "properties": { @@ -9569,6 +10535,27 @@ } } }, + "v1ActivityIdConflictPolicy": { + "type": "string", + "enum": [ + "ACTIVITY_ID_CONFLICT_POLICY_UNSPECIFIED", + "ACTIVITY_ID_CONFLICT_POLICY_FAIL", + "ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING" + ], + "default": "ACTIVITY_ID_CONFLICT_POLICY_UNSPECIFIED", + "description": "Defines what to do when trying to start an activity with the same ID as a *running* activity.\nNote that it is *never* valid to have two running instances of the same activity ID.\n\nSee `ActivityIdReusePolicy` for handling activity ID duplication with a *closed* activity.\n\n - ACTIVITY_ID_CONFLICT_POLICY_FAIL: Don't start a new activity; instead return `ActivityExecutionAlreadyStarted` error.\n - ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING: Don't start a new activity; instead return a handle for the running activity." + }, + "v1ActivityIdReusePolicy": { + "type": "string", + "enum": [ + "ACTIVITY_ID_REUSE_POLICY_UNSPECIFIED", + "ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE", + "ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY", + "ACTIVITY_ID_REUSE_POLICY_REJECT_DUPLICATE" + ], + "default": "ACTIVITY_ID_REUSE_POLICY_UNSPECIFIED", + "description": "Defines whether to allow re-using an activity ID from a previously *closed* activity.\nIf the request is denied, the server returns an `ActivityExecutionAlreadyStarted` error.\n\nSee `ActivityIdConflictPolicy` for handling ID duplication with a *running* activity.\n\n - ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE: Always allow starting an activity using the same activity ID.\n - ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY: Allow starting an activity using the same ID only when the last activity's final state is one\nof {failed, canceled, terminated, timed out}.\n - ACTIVITY_ID_REUSE_POLICY_REJECT_DUPLICATE: Do not permit re-use of the ID for this activity. Future start requests could potentially change the policy,\nallowing re-use of the ID." + }, "v1ActivityOptions": { "type": "object", "properties": { @@ -9592,7 +10579,8 @@ "description": "Maximum permitted time between successful worker heartbeats." }, "retryPolicy": { - "$ref": "#/definitions/v1RetryPolicy" + "$ref": "#/definitions/v1RetryPolicy", + "description": "The retry policy for the activity. Will never exceed `schedule_to_close_timeout`." } } }, @@ -10859,6 +11847,40 @@ } } }, + "v1CountActivityExecutionsResponse": { + "type": "object", + "properties": { + "count": { + "type": "string", + "format": "int64", + "description": "If `query` is not grouping by any field, the count is an approximate number\nof activities that match the query.\nIf `query` is grouping by a field, the count is simply the sum of the counts\nof the groups returned in the response. This number can be smaller than the\ntotal number of activities matching the query." + }, + "groups": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1CountActivityExecutionsResponseAggregationGroup" + }, + "description": "Contains the groups if the request is grouping by a field.\nThe list might not be complete, and the counts of each group is approximate." + } + } + }, + "v1CountActivityExecutionsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CountWorkflowExecutionsResponse": { "type": "object", "properties": { @@ -10871,12 +11893,28 @@ "type": "array", "items": { "type": "object", - "$ref": "#/definitions/CountWorkflowExecutionsResponseAggregationGroup" + "$ref": "#/definitions/v1CountWorkflowExecutionsResponseAggregationGroup" }, "description": "`groups` contains the groups if the request is grouping by a field.\nThe list might not be complete, and the counts of each group is approximate." } } }, + "v1CountWorkflowExecutionsResponseAggregationGroup": { + "type": "object", + "properties": { + "groupValues": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1Payload" + } + }, + "count": { + "type": "string", + "format": "int64" + } + } + }, "v1CreateNexusEndpointRequest": { "type": "object", "properties": { @@ -10929,6 +11967,9 @@ } } }, + "v1DeleteActivityExecutionResponse": { + "type": "object" + }, "v1DeleteNamespaceResponse": { "type": "object", "properties": { @@ -11057,6 +12098,36 @@ "type": "object", "description": "Deprecated." }, + "v1DescribeActivityExecutionResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the activity, useful when run_id was not specified in the request." + }, + "info": { + "$ref": "#/definitions/v1ActivityExecutionInfo", + "description": "Information about the activity execution." + }, + "input": { + "$ref": "#/definitions/v1Payloads", + "description": "Serialized activity input, passed as arguments to the activity function.\nOnly set if include_input was true in the request." + }, + "result": { + "$ref": "#/definitions/v1Payloads", + "description": "The result if the activity completed successfully." + }, + "failure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The failure if the activity completed unsuccessfully." + }, + "longPollToken": { + "type": "string", + "format": "byte", + "description": "Token for follow-on long-poll requests. Absent only if the activity is complete." + } + } + }, "v1DescribeBatchOperationResponse": { "type": "object", "properties": { @@ -11555,6 +12626,23 @@ } } }, + "v1GetActivityExecutionOutcomeResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the activity, useful when run_id was not specified in the request." + }, + "result": { + "$ref": "#/definitions/v1Payloads", + "description": "The result if the activity completed successfully." + }, + "failure": { + "$ref": "#/definitions/apifailurev1Failure", + "description": "The failure if the activity completed unsuccessfully." + } + } + }, "v1GetClusterInfoResponse": { "type": "object", "properties": { @@ -12124,6 +13212,23 @@ }, "description": "IntervalSpec matches times that can be expressed as:\nepoch + n * interval + phase\nwhere n is an integer.\nphase defaults to zero if missing. interval is required.\nBoth interval and phase must be non-negative and are truncated to the nearest\nsecond before any calculations.\nFor example, an interval of 1 hour with phase of zero would match every hour,\non the hour. The same interval but a phase of 19 minutes would match every\nxx:19:00. An interval of 28 days with phase zero would match\n2022-02-17T00:00:00Z (among other times). The same interval with a phase of 3\ndays, 5 hours, and 23 minutes would match 2022-02-20T05:23:00Z instead." }, + "v1ListActivityExecutionsResponse": { + "type": "object", + "properties": { + "executions": { + "type": "array", + "items": { + "type": "object", + "$ref": "#/definitions/v1ActivityExecutionListInfo" + } + }, + "nextPageToken": { + "type": "string", + "format": "byte", + "description": "Token to use to fetch the next page. If empty, there is no next page." + } + } + }, "v1ListArchivedWorkflowExecutionsResponse": { "type": "object", "properties": { @@ -13357,7 +14462,7 @@ }, "activityId": { "type": "string", - "description": "The autogenerated or user specified identifier of this activity. Can be used to complete the\nactivity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage\nhas resolved, but unique IDs for every activity invocation is a good idea." + "description": "The autogenerated or user specified identifier of this activity. Can be used to complete the\nactivity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage\nhas resolved, but unique IDs for every activity invocation is a good idea.\nNote that only a workflow activity ID may be autogenerated." }, "header": { "$ref": "#/definitions/v1Header", @@ -13857,6 +14962,9 @@ ], "default": "REPLICATION_STATE_UNSPECIFIED" }, + "v1RequestCancelActivityExecutionResponse": { + "type": "object" + }, "v1RequestCancelActivityTaskCommandAttributes": { "type": "object", "properties": { @@ -14969,6 +16077,19 @@ "v1SignalWorkflowExecutionResponse": { "type": "object" }, + "v1StartActivityExecutionResponse": { + "type": "object", + "properties": { + "runId": { + "type": "string", + "description": "The run ID of the activity that was started - or used (via ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING)." + }, + "started": { + "type": "boolean", + "description": "If true, a new activity was started." + } + } + }, "v1StartBatchOperationResponse": { "type": "object" }, @@ -15730,6 +16851,9 @@ "default": "TASK_REACHABILITY_UNSPECIFIED", "description": "Specifies which category of tasks may reach a worker on a versioned task queue.\nUsed both in a reachability query and its response.\nDeprecated.\n\n - TASK_REACHABILITY_NEW_WORKFLOWS: There's a possiblity for a worker to receive new workflow tasks. Workers should *not* be retired.\n - TASK_REACHABILITY_EXISTING_WORKFLOWS: There's a possiblity for a worker to receive existing workflow and activity tasks from existing workflows. Workers\nshould *not* be retired.\nThis enum value does not distinguish between open and closed workflows.\n - TASK_REACHABILITY_OPEN_WORKFLOWS: There's a possiblity for a worker to receive existing workflow and activity tasks from open workflows. Workers\nshould *not* be retired.\n - TASK_REACHABILITY_CLOSED_WORKFLOWS: There's a possiblity for a worker to receive existing workflow tasks from closed workflows. Workers may be\nretired dependending on application requirements. For example, if there's no need to query closed workflows." }, + "v1TerminateActivityExecutionResponse": { + "type": "object" + }, "v1TerminateWorkflowExecutionResponse": { "type": "object" }, diff --git a/openapi/openapiv3.yaml b/openapi/openapiv3.yaml index 2d04d5270..d42c34400 100644 --- a/openapi/openapiv3.yaml +++ b/openapi/openapiv3.yaml @@ -122,6 +122,48 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities: + get: + tags: + - WorkflowService + description: ListActivityExecutions is a visibility API to list activity executions in a specific namespace. + operationId: ListActivityExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + description: Max number of executions to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListActivityExecutionsResponse. + schema: + type: string + format: bytes + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListActivityExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/activities/cancel: post: tags: @@ -163,7 +205,7 @@ paths: tags: - WorkflowService description: |- - See `RecordActivityTaskCanceled`. This version allows clients to record failures by + See `RespondActivityTaskCanceled`. This version allows clients to record failures by namespace/workflow id/activity id instead of task token. (-- api-linter: core::0136::prepositions=disabled @@ -237,7 +279,7 @@ paths: tags: - WorkflowService description: |- - See `RecordActivityTaskCompleted`. This version allows clients to record completions by + See `RespondActivityTaskCompleted`. This version allows clients to record completions by namespace/workflow id/activity id instead of task token. (-- api-linter: core::0136::prepositions=disabled @@ -437,6 +479,8 @@ paths: - The activity should respond to the cancellation accordingly. Returns a `NotFound` error if there is no pending activity with the provided ID or type + This API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and + structured to work well for standalone activities. operationId: PauseActivity parameters: - name: namespace @@ -486,6 +530,8 @@ paths: 'keep_paused': if the activity is paused, it will remain paused. Returns a `NotFound` error if there is no pending activity with the provided ID or type. + This API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and + structured to work well for standalone activities. operationId: ResetActivity parameters: - name: namespace @@ -531,6 +577,8 @@ paths: 'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset. Returns a `NotFound` error if there is no pending activity with the provided ID or type + This API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and + structured to work well for standalone activities. operationId: UnpauseActivity parameters: - name: namespace @@ -565,6 +613,8 @@ paths: description: |- UpdateActivityOptions is called by the client to update the options of an activity by its ID or type. If there are multiple pending activities of the provided type - all of them will be updated. + This API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and + structured to work well for standalone activities. operationId: UpdateActivityOptions parameters: - name: namespace @@ -592,6 +642,259 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{activityId}: + get: + tags: + - WorkflowService + description: |- + DescribeActivityExecution returns information about an activity execution. + Supported use cases include: + - Get current activity info without waiting + - Long-poll for next state change and return new activity info + Response can optionally include activity input or outcome (if the activity has completed). + operationId: DescribeActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Activity run ID. If empty the request targets the latest run. + schema: + type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the activity has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity + state changes from the state encoded in this token. If absent, return current state immediately. + If present, run_id must also be present. + Note that activity state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartActivityExecution starts a new activity execution. + + Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace + unless permitted by the specified ID conflict policy. + operationId: StartActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{activityId}/cancel: + post: + tags: + - WorkflowService + description: |- + RequestCancelActivityExecution requests cancellation of an activity execution. + + Requesting to cancel an activity does not automatically transition the activity to canceled status. If the + activity has a currently running attempt, the activity will only transition to canceled status if the current + attempt is unsuccessful. + TODO: Clarify what happens if there are no more allowed retries after the current attempt. + + It returns success if the requested activity is already closed. + TODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior? + operationId: RequestCancelActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{activityId}/outcome: + get: + tags: + - WorkflowService + description: |- + GetActivityExecutionOutcome long-polls for an activity execution to complete and returns + the outcome (result or failure). + operationId: GetActivityExecutionOutcome + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Activity run ID. If empty the request targets the latest run. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetActivityExecutionOutcomeResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activities/{activityId}/terminate: + post: + tags: + - WorkflowService + description: |- + TerminateActivityExecution terminates an existing activity execution immediately. + + Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a + running attempt and will be requested to be canceled by the server when it heartbeats. + operationId: TerminateActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /api/v1/namespaces/{namespace}/activity-count: + get: + tags: + - WorkflowService + description: CountActivityExecutions is a visibility API to count of activity executions in a specific namespace. + operationId: CountActivityExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountActivityExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /api/v1/namespaces/{namespace}/archived-workflows: get: tags: @@ -3605,6 +3908,48 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities: + get: + tags: + - WorkflowService + description: ListActivityExecutions is a visibility API to list activity executions in a specific namespace. + operationId: ListActivityExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: pageSize + in: query + description: Max number of executions to return per page. + schema: + type: integer + format: int32 + - name: nextPageToken + in: query + description: Token returned in ListActivityExecutionsResponse. + schema: + type: string + format: bytes + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ListActivityExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/activities/cancel: post: tags: @@ -3646,7 +3991,7 @@ paths: tags: - WorkflowService description: |- - See `RecordActivityTaskCanceled`. This version allows clients to record failures by + See `RespondActivityTaskCanceled`. This version allows clients to record failures by namespace/workflow id/activity id instead of task token. (-- api-linter: core::0136::prepositions=disabled @@ -3720,7 +4065,7 @@ paths: tags: - WorkflowService description: |- - See `RecordActivityTaskCompleted`. This version allows clients to record completions by + See `RespondActivityTaskCompleted`. This version allows clients to record completions by namespace/workflow id/activity id instead of task token. (-- api-linter: core::0136::prepositions=disabled @@ -3920,6 +4265,8 @@ paths: - The activity should respond to the cancellation accordingly. Returns a `NotFound` error if there is no pending activity with the provided ID or type + This API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and + structured to work well for standalone activities. operationId: PauseActivity parameters: - name: namespace @@ -3969,6 +4316,8 @@ paths: 'keep_paused': if the activity is paused, it will remain paused. Returns a `NotFound` error if there is no pending activity with the provided ID or type. + This API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and + structured to work well for standalone activities. operationId: ResetActivity parameters: - name: namespace @@ -4014,6 +4363,8 @@ paths: 'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset. Returns a `NotFound` error if there is no pending activity with the provided ID or type + This API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and + structured to work well for standalone activities. operationId: UnpauseActivity parameters: - name: namespace @@ -4048,6 +4399,8 @@ paths: description: |- UpdateActivityOptions is called by the client to update the options of an activity by its ID or type. If there are multiple pending activities of the provided type - all of them will be updated. + This API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and + structured to work well for standalone activities. operationId: UpdateActivityOptions parameters: - name: namespace @@ -4075,6 +4428,259 @@ paths: application/json: schema: $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{activityId}: + get: + tags: + - WorkflowService + description: |- + DescribeActivityExecution returns information about an activity execution. + Supported use cases include: + - Get current activity info without waiting + - Long-poll for next state change and return new activity info + Response can optionally include activity input or outcome (if the activity has completed). + operationId: DescribeActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Activity run ID. If empty the request targets the latest run. + schema: + type: string + - name: includeInput + in: query + description: Include the input field in the response. + schema: + type: boolean + - name: includeOutcome + in: query + description: Include the outcome (result/failure) in the response if the activity has completed. + schema: + type: boolean + - name: longPollToken + in: query + description: |- + Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity + state changes from the state encoded in this token. If absent, return current state immediately. + If present, run_id must also be present. + Note that activity state may change multiple times between requests, therefore it is not + guaranteed that a client making a sequence of long-poll requests will see a complete + sequence of state changes. + schema: + type: string + format: bytes + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DescribeActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + post: + tags: + - WorkflowService + description: |- + StartActivityExecution starts a new activity execution. + + Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace + unless permitted by the specified ID conflict policy. + operationId: StartActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StartActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StartActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{activityId}/cancel: + post: + tags: + - WorkflowService + description: |- + RequestCancelActivityExecution requests cancellation of an activity execution. + + Requesting to cancel an activity does not automatically transition the activity to canceled status. If the + activity has a currently running attempt, the activity will only transition to canceled status if the current + attempt is unsuccessful. + TODO: Clarify what happens if there are no more allowed retries after the current attempt. + + It returns success if the requested activity is already closed. + TODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior? + operationId: RequestCancelActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/RequestCancelActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{activityId}/outcome: + get: + tags: + - WorkflowService + description: |- + GetActivityExecutionOutcome long-polls for an activity execution to complete and returns + the outcome (result or failure). + operationId: GetActivityExecutionOutcome + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + - name: runId + in: query + description: Activity run ID. If empty the request targets the latest run. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/GetActivityExecutionOutcomeResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activities/{activityId}/terminate: + post: + tags: + - WorkflowService + description: |- + TerminateActivityExecution terminates an existing activity execution immediately. + + Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a + running attempt and will be requested to be canceled by the server when it heartbeats. + operationId: TerminateActivityExecution + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: activityId + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateActivityExecutionRequest' + required: true + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/TerminateActivityExecutionResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' + /namespaces/{namespace}/activity-count: + get: + tags: + - WorkflowService + description: CountActivityExecutions is a visibility API to count of activity executions in a specific namespace. + operationId: CountActivityExecutions + parameters: + - name: namespace + in: path + required: true + schema: + type: string + - name: query + in: query + description: Visibility query, see https://docs.temporal.io/list-filter for the syntax. + schema: + type: string + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CountActivityExecutionsResponse' + default: + description: Default error response + content: + application/json: + schema: + $ref: '#/components/schemas/Status' /namespaces/{namespace}/archived-workflows: get: tags: @@ -6615,6 +7221,190 @@ paths: $ref: '#/components/schemas/Status' components: schemas: + ActivityExecutionInfo: + type: object + properties: + activityId: + type: string + description: Unique identifier of this activity within its namespace along with run ID (below). + runId: + type: string + activityType: + allOf: + - $ref: '#/components/schemas/ActivityType' + description: The type of the activity, a string that maps to a registered activity on a worker. + status: + enum: + - ACTIVITY_EXECUTION_STATUS_UNSPECIFIED + - ACTIVITY_EXECUTION_STATUS_RUNNING + - ACTIVITY_EXECUTION_STATUS_COMPLETED + - ACTIVITY_EXECUTION_STATUS_FAILED + - ACTIVITY_EXECUTION_STATUS_CANCELED + - ACTIVITY_EXECUTION_STATUS_TERMINATED + - ACTIVITY_EXECUTION_STATUS_TIMED_OUT + type: string + description: A general status for this activity, indicates whether it is currently running or in one of the terminal statuses. + format: enum + runState: + enum: + - PENDING_ACTIVITY_STATE_UNSPECIFIED + - PENDING_ACTIVITY_STATE_SCHEDULED + - PENDING_ACTIVITY_STATE_STARTED + - PENDING_ACTIVITY_STATE_CANCEL_REQUESTED + - PENDING_ACTIVITY_STATE_PAUSED + - PENDING_ACTIVITY_STATE_PAUSE_REQUESTED + type: string + description: More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING. + format: enum + heartbeatDetails: + allOf: + - $ref: '#/components/schemas/Payloads' + description: Details provided in the last recorded activity heartbeat. + lastHeartbeatTime: + type: string + description: Time the last heartbeat was recorded. + format: date-time + lastStartedTime: + type: string + description: Time the last attempt was started. + format: date-time + attempt: + type: integer + description: |- + The attempt this activity is currently on. + Incremented each time a new attempt is started. + TODO(dandavison): Confirm if this is on scheduled or started. + format: int32 + maximumAttempts: + type: integer + format: int32 + scheduledTime: + type: string + description: Time the activity was originally scheduled via a StartActivityExecution request. + format: date-time + expirationTime: + type: string + description: Scheduled time + schedule to close timeout. + format: date-time + lastFailure: + allOf: + - $ref: '#/components/schemas/Failure' + description: Failure details from the last failed attempt. + lastWorkerIdentity: + type: string + currentRetryInterval: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Time from the last attempt failure to the next activity retry. + If the activity is currently running, this represents the next retry interval in case the attempt fails. + If activity is currently backing off between attempt, this represents the current retry interval. + If there is no next retry allowed, this field will be null. + This interval is typically calculated from the specified retry policy, but may be modified if an activity fails + with a retryable application failure specifying a retry delay. + lastAttemptCompleteTime: + type: string + description: The time when the last activity attempt completed. If activity has not been completed yet, it will be null. + format: date-time + nextAttemptScheduleTime: + type: string + description: |- + The time when the next activity attempt will be scheduled. + If activity is currently scheduled or started, this field will be null. + format: date-time + lastDeploymentVersion: + allOf: + - $ref: '#/components/schemas/WorkerDeploymentVersion' + description: |- + The Worker Deployment Version this activity was dispatched to most recently. + If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker. + priority: + allOf: + - $ref: '#/components/schemas/Priority' + description: Priority metadata. + activityOptions: + allOf: + - $ref: '#/components/schemas/ActivityOptions' + description: Current activity options. May be different from the one used to start the activity. + stateTransitionCount: + type: string + description: Incremented each time the activity's state is mutated in persistence. + searchAttributes: + $ref: '#/components/schemas/SearchAttributes' + header: + $ref: '#/components/schemas/Header' + userMetadata: + allOf: + - $ref: '#/components/schemas/UserMetadata' + description: Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity. + canceledReason: + type: string + description: Set if activity cancelation was requested. + description: Information about a standalone activity. + ActivityExecutionListInfo: + type: object + properties: + activityId: + type: string + description: For standalone activity - a unique identifier of this activity within its namespace along with run ID (below). + runId: + type: string + description: The run ID of the workflow or standalone activity. + workflowId: + type: string + description: Workflow that contains this activity - only present for workflow activity. + activityType: + allOf: + - $ref: '#/components/schemas/ActivityType' + description: The type of the activity, a string that maps to a registered activity on a worker. + scheduledTime: + type: string + description: |- + Time the activity was originally scheduled via a StartActivityExecution request. + TODO: Workflows call this schedule_time but it's scheduled_time in PendingActivityInfo, what should we choose for + consistency? + format: date-time + closeTime: + type: string + description: If the activity is in a terminal status, this field represents the time the activity transitioned to that status. + format: date-time + status: + enum: + - ACTIVITY_EXECUTION_STATUS_UNSPECIFIED + - ACTIVITY_EXECUTION_STATUS_RUNNING + - ACTIVITY_EXECUTION_STATUS_COMPLETED + - ACTIVITY_EXECUTION_STATUS_FAILED + - ACTIVITY_EXECUTION_STATUS_CANCELED + - ACTIVITY_EXECUTION_STATUS_TERMINATED + - ACTIVITY_EXECUTION_STATUS_TIMED_OUT + type: string + description: |- + Only scheduled and terminal statuses appear here. More detailed information in PendingActivityInfo but not + available in the list response. + format: enum + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes from the start request. + taskQueue: + type: string + description: The task queue this activity was scheduled on when it was originally started, updated on activity options update. + stateTransitionCount: + type: string + description: Updated on terminal status. + stateSizeBytes: + type: string + description: Updated once on scheduled and once on terminal status. + executionDuration: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + The difference between close time and scheduled time. + This field is only populated if the activity is closed. + description: |- + Limited activity information returned in the list response. + When adding fields here, ensure that it is also present in ActivityExecutionInfo (note that it + may already be present in ActivityExecutionInfo but not at the top-level). ActivityFailureInfo: type: object properties: @@ -6680,7 +7470,9 @@ components: type: string description: Maximum permitted time between successful worker heartbeats. retryPolicy: - $ref: '#/components/schemas/RetryPolicy' + allOf: + - $ref: '#/components/schemas/RetryPolicy' + description: The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. ActivityPropertiesModifiedExternallyEventAttributes: type: object properties: @@ -7682,6 +8474,33 @@ components: type: string description: Time of the last update. format: date-time + CountActivityExecutionsResponse: + type: object + properties: + count: + type: string + description: |- + If `query` is not grouping by any field, the count is an approximate number + of activities that match the query. + If `query` is grouping by a field, the count is simply the sum of the counts + of the groups returned in the response. This number can be smaller than the + total number of activities matching the query. + groups: + type: array + items: + $ref: '#/components/schemas/CountActivityExecutionsResponse_AggregationGroup' + description: |- + Contains the groups if the request is grouping by a field. + The list might not be complete, and the counts of each group is approximate. + CountActivityExecutionsResponse_AggregationGroup: + type: object + properties: + groupValues: + type: array + items: + $ref: '#/components/schemas/Payload' + count: + type: string CountWorkflowExecutionsResponse: type: object properties: @@ -7931,6 +8750,34 @@ components: Holds information about ongoing transition of a workflow execution from one worker deployment version to another. Experimental. Might change in the future. + DescribeActivityExecutionResponse: + type: object + properties: + runId: + type: string + description: The run ID of the activity, useful when run_id was not specified in the request. + info: + allOf: + - $ref: '#/components/schemas/ActivityExecutionInfo' + description: Information about the activity execution. + input: + allOf: + - $ref: '#/components/schemas/Payloads' + description: |- + Serialized activity input, passed as arguments to the activity function. + Only set if include_input was true in the request. + result: + allOf: + - $ref: '#/components/schemas/Payloads' + description: The result if the activity completed successfully. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The failure if the activity completed unsuccessfully. + longPollToken: + type: string + description: Token for follow-on long-poll requests. Absent only if the activity is complete. + format: bytes DescribeBatchOperationResponse: type: object properties: @@ -8465,6 +9312,20 @@ components: allOf: - $ref: '#/components/schemas/WorkerConfig' description: The worker configuration. + GetActivityExecutionOutcomeResponse: + type: object + properties: + runId: + type: string + description: The run ID of the activity, useful when run_id was not specified in the request. + result: + allOf: + - $ref: '#/components/schemas/Payloads' + description: The result if the activity completed successfully. + failure: + allOf: + - $ref: '#/components/schemas/Failure' + description: The failure if the activity completed unsuccessfully. GetClusterInfoResponse: type: object properties: @@ -8973,11 +9834,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: @@ -9000,6 +9873,17 @@ components: $ref: '#/components/schemas/WorkflowEvent_EventReference' requestIdRef: $ref: '#/components/schemas/WorkflowEvent_RequestIdReference' + ListActivityExecutionsResponse: + type: object + properties: + executions: + type: array + items: + $ref: '#/components/schemas/ActivityExecutionListInfo' + nextPageToken: + type: string + description: Token to use to fetch the next page. If empty, there is no next page. + format: bytes ListArchivedWorkflowExecutionsResponse: type: object properties: @@ -10429,10 +11313,12 @@ components: description: Namespace of the workflow which scheduled this activity workflowId: type: string - description: Id of the workflow which scheduled this activity + description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity runId: type: string - description: Run Id of the workflow which scheduled this activity + description: |- + For a workflow activity - the run ID of the workflow which scheduled this activity. + For a standalone activity - the run ID of the activity. activityId: type: string description: Id of the activity we're heartbeating @@ -10576,6 +11462,30 @@ components: input: $ref: '#/components/schemas/Input' description: The client request that triggers a Workflow Update. + RequestCancelActivityExecutionRequest: + type: object + properties: + namespace: + type: string + activityId: + type: string + runId: + type: string + description: Activity run ID, targets the latest run if run_id is empty. + identity: + type: string + description: The identity of the worker/client. + requestId: + type: string + description: Used to de-dupe cancellation requests. + reason: + type: string + description: |- + Reason for requesting the cancellation, recorded and available via the PollActivityExecution API. + Not propagated to a worker if an activity attempt is currently running. + RequestCancelActivityExecutionResponse: + type: object + properties: {} RequestCancelExternalWorkflowExecutionFailedEventAttributes: type: object properties: @@ -10949,10 +11859,12 @@ components: description: Namespace of the workflow which scheduled this activity workflowId: type: string - description: Id of the workflow which scheduled this activity + description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity runId: type: string - description: Run Id of the workflow which scheduled this activity + description: |- + For a workflow activity - the run ID of the workflow which scheduled this activity. + For a standalone activity - the run ID of the activity. activityId: type: string description: Id of the activity to confirm is cancelled @@ -11016,10 +11928,12 @@ components: description: Namespace of the workflow which scheduled this activity workflowId: type: string - description: Id of the workflow which scheduled this activity + description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity runId: type: string - description: Run Id of the workflow which scheduled this activity + description: |- + For a workflow activity - the run ID of the workflow which scheduled this activity. + For a standalone activity - the run ID of the activity. activityId: type: string description: Id of the activity to complete @@ -11079,10 +11993,12 @@ components: description: Namespace of the workflow which scheduled this activity workflowId: type: string - description: Id of the workflow which scheduled this activity + description: Id of the workflow which scheduled this activity, leave empty to target a standalone activity runId: type: string - description: Run Id of the workflow which scheduled this activity + description: |- + For a workflow activity - the run ID of the workflow which scheduled this activity. + For a standalone activity - the run ID of the activity. activityId: type: string description: Id of the activity to fail @@ -12066,6 +12982,112 @@ components: SignalWorkflowExecutionResponse: type: object properties: {} + StartActivityExecutionRequest: + type: object + properties: + namespace: + type: string + identity: + type: string + description: The identity of the client who initiated this request + requestId: + type: string + description: A unique identifier for this start request. Typically UUIDv4. + activityId: + type: string + activityType: + $ref: '#/components/schemas/ActivityType' + taskQueue: + allOf: + - $ref: '#/components/schemas/TaskQueue' + description: Task queue to schedule this activity on. + scheduleToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Indicates how long the caller is willing to wait for an activity completion. Limits how long + retries will be attempted. Either this or `start_to_close_timeout` must be specified. + + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + scheduleToStartTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Limits time an activity task can stay in a task queue before a worker picks it up. This + timeout is always non retryable, as all a retry would achieve is to put it back into the same + queue. Defaults to `schedule_to_close_timeout` if not specified. + + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + startToCloseTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: |- + Maximum time an activity is allowed to execute after being picked up by a worker. This + timeout is always retryable. Either this or `schedule_to_close_timeout` must be + specified. + + (-- api-linter: core::0140::prepositions=disabled + aip.dev/not-precedent: "to" is used to indicate interval. --) + heartbeatTimeout: + pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$ + type: string + description: Maximum permitted time between successful worker heartbeats. + retryPolicy: + allOf: + - $ref: '#/components/schemas/RetryPolicy' + description: The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + input: + allOf: + - $ref: '#/components/schemas/Payloads' + description: Serialized arguments to the activity. These are passed as arguments to the activity function. + idReusePolicy: + enum: + - ACTIVITY_ID_REUSE_POLICY_UNSPECIFIED + - ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE + - ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY + - ACTIVITY_ID_REUSE_POLICY_REJECT_DUPLICATE + type: string + description: |- + Defines whether to allow re-using the activity id from a previously *closed* activity. + The default policy is ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE. + format: enum + idConflictPolicy: + enum: + - ACTIVITY_ID_CONFLICT_POLICY_UNSPECIFIED + - ACTIVITY_ID_CONFLICT_POLICY_FAIL + - ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING + type: string + description: |- + Defines how to resolve an activity id conflict with a *running* activity. + The default policy is ACTIVITY_ID_CONFLICT_POLICY_FAIL. + format: enum + searchAttributes: + allOf: + - $ref: '#/components/schemas/SearchAttributes' + description: Search attributes for indexing. + header: + allOf: + - $ref: '#/components/schemas/Header' + description: Header for context propagation and tracing purposes. + userMetadata: + allOf: + - $ref: '#/components/schemas/UserMetadata' + description: Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity. + priority: + allOf: + - $ref: '#/components/schemas/Priority' + description: Priority metadata. + StartActivityExecutionResponse: + type: object + properties: + runId: + type: string + description: The run ID of the activity that was started - or used (via ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING). + started: + type: boolean + description: If true, a new activity was started. StartBatchOperationRequest: type: object properties: @@ -12708,6 +13730,25 @@ components: description: Last time versioning information of this Task Queue changed. format: date-time description: Experimental. Worker Deployments are experimental and might significantly change in the future. + TerminateActivityExecutionRequest: + type: object + properties: + namespace: + type: string + activityId: + type: string + runId: + type: string + description: Activity run ID, targets the latest run if run_id is empty. + reason: + type: string + description: Reason for requesting the termination, recorded in in the activity's result failure outcome. + identity: + type: string + description: The identity of the worker/client. + TerminateActivityExecutionResponse: + type: object + properties: {} TerminateWorkflowExecutionRequest: type: object properties: diff --git a/temporal/api/activity/v1/message.proto b/temporal/api/activity/v1/message.proto index e70e814b4..394bb6b94 100644 --- a/temporal/api/activity/v1/message.proto +++ b/temporal/api/activity/v1/message.proto @@ -9,10 +9,16 @@ option java_outer_classname = "MessageProto"; option ruby_package = "Temporalio::Api::Activity::V1"; option csharp_namespace = "Temporalio.Api.Activity.V1"; +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + import "temporal/api/common/v1/message.proto"; +import "temporal/api/deployment/v1/message.proto"; +import "temporal/api/enums/v1/activity.proto"; +import "temporal/api/enums/v1/workflow.proto"; +import "temporal/api/failure/v1/message.proto"; import "temporal/api/taskqueue/v1/message.proto"; - -import "google/protobuf/duration.proto"; +import "temporal/api/sdk/v1/user_metadata.proto"; message ActivityOptions { temporal.api.taskqueue.v1.TaskQueue task_queue = 1; @@ -40,6 +46,111 @@ message ActivityOptions { google.protobuf.Duration start_to_close_timeout = 4; // Maximum permitted time between successful worker heartbeats. google.protobuf.Duration heartbeat_timeout = 5; - + // The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. temporal.api.common.v1.RetryPolicy retry_policy = 6; -} \ No newline at end of file +} + +// Information about a standalone activity. +message ActivityExecutionInfo { + // Unique identifier of this activity within its namespace along with run ID (below). + string activity_id = 1; + string run_id = 2; + + // The type of the activity, a string that maps to a registered activity on a worker. + temporal.api.common.v1.ActivityType activity_type = 3; + // A general status for this activity, indicates whether it is currently running or in one of the terminal statuses. + temporal.api.enums.v1.ActivityExecutionStatus status = 4; + // More detailed breakdown of ACTIVITY_EXECUTION_STATUS_RUNNING. + temporal.api.enums.v1.PendingActivityState run_state = 5; + // Details provided in the last recorded activity heartbeat. + temporal.api.common.v1.Payloads heartbeat_details = 6; + // Time the last heartbeat was recorded. + google.protobuf.Timestamp last_heartbeat_time = 7; + // Time the last attempt was started. + google.protobuf.Timestamp last_started_time = 8; + // The attempt this activity is currently on. + // Incremented each time a new attempt is started. + // TODO(dandavison): Confirm if this is on scheduled or started. + int32 attempt = 9; + int32 maximum_attempts = 10; + // Time the activity was originally scheduled via a StartActivityExecution request. + google.protobuf.Timestamp scheduled_time = 11; + // Scheduled time + schedule to close timeout. + google.protobuf.Timestamp expiration_time = 12; + // Failure details from the last failed attempt. + temporal.api.failure.v1.Failure last_failure = 13; + string last_worker_identity = 14; + + // Time from the last attempt failure to the next activity retry. + // If the activity is currently running, this represents the next retry interval in case the attempt fails. + // If activity is currently backing off between attempt, this represents the current retry interval. + // If there is no next retry allowed, this field will be null. + // This interval is typically calculated from the specified retry policy, but may be modified if an activity fails + // with a retryable application failure specifying a retry delay. + google.protobuf.Duration current_retry_interval = 15; + + // The time when the last activity attempt completed. If activity has not been completed yet, it will be null. + google.protobuf.Timestamp last_attempt_complete_time = 16; + + // The time when the next activity attempt will be scheduled. + // If activity is currently scheduled or started, this field will be null. + google.protobuf.Timestamp next_attempt_schedule_time = 17; + + // The Worker Deployment Version this activity was dispatched to most recently. + // If nil, the activity has not yet been dispatched or was last dispatched to an unversioned worker. + temporal.api.deployment.v1.WorkerDeploymentVersion last_deployment_version = 18; + + // Priority metadata. + temporal.api.common.v1.Priority priority = 19; + + // Current activity options. May be different from the one used to start the activity. + temporal.api.activity.v1.ActivityOptions activity_options = 20; + + // Incremented each time the activity's state is mutated in persistence. + int64 state_transition_count = 21; + + temporal.api.common.v1.SearchAttributes search_attributes = 22; + temporal.api.common.v1.Header header = 23; + // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity. + temporal.api.sdk.v1.UserMetadata user_metadata = 24; + + // Set if activity cancelation was requested. + string canceled_reason = 25; +} + +// Limited activity information returned in the list response. +// When adding fields here, ensure that it is also present in ActivityExecutionInfo (note that it +// may already be present in ActivityExecutionInfo but not at the top-level). +message ActivityExecutionListInfo { + // For standalone activity - a unique identifier of this activity within its namespace along with run ID (below). + string activity_id = 1; + // The run ID of the workflow or standalone activity. + string run_id = 2; + // Workflow that contains this activity - only present for workflow activity. + string workflow_id = 3; + + // The type of the activity, a string that maps to a registered activity on a worker. + temporal.api.common.v1.ActivityType activity_type = 4; + // Time the activity was originally scheduled via a StartActivityExecution request. + // TODO: Workflows call this schedule_time but it's scheduled_time in PendingActivityInfo, what should we choose for + // consistency? + google.protobuf.Timestamp scheduled_time = 5; + // If the activity is in a terminal status, this field represents the time the activity transitioned to that status. + google.protobuf.Timestamp close_time = 6; + // Only scheduled and terminal statuses appear here. More detailed information in PendingActivityInfo but not + // available in the list response. + temporal.api.enums.v1.ActivityExecutionStatus status = 7; + + // Search attributes from the start request. + temporal.api.common.v1.SearchAttributes search_attributes = 8; + + // The task queue this activity was scheduled on when it was originally started, updated on activity options update. + string task_queue = 9; + // Updated on terminal status. + int64 state_transition_count = 10; + // Updated once on scheduled and once on terminal status. + int64 state_size_bytes = 11; + // The difference between close time and scheduled time. + // This field is only populated if the activity is closed. + google.protobuf.Duration execution_duration = 12; +} diff --git a/temporal/api/common/v1/message.proto b/temporal/api/common/v1/message.proto index 838f5fefc..33e3a48c0 100644 --- a/temporal/api/common/v1/message.proto +++ b/temporal/api/common/v1/message.proto @@ -232,9 +232,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; } } @@ -338,4 +346,3 @@ message WorkerSelector { string worker_instance_key = 1; } } - diff --git a/temporal/api/enums/v1/activity.proto b/temporal/api/enums/v1/activity.proto new file mode 100644 index 000000000..8a6e09f3e --- /dev/null +++ b/temporal/api/enums/v1/activity.proto @@ -0,0 +1,68 @@ +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 = "ActivityProto"; +option ruby_package = "Temporalio::Api::Enums::V1"; +option csharp_namespace = "Temporalio.Api.Enums.V1"; + +// Status of a standalone activity. +// The status is updated once, when the activity is originally scheduled, and again when the activity reaches a terminal +// status. +// TODO: Should this be a common execution status? Seems like the other archetypes will share this status. +// (-- api-linter: core::0216::synonyms=disabled +// aip.dev/not-precedent: Named consistently with WorkflowExecutionStatus. --) +enum ActivityExecutionStatus { + ACTIVITY_EXECUTION_STATUS_UNSPECIFIED = 0; + // The activity is not in a terminal status. This does not necessarily mean that there is a currently running + // attempt. The activity may be backing off between attempts or waiting for a worker to pick it up. + ACTIVITY_EXECUTION_STATUS_RUNNING = 1; + // The activity completed successfully. + ACTIVITY_EXECUTION_STATUS_COMPLETED = 2; + // The activity completed with failure. + ACTIVITY_EXECUTION_STATUS_FAILED = 3; + // The activity completed as canceled. + // Requesting to cancel an activity does not automatically transition the activity to canceled status. If the + // activity has a currently running attempt, the activity will only transition to canceled status if the current + // attempt is unsuccessful. + // TODO: Clarify what happens if there are no more allowed retries after the current attempt. + ACTIVITY_EXECUTION_STATUS_CANCELED = 4; + // The activity was terminated. Termination does not reach the worker and the activity code cannot react to it. + // A terminated activity may have a running attempt and will be requested to be canceled by the server when it + // heartbeats. + ACTIVITY_EXECUTION_STATUS_TERMINATED = 5; + // The activity has timed out by reaching the specified shedule-to-start or schedule-to-close timeouts. + // TODO: Clarify if there are other conditions where the activity can end up in timed out status. + ACTIVITY_EXECUTION_STATUS_TIMED_OUT = 6; +} + +// Defines whether to allow re-using an activity ID from a previously *closed* activity. +// If the request is denied, the server returns an `ActivityExecutionAlreadyStarted` error. +// +// See `ActivityIdConflictPolicy` for handling ID duplication with a *running* activity. +enum ActivityIdReusePolicy { + ACTIVITY_ID_REUSE_POLICY_UNSPECIFIED = 0; + // Always allow starting an activity using the same activity ID. + ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE = 1; + // Allow starting an activity using the same ID only when the last activity's final state is one + // of {failed, canceled, terminated, timed out}. + ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY = 2; + // Do not permit re-use of the ID for this activity. Future start requests could potentially change the policy, + // allowing re-use of the ID. + ACTIVITY_ID_REUSE_POLICY_REJECT_DUPLICATE = 3; +} + +// Defines what to do when trying to start an activity with the same ID as a *running* activity. +// Note that it is *never* valid to have two running instances of the same activity ID. +// +// See `ActivityIdReusePolicy` for handling activity ID duplication with a *closed* activity. +enum ActivityIdConflictPolicy { + ACTIVITY_ID_CONFLICT_POLICY_UNSPECIFIED = 0; + // Don't start a new activity; instead return `ActivityExecutionAlreadyStarted` error. + ACTIVITY_ID_CONFLICT_POLICY_FAIL = 1; + // Don't start a new activity; instead return a handle for the running activity. + ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING = 2; +} diff --git a/temporal/api/errordetails/v1/message.proto b/temporal/api/errordetails/v1/message.proto index 315d30c57..c01e90e2c 100644 --- a/temporal/api/errordetails/v1/message.proto +++ b/temporal/api/errordetails/v1/message.proto @@ -121,3 +121,11 @@ message MultiOperationExecutionFailure { repeated google.protobuf.Any details = 3; } } + +// An error indicating that an activity execution failed to start. Returned when there is an existing activity with the +// given activity ID, and the given ID reuse and conflict policies do not permit starting a new one or attaching to an +// existing one. +message ActivityExecutionAlreadyStartedFailure { + string start_request_id = 1; + string run_id = 2; +} diff --git a/temporal/api/workflowservice/v1/request_response.proto b/temporal/api/workflowservice/v1/request_response.proto index 69b673c81..d18f1868c 100644 --- a/temporal/api/workflowservice/v1/request_response.proto +++ b/temporal/api/workflowservice/v1/request_response.proto @@ -19,6 +19,7 @@ import "temporal/api/enums/v1/reset.proto"; import "temporal/api/enums/v1/task_queue.proto"; import "temporal/api/enums/v1/deployment.proto"; import "temporal/api/enums/v1/update.proto"; +import "temporal/api/enums/v1/activity.proto"; import "temporal/api/activity/v1/message.proto"; import "temporal/api/common/v1/message.proto"; import "temporal/api/history/v1/message.proto"; @@ -455,6 +456,7 @@ message PollActivityTaskQueueResponse { // The autogenerated or user specified identifier of this activity. Can be used to complete the // activity via `RespondActivityTaskCompletedById`. May be re-used as long as the last usage // has resolved, but unique IDs for every activity invocation is a good idea. + // Note that only a workflow activity ID may be autogenerated. string activity_id = 6; // Headers specified by the scheduling workflow. Commonly used to propagate contextual info // from the workflow to its activities. For example, tracing contexts. @@ -520,9 +522,10 @@ message RecordActivityTaskHeartbeatResponse { message RecordActivityTaskHeartbeatByIdRequest { // Namespace of the workflow which scheduled this activity string namespace = 1; - // Id of the workflow which scheduled this activity + // Id of the workflow which scheduled this activity, leave empty to target a standalone activity string workflow_id = 2; - // Run Id of the workflow which scheduled this activity + // For a workflow activity - the run ID of the workflow which scheduled this activity. + // For a standalone activity - the run ID of the activity. string run_id = 3; // Id of the activity we're heartbeating string activity_id = 4; @@ -572,9 +575,10 @@ message RespondActivityTaskCompletedResponse { message RespondActivityTaskCompletedByIdRequest { // Namespace of the workflow which scheduled this activity string namespace = 1; - // Id of the workflow which scheduled this activity + // Id of the workflow which scheduled this activity, leave empty to target a standalone activity string workflow_id = 2; - // Run Id of the workflow which scheduled this activity + // For a workflow activity - the run ID of the workflow which scheduled this activity. + // For a standalone activity - the run ID of the activity. string run_id = 3; // Id of the activity to complete string activity_id = 4; @@ -619,9 +623,10 @@ message RespondActivityTaskFailedResponse { message RespondActivityTaskFailedByIdRequest { // Namespace of the workflow which scheduled this activity string namespace = 1; - // Id of the workflow which scheduled this activity + // Id of the workflow which scheduled this activity, leave empty to target a standalone activity string workflow_id = 2; - // Run Id of the workflow which scheduled this activity + // For a workflow activity - the run ID of the workflow which scheduled this activity. + // For a standalone activity - the run ID of the activity. string run_id = 3; // Id of the activity to fail string activity_id = 4; @@ -666,9 +671,10 @@ message RespondActivityTaskCanceledResponse { message RespondActivityTaskCanceledByIdRequest { // Namespace of the workflow which scheduled this activity string namespace = 1; - // Id of the workflow which scheduled this activity + // Id of the workflow which scheduled this activity, leave empty to target a standalone activity string workflow_id = 2; - // Run Id of the workflow which scheduled this activity + // For a workflow activity - the run ID of the workflow which scheduled this activity. + // For a standalone activity - the run ID of the activity. string run_id = 3; // Id of the activity to confirm is cancelled string activity_id = 4; @@ -2651,3 +2657,208 @@ message UnpauseWorkflowExecutionRequest { // Response to a successful UnpauseWorkflowExecution request. message UnpauseWorkflowExecutionResponse { } + +message StartActivityExecutionRequest { + string namespace = 1; + // The identity of the client who initiated this request + string identity = 2; + // A unique identifier for this start request. Typically UUIDv4. + string request_id = 3; + + string activity_id = 4; + temporal.api.common.v1.ActivityType activity_type = 5; + + // Task queue to schedule this activity on. + temporal.api.taskqueue.v1.TaskQueue task_queue = 6; + // Indicates how long the caller is willing to wait for an activity completion. Limits how long + // retries will be attempted. Either this or `start_to_close_timeout` must be specified. + // + // (-- api-linter: core::0140::prepositions=disabled + // aip.dev/not-precedent: "to" is used to indicate interval. --) + google.protobuf.Duration schedule_to_close_timeout = 7; + // Limits time an activity task can stay in a task queue before a worker picks it up. This + // timeout is always non retryable, as all a retry would achieve is to put it back into the same + // queue. Defaults to `schedule_to_close_timeout` if not specified. + // + // (-- api-linter: core::0140::prepositions=disabled + // aip.dev/not-precedent: "to" is used to indicate interval. --) + google.protobuf.Duration schedule_to_start_timeout = 8; + // Maximum time an activity is allowed to execute after being picked up by a worker. This + // timeout is always retryable. Either this or `schedule_to_close_timeout` must be + // specified. + // + // (-- api-linter: core::0140::prepositions=disabled + // aip.dev/not-precedent: "to" is used to indicate interval. --) + google.protobuf.Duration start_to_close_timeout = 9; + // Maximum permitted time between successful worker heartbeats. + google.protobuf.Duration heartbeat_timeout = 10; + // The retry policy for the activity. Will never exceed `schedule_to_close_timeout`. + temporal.api.common.v1.RetryPolicy retry_policy = 11; + + // Serialized arguments to the activity. These are passed as arguments to the activity function. + temporal.api.common.v1.Payloads input = 12; + + // Defines whether to allow re-using the activity id from a previously *closed* activity. + // The default policy is ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE. + temporal.api.enums.v1.ActivityIdReusePolicy id_reuse_policy = 13; + // Defines how to resolve an activity id conflict with a *running* activity. + // The default policy is ACTIVITY_ID_CONFLICT_POLICY_FAIL. + temporal.api.enums.v1.ActivityIdConflictPolicy id_conflict_policy = 14; + + // Search attributes for indexing. + temporal.api.common.v1.SearchAttributes search_attributes = 15; + // Header for context propagation and tracing purposes. + temporal.api.common.v1.Header header = 16; + // Metadata for use by user interfaces to display the fixed as-of-start summary and details of the activity. + temporal.api.sdk.v1.UserMetadata user_metadata = 17; + // Priority metadata. + temporal.api.common.v1.Priority priority = 18; +} + +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; +} + +message DescribeActivityExecutionRequest { + string namespace = 1; + string activity_id = 2; + // Activity run ID. If empty the request targets the latest run. + string run_id = 3; + // Include the input field in the response. + bool include_input = 4; + // Include the outcome (result/failure) in the response if the activity has completed. + bool include_outcome = 5; + // Token from a previous DescribeActivityExecutionResponse. If present, long-poll until activity + // state changes from the state encoded in this token. If absent, return current state immediately. + // If present, run_id must also be present. + // Note that activity state may change multiple times between requests, therefore it is not + // guaranteed that a client making a sequence of long-poll requests will see a complete + // sequence of state changes. + bytes long_poll_token = 6; +} + +message DescribeActivityExecutionResponse { + // The run ID of the activity, useful when run_id was not specified in the request. + string run_id = 1; + + // Information about the activity execution. + temporal.api.activity.v1.ActivityExecutionInfo info = 2; + + // Serialized activity input, passed as arguments to the activity function. + // Only set if include_input was true in the request. + temporal.api.common.v1.Payloads input = 3; + + // Only set if the activity is completed and include_outcome was true in the request. + oneof outcome { + // The result if the activity completed successfully. + temporal.api.common.v1.Payloads result = 4; + // The failure if the activity completed unsuccessfully. + temporal.api.failure.v1.Failure failure = 5; + } + + // Token for follow-on long-poll requests. Absent only if the activity is complete. + bytes long_poll_token = 6; +} + +message GetActivityExecutionOutcomeRequest { + string namespace = 1; + string activity_id = 2; + // Activity run ID. If empty the request targets the latest run. + string run_id = 3; +} + +message GetActivityExecutionOutcomeResponse { + // The run ID of the activity, useful when run_id was not specified in the request. + string run_id = 1; + + oneof outcome { + // The result if the activity completed successfully. + temporal.api.common.v1.Payloads result = 2; + // The failure if the activity completed unsuccessfully. + temporal.api.failure.v1.Failure failure = 3; + } +} + +message ListActivityExecutionsRequest { + string namespace = 1; + // Max number of executions to return per page. + int32 page_size = 2; + // Token returned in ListActivityExecutionsResponse. + bytes next_page_token = 3; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + string query = 4; +} + +message ListActivityExecutionsResponse { + repeated temporal.api.activity.v1.ActivityExecutionListInfo executions = 1; + // Token to use to fetch the next page. If empty, there is no next page. + bytes next_page_token = 2; +} + +message CountActivityExecutionsRequest { + string namespace = 1; + // Visibility query, see https://docs.temporal.io/list-filter for the syntax. + string query = 2; +} + +message CountActivityExecutionsResponse { + // If `query` is not grouping by any field, the count is an approximate number + // of activities that match the query. + // If `query` is grouping by a field, the count is simply the sum of the counts + // of the groups returned in the response. This number can be smaller than the + // total number of activities matching the query. + int64 count = 1; + + // Contains the groups if the request is grouping by a field. + // The list might not be complete, and the counts of each group is approximate. + repeated AggregationGroup groups = 2; + + message AggregationGroup { + repeated temporal.api.common.v1.Payload group_values = 1; + int64 count = 2; + } +} + +message RequestCancelActivityExecutionRequest { + string namespace = 1; + string activity_id = 2; + // Activity run ID, targets the latest run if run_id is empty. + string run_id = 3; + // The identity of the worker/client. + string identity = 4; + // Used to de-dupe cancellation requests. + string request_id = 5; + // Reason for requesting the cancellation, recorded and available via the PollActivityExecution API. + // Not propagated to a worker if an activity attempt is currently running. + string reason = 6; +} + +message RequestCancelActivityExecutionResponse { +} + +message TerminateActivityExecutionRequest { + string namespace = 1; + string activity_id = 2; + // Activity run ID, targets the latest run if run_id is empty. + string run_id = 3; + // Reason for requesting the termination, recorded in in the activity's result failure outcome. + string reason = 4; + // The identity of the worker/client. + string identity = 5; +} + +message TerminateActivityExecutionResponse { +} + +message DeleteActivityExecutionRequest { + string namespace = 1; + string activity_id = 2; + // Activity run ID, targets the latest run if run_id is empty. + string run_id = 3; +} + +message DeleteActivityExecutionResponse { +} diff --git a/temporal/api/workflowservice/v1/service.proto b/temporal/api/workflowservice/v1/service.proto index 33304937a..4f940c350 100644 --- a/temporal/api/workflowservice/v1/service.proto +++ b/temporal/api/workflowservice/v1/service.proto @@ -253,7 +253,7 @@ service WorkflowService { }; } - // See `RecordActivityTaskCompleted`. This version allows clients to record completions by + // See `RespondActivityTaskCompleted`. This version allows clients to record completions by // namespace/workflow id/activity id instead of task token. // // (-- api-linter: core::0136::prepositions=disabled @@ -317,7 +317,7 @@ service WorkflowService { }; } - // See `RecordActivityTaskCanceled`. This version allows clients to record failures by + // See `RespondActivityTaskCanceled`. This version allows clients to record failures by // namespace/workflow id/activity id instead of task token. // // (-- api-linter: core::0136::prepositions=disabled @@ -1024,6 +1024,8 @@ service WorkflowService { // UpdateActivityOptions is called by the client to update the options of an activity by its ID or type. // If there are multiple pending activities of the provided type - all of them will be updated. + // This API will be deprecated soon and replaced with a newer UpdateActivityExecutionOptions that is better named and + // structured to work well for standalone activities. rpc UpdateActivityOptions (UpdateActivityOptionsRequest) returns (UpdateActivityOptionsResponse) { option (google.api.http) = { post: "/namespaces/{namespace}/activities/update-options" @@ -1063,6 +1065,8 @@ service WorkflowService { // - The activity should respond to the cancellation accordingly. // // Returns a `NotFound` error if there is no pending activity with the provided ID or type + // This API will be deprecated soon and replaced with a newer PauseActivityExecution that is better named and + // structured to work well for standalone activities. rpc PauseActivity (PauseActivityRequest) returns (PauseActivityResponse) { option (google.api.http) = { post: "/namespaces/{namespace}/activities/pause" @@ -1087,6 +1091,8 @@ service WorkflowService { // 'reset_heartbeat': the activity heartbeat timer and heartbeats will be reset. // // Returns a `NotFound` error if there is no pending activity with the provided ID or type + // This API will be deprecated soon and replaced with a newer UnpauseActivityExecution that is better named and + // structured to work well for standalone activities. rpc UnpauseActivity (UnpauseActivityRequest) returns (UnpauseActivityResponse) { option (google.api.http) = { post: "/namespaces/{namespace}/activities/unpause" @@ -1115,6 +1121,8 @@ service WorkflowService { // 'keep_paused': if the activity is paused, it will remain paused. // // Returns a `NotFound` error if there is no pending activity with the provided ID or type. + // This API will be deprecated soon and replaced with a newer ResetActivityExecution that is better named and + // structured to work well for standalone activities. rpc ResetActivity (ResetActivityRequest) returns (ResetActivityResponse) { option (google.api.http) = { post: "/namespaces/{namespace}/activities/reset" @@ -1287,4 +1295,108 @@ service WorkflowService { body: "*" }; } + + // StartActivityExecution starts a new activity execution. + // + // Returns an `ExecutionAlreadyStarted` error if an instance already exists with same activity ID in this namespace + // unless permitted by the specified ID conflict policy. + rpc StartActivityExecution (StartActivityExecutionRequest) returns (StartActivityExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/activities/{activity_id}" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/activities/{activity_id}" + body: "*" + } + }; + } + + // DescribeActivityExecution returns information about an activity execution. + // Supported use cases include: + // - Get current activity info without waiting + // - Long-poll for next state change and return new activity info + // Response can optionally include activity input or outcome (if the activity has completed). + rpc DescribeActivityExecution (DescribeActivityExecutionRequest) returns (DescribeActivityExecutionResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/activities/{activity_id}" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/activities/{activity_id}" + } + }; + } + + // GetActivityExecutionOutcome long-polls for an activity execution to complete and returns + // the outcome (result or failure). + rpc GetActivityExecutionOutcome (GetActivityExecutionOutcomeRequest) returns (GetActivityExecutionOutcomeResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/activities/{activity_id}/outcome" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/activities/{activity_id}/outcome" + } + }; + } + + // ListActivityExecutions is a visibility API to list activity executions in a specific namespace. + rpc ListActivityExecutions (ListActivityExecutionsRequest) returns (ListActivityExecutionsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/activities" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/activities" + } + }; + } + + // CountActivityExecutions is a visibility API to count of activity executions in a specific namespace. + rpc CountActivityExecutions (CountActivityExecutionsRequest) returns (CountActivityExecutionsResponse) { + option (google.api.http) = { + get: "/namespaces/{namespace}/activity-count" + additional_bindings { + get: "/api/v1/namespaces/{namespace}/activity-count" + } + }; + } + + // RequestCancelActivityExecution requests cancellation of an activity execution. + // + // Requesting to cancel an activity does not automatically transition the activity to canceled status. If the + // activity has a currently running attempt, the activity will only transition to canceled status if the current + // attempt is unsuccessful. + // TODO: Clarify what happens if there are no more allowed retries after the current attempt. + // + // It returns success if the requested activity is already closed. + // TODO: This ^^ is copied from RequestCancelWorkflowExecution, do we want to preserve this behavior? + rpc RequestCancelActivityExecution (RequestCancelActivityExecutionRequest) returns (RequestCancelActivityExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/activities/{activity_id}/cancel" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/activities/{activity_id}/cancel" + body: "*" + } + }; + } + + // TerminateActivityExecution terminates an existing activity execution immediately. + // + // Termination does not reach the worker and the activity code cannot react to it. A terminated activity may have a + // running attempt and will be requested to be canceled by the server when it heartbeats. + rpc TerminateActivityExecution (TerminateActivityExecutionRequest) returns (TerminateActivityExecutionResponse) { + option (google.api.http) = { + post: "/namespaces/{namespace}/activities/{activity_id}/terminate" + body: "*" + additional_bindings { + post: "/api/v1/namespaces/{namespace}/activities/{activity_id}/terminate" + body: "*" + } + }; + } + + // DeleteActivityExecution asynchronously deletes a specific activity execution (when + // ActivityExecution.run_id is provided) or the latest activity execution (when + // ActivityExecution.run_id is not provided). If the activity EXecution is running, it will be + // terminated before deletion. + // + // (-- api-linter: core::0127::http-annotation=disabled + // aip.dev/not-precedent: Activity deletion not exposed to HTTP, users should use cancel or terminate. --) + rpc DeleteActivityExecution (DeleteActivityExecutionRequest) returns (DeleteActivityExecutionResponse) {} }