GET SystemStatus/Upgrade/Engine

Returns the most recent upgrade status of one Trust Protection Platform engine.

Requirements

  • Permissions:  The caller must have View permission or Read permission to the engine root.
  • Token scope:  Any valid scope, such as Agent, Certificate, or SSH

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Specify the engine {guid} or Id, not both.

Input parameters

Name

Description

{guid}

The unique identifier of the engine. To get this value, call GET ProcessingEngines.

Id

The engine ID. To get this value, call GET ProcessingEngines.

UpgradeId

(Optional) To get the most recent upgrade, omit this parameter. In the request URL, specify an upgrade ID from GET SystemStatus/Upgrade/History.

Returns

If an error occurs, this method returns a HTTP message and an error with one of the following messages:

  • Failed to read engine upgrade objects, error: [Error]

  • Failed to read engine upgrade status, error: [Error]

  • Failed to read engine upgrade status, object must be of type: [ConfigClass.Names.VenafiPlatform]
  • Failed to read platform upgrade details, error: [Error]

  • Failed to read upgrade tasks, error: [Error]

  • Reading engine upgrade status failed, failed to lookup current grouping Id, error: [Error]

Otherwise, this method returns a HTTP 200 and the following message body:

Response description

Name

Description

Name

Description

Engine

The description of a Trust Protection Platform engine:

  • DN: The distinguished name (DN) of the Trust Protection Platform engine.
  • DisplayName: The engine name that appears in the UI.
  • Guid: The unique identifier of the engine.
  • Id: The engine ID.
  • Name: The computer name of the Engine.
Status The Engine Upgrade Status.
UpgradeStartTime

The UTC start time that the upgrade began on this engine.

UpgradeStopTime The UTC completion time when this engine finished the upgrade.

TasksCompleted

Appears only when tasks have completed. An array of details about each upgrade task:

  • DisplayName: The upgrade task name as it appears in the Upgrade dashboard.
  • Name: The task name.
  • StartTime: The UTC time that the task began on this engine.
  • StopTime: The UTC time that the task finished on this engine.
  • WarningCount: The number of warnings that occurred while running the task. For warning details, check the log.

TasksPending

Appears only when tasks are pending. An array of details about each pending upgrade task. The order of the tasks shows pending order of execution:

  • DisplayName: The upgrade task name as it appears in the Upgrade dashboard.
  • Name: The task name.

TaskRunning

Appears only when a task is running. The upgrade task that is currently running on this engine: 

  • DisplayName: The upgrade task name that is currently running.
  • Name: The task name.
  • StartTime: The UTC time that the task began on this engine.

Example: Show the engine status of an upgrade

GET https://tpp.venafi.example/vedsdk/SystemStatus/Upgrade/Engine?guid={7ebf2b04-dd12-4c0b-b9ab-3ccedf9b5a4a}
Authorization:Bearer 4MyGeneratedBearerTknz==

Response

HTTP/1.1 200 OK
{
   "EngineUpgrade":{
      "Engine":{
         "DN":"\\VED\\Engines\\WIN-MLK71Q10559",
         "DisplayName":"WIN-MLK71Q10559",
         "Guid":"{7ebf2b04-dd12-4c0b-b9ab-3ccedf9b5a4a}",
         "Id":11,
         "Name":"WIN-MLK71Q10559"
      },
      "Status":"Upgrade Complete",
      "UpgradeStartTime":"2020-02-18T22:56:42.0000000Z",
      "UpgradeStopTime":"2020-02-18T23:08:47.0000000Z",
      "TasksCompleted":[
         {
            "DisplayName":"Update Script Target Stage Check",
            "Name":"Update Script Target Stage Check",
            "StartTime":"2020-02-18T22:55:07.0000000Z",
            "StopTime":"2020-02-18T22:55:07.0000000Z",
            "WarningCount":0
         },
         {
            "DisplayName":"19.2 Authorized users report initial calculation",
            "Name":"19.2 Authorized users report initial calculation",
            "StartTime":"2020-02-18T22:58:07.0000000Z",
            "StopTime":"2020-02-18T22:58:07.0000000Z",
            "WarningCount":0
         }
      ]
   }
}