update/changecontrol.v1: Add Step Info within CC Stage

Updated the changecontrol.v1 service proto with the definitions
of the step statuses for actions performed by CC :
- message StepInfo : holds the status information for the action step
- message ActionSteps : holds a mapping between step sequence number and its StepInfo
- message Stage : holds a new field representing the ActionSteps for the stage.

Change-Id: I5525c9ff5dd1d7cfb61bb559680430b6c63e15d9

arista/changecontrol.v1/changecontrol-changelog.yaml

@@ -7,6 +7,12 @@
 # New entries go on top.
 
 Changes:
+    - date: 2025-01-06
+      description: Define and add ActionSteps within ChangeControl stage.
+      version: 1.1.2
+      cvaas: true
+      onprem: true
+
     - date: 2024-10-09
       description: add device_id_to_stage_ids map
       version: 1.1.1

arista/changecontrol.v1/changecontrol.proto

@@ -171,6 +171,42 @@ enum StageStatus {
     STAGE_STATUS_NOT_STARTED = 3;
 }
 
+// StepStatus defines the possible execution statuses of a step within an action.
+enum StepStatus {
+    // STEP_STATUS_UNSPECIFIED represents an unspecified state for a step within
+    // an action.
+    STEP_STATUS_UNSPECIFIED = 0;
+    // STEP_STATUS_NOT_STARTED represents that the step has not started execution.
+    STEP_STATUS_NOT_STARTED = 1;
+    // STEP_STATUS_RUNNING represents that the step is under execution.
+    STEP_STATUS_RUNNING = 2;
+    // STEP_STATUS_FINISHED represents that the step has finished execution.
+    STEP_STATUS_FINISHED = 3;
+    // STEP_STATUS_SKIPPED represents that the step has been skipped from execution.
+    STEP_STATUS_SKIPPED = 4;
+    // STEP_STATUS_FAILED represents that the step has failed its execution.
+    STEP_STATUS_FAILED = 5;
+}
+
+// StepInfo contains the status details of an action step.
+message StepInfo {
+	// name represents the name of the step.
+	google.protobuf.StringValue name = 1;
+	// status represents the present execution status of the step.
+	StepStatus status = 2;
+	// error captures any error that occurred.
+	google.protobuf.StringValue error = 3;
+	// message represents any relevant information associated with the step.
+	google.protobuf.StringValue message = 4;
+}
+
+// ActionSteps tracks the status of each step within an action.
+message ActionSteps {
+	// values maps each action step's execution sequence to its status information,
+	// represented by StepInfo.
+	map<string, StepInfo> values = 1;
+}
+
 // Stage holds the configuration and status of a stage.
 message Stage {
 	// name is the name of the stage.
@@ -185,10 +221,15 @@ message Stage {
 	// error is any error that occured during the execution
 	// of the stage.
 	google.protobuf.StringValue error = 5;
-	// start_time is the time when status change to Running
+	// start_time is the time when status change to Running.
 	google.protobuf.Timestamp start_time = 6;
-	// end_time is the time when status change to Completed
+	// end_time is the time when status change to Completed.
 	google.protobuf.Timestamp end_time = 7;
+	// steps represent the granular steps and their statuses
+	// associated with the action performed in the change control stage.
+	// Each stage generally defines either an action
+	// or a series of sub-stages.
+	ActionSteps steps = 8;
 }
 
 // StageMap is a map from stage ID to `Stage`. This has essentially

arista/changecontrol.v1/services.gen.swagger.json

@@ -1654,6 +1654,19 @@
       },
       "description": "Action is an action to perform during the execution of\na stage of a change control. Available actions can be\nfetched using the \"action\" services."
     },
+    "arista.changecontrol.v1.ActionSteps": {
+      "type": "object",
+      "properties": {
+        "values": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/arista.changecontrol.v1.StepInfo"
+          },
+          "description": "values maps each action step's execution sequence to its status information,\nrepresented by StepInfo."
+        }
+      },
+      "description": "ActionSteps tracks the status of each step within an action."
+    },
     "arista.changecontrol.v1.ApproveConfig": {
       "type": "object",
       "properties": {
@@ -2428,12 +2441,16 @@
         "startTime": {
           "type": "string",
           "format": "date-time",
-          "title": "start_time is the time when status change to Running"
+          "description": "start_time is the time when status change to Running."
         },
         "endTime": {
           "type": "string",
           "format": "date-time",
-          "title": "end_time is the time when status change to Completed"
+          "description": "end_time is the time when status change to Completed."
+        },
+        "steps": {
+          "$ref": "#/definitions/arista.changecontrol.v1.ActionSteps",
+          "description": "steps represent the granular steps and their statuses\nassociated with the action performed in the change control stage.\nEach stage generally defines either an action\nor a series of sub-stages."
         }
       },
       "description": "Stage holds the configuration and status of a stage."
@@ -2493,6 +2510,41 @@
       "default": "STAGE_STATUS_UNSPECIFIED",
       "description": "StageStatus defines the possible execution statuses of a stage.\n\n - STAGE_STATUS_UNSPECIFIED: STAGE_STATUS_UNSPECIFIED means unknown stage status.\n - STAGE_STATUS_RUNNING: STAGE_STATUS_RUNNING means the stage has begun execution.\n - STAGE_STATUS_COMPLETED: STAGE_STATUS_COMPLETED means the stage has ceased execution.\nSuccess/failure of a stage cannot be inferred from this status\nalone but rather this status plus the stage error. That is, no\nerror implies success and some error implies failure.\n - STAGE_STATUS_NOT_STARTED: STAGE_STATUS_NOT_STARTED means the stage has not been started."
     },
+    "arista.changecontrol.v1.StepInfo": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "name represents the name of the step."
+        },
+        "status": {
+          "$ref": "#/definitions/arista.changecontrol.v1.StepStatus",
+          "description": "status represents the present execution status of the step."
+        },
+        "error": {
+          "type": "string",
+          "description": "error captures any error that occurred."
+        },
+        "message": {
+          "type": "string",
+          "description": "message represents any relevant information associated with the step."
+        }
+      },
+      "description": "StepInfo contains the status details of an action step."
+    },
+    "arista.changecontrol.v1.StepStatus": {
+      "type": "string",
+      "enum": [
+        "STEP_STATUS_UNSPECIFIED",
+        "STEP_STATUS_NOT_STARTED",
+        "STEP_STATUS_RUNNING",
+        "STEP_STATUS_FINISHED",
+        "STEP_STATUS_SKIPPED",
+        "STEP_STATUS_FAILED"
+      ],
+      "default": "STEP_STATUS_UNSPECIFIED",
+      "description": "StepStatus defines the possible execution statuses of a step within an action.\n\n - STEP_STATUS_UNSPECIFIED: STEP_STATUS_UNSPECIFIED represents an unspecified state for a step within\nan action.\n - STEP_STATUS_NOT_STARTED: STEP_STATUS_NOT_STARTED represents that the step has not started execution.\n - STEP_STATUS_RUNNING: STEP_STATUS_RUNNING represents that the step is under execution.\n - STEP_STATUS_FINISHED: STEP_STATUS_FINISHED represents that the step has finished execution.\n - STEP_STATUS_SKIPPED: STEP_STATUS_SKIPPED represents that the step has been skipped from execution.\n - STEP_STATUS_FAILED: STEP_STATUS_FAILED represents that the step has failed its execution."
+    },
     "arista.changecontrol.v1.TimestampFlag": {
       "type": "object",
       "properties": {