Add Callbacks and Links to Workflow Update

openapi/openapiv2.json

@@ -8650,9 +8650,21 @@
       "properties": {
         "workflowClosed": {
           "$ref": "#/definitions/CallbackInfoWorkflowClosed"
+        },
+        "updateWorkflowExecutionCompleted": {
+          "$ref": "#/definitions/CallbackInfoUpdateWorkflowExecutionCompleted"
         }
       }
     },
+    "CallbackInfoUpdateWorkflowExecutionCompleted": {
+      "type": "object",
+      "properties": {
+        "updateId": {
+          "type": "string"
+        }
+      },
+      "description": "Trigger for when a workflow update is completed."
+    },
     "CallbackInfoWorkflowClosed": {
       "type": "object",
       "description": "Trigger for when the workflow is closed."
@@ -8769,6 +8781,24 @@
       },
       "description": "A link to a built-in batch job.\nBatch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).\nThis link can be put on workflow history events generated by actions taken by a batch job."
     },
+    "LinkWorkflow": {
+      "type": "object",
+      "properties": {
+        "namespace": {
+          "type": "string"
+        },
+        "workflowId": {
+          "type": "string"
+        },
+        "runId": {
+          "type": "string"
+        },
+        "reason": {
+          "$ref": "#/definitions/v1LinkReason"
+        }
+      },
+      "description": "A link to a workflow execution. This is a more general version of WorkflowEvent that doesn't specify a \nparticular event within the workflow, useful when you want to link to a workflow but there is no particular event to link to,\nsuch as a Query or a Rejected Update."
+    },
     "LinkWorkflowEvent": {
       "type": "object",
       "properties": {
@@ -9103,6 +9133,23 @@
       },
       "description": "RequestIdReference is a indirect reference to a history event through the request ID."
     },
+    "WorkflowExecutionOptionsUpdatedEventAttributesWorkflowUpdateOptionsUpdate": {
+      "type": "object",
+      "properties": {
+        "attachedRequestId": {
+          "type": "string",
+          "title": "Request ID attached to the running workflow update so that subsequent requests with same\nrequest ID will be deduped"
+        },
+        "attachedCompletionCallbacks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Callback"
+          },
+          "description": "Completion callbacks attached to the running workflow update."
+        }
+      }
+    },
     "WorkflowRuleActionActionActivityPause": {
       "type": "object"
     },
@@ -10534,6 +10581,26 @@
                   "description": "The arguments to pass to the named Update handler."
                 }
               }
+            },
+            "requestId": {
+              "type": "string",
+              "description": "The request ID of the request."
+            },
+            "completionCallbacks": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "$ref": "#/definitions/v1Callback"
+              },
+              "description": "Callbacks to be called by the server when this update reaches a terminal state."
+            },
+            "links": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "$ref": "#/definitions/apiCommonV1Link"
+              },
+              "description": "Links to be associated with this update."
             }
           },
           "description": "The request information that will be delivered all the way down to the\nWorkflow Execution."
@@ -13303,10 +13370,23 @@
         },
         "batchJob": {
           "$ref": "#/definitions/LinkBatchJob"
+        },
+        "workflow": {
+          "$ref": "#/definitions/LinkWorkflow"
         }
       },
       "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."
     },
+    "v1LinkReason": {
+      "type": "string",
+      "enum": [
+        "LINK_REASON_UNSPECIFIED",
+        "LINK_REASON_QUERY",
+        "LINK_REASON_UPDATE_REJECTED"
+      ],
+      "default": "LINK_REASON_UNSPECIFIED",
+      "description": "LinkReason is the reason for linking to a workflow execution."
+    },
     "v1ListActivityExecutionsResponse": {
       "type": "object",
       "properties": {
@@ -13744,6 +13824,10 @@
         "pollerAutoscaling": {
           "type": "boolean",
           "title": "True if the namespace supports poller autoscaling"
+        },
+        "workflowUpdateCallbacks": {
+          "type": "boolean",
+          "title": "True if the namespace supports attaching callbacks on workflow updates"
         }
       },
       "description": "Namespace capability details. Should contain what features are enabled in a namespace."
@@ -14892,6 +14976,26 @@
         },
         "input": {
           "$ref": "#/definitions/v1Input"
+        },
+        "requestId": {
+          "type": "string",
+          "description": "The request ID of the request."
+        },
+        "completionCallbacks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Callback"
+          },
+          "description": "Callbacks to be called by the server when this update reaches a terminal state."
+        },
+        "links": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Link"
+          },
+          "description": "Links to be associated with this update."
         }
       },
       "description": "The client request that triggers a Workflow Update."
@@ -16573,6 +16677,10 @@
         "stage": {
           "$ref": "#/definitions/v1UpdateWorkflowExecutionLifecycleStage",
           "description": "The most advanced lifecycle stage that the Update is known to have\nreached, where lifecycle stages are ordered\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_UNSPECIFIED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ADMITTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_ACCEPTED <\nUPDATE_WORKFLOW_EXECUTION_LIFECYCLE_STAGE_COMPLETED.\nUNSPECIFIED will be returned if and only if the server's maximum wait\ntime was reached before the Update reached the stage specified in the\nrequest WaitPolicy, and before the context deadline expired; clients may\nmay then retry the call as needed."
+        },
+        "link": {
+          "$ref": "#/definitions/v1Link",
+          "description": "Link to the update event. May be null if the update has not yet been accepted."
         }
       }
     },
@@ -17574,6 +17682,12 @@
         "priority": {
           "$ref": "#/definitions/v1Priority",
           "description": "Priority override upserted in this event. Represents the full priority; not just partial fields.\nIgnored if nil."
+        },
+        "workflowUpdateOptions": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/WorkflowExecutionOptionsUpdatedEventAttributesWorkflowUpdateOptionsUpdate"
+          }
         }
       }
     },
@@ -17883,6 +17997,14 @@
         "acceptedRequest": {
           "$ref": "#/definitions/v1Request",
           "description": "The message payload of the original request message that initiated this\nupdate."
+        },
+        "completionCallbacks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Callback"
+          },
+          "title": "Completion callbacks attached when this update was started.\nTODO(quinn) maybe not needed"
         }
       }
     },

openapi/openapiv3.yaml

@@ -8776,6 +8776,14 @@ components:
       properties:
         workflowClosed:
           $ref: '#/components/schemas/CallbackInfo_WorkflowClosed'
+        updateWorkflowExecutionCompleted:
+          $ref: '#/components/schemas/CallbackInfo_UpdateWorkflowExecutionCompleted'
+    CallbackInfo_UpdateWorkflowExecutionCompleted:
+      type: object
+      properties:
+        updateId:
+          type: string
+      description: Trigger for when a workflow update is completed.
     CallbackInfo_WorkflowClosed:
       type: object
       properties: {}
@@ -10373,6 +10381,8 @@ components:
           $ref: '#/components/schemas/Link_WorkflowEvent'
         batchJob:
           $ref: '#/components/schemas/Link_BatchJob'
+        workflow:
+          $ref: '#/components/schemas/Link_Workflow'
       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:
@@ -10387,6 +10397,23 @@ components:
         A link to a built-in batch job.
          Batch jobs can be used to perform operations on a set of workflows (e.g. terminate, signal, cancel, etc).
          This link can be put on workflow history events generated by actions taken by a batch job.
+    Link_Workflow:
+      type: object
+      properties:
+        namespace:
+          type: string
+        workflowId:
+          type: string
+        runId:
+          type: string
+        reason:
+          enum:
+            - LINK_REASON_UNSPECIFIED
+            - LINK_REASON_QUERY
+            - LINK_REASON_UPDATE_REJECTED
+          type: string
+          format: enum
+      description: "A link to a workflow execution. This is a more general version of WorkflowEvent that doesn't specify a \n particular event within the workflow, useful when you want to link to a workflow but there is no particular event to link to,\n such as a Query or a Rejected Update."
     Link_WorkflowEvent:
       type: object
       properties:
@@ -10774,6 +10801,9 @@ components:
         pollerAutoscaling:
           type: boolean
           description: True if the namespace supports poller autoscaling
+        workflowUpdateCallbacks:
+          type: boolean
+          description: True if the namespace supports attaching callbacks on workflow updates
       description: Namespace capability details. Should contain what features are enabled in a namespace.
     NamespaceInfo_Limits:
       type: object
@@ -12082,6 +12112,19 @@ components:
           $ref: '#/components/schemas/Meta'
         input:
           $ref: '#/components/schemas/Input'
+        requestId:
+          type: string
+          description: The request ID of the request.
+        completionCallbacks:
+          type: array
+          items:
+            $ref: '#/components/schemas/Callback'
+          description: Callbacks to be called by the server when this update reaches a terminal state.
+        links:
+          type: array
+          items:
+            $ref: '#/components/schemas/Link'
+          description: Links to be associated with this update.
       description: The client request that triggers a Workflow Update.
     RequestCancelActivityExecutionRequest:
       type: object
@@ -15039,6 +15082,10 @@ components:
              request WaitPolicy, and before the context deadline expired; clients may
              may then retry the call as needed.
           format: enum
+        link:
+          allOf:
+            - $ref: '#/components/schemas/Link'
+          description: Link to the update event. May be null if the update has not yet been accepted.
     UpsertWorkflowSearchAttributesEventAttributes:
       type: object
       properties:
@@ -16309,6 +16356,23 @@ components:
           description: |-
             Priority override upserted in this event. Represents the full priority; not just partial fields.
              Ignored if nil.
+        workflowUpdateOptions:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/WorkflowExecutionOptionsUpdatedEventAttributes_WorkflowUpdateOptionsUpdate'
+    WorkflowExecutionOptionsUpdatedEventAttributes_WorkflowUpdateOptionsUpdate:
+      type: object
+      properties:
+        attachedRequestId:
+          type: string
+          description: |-
+            Request ID attached to the running workflow update so that subsequent requests with same
+             request ID will be deduped
+        attachedCompletionCallbacks:
+          type: array
+          items:
+            $ref: '#/components/schemas/Callback'
+          description: Completion callbacks attached to the running workflow update.
     WorkflowExecutionPauseInfo:
       type: object
       properties:
@@ -16666,6 +16730,13 @@ components:
           description: |-
             The message payload of the original request message that initiated this
              update.
+        completionCallbacks:
+          type: array
+          items:
+            $ref: '#/components/schemas/Callback'
+          description: |-
+            Completion callbacks attached when this update was started.
+             TODO(quinn) maybe not needed
     WorkflowExecutionUpdateAdmittedEventAttributes:
       type: object
       properties:

temporal/api/common/v1/message.proto

@@ -15,6 +15,7 @@ import "google/protobuf/empty.proto";
 import "temporal/api/enums/v1/common.proto";
 import "temporal/api/enums/v1/event_type.proto";
 import "temporal/api/enums/v1/reset.proto";
+import "temporal/api/enums/v1/link.proto";
 
 message DataBlob {
     temporal.api.enums.v1.EncodingType encoding_type = 1;
@@ -240,9 +241,20 @@ message Link {
         string job_id = 1;
     }
 
+    // A link to a workflow execution. This is a more general version of WorkflowEvent that doesn't specify a 
+    // particular event within the workflow, useful when you want to link to a workflow but there is no particular event to link to,
+    // such as a Query or a Rejected Update.
+    message Workflow {
+        string namespace = 1;
+        string workflow_id = 2;
+        string run_id = 3;
+        temporal.api.enums.v1.LinkReason reason = 4;
+    }
+
     oneof variant {
         WorkflowEvent workflow_event = 1;
         BatchJob batch_job = 2;
+        Workflow workflow = 3;
     }
 }
 

temporal/api/enums/v1/link.proto

@@ -0,0 +1,17 @@
+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 = "LinkProto";
+option ruby_package = "Temporalio::Api::Enums::V1";
+option csharp_namespace = "Temporalio.Api.Enums.V1";
+
+// LinkReason is the reason for linking to a workflow execution.
+enum LinkReason {
+    LINK_REASON_UNSPECIFIED = 0;
+    LINK_REASON_QUERY = 1;
+    LINK_REASON_UPDATE_REJECTED = 2;
+}