Provision Service

The Provision service enables you to perform the following set up processes for Control-M/Servers and Agents:

Agent and Plug-in Provisioning: Provision an Agent and deploy plug-ins to the Agent during the provision process.
Agent Upgrade and Plug-in Deployment Provisioning: Upgrade an Agent and deploy plug-ins to the Agent.
Control-M/Server Provisioning: Provision a Control-M/Server that is either new or an existing Control-M/Server that you transfer from one host to another (server rehydration).

You must install a Control-M/Server and Agent to run and monitor jobs on your application host.

To provision an Agent or Control-M/Server on a host that uses a proxy server, ensure that the proxy server settings are defined, as described in Proxy Server Configuration.

Agent and Plug-in Provisioning

Provisioning Agents is based on images. An image is JSON code that lists the installation packages in the order they are installed. Control-M Automation API provides several default images, and enables you to create custom images that include, for example, a newer version of the Agent.

You must obtain the installation packages referenced in the images, including packages for Agents, application plug-ins, and integration plug-ins before the provision process. You can save the installation packages in a customized location, such as in a JFrog Artifactory repository, Amazon S3 buckets, or a local file system. Alternatively, you can set up a local repository to save the installation packages and images. For more information about these administrative tasks, see Control-M Automation API Provisioning.

You can install an Agent with one of the following methods:

Run separate image and setup commands: Enables you to download and prepare the installation files for the Agent with the image command. You can set up the Agent and register it to the Control-M/Server with the setup command at a later time. This method is beneficial for dynamic installations, such as installations that use a VM image.
Run a single install command: Performs the full Agent installation process with a single install command. This method is beneficial for static architectures that do not distinguish between image building and instantiation.

The following table describes the API commands to set up repositories for provisioning, provision Agents, and deploy plug-ins.

Command	Description
provision images	Gets a list of available images.
provision image	Prepares the file system to install an Agent.
provision agent::setup	Registers an Agent and connects it to a Control-M/Server.
provision agent::install	Runs all phases of image installation, including image and setup.
provision image::remove	Uninstalls an image from the user account but does not unregister it.
provision agent::uninstall	Uninstalls an image from the user account and unregisters it.
provision repository::add	Adds a repository where installation packages and images are stored for provisioning.
provision repository::get	Gets details of a repository used in provisioning actions.
provision repositories::get	Gets details of all defined repositories from Control-M/EM.
provision repository::delete	Deletes a repository for provisioning.
provision repository::set	Sets the default repository for provisioning actions.

provision images

The provision images command enables you to get a list of the images that are available on the Control-M/Server for a specific operating system. The command returns a list of image names.

CLI Syntax

The following shows the CLI syntax for the provision images command:

ctm provision images <os>

The following table describes the provision images command parameters.

Parameter	Description
os	Determines the operating system specified for the retrieved images. Valid values: Linux (for Linux 64-bit) Windows (for Windows 64-bit) AIX

The following example shows a request for a list of available images and a typical response:

Copy

> ctm provision images Linux -e devEnvironment
[
  "Agent.Linux",
  "Agent_20.Linux",
  "ApplicationsAgent.Linux",
  "BigDataAgent.Linux",
  "Server.Linux",
  "Server_20.Linux"
]

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

REST API Syntax

The following example shows the REST API syntax for the provision images command in cURL:

Copy

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

curl -H "$AuthHeader" $endpoint/provision/images/$os

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

provision image

The provision image command enables you to download an image and prepares it for installation.

If the image is an Agent image, this command also installs the image into the current user account, but does not configure it or register it with a Control-M/Server.

You can use this command also to install Control-M Integrations plug-ins. Store the obtained plug-in zip file in the <EM_HOME>/AUTO_DEPLOY directory and then run this command only.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision image command:

ctm provision image <image> -f <configuration file> [-r <repository name>]

The following table describes the provision image command parameters.

Parameter	Description
image	Determines which image to prepare for installation. You can specify the image in one of the following ways: The name of one of the image files returned by the provision images command. You do not need to include the OS extension in the name of the image file. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically. If you set up a local repository, as described in Setting Up a Local Repository for Provision Images and Installation Packages, you can specify the image in the following format: <name>.<version> where the image <name> is one of the following: Agent Hadoop Databases AWS Airflow OEBS PeopleSoft SAP Informatica Informatica.9.0.21.300
configuration file	Defines the JSON file that contains the javaHome parameter when you provision an Agent. The following example shows the parameter in a JSON configuration file that indicates the location of the JRE to install an Agent on Windows: Copy `{ "javaHome": "C:\\java\\Eclipse_Adoptium_jre-17.0.6.10-hotspot" }`
repository name	Determines which local repository to select for this provisioning action. Select from all the local repositories defined with provision repository::add. If you do not specify the local repository with the -r option, ensure that you set a default with provision repository::set.

Parameter

Description

image

Determines which image to prepare for installation.

You can specify the image in one of the following ways:

The name of one of the image files returned by the provision images command.

You do not need to include the OS extension in the name of the image file. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically.
If you set up a local repository, as described in Setting Up a Local Repository for Provision Images and Installation Packages, you can specify the image in the following format:

<name>.<version>

where the image <name> is one of the following:
- Agent
- Hadoop
- Databases
- AWS
- Airflow
- OEBS
- PeopleSoft
- SAP
- Informatica
Informatica.9.0.21.300

configuration file

Defines the JSON file that contains the javaHome parameter when you provision an Agent.

The following example shows the parameter in a JSON configuration file that indicates the location of the JRE to install an Agent on Windows:

Copy

{
"javaHome": "C:\\java\\Eclipse_Adoptium_jre-17.0.6.10-hotspot"
}

repository name

Determines which local repository to select for this provisioning action. Select from all the local repositories defined with provision repository::add.

If you do not specify the local repository with the -r option, ensure that you set a default with provision repository::set.

provision agent::setup

The provision agent::setup command enables you to connect and register an image with a Control-M environment.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision agent::setup command:

ctm provision agent::setup [server] [name] [port] [-f <configuration file>]

The following table describes the provision agent::setup command parameters.

Parameter	Description
server	Defines the Control-M/Server to register the Agent. If omitted or empty and there is only one Control-M/Server, the system selects that server. In this scenario, if you define name or port, include "" as a placeholder for the server. provision agent::setup provision agent::setup "" "" 2056 provision agent::setup "" "alias1" 2056
name	Defines the hostname or alias of the Agent. This is the logical name of the Agent. If omitted or empty, the system uses the hostname. In this scenario, if you define server or port, include "" as a placeholder for the name.
port	Defines the port to designate as the Agent listening TCP/IP port. If omitted or empty, the system uses an available free port. In this scenario, if you define name and server, include "" as a placeholder for the port.
configuration file	(Optional) Defines the JSON file with additional parameters. The following example shows a configuration file: Copy `{ "connectionInitiator": "AgentToServer", "tag": "abc_1234", "serverHostName":"ctmServer2", "serverPort": 7777, "secondaryServerHostName": "ctmServer3" }`

The following table describes additional provision agent::setup command parameters in the configuration file.

Parameter	Description
connectionInitiator	Determines the component that initiates the connection between the Agent and Control-M/Server. Values: AgentToServer ServerToAgent BothAllowed Default: BothAllowed
tag	Defines a tag associated with the Agent in Role-Based Administration (RBA). Tags can contain alphanumeric characters and underscores. The maximum length is 85 characters. This parameter is available only for Control-M/EM version 9.0.20 or higher.
serverHostName	Defines the name of the server host to override the default server hostname. This is a required parameter to provision an agent with Role Authorizations.
serverPort	Defines the port number for server-to-agent communication to override the default server port. This is a required parameter to provision an agent with Role Authorizations.
secondaryServerHostName	Defines the name of the secondary Control-M/Server host for High Availability (HA) configurations. This is a required parameter to provision an agent with Role Authorizations.

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

provision agent::install

The provision agent::install command enables you to combine the image and setup commands into one action. The command downloads the agent, and then connects and registers it with a Control-M/Server.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision agent::install command:

ctm provision agent::install <image> [server] [name] [port] [-f <configuration file>] [-r <repository name>]

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

Parameter	Description
image	Determines which image to install. You can specify the image in one of the following ways: The name of one of the image files that the provision images command returns. You do not need to include the OS extension in the name of the image file. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically. If you set up a local repository, as described in Setting Up a Local Repository for Provision Images and Installation Packages, specify the image in the following format: <name>.<version> where the image <name> is one of the following: Agent Hadoop Databases AWS Airflow OEBS PeopleSoft SAP Informatica Informatica.9.0.21.300
server	Determines the Control-M/Server to register the Agent. If omitted or empty and there is only one Control-M/Server, the system selects that server. In this scenario, if you define name or port, include "" as a placeholder for the server. provision agent::install provision agent::install"" "" 2056 provision agent::install"" "alias1" 2056
name	Defines the hostname or alias of the Agent. This is the logical name of the Agent. If omitted or empty, the system uses the hostname. In this scenario, if you define server or port, include "" as a placeholder for the name.
port	Determines the port to designate as the Agent listening TCP/IP port. If omitted or empty, the system uses an available free port. In this scenario, if you define name and server, include "" as a placeholder for the port.
configuration file	(Optional) Defines the full path to a JSON file that contains additional parameters. Mandatory for Control-M/Agent upgrade to version 9.0.21: You must use a configuration file and set the mandatory javaHome parameter. The following example shows a configuration file: Copy `{ "connectionInitiator": "AgentToServer", "tag": "abc_1234", "serverHostName":"ctmServer2", "serverPort": 7777, "javaHome": "C:\\java\\Eclipse_Adoptium_jre-17.0.6.10-hotspot" }`
repository name	Determines which local repository to select for this provisioning action. Select from all the local repositories defined with provision repository::add. If you do not specify the local repository with the -r option, ensure that you set a default with provision repository::set.

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

Parameter	Description
connectionInitiator	Determines the component that initiates the connection between the Agent and Control-M/Server. Values: AgentToServer ServerToAgent BothAllowed Default: BothAllowed
tag	Defines a tag associated with the Agent in Role-Based Administration (RBA). Tags can contain alphanumeric characters and underscores. The maximum length is 85 characters.
serverHostName	Defines the server hostname to override the default. This is a required parameter to provision an agent with Role Authorizations.
serverPort	Defines the port number for server-to-agent communication to override the default server port. This is a required parameter to provision an agent with Role Authorizations.
javaHome	(Mandatory) Defines the full path to a JRE.

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

provision image::remove

The provision image::remove command enables you to uninstall an image from a user account without unregistration in Control-M.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision image::remove command:

ctm provision image::remove

provision agent::uninstall

The provision agent::uninstall command enables you to uninstall an image from a user account and unregisters it from the Control-M/Server.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision agent::uninstall command:

ctm provision agent::uninstall

provision repository::add

The provision repository::add command enables you to define a repository to store installation packages and images for provisioning actions.

This method to define a local repository is an alternative to environment configure. It enables you to define numerous different repositories in Control-M/EM and each supports multiple Control-M environments.

CLI Syntax

The following shows the CLI syntax for the provision repository::add command:

ctm provision repository::add <name> <location> [<description>]

The following table describes the provision repository::add command parameters.

Parameter	Description
name	Defines the repository name.
location	Defines the path to the storage location of the installation packages for provisioning actions. Local filesystem: file:///home//localProvisionRepo Amazon S3 Bucket: https://s3-us-west-2.amazonaws.com/localProvisionRepo
description	(Optional) Defines a textual description of the repository.

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

REST API Syntax

The following example shows the REST API syntax for the provision repository::add command in cURL:

Copy

name=Location1
location="file:///home//localProvisionRepo"
description="Local repository"
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
  
curl -H "$AuthHeader" -X POST  "$endpoint/provision/repository" 
-d '{"name": "$name", "location": "$location", ["description": "$description"]}'

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

provision repository::get

The provision repository::get command enables you to get details of a repository defined for provisioning actions.

CLI Syntax

The following shows the CLI syntax for the provision repository::get command:

ctm provision repository::get <name>

where <name> is the name of the local repository defined for provisioning actions.

REST API Syntax

The following example shows the REST API syntax for the provision repository::get command in cURL:

Copy

name=Location1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
  
curl -H "$AuthHeader" "$endpoint/provision/repository/$name"

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

provision repositories::get

The provision repositories::get command enables you to get the details of all provisioning repositories defined in Control-M/EM.

CLI Syntax

The following shows the CLI syntax for provision repositories::get the command:

ctm provision repositories::get

REST API Syntax

The following example shows the REST API syntax for the provision repositories::get command in cURL:

Copy

AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
  
curl -H "$AuthHeader" "$endpoint/provision/repositories"

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

provision repository::delete

The provision repository::delete command enables you to delete a repository defined for provisioning actions from Control-M/EM. The response returns the details of all remaining repositories.

CLI Syntax

The following shows the CLI syntax for the provision repository::delete command:

ctm provision repository::delete <name>

where <name> is the name of the defined local repository that you no longer want for provisioning actions.

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

REST API Syntax

The following example shows the REST API syntax for the provision repository::delete command in cURL:

Copy

name=Location1
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
  
curl -X DELETE -H "$AuthHeader" "$endpoint/provision/repository/$name"

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

provision repository::set

The provision repository::set command enables you to set the default repository for provisioning actions (of all provisioning repositories defined in Control-M/EM).

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision repository::set command:

ctm provision repository::set <name>

where <name> is the name of the defined local repository that you want as the default for provisioning actions.

If the default repository is set in multiple ways, the actual default is determined according to the following order of precedence:

As set by the -r option in the individual provision image or provision agent::install command.
As set by the EXT_AUTO_DEPLOY and EXT_APPLICATION_ARTIFACTS_JSON_URL parameters via environment configure.
As set by the following API command:

provision repository::set.

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.

	Control-M/Agent	Control-M Managed File Transfer (MFT)	Control-M Application Pack
Upgrade to a new version	Yes	Yes	Yes
Roll back to a previous version	Yes	Yes	Yes
Install new plug-in on an existing Agent	NA	Yes	Yes
Remove plug-in from an Agent	NA	Yes	No

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:

Agent and Plug-in Provisioning: 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

CLI Syntax

The following shows the CLI syntax for the provision upgrades:versions::get command:

ctm provision upgrades:versions::get

REST API Syntax

The following example shows the REST API syntax for the provision upgrades:versions::get command:

Copy

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

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

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

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

Copy

[
 {
   "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.

CLI Syntax

The following shows the CLI syntax for the provision upgrades:agents::get command:

ctm provision upgrades:agents::get [-s <query string>]

where <query string> can contain one or both of the following fields:

Field	Values
type	Determines the upgrade type. Valid values: Agent MFT AppPack
version	Determines the target upgrade version, such as 9.0.20.200 or 9.0.21.000.

Field

Values

type

Determines the upgrade type.

Valid values:

Agent
MFT
AppPack

version

Determines the target upgrade version, such as 9.0.20.200 or 9.0.21.000.

The following example shows a command that returns details for agents that can be upgraded to version 9.0.20.200:

ctm provision upgrades:agents::get -s "type=Agent&version=9.0.20.200"

The following example shows a command that returns details for agents where Control-M MFT can be deployed:

ctm provision upgrades:agents::get -s "type=MFT"

REST API Syntax

The following example shows the REST API syntax for the provision upgrades:agents::get command:

Copy

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"

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

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

The following example shows one agent is eligible to upgrade from version 9.0.00 to version 9.0.18.100. The same agent is also eligible to install Control-M MFT version 9.0.18.000, which is currently not installed.

Copy

[
    {
        "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.

CLI Syntax

The following shows the CLI syntax for the provision upgrade::install command:

ctm provision upgrade::install <server> <agent> <type> <version> [activityName] [-f <configuration file>]

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

Parameter	Description
server	Defines the name of the Control-M/Server.
agent	Defines the Agent hostname or alias.
type	Determines the upgrade type: Valid values: Agent MFT AppPack
version	Determines the target upgrade version, such as 9.0.20.200 or 9.0.21.000.
activityName	(Optional) Defines a name for this upgrade activity. If you do not specify an activity name, the default activity name is <server>, <agent>, <type>.
configuration file	Defines the full path to a JSON file with installation details. If you upgrade the Agent to version 9.0.21, you must use a configuration file and set the mandatory javaHome parameter. For more details about this configuration file, see Configuration file for provision upgrade or rollback.

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

REST API Syntax

The following example shows the REST API syntax for the provision upgrade::install command in cURL:

Copy

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 path to the configuration file is prefixed with an @ character.

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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.

Parameter	Description
installUser	Defines the user account to install the package. This parameter is required if all of the following conditions exist: The Agent is hosted on a Windows host. The Control-M/Agent version is lower than 9.0.00.300 (version 9.0.00, fix pack 3). The Agent security setting Logon as User is set to Yes. For more information, see Security Parameters. In all other cases, the system automatically sets the user and ignores any value set with this parameter. Due to JSON character escaping, if the username includes a backslash, each backslash must be doubled (for example, "domain\\userName").
notifyAddress	(Optional) Defines an email address list of recipients who receive notifications about the upgrade or rollback process. Multiple email addresses must be separated by a semicolon (;) character.
description	(Optional) Describes the upgrade activity.
useNetworkDeployment	(Optional) Determines the location of the installation files to upgrade the selected Agents or its plug-ins. Valid values: True: Retrieves the installation files from a network location. False: Retrieves the installation files from Control-M/EM. Default: False To upgrade from a network location, you must first define the same network location in the Control-M/EM system parameter CentralDeployLocation and the Control-M/Server system parameters CTM_AUTO_DEPLOY_PACKAGE_LOCATION_WINDOWS and CTM_AUTO_DEPLOY_PACKAGE_LOCATION_UNIX. The upgrade fails if you do not define these parameters and you set the useNetworkDeployment parameter to True. This feature requires Control-M/EM version 9.0.21.
javaHome	(Mandatory) Defines the full path to JRE. This feature requires Control-M/EM version 9.0.21.

If you upgrade Control-M/Agent to version 9.0.21, you must use a configuration file and set the mandatory javaHome parameter.

The following sample configuration file contains all possible parameters, including the optional parameters and the parameters that you can alternatively set with the CLI command:

Copy

{
  "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>

LocalControlM:12

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 a 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.

CLI Syntax

The following shows the CLI syntax for the provision upgrade::uninstall command:

ctm provision upgrade::uninstall <server> <agent> <type> <version> [activityName] [-f <configuration file>]

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

Parameter	Description
server	Defines the name of the Control-M/Server.
agent	Defines the Agent hostname or alias.
type	Determines one of the following types of upgrade that is uninstalled: Agent MFT AppPack
version	Determines the version to uninstall.
activityName	(Optional) Defines a name for this upgrade activity. If you do not specify an activity name, the default activity name is "<server>, <agent>, <type>".
configuration file	Defines the full path to a JSON file that contains uninstallation details. For more details about this configuration file, see Configuration file for provision upgrade or rollback.

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

REST API Syntax

The following example shows the REST API syntax for the provision upgrade::uninstall command in cURL:

Copy

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 path to the configuration file is prefixed with an @ character.

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

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

<server>:<activityNumber>

LocalControlM:12

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.

CLI Syntax

The following shows the CLI syntax for the provision upgrade::get command:

ctm provision upgrade::get <upgradeID>

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

REST API Syntax

The following example shows the REST API syntax for the provision upgrade::get command:

Copy

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

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

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

For more information, see Control-M Automation REST API Reference.

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.

CLI Syntax

The following shows the CLI syntax for the provision upgrades::get command:

ctm provision upgrades::get [-s <query string>]

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

For multiple values, type commas. You can type ? and * as wildcards.

Field	Description
server	Defines the name of the Control-M/Server. This field was previously named ctm (deprecated name).
agent	Defines the Agent hostname or alias.
fromVersion	Determines the source version before the upgrade activity. 9.0.00.100
toVersion	Determines the target version. 9.0.18.200
acivity	Determines the upgrade activity type. Valid values: Install Uninstall
status	Determines the activity status. Valid values: Running TransferCompleted Completed Canceled Failed Unavailable
activityName	Defines the name of the upgrade activity.

The following example shows a command that returns status details for upgrades or rollbacks to version 9.0.18 and its fix packs on Agent1 and Agent2:

ctm provision upgrades::get -s "agent=Agent1,Agent2&toVersion=9.0.18*"

REST API Syntax

The following example shows the REST API syntax for the provision upgrades::get command:

Copy

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*"

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

For more information, see Control-M Automation REST API Reference.

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.

CLI Syntax

The following shows the CLI syntax for the provision upgrade:output::get command:

ctm provision upgrade:output::get <upgradeID>

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

REST API Syntax

The following example shows the REST API syntax for the provision upgrade:output::get command:

Copy

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

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

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

provision upgrade::retry

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

The original upgrade activity already has an assigned upgradeID. The retry activity does not create a new one. The response only returns a message that the retry started.

CLI Syntax

The following shows the CLI syntax for the provision upgrade::retry command:

ctm provision upgrade::retry <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, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the provision upgrade::retry command:

Copy

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

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

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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.

CLI Syntax

The following shows the CLI syntax for the provision upgrade::delete command:

ctm provision upgrade::delete <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, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the provision upgrade::delete command:

Copy

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"

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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.

CLI Syntax

The following shows the CLI syntax for the provision upgrade::cancel command:

ctm provision upgrade::cancel <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, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the provision upgrade::cancel command:

Copy

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"

To select the AuthHeader value ("Authorization: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Control-M/Server Provisioning

The Control-M/Server provision process is supported on Windows with an MS SQL database and on Linux with an Oracle database. You can create a new Control-M/Server or transfer an existing Control-M/Server from one host to another (server rehydration).

Provisioning Control-M/Server is based on images. An image is JSON code that lists the installation packages in the order they are installed. Control-M Automation API provides several default images, and you can create custom images that include, for example, a newer version of Control-M/Server.

You must obtain the Control-M/Server installation packages that are referenced in the images before provisioning. You can save these installation packages in a customized location, such as in a JFrog Artifactory repository, Amazon S3 buckets, or a local file system. Alternatively, you can set up a local repository to save the installation packages and images.

You can provision Control-M/Server with one of the following methods:

Run separate image and setup commands: Enables you to download and prepare the installation files for Control-M/Server with the image command. You can later install and register Control-M/Server with the setup command. This is useful for dynamic installations, such as installations that use a VM image.
Run a single install command: Performs the full Control-M/Server installation process with a single install command. This is useful for static architectures that do not distinguish between image building and instantiation.

Control-M/Server setup or installation is based on settings that you define in a configuration file that is a payload JSON file. For the full description of this configuration file, see Server Provisioning Configuration.

The following API commands enable you to provision or uninstall Control-M/Server:

provision images: (For Control-M/Servers and Agents) Lists all existing images.
provision image: (For Control-M/Servers and Agents) Downloads and prepares an image.
provision server::setup: Installs a Control-M/Server and registers it in the Control-M environment.
provision server::install: Combines the image and setup commands into one action.
provision image::remove: (For Control-M/Servers and Agents) Removes an image from the user account.
provision server::uninstall: Uninstalls a Control-M/Server from the user account and unregisters it from the Control-M environment.

provision server::setup

The provision server::setup command enables you to install a Control-M/Server and registers it in the Control-M environment.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision server::setup command:

ctm provision server::setup -f <configuration file>

where <configuration file> is a JSON file that contains Control-M/Server definitions. For the full description of this configuration file, see Server Provisioning Configuration.

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

provision server::install

The provision server::install command enables you to combine the image and setup commands into one action. It downloads the Control-M/Server, installs it and registers it in the Control-M environment.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision server::install command:

ctm provision server::install <image> -f <configuration file>

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

Parameter	Description
image	Defines the image that you want to install. This is one of the images returned by the provision images command.
configuration file	Defines the JSON file that contains Control-M/Server definitions. For the full description of this configuration file, see Server Provisioning Configuration.

Parameter

Description

image

Defines the image that you want to install. This is one of the images returned by the provision images command.

configuration file

Defines the JSON file that contains Control-M/Server definitions.

For the full description of this configuration file, see Server Provisioning Configuration.

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

provision server::uninstall

The provision server::uninstall command enables you to uninstall a Control-M/Server from the user account and unregisters it from the Control-M environment.

This API command is supported only through the CLI and cannot be called through a REST API command.

CLI Syntax

The following shows the CLI syntax for the provision server::uninstall command:

ctm provision server::uninstall [server]

where [server] is the name of the Control-M/Server. This is required only on a Linux host that has multiple Control-M/Servers installed.

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