Agent Upgrade and Plug-in Deployment Provisioning

You can use API commands for various upgrade activities on Agents, including Agent upgrades and plug-in deployments.

The following table lists the various activities that the provision upgrade group of API commands supports.

You must obtain the Agent installation packages for the upgrades and place them in the <EM_HOME>/AUTO_DEPLOY directory before the provision process. You must also ensure that the <EM_HOME>/CM_DEPLOY directory contains packages that are available for deployment from your Control-M MFT and Control-M Application Pack installations. For more information about preparing the packages, see Preparing Installation Packages for Agent Upgrades.

The Provision service offers the following commands for upgrade processes:

• provision upgrades:versions::get: Obtains a list of available upgrades based on the installation packages in your directories.

• provision upgrades:agents::get: Obtains a list of Agents in your environment that are eligible for an upgrade.

• provision upgrade::install: Transfers a deployment package and installs it.

• provision upgrade::uninstall: Rolls back an upgrade deployment package at the target Agent.

• provision upgrade::get: Obtains status details for a specific upgrade activity.

• provision upgrades::get: Obtains status details for all upgrade activities or for multiple upgrade activities based on specified filters.

• provision upgrade:output::get: Retrieves output log messages from the Agent regarding a specific upgrade activity.

• provision upgrade::retry: Retries to run an upgrade activity that failed previously.

• provision upgrade::delete: Deletes the record of an upgrade activity that finished running.

• provision upgrade::cancel: Aborts an upgrade activity that is currently running.

provision upgrades:versions::get

The provision upgrades:versions::get command enables you to obtain a list of available upgrades based on the installation packages currently stored in the following directories:

• Control-M/Agent Packages: <EM_HOME>/AUTO_DEPLOY

• Control-M MFT and Control-M Application Pack Packages: <EM_HOME>/CM_DEPLOY

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" $endpoint/provision/upgrades/versions

Response

The following example shows a response that lists all available upgrades according to type (Agent, MFT, or AppPack) and target version:

[
 {
   "type": "Agent",
   "version": "9.0.18.200"
 },{
   "type": "AppPack",
   "version": "9.0.18.100"
 },{
   "type": "MFT",
   "version": "9.0.18.100"
 }
]

provision upgrades:agents::get

The provision upgrades:agents::get command enables you to obtain a list of agents in your environment that are eligible for upgrade with any of the packages in your directories. You can optionally limit the list to upgrades of a certain type (Agent, MFT, or AppPack) and target version.

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/provision/upgrades/agents?type=Agent&version=9.0.20.200"

where <query string> can contain any of the following fields:

Response

The response provides details for each agent and each possible upgrade.

200: Response - UpgradeAgentInfoList
[
    {
        "agent": "vw-one-ae65",
        "ctm": "vw-one-ae65",
        "type": "Agent",
        "platform": "windows_x86_64",
        "fromVersion": "9.0.00",
        "toVersion": "9.0.18.100"
    },{
        "agent": "vw-tlv-one-ae65",
        "ctm": "vw-tlv-one-ae65",
        "type": "MFT",
        "platform": "windows_x86_64",
        "fromVersion": "",
        "toVersion": "9.0.18.000"
    }
]

provision upgrade::install

The provision upgrade::install command enables you to transfer a deployment package to the agent host and installs it there. Use this API command for any of the following activities:

• Upgrade an Agent to a newer version.

• Install a new Control-M MFT or Control Application Pack plug-in on an existing Agent.

• Upgrade a Control-M MFT or Control Application Pack plug-in on the Agent.

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type:application/json" -X POST
--data "@installConfigurationFile.json" $endpoint/provision/upgrade/install

The following table describes the provision upgrade::install command parameters.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

Configuration File for Provision Upgrade or Rollback

If you run a REST API command, specify in the configuration file the values of the various upgrade parameters or rollback parameters (which can be included in a CLI command). These parameters include several required parameters (server, agent, type, and version) and the optional activityName.

You also need a configuration file if you specify values for additional parameters. These parameters cannot be included in the CLI command.

The following table describes additional provision upgrade::install command parameters for the command file.

{
  "server": "localControlM",
  "agent": "agent1",
  "type": "Agent",
  "version": "9.0.21",   
  "activityName": "Agent1 upgrade for localControlM",
  "installUser": "user3",
  "notifyAddress": "[email protected];[email protected]",
  "description": "Upgrading the agent to version 9.0.21"
  "useNetworkDeployment": "false"
  "javaHome": "C:\\java\\Eclipse_Adoptium_jre-17.0.6.10-hotspot"
}

Response

The installation package is deployed and installed, and an upgradeID is returned. The upgradeID has the following format:

<server>:<activityNumber>

provision upgrade::uninstall

The provision upgrade::uninstall command enables you to uninstall an upgrade deployment package at the target Agent. This API command is applicable for each of the following activities:

• Roll back the newest version of Control-M/Agent.

• Roll back the newest version of a Control-M MFT or Control Application Pack plug-in.

• Remove the Control-M MFT plug-in from the Agent if there is no previous version installed.

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type:application/json" -X POST
--data "@installConfigurationFile.json" $endpoint/provision/upgrade/uninstall

The following table describes the provision upgrade::uninstall command parameters.

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

Response

The installation package is uninstalled, and an upgradeID is returned. The upgradeID has the following format:

<server>:<activityNumber>

provision upgrade::get

The provision upgrade::get command enables you to obtain status details for a specific upgrade activity.

The response provides the upgrade activity status and various additional details, such as UTC timestamps of certain phases during the upgrade activity.

upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/provision/upgrade/$upgradeID"

where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

provision upgrades::get

The provision upgrades::get command enables you to obtain status details for all upgrade activities or for multiple upgrade activities based on specified filters.

The response provides the status of each upgrade activity and various additional details, such as timestamps of certain phases during the upgrade activity.

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/provision/upgrades?agent=Agent2&toVersion=9.0.18*"

The following table describes the fields that you can use in the provision upgrades::get query string.

provision upgrade:output::get

The provision upgrade:output::get command enables you to retrieve output log messages from the Agent for a specific upgrade activity. The output log messages appear on-screen.

upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/provision/upgrade/$upgradeID/output"

where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

provision upgrade::retry

The provision upgrade::retry command enables you to retry to run an upgrade activity that previously failed.

upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/provision/upgrade/$upgradeID/retry"

where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

provision upgrade::delete

The provision upgrade::delete command enables you to delete the record of an upgrade activity that finished running. The upgrade activity status is either Completed, Canceled, or Failed.

upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/provision/upgrade/$upgradeID"

where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

provision upgrade::cancel

The provision upgrade::cancel command enables you to abort an upgrade activity that is running. The upgrade activity status is Running or TransferCompleted.

upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/provision/upgrade/$upgradeID/cancel"

where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).

If annotation is enabled for the Configuration Management category in the CCM or Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.