Add WorkflowIdConflictPolicy

openapi/openapiv2.json

@@ -2438,7 +2438,12 @@
           "title": "Used to de-dupe signal w/ start requests"
         },
         "workflowIdReusePolicy": {
-          "$ref": "#/definitions/v1WorkflowIdReusePolicy"
+          "$ref": "#/definitions/v1WorkflowIdReusePolicy",
+          "description": "Defines whether to allow re-using the workflow id from a previously *closed* workflow.\nThe default policy is WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.\n\nSee `workflow_id_reuse_policy` for handling a workflow id duplication with a *running* workflow."
+        },
+        "workflowIdConflictPolicy": {
+          "$ref": "#/definitions/v1WorkflowIdConflictPolicy",
+          "description": "Defines how to resolve a workflow id conflict with a *running* workflow.\nThe default policy is WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING.\nNote that WORKFLOW_ID_CONFLICT_POLICY_FAIL is an invalid option.\n\nSee `workflow_id_reuse_policy` for handling a workflow id duplication with a *closed* workflow."
         },
         "signalInput": {
           "$ref": "#/definitions/v1Payloads",
@@ -2450,7 +2455,7 @@
         },
         "retryPolicy": {
           "$ref": "#/definitions/v1RetryPolicy",
-          "description": "Retry policy for the workflow Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE."
+          "title": "Retry policy for the workflow"
         },
         "cronSchedule": {
           "type": "string",
@@ -2589,7 +2594,11 @@
         },
         "workflowIdReusePolicy": {
           "$ref": "#/definitions/v1WorkflowIdReusePolicy",
-          "description": "Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE."
+          "description": "Defines whether to allow re-using the workflow id from a previously *closed* workflow.\nThe default policy is WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.\n\nSee `workflow_id_conflict_policy` for handling a workflow id duplication with a *running* workflow."
+        },
+        "workflowIdConflictPolicy": {
+          "$ref": "#/definitions/v1WorkflowIdConflictPolicy",
+          "description": "Defines how to resolve a workflow id conflict with a *running* workflow.\nThe default policy is WORKFLOW_ID_CONFLICT_POLICY_FAIL.\n\nSee `workflow_id_reuse_policy` for handling a workflow id duplication with a *closed* workflow."
         },
         "retryPolicy": {
           "$ref": "#/definitions/v1RetryPolicy",
@@ -6691,7 +6700,12 @@
       "type": "object",
       "properties": {
         "runId": {
-          "type": "string"
+          "type": "string",
+          "description": "The run id of the workflow that was started - or just signaled, if it was already running."
+        },
+        "started": {
+          "type": "boolean",
+          "description": "If true, a new workflow was started."
         }
       }
     },
@@ -6949,7 +6963,12 @@
       "type": "object",
       "properties": {
         "runId": {
-          "type": "string"
+          "type": "string",
+          "description": "The run id of the workflow that was started - or used (via WorkflowIdConflictPolicy USE_EXISTING)."
+        },
+        "started": {
+          "type": "boolean",
+          "description": "If true, a new workflow was started."
         },
         "eagerWorkflowTask": {
           "$ref": "#/definitions/v1PollWorkflowTaskQueueResponse",
@@ -7968,6 +7987,17 @@
         }
       }
     },
+    "v1WorkflowIdConflictPolicy": {
+      "type": "string",
+      "enum": [
+        "WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED",
+        "WORKFLOW_ID_CONFLICT_POLICY_FAIL",
+        "WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING",
+        "WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING"
+      ],
+      "default": "WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED",
+      "description": "Defines what to do when trying to start a workflow with the same workflow 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 handling workflow id duplication with a *closed* workflow.\n\n - WORKFLOW_ID_CONFLICT_POLICY_FAIL: Don't start a new workflow; instead return `WorkflowExecutionAlreadyStartedFailure`.\n - WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING: Don't start a new workflow; instead return a workflow handle for the running workflow.\n - WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING: Terminate the running workflow before starting a new one."
+    },
     "v1WorkflowIdReusePolicy": {
       "type": "string",
       "enum": [
@@ -7978,7 +8008,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 a workflow id from a previously *closed* workflow.\nIf the request is denied, a `WorkflowExecutionAlreadyStartedFailure` is returned.\n\nSee `WorkflowIdConflictPolicy` for handling workflow id duplication with 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: This option belongs in WorkflowIdConflictPolicy but is here for backwards compatibility.\nIf specified, it acts like ALLOW_DUPLICATE, but also the WorkflowId*Conflict*Policy on\nthe request is treated as WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING.\nIf no running workflow, then the behavior is the same as ALLOW_DUPLICATE."
     },
     "v1WorkflowPropertiesModifiedEventAttributes": {
       "type": "object",

openapi/openapiv3.yaml

@@ -4701,6 +4701,25 @@ components:
             - WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE
             - WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING
           type: string
+          description: |-
+            Defines whether to allow re-using the workflow id from a previously *closed* workflow.
+             The default policy is WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.
+
+             See `workflow_id_reuse_policy` for handling a workflow id duplication with a *running* workflow.
+          format: enum
+        workflowIdConflictPolicy:
+          enum:
+            - WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED
+            - WORKFLOW_ID_CONFLICT_POLICY_FAIL
+            - WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING
+            - WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING
+          type: string
+          description: |-
+            Defines how to resolve a workflow id conflict with a *running* workflow.
+             The default policy is WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING.
+             Note that WORKFLOW_ID_CONFLICT_POLICY_FAIL is an invalid option.
+
+             See `workflow_id_reuse_policy` for handling a workflow id duplication with a *closed* workflow.
           format: enum
         signalName:
           type: string
@@ -4715,7 +4734,7 @@ components:
         retryPolicy:
           allOf:
             - $ref: '#/components/schemas/RetryPolicy'
-          description: 'Retry policy for the workflow Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.'
+          description: Retry policy for the workflow
         cronSchedule:
           type: string
           description: See https://docs.temporal.io/docs/content/what-is-a-temporal-cron-job/
@@ -4743,6 +4762,10 @@ components:
       properties:
         runId:
           type: string
+          description: The run id of the workflow that was started - or just signaled, if it was already running.
+        started:
+          type: boolean
+          description: If true, a new workflow was started.
     SignalWorkflowExecutionRequest:
       type: object
       properties:
@@ -4968,7 +4991,24 @@ 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 workflow id from a previously *closed* workflow.
+             The default policy is WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.
+
+             See `workflow_id_conflict_policy` for handling a workflow id duplication with a *running* workflow.
+          format: enum
+        workflowIdConflictPolicy:
+          enum:
+            - WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED
+            - WORKFLOW_ID_CONFLICT_POLICY_FAIL
+            - WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING
+            - WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING
+          type: string
+          description: |-
+            Defines how to resolve a workflow id conflict with a *running* workflow.
+             The default policy is WORKFLOW_ID_CONFLICT_POLICY_FAIL.
+
+             See `workflow_id_reuse_policy` for handling a workflow id duplication with a *closed* workflow.
           format: enum
         retryPolicy:
           allOf:
@@ -5020,6 +5060,10 @@ components:
       properties:
         runId:
           type: string
+          description: The run id of the workflow that was started - or used (via WorkflowIdConflictPolicy USE_EXISTING).
+        started:
+          type: boolean
+          description: If true, a new workflow was started.
         eagerWorkflowTask:
           allOf:
             - $ref: '#/components/schemas/PollWorkflowTaskQueueResponse'

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 a workflow id from a previously *closed* workflow.
+// If the request is denied, a `WorkflowExecutionAlreadyStartedFailure` is returned.
+//
+// See `WorkflowIdConflictPolicy` for handling workflow id duplication with a *running* workflow.
 enum WorkflowIdReusePolicy {
     WORKFLOW_ID_REUSE_POLICY_UNSPECIFIED = 0;
     // Allow starting a workflow execution using the same workflow id.
@@ -43,11 +45,27 @@ enum WorkflowIdReusePolicy {
     // Do not permit re-use of the workflow id for this workflow. Future start workflow requests
     // 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
+    // This option belongs in WorkflowIdConflictPolicy but is here for backwards compatibility.
+    // If specified, it acts like ALLOW_DUPLICATE, but also the WorkflowId*Conflict*Policy on
+    // the request is treated as WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING.
+    // 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 workflow 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 handling workflow id duplication with a *closed* workflow.
+enum WorkflowIdConflictPolicy {
+    WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED = 0;
+    // Don't start a new workflow; instead return `WorkflowExecutionAlreadyStartedFailure`.
+    WORKFLOW_ID_CONFLICT_POLICY_FAIL = 1;
+    // Don't start a new workflow; instead return a workflow handle for the running workflow.
+    WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING = 2;
+    // Terminate the running workflow before starting a new one.
+    WORKFLOW_ID_CONFLICT_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

@@ -156,8 +156,16 @@ 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 workflow id from a previously *closed* workflow.
+    // The default policy is WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.
+    //
+    // See `workflow_id_conflict_policy` for handling a workflow id duplication with a *running* workflow.
     temporal.api.enums.v1.WorkflowIdReusePolicy workflow_id_reuse_policy = 11;
+    // Defines how to resolve a workflow id conflict with a *running* workflow.
+    // The default policy is WORKFLOW_ID_CONFLICT_POLICY_FAIL.
+    //
+    // See `workflow_id_reuse_policy` for handling a workflow id duplication with a *closed* workflow.
+    temporal.api.enums.v1.WorkflowIdConflictPolicy workflow_id_conflict_policy = 22;
     // The retry policy for the workflow. Will never exceed `workflow_execution_timeout`.
     temporal.api.common.v1.RetryPolicy retry_policy = 12;
     // See https://docs.temporal.io/docs/content/what-is-a-temporal-cron-job/
@@ -180,15 +188,17 @@ 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;
 }
 
 message StartWorkflowExecutionResponse {
+    // The run id of the workflow that was started - or used (via WorkflowIdConflictPolicy USE_EXISTING).
     string run_id = 1;
+    // If true, a new workflow was started.
+    bool started = 3;
     // When `request_eager_execution` is set on the `StartWorkflowExecutionRequest`, the server - if supported - will
     // return the first workflow task to be eagerly executed.
     // The caller is expected to have a worker available to process the task.
@@ -633,14 +643,24 @@ message SignalWithStartWorkflowExecutionRequest {
     string identity = 9;
     // Used to de-dupe signal w/ start requests
     string request_id = 10;
+    // Defines whether to allow re-using the workflow id from a previously *closed* workflow.
+    // The default policy is WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.
+    //
+    // See `workflow_id_reuse_policy` for handling a workflow id duplication with a *running* workflow.
     temporal.api.enums.v1.WorkflowIdReusePolicy workflow_id_reuse_policy = 11;
+    // Defines how to resolve a workflow id conflict with a *running* workflow.
+    // The default policy is WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING.
+    // Note that WORKFLOW_ID_CONFLICT_POLICY_FAIL is an invalid option.
+    //
+    // See `workflow_id_reuse_policy` for handling a workflow id duplication with a *closed* workflow.
+    temporal.api.enums.v1.WorkflowIdConflictPolicy workflow_id_conflict_policy = 22;
     // The workflow author-defined name of the signal to send to the workflow
     string signal_name = 12;
     // Serialized value(s) to provide with the signal
     temporal.api.common.v1.Payloads signal_input = 13;
     // Deprecated
     string control = 14;
-    // Retry policy for the workflow Default: WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE.
+    // Retry policy for the workflow
     temporal.api.common.v1.RetryPolicy retry_policy = 15;
     // See https://docs.temporal.io/docs/content/what-is-a-temporal-cron-job/
     string cron_schedule = 16;
@@ -659,7 +679,10 @@ message SignalWithStartWorkflowExecutionRequest {
 }
 
 message SignalWithStartWorkflowExecutionResponse {
+    // The run id of the workflow that was started - or just signaled, if it was already running.
     string run_id = 1;
+    // If true, a new workflow was started.
+    bool started = 2;
 }
 
 message ResetWorkflowExecutionRequest {