Provision Service
The Provision service provides you access to the full cycle of the following setup processes for agents and servers:
-
Provision a New Control-M/Agent and Plug-ins: Provision Agents and deploy plug-ins to the Agent during the provision process.
-
Upgrade an Existing Control-M/Agent: Upgrade an existing Agent and deploy plug-ins to it.
-
Provision a Control-M/Server: Provision a Control-M/Server either as a new server or an existing Control-M/Server that you transfer from one host to another (server rehydration).
You must install a Control-M/Server and Control-M/Agent to run and monitor jobs on your application host.
To provision a Control-M/ Agent or a Control-M/Server on a host that uses a proxy server, ensure that the HTTP_PROXY and HTTPS_PROXY environment variables are defined. The values for these variables are in the following format:
{protocol}://{host}:{port}
-
http://172.19.0.169:3128
-
https://server.com:3128
You must include logon credentials for authentication to the proxy.
HTTP_PROXY= http://username:password@proxy.example.com:1234
To opt out of proxying on specific hosts or particular destination ports, you can use the NO_PROXY environment variable, set with a comma-separated list of hosts.
NO_PROXY=hostname.example.com,10.1.0.0/16,172.30.0.0/16:443
Provision a New Control-M/Agent and Plug-ins
The following API commands enable you to provision Agents and deploy plug-ins:
-
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 with 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.
You can select one of the following options to install an Agent:
-
Run the image and setup commands separately. This is useful if your architecture requires dynamic installation and Agent setup. In this scenario, run the image command to prepare your image with the Agent inside it. An image can be a VM image, a Docker image, or an AWS AMI. Then, when necessary, run the setup command to dynamically set up the Agent and register it to the Control-M/Server.
-
Run the install command for all installation phases. This option is useful in a static architecture that has no distinction between building an image and instantiation.
The images used during the provision process are JSON code. Each image contains a list of installation packages in the order that they are installed. The base Control-M Automation API installation provides several default images. You can also create additional custom images, such as an image to install a newer Control-M/Agent version. Before you begin the provision process, you must obtain the installation packages for the Agent, application plug-ins, or integration plug-ins and plug-ins developed in Control-M Application Integrator referenced within the images. You can also customize the location to save these packages, such as in a JFrog Artifactory repository, Amazon S3 buckets, or a local file system. Alternatively, you can set up a local repository for both installation packages and images. For more information about these preparatory tasks, see Control-M Automation API Provisioning.
provision images
The provision images command enables you to get a list of the images that are available on the server for a specific OS. 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 supported operating systems. Valid values:
|
The following example shows a request for a list of available images and a typical response:
> 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 Control-M, 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:
os=Linux
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/provision/images/$os
To select the AuthHeader value ("Authentication: 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 images command:
ctm provision image <image> -f <configuration file>
The following table describes the provision image command parameters.
Parameter |
Description |
---|---|
image |
Determines which image to You do not need to include the OS extension in the name of the image. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically. |
configuration file |
Defines the JSON file that contains the javaHome parameter when you provision a Control-M/Agent. The following example shows the parameter in a JSON configuration file that indicates the location of the JRE to install a Control-M/Agent on Windows: Copy
|
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 host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. If omitted or empty, the system uses the host name. In this scenario, if you define server or port, include "" as a placeholder for the name. |
port |
Defines the port to designate as the Control-M/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
|
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 Control-M/Agent and Control-M/Server. Values:
Default: BothAllowed |
tag |
Defines a tag associated with the Control-M/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 later. |
serverHostName |
Defines the name of the server host to override the default server host name. This is a required parameter to provision an agent with |
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 |
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 |
If annotation is enabled for the Configuration Management category in Control-M, 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>]
The following table describes the provision agent::install command parameters.
Parameter |
Description |
---|---|
image |
Determines which image to install You do not need to include the OS extension in the name of the image. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically. |
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 host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. If omitted or empty, the system uses the host name. In this scenario, if you define server or port, include "" as a placeholder for the name. |
port |
Determines the port to designate as the Control-M/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
|
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 Control-M/Agent and Control-M/Server. Values:
Default: BothAllowed |
tag |
Defines a tag associated with the Control-M/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/Server version 9.0.20 or higher. |
serverHostName |
Defines the server host name to override the default. This is a required parameter to provision an agent with |
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 |
javaHome |
(Mandatory) Defines the full path to a JRE. |
If annotation is enabled for the Configuration Management category in Control-M, 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 this user account without its 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 this 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
Upgrade an Existing Control-M/Agent and Application Plug-ins
You can use API commands to implement various upgrade activities on existing Control-M/Agents, including agent upgrades and plug-in deployments.
The following table lists the various activities you can do with the provision upgrade group of API commands.
|
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 |
Before you begin the provision process, you must obtain the Control-M/Agent installation packages for the upgrades and place them in the <EM_HOME>/AUTO_DEPLOY directory. 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 a New Control-M/Agent and Plug-ins: 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 Control-M/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 Control-M/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:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" $endpoint/provision/upgrades/versions
To select the AuthHeader value ("Authentication: 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:
[
{
"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 which upgrade type. Valid values:
|
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:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: 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 ("Authentication: 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.
[
{
"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 a Control-M/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 name of host or alias of the Control-M/Agent. |
type |
Determines which upgrade type: Valid values:
|
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 that contains installation details. If you upgrade Control-M/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 Control-M, 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:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: 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 ("Authentication: 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 to use in the command file.
Parameter |
Description |
---|---|
installUser |
Defines the user account to install the package. This parameter is required if all the following conditions exist:
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 user name 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. |
(Optional) Determines the location of the installation files to upgrade the selected Control-M/Agents or its plug-ins. Valid values:
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. |
|
(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:
{
"server": "localControlM",
"agent": "agent1",
"type": "Agent",
"version": "9.0.21",
"activityName": "Agent1 upgrade for localControlM",
"installUser": "user3",
"notifyAddress": "joe@example.com;jane@example.com",
"description": "Upgrading the agent to version 9.0.21"
"useNetworkDeployment": "false"
"javaHome": "C:\\java\\Eclipse_Adoptium_jre-11.0.14.9-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 Control-M/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 name of the host or the alias of the Control-M/Agent. |
type |
Determines one of the following types of upgrade that is uninstalled:
|
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 |
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 Control-M, 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:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: 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 ("Authentication: 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:
upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/provision/upgrade/$upgradeID"
To select the AuthHeader value ("Authentication: 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>]
where <query string> can contain any of the additional fields.
For multiple values, type commas. You can type ? and * as wildcards.
The following table describes the provision upgrades::get command parameters.
Field |
Description |
---|---|
server |
Defines the name of the Control-M/Server. This field was previously named ctm (deprecated name). |
agent |
Defines the name of the host or alias of the Control-M/Agent. |
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:
|
status |
Determines the activity status. Valid values:
|
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:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/provision/upgrades?agent=Agent2&toVersion=9.0.18*"
To select the AuthHeader value ("Authentication: 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 Control-M/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:
upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/provision/upgrade/$upgradeID/output"
To select the AuthHeader value ("Authentication: 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 Control-M, 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:
upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/provision/upgrade/$upgradeID/retry"
To select the AuthHeader value ("Authentication: 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 Control-M, 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:
upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/provision/upgrade/$upgradeID"
To select the AuthHeader value ("Authentication: 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 Control-M, 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:
upgradeID="ctm1:3"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/provision/upgrade/$upgradeID/cancel"
To select the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Provision a Control-M/Server
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 you can transfer an existing Control-M/Server from one host to another (server rehydration).
You can run either two separate commands or a single command when you provision a Control-M/Server.
The following table describes both methods to provision a Control-M/Server.
Method |
Typical scenario |
Commands |
---|---|---|
Two separate commands |
Dynamic installation: An image, such as a VM image, is prepared with the Control-M/Server ready inside it. The setup process is at a later time, when required. |
|
One command |
A more static architecture, with no distinction between building an image and instantiation. |
|
An additional command is available to uninstall a Control-M/Server from the host.
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 images for the provision process are JSON code. Each image contains a list of installation packages in the order that they are installed. The base Control-M Automation API installation provides several default images. You can also create additional custom images, such as an image to install a newer Control-M/Agent version. Before you begin to provision, you must obtain the installation packages referenced within the images. You can also customize the location to save these packages, such as in a JFrog Artifactory repository, Amazon S3 buckets, or a local file system. Alternatively, if you set up a different location for packages with local Control-M Automation API CLI parameters, see environment configure. For more information about these preparatory tasks, see Control-M Automation API Provisioning.
The following image-related commands enable you to manage Control-M/Agents and Control-M/Server images:
-
provision images: List all existing images.
-
provision image: Download and prepare an image.
-
provision image::remove: Remove an image from the user account.
The following API commands enable you to provision a Control-M/Server:
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 Control-M, 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. |
If annotation is enabled for the Configuration Management category in Control-M, 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 this 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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.