Rename Nexus Operation ID to token (#548)

- Leave operation ID fields in tact and mark them as deprecated. We may
delete (reserve) them later on.

Author: bergundy

openapi/openapiv2.json

@@ -5660,14 +5660,18 @@
       "type": "object",
       "properties": {
         "operationId": {
-          "type": "string"
+          "type": "string",
+          "description": "Deprecated: Renamed to operation_token."
         },
         "links": {
           "type": "array",
           "items": {
             "type": "object",
             "$ref": "#/definitions/apinexusv1Link"
           }
+        },
+        "operationToken": {
+          "type": "string"
         }
       },
       "description": "The operation will complete asynchronously.\nThe returned ID can be used to reference this operation."
@@ -7668,7 +7672,11 @@
         },
         "operationId": {
           "type": "string",
-          "description": "Operation ID as originally generated by a Handler."
+          "description": "Operation ID as originally generated by a Handler.\n\nDeprecated: Renamed to operation_token."
+        },
+        "operationToken": {
+          "type": "string",
+          "description": "Operation token as originally generated by a Handler."
         }
       },
       "description": "A request to cancel an operation."
@@ -9902,7 +9910,11 @@
         },
         "operationId": {
           "type": "string",
-          "description": "Operation ID - may be empty if the operation completed synchronously."
+          "description": "Operation ID - may be empty if the operation completed synchronously.\n\nDeprecated: Renamed to operation_token."
+        },
+        "operationToken": {
+          "type": "string",
+          "description": "Operation token - may be empty if the operation completed synchronously."
         }
       }
     },
@@ -9962,11 +9974,15 @@
         },
         "operationId": {
           "type": "string",
-          "description": "The operation ID returned by the Nexus handler in the response to the StartOperation request.\nThis ID is used when canceling the operation."
+          "description": "The operation ID returned by the Nexus handler in the response to the StartOperation request.\nThis ID is used when canceling the operation.\n\nDeprecated: Renamed to operation_token."
         },
         "requestId": {
           "type": "string",
           "description": "The request ID allocated at schedule time."
+        },
+        "operationToken": {
+          "type": "string",
+          "description": "The operation token returned by the Nexus handler in the response to the StartOperation request.\nThis token is used when canceling the operation."
         }
       },
       "description": "Event marking an asynchronous operation was started by the responding Nexus handler.\nIf the operation completes synchronously, this event is not generated.\nIn rare situations, such as request timeouts, the service may fail to record the actual start time and will fabricate\nthis event upon receiving the operation completion via callback."
@@ -10185,7 +10201,7 @@
         },
         "operationId": {
           "type": "string",
-          "description": "Operation ID. Only set for asynchronous operations after a successful StartOperation call."
+          "description": "Operation ID. Only set for asynchronous operations after a successful StartOperation call.\n\nDeprecated: Renamed to operation_token."
         },
         "scheduleToCloseTimeout": {
           "type": "string",
@@ -10229,6 +10245,10 @@
         "blockedReason": {
           "type": "string",
           "description": "If the state is BLOCKED, blocked reason provides additional information."
+        },
+        "operationToken": {
+          "type": "string",
+          "description": "Operation token. Only set for asynchronous operations after a successful StartOperation call."
         }
       },
       "description": "PendingNexusOperationInfo contains the state of a pending Nexus operation."

openapi/openapiv3.yaml

@@ -7389,7 +7389,13 @@ components:
           description: Operation name.
         operationId:
           type: string
-          description: Operation ID - may be empty if the operation completed synchronously.
+          description: |-
+            Operation ID - may be empty if the operation completed synchronously.
+
+             Deprecated: Renamed to operation_token.
+        operationToken:
+          type: string
+          description: Operation token - may be empty if the operation completed synchronously.
     NexusOperationScheduledEventAttributes:
       type: object
       properties:
@@ -7452,9 +7458,16 @@ components:
           description: |-
             The operation ID returned by the Nexus handler in the response to the StartOperation request.
              This ID is used when canceling the operation.
+
+             Deprecated: Renamed to operation_token.
         requestId:
           type: string
           description: The request ID allocated at schedule time.
+        operationToken:
+          type: string
+          description: |-
+            The operation token returned by the Nexus handler in the response to the StartOperation request.
+             This token is used when canceling the operation.
       description: |-
         Event marking an asynchronous operation was started by the responding Nexus handler.
          If the operation completes synchronously, this event is not generated.
@@ -7669,7 +7682,10 @@ components:
           description: Operation name.
         operationId:
           type: string
-          description: Operation ID. Only set for asynchronous operations after a successful StartOperation call.
+          description: |-
+            Operation ID. Only set for asynchronous operations after a successful StartOperation call.
+
+             Deprecated: Renamed to operation_token.
         scheduleToCloseTimeout:
           pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
           type: string
@@ -7719,6 +7735,9 @@ components:
         blockedReason:
           type: string
           description: If the state is BLOCKED, blocked reason provides additional information.
+        operationToken:
+          type: string
+          description: Operation token. Only set for asynchronous operations after a successful StartOperation call.
       description: PendingNexusOperationInfo contains the state of a pending Nexus operation.
     PendingWorkflowTaskInfo:
       type: object

temporal/api/failure/v1/message.proto

@@ -95,7 +95,11 @@ message NexusOperationFailureInfo {
     // Operation name.
     string operation = 4;
     // Operation ID - may be empty if the operation completed synchronously.
+    //
+    // Deprecated: Renamed to operation_token.
     string operation_id = 5;
+    // Operation token - may be empty if the operation completed synchronously.
+    string operation_token = 6;
 }
 
 message NexusHandlerFailureInfo {

temporal/api/history/v1/message.proto

@@ -866,10 +866,16 @@ message NexusOperationStartedEventAttributes {
     int64 scheduled_event_id = 1;
     // The operation ID returned by the Nexus handler in the response to the StartOperation request.
     // This ID is used when canceling the operation.
+    //
+    // Deprecated: Renamed to operation_token.
     string operation_id = 3;
 
     // The request ID allocated at schedule time.
     string request_id = 4;
+
+    // The operation token returned by the Nexus handler in the response to the StartOperation request.
+    // This token is used when canceling the operation.
+    string operation_token = 5;
 }
 
 // Nexus operation completed successfully.

temporal/api/nexus/v1/message.proto

@@ -84,7 +84,12 @@ message CancelOperationRequest {
     // Type of operation to cancel.
     string operation = 2;
     // Operation ID as originally generated by a Handler.
+    //
+    // Deprecated: Renamed to operation_token.
     string operation_id = 3;
+
+    // Operation token as originally generated by a Handler.
+    string operation_token = 4;
 }
 
 // A Nexus request.
@@ -115,8 +120,10 @@ message StartOperationResponse {
     // The operation will complete asynchronously.
     // The returned ID can be used to reference this operation.
     message Async {
+        // Deprecated: Renamed to operation_token.
         string operation_id = 1;
         repeated Link links = 2;
+        string operation_token = 3;
     }
 
     oneof variant {

temporal/api/workflow/v1/message.proto

@@ -367,6 +367,8 @@ message PendingNexusOperationInfo {
     string operation = 3;
 
     // Operation ID. Only set for asynchronous operations after a successful StartOperation call.
+    //
+    // Deprecated: Renamed to operation_token.
     string operation_id = 4;
 
     // Schedule-to-close timeout for this operation.
@@ -399,6 +401,9 @@ message PendingNexusOperationInfo {
 
     // If the state is BLOCKED, blocked reason provides additional information.
     string blocked_reason = 14;
+
+    // Operation token. Only set for asynchronous operations after a successful StartOperation call.
+    string operation_token = 15;
 }
 
 // NexusOperationCancellationInfo contains the state of a nexus operation cancellation.