Add WorkflowIdCollisionPolicy

openapi/openapiv2.json

@@ -2438,7 +2438,8 @@
           "title": "Used to de-dupe signal w/ start requests"
         },
         "workflowIdReusePolicy": {
-          "$ref": "#/definitions/v1WorkflowIdReusePolicy"
+          "$ref": "#/definitions/v1WorkflowIdReusePolicy",
+          "title": "Defines whether to allow re-using the ID from a previously closed workflow.\nDefault: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE"
         },
         "signalInput": {
           "$ref": "#/definitions/v1Payloads",
@@ -2472,6 +2473,10 @@
         "skipGenerateWorkflowTask": {
           "type": "boolean",
           "description": "Indicates that a new workflow task should not be generated when this signal is received."
+        },
+        "collisionPolicy": {
+          "$ref": "#/definitions/v1WorkflowIdCollisionPolicy",
+          "title": "Defines how to resolve an ID conflict with a running workflow.\nDefault: WORKFLOW_ID_COLLISION_POLICY_FAIL"
         }
       }
     },
@@ -2589,7 +2594,7 @@
         },
         "workflowIdReusePolicy": {
           "$ref": "#/definitions/v1WorkflowIdReusePolicy",
-          "description": "Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE."
+          "title": "Defines whether to allow re-using the ID from a previously closed workflow.\nDefault: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE"
         },
         "retryPolicy": {
           "$ref": "#/definitions/v1RetryPolicy",
@@ -2630,6 +2635,10 @@
             "$ref": "#/definitions/v1Callback"
           },
           "description": "Callbacks to be called by the server when this workflow reaches a terminal state.\nIf the workflow continues-as-new, these callbacks will be carried over to the new execution.\nCallback addresses must be whitelisted in the server's dynamic configuration."
+        },
+        "collisionPolicy": {
+          "$ref": "#/definitions/v1WorkflowIdCollisionPolicy",
+          "title": "Defines how to resolve an ID conflict with a running workflow.\nDefault: WORKFLOW_ID_COLLISION_POLICY_FAIL"
         }
       }
     },
@@ -7968,6 +7977,17 @@
         }
       }
     },
+    "v1WorkflowIdCollisionPolicy": {
+      "type": "string",
+      "enum": [
+        "WORKFLOW_ID_COLLISION_POLICY_UNSPECIFIED",
+        "WORKFLOW_ID_COLLISION_POLICY_FAIL",
+        "WORKFLOW_ID_COLLISION_POLICY_USE_EXISTING",
+        "WORKFLOW_ID_COLLISION_POLICY_TERMINATE_EXISTING"
+      ],
+      "default": "WORKFLOW_ID_COLLISION_POLICY_UNSPECIFIED",
+      "description": "Defines what to do when trying to start a workflow with the same ID as a *running* workflow.\nNote that it is *never* valid to have two actively running instances of the same workflow id.\n\nSee `WorkflowIdReusePolicy` for the policy for a *closed* workflow.\n\n - WORKFLOW_ID_COLLISION_POLICY_FAIL: Don't start a new workflow; instead return `WorkflowExecutionAlreadyStartedFailure`.\n - WORKFLOW_ID_COLLISION_POLICY_USE_EXISTING: Don't start a new workflow; instead return a workflow handle for the running workflow.\n - WORKFLOW_ID_COLLISION_POLICY_TERMINATE_EXISTING: Terminate the running Workflow before starting a new one."
+    },
     "v1WorkflowIdReusePolicy": {
       "type": "string",
       "enum": [
@@ -7978,7 +7998,7 @@
         "WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING"
       ],
       "default": "WORKFLOW_ID_REUSE_POLICY_UNSPECIFIED",
-      "description": "Defines how new runs of a workflow with a particular ID may or may not be allowed. Note that\nit is *never* valid to have two actively running instances of the same workflow id.\n\n - WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE: Allow starting a workflow execution using the same workflow id.\n - WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY: Allow starting a workflow execution using the same workflow id, only when the last\nexecution's final state is one of [terminated, cancelled, timed out, failed].\n - WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE: Do not permit re-use of the workflow id for this workflow. Future start workflow requests\ncould potentially change the policy, allowing re-use of the workflow id.\n - WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING: If a workflow is running using the same workflow ID, terminate it and start a new one.\nIf no running workflow, then the behavior is the same as ALLOW_DUPLICATE"
+      "description": "Defines whether to allow re-using an ID from a previously *closed* workflow.\nIf the request is denied, a `WorkflowExecutionAlreadyStartedFailure` is returned.\n\nSee `WorkflowIdCollisionPolicy` for the policy for a *running* workflow.\n\n - WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE: Allow starting a workflow execution using the same workflow id.\n - WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY: Allow starting a workflow execution using the same workflow id, only when the last\nexecution's final state is one of [terminated, cancelled, timed out, failed].\n - WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE: Do not permit re-use of the workflow id for this workflow. Future start workflow requests\ncould potentially change the policy, allowing re-use of the workflow id.\n - WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING: If a workflow is running using the same workflow ID, terminate it and start a new one.\nIf no running workflow, then the behavior is the same as ALLOW_DUPLICATE."
     },
     "v1WorkflowPropertiesModifiedEventAttributes": {
       "type": "object",

openapi/openapiv3.yaml

@@ -4710,6 +4710,9 @@ components:
             - WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE
             - WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING
           type: string
+          description: |-
+            Defines whether to allow re-using the ID from a previously closed workflow.
+             Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE
           format: enum
         signalName:
           type: string
@@ -4747,6 +4750,17 @@ components:
         skipGenerateWorkflowTask:
           type: boolean
           description: Indicates that a new workflow task should not be generated when this signal is received.
+        collisionPolicy:
+          enum:
+            - WORKFLOW_ID_COLLISION_POLICY_UNSPECIFIED
+            - WORKFLOW_ID_COLLISION_POLICY_FAIL
+            - WORKFLOW_ID_COLLISION_POLICY_USE_EXISTING
+            - WORKFLOW_ID_COLLISION_POLICY_TERMINATE_EXISTING
+          type: string
+          description: |-
+            Defines how to resolve an ID conflict with a running workflow.
+             Default: WORKFLOW_ID_COLLISION_POLICY_FAIL
+          format: enum
     SignalWithStartWorkflowExecutionResponse:
       type: object
       properties:
@@ -4977,7 +4991,9 @@ components:
             - WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE
             - WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING
           type: string
-          description: 'Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.'
+          description: |-
+            Defines whether to allow re-using the ID from a previously closed workflow.
+             Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE
           format: enum
         retryPolicy:
           allOf:
@@ -5024,6 +5040,17 @@ components:
             Callbacks to be called by the server when this workflow reaches a terminal state.
              If the workflow continues-as-new, these callbacks will be carried over to the new execution.
              Callback addresses must be whitelisted in the server's dynamic configuration.
+        collisionPolicy:
+          enum:
+            - WORKFLOW_ID_COLLISION_POLICY_UNSPECIFIED
+            - WORKFLOW_ID_COLLISION_POLICY_FAIL
+            - WORKFLOW_ID_COLLISION_POLICY_USE_EXISTING
+            - WORKFLOW_ID_COLLISION_POLICY_TERMINATE_EXISTING
+          type: string
+          description: |-
+            Defines how to resolve an ID conflict with a running workflow.
+             Default: WORKFLOW_ID_COLLISION_POLICY_FAIL
+          format: enum
     StartWorkflowExecutionResponse:
       type: object
       properties:

temporal/api/enums/v1/workflow.proto

@@ -31,8 +31,10 @@ option java_outer_classname = "WorkflowProto";
 option ruby_package = "Temporalio::Api::Enums::V1";
 option csharp_namespace = "Temporalio.Api.Enums.V1";
 
-// Defines how new runs of a workflow with a particular ID may or may not be allowed. Note that
-// it is *never* valid to have two actively running instances of the same workflow id.
+// Defines whether to allow re-using an ID from a previously *closed* workflow.
+// If the request is denied, a `WorkflowExecutionAlreadyStartedFailure` is returned.
+//
+// See `WorkflowIdCollisionPolicy` for the policy for a *running* workflow.
 enum WorkflowIdReusePolicy {
     WORKFLOW_ID_REUSE_POLICY_UNSPECIFIED = 0;
     // Allow starting a workflow execution using the same workflow id.
@@ -44,10 +46,24 @@ enum WorkflowIdReusePolicy {
     // could potentially change the policy, allowing re-use of the workflow id.
     WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE = 3;
     // If a workflow is running using the same workflow ID, terminate it and start a new one.
-    // If no running workflow, then the behavior is the same as ALLOW_DUPLICATE
+    // If no running workflow, then the behavior is the same as ALLOW_DUPLICATE.
     WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING = 4;
 }
 
+// Defines what to do when trying to start a workflow with the same ID as a *running* workflow.
+// Note that it is *never* valid to have two actively running instances of the same workflow id.
+//
+// See `WorkflowIdReusePolicy` for the policy for a *closed* workflow.
+enum WorkflowIdCollisionPolicy {
+    WORKFLOW_ID_COLLISION_POLICY_UNSPECIFIED = 0;
+    // Don't start a new workflow; instead return `WorkflowExecutionAlreadyStartedFailure`.
+    WORKFLOW_ID_COLLISION_POLICY_FAIL = 1;
+    // Don't start a new workflow; instead return a workflow handle for the running workflow.
+    WORKFLOW_ID_COLLISION_POLICY_USE_EXISTING = 2;
+    // Terminate the running Workflow before starting a new one.
+    WORKFLOW_ID_COLLISION_POLICY_TERMINATE_EXISTING = 3;
+}
+
 // Defines how child workflows will react to their parent completing
 enum ParentClosePolicy {
     PARENT_CLOSE_POLICY_UNSPECIFIED = 0;

temporal/api/workflowservice/v1/request_response.proto

@@ -160,7 +160,8 @@ message StartWorkflowExecutionRequest {
     string identity = 9;
     // A unique identifier for this start request. Typically UUIDv4.
     string request_id = 10;
-    // Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.
+    // Defines whether to allow re-using the ID from a previously closed workflow.
+    // Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE
     temporal.api.enums.v1.WorkflowIdReusePolicy workflow_id_reuse_policy = 11;
     // The retry policy for the workflow. Will never exceed `workflow_execution_timeout`.
     temporal.api.common.v1.RetryPolicy retry_policy = 12;
@@ -184,11 +185,13 @@ message StartWorkflowExecutionRequest {
     // If the workflow gets a signal before the delay, a workflow task will be dispatched and the rest
     // of the delay will be ignored.
     google.protobuf.Duration workflow_start_delay = 20;
-
     // Callbacks to be called by the server when this workflow reaches a terminal state.
     // If the workflow continues-as-new, these callbacks will be carried over to the new execution.
     // Callback addresses must be whitelisted in the server's dynamic configuration.
     repeated temporal.api.common.v1.Callback completion_callbacks = 21;
+    // Defines how to resolve an ID conflict with a running workflow.
+    // Default: WORKFLOW_ID_COLLISION_POLICY_FAIL
+    temporal.api.enums.v1.WorkflowIdCollisionPolicy collision_policy = 22;
 }
 
 message StartWorkflowExecutionResponse {
@@ -637,6 +640,8 @@ message SignalWithStartWorkflowExecutionRequest {
     string identity = 9;
     // Used to de-dupe signal w/ start requests
     string request_id = 10;
+    // Defines whether to allow re-using the ID from a previously closed workflow.
+    // Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE
     temporal.api.enums.v1.WorkflowIdReusePolicy workflow_id_reuse_policy = 11;
     // The workflow author-defined name of the signal to send to the workflow
     string signal_name = 12;
@@ -660,6 +665,9 @@ message SignalWithStartWorkflowExecutionRequest {
     google.protobuf.Duration workflow_start_delay = 20;
     // Indicates that a new workflow task should not be generated when this signal is received.
     bool skip_generate_workflow_task = 21;
+    // Defines how to resolve an ID conflict with a running workflow.
+    // Default: WORKFLOW_ID_COLLISION_POLICY_FAIL
+    temporal.api.enums.v1.WorkflowIdCollisionPolicy collision_policy = 22;
 }
 
 message SignalWithStartWorkflowExecutionResponse {