Provision service

For Control-M to run and monitor jobs on your application host, a Control-M/Server and Control-M/Agent should be installed. The Provision service allows you access to the full cycle of the following setup processes for agents and servers:

• Provisioning a new installation of a new Control-M/Agent, including the option of deploying application plug-ins to the Agent during provisioning
• Upgrading an existing Control-M/Agent and deploying certain plug-ins to an existing Agent
• Provisioning a Control-M/Server, either as a new server or by transferring an existing Control-M/Server from one machine to another (server rehydration)

Provisioning a new Control-M/Agent and deploying application plug-ins

For a new installation, the Provision service includes the following major commands:

• Image: prepares the file system installation of the Agent
• Setup: registers and configures the Agent with a Control-M/Server
• Install: runs image and setup in a single step

Separating the Image and Setup phases can help in a situation in which installing and setting up Agents dynamically is required by your architecture. In this scenario, you can prepare your image (whether it is a VM image, a Docker image, AWS AMI, etc.) with the Agent inside it. Then when required, use the setup command to dynamically perform Agent setup and register it to the Control-M/Server.

For a more static architecture, where there is no distinction between building an image and instantiation, you can use the provision install command, which allows you to install in a single step.

Additional commands are available for removing an image and for uninstalling a Control-M/Agent from the application host.

The images used during provisioning are JSON code too. Each image contains a list of installation packages in the order that they are installed. Several default images are provided with the base installation of Control-M Automation API, and you can create additional custom images (for example, for installation of a newer version of the Control-M/Agent). To prepare for provisioning, you must obtain the installation packages that are referenced within the images. You can also (optionally) customize the location in which to save these packages (for example, you might want to save the packages in a JFrog Artifactory repository, in Amazon S3 Buckets, or in your local file system). For more information about these preparatory tasks, see the Control-M Administrator Guide in the Control-M Online Help.

provision images

Get a list of the images available for a specific OS. Returns a list of image names.

CLI Syntax

ctm provision images <os>

Where:

Here is an example of requesting a list of available images and a typical response:

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

REST API Syntax

Example using  curl:

os=Linux
curl -H "Authorization: Bearer $token" $endpoint/provision/images/$os

provision image

Downloads an image and prepares it for installation.

In the case of 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.

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

CLI Syntax

ctm provision image <image>

Where:

provision agent::setup  

Connects and registers an image with a Control-M environment.

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

CLI Syntax

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

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{
    "connectionInitiator": "AgentToServer"
}

Where:

For example:

provision agent::setup
provision agent::setup ""          ""       2056
provision agent::setup "controlm1" ""       2056
provision agent::setup ""          "alias1" 2056
provision agent::setup -f persistent.json

provision agent::install

Combines the image and the setup commands into one action. Downloads the agent and then connects and registers it with a Control-M/Server.

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

CLI Syntax

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

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{
    "connectionInitiator": "AgentToServer"
}

Where:

provision image::remove

Uninstalls a Control-M image from this user account without unregistering it in Control-M.

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

CLI Syntax

ctm provision image::remove

provision agent::uninstall

Uninstalls a Control-M image from this user account and unregisters it from the Control-M/Server.

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

CLI Syntax

ctm provision agent::uninstall

Upgrading an existing Control-M/Agent and deploying application plug-ins

You can use API commands to perform various upgrade activities on existing Control-M/Agents, including agent upgrades and plug-in deployments. The following table lists the various activities that you can perform using 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
Roll back to a previous version
Install new plug-in on existing agent	NA
Remove plug-in from Agent	NA

To prepare for provisioning, you must obtain the Control-M/Agent installation packages that you plan to use in your 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 installations of Control-M MFT and Control-M Application Pack. For more information about preparing the packages, see the Control-M Administrator Guide in the Control-M Online Help.

The Provision service offers the following commands for upgrade processes:

provision upgrades:versions::get

Obtains a list of upgrades that are available, based on the installation packages that are currently stored in your directories — Control-M/Agent packages in <EM_HOME>/AUTO_DEPLOY, Control-M MFT and Control-M Application Pack packages in <EM_HOME>/CM_DEPLOY.

CLI Syntax

ctm provision upgrades:versions::get

REST API Syntax

See REST API reference.

curl -H "Authorization: Bearer $token" $endpoint/provision/upgrades/versions

Response

The response lists all available upgrades according to type (Agent, MFT, or AppPack) and target version, as in the following example:

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

Obtains a list of agents in your environment that are eligible for upgrade using any of the packages that are found in your directories. You can optionally limit the list to upgrades of a certain type (Agent, MFT, or AppPack) and target version.

CLI Syntax

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

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

The following example command will return details for agents that can be upgraded to version 9.0.18.200:

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

The following example command will return details for agents on which Control-M MFT can be deployed (installed or upgraded):

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

REST API Syntax

See REST API reference.

curl -H "Authorization: Bearer $token" 
"$endpoint/provision/upgrades/agents?type=Agent&version=9.0.18.000"

Response

The response provides details for each agent and each possible upgrade that can be performed on it. In the following example, one agent was found eligible for upgrade from version 9.0.00 to version 9.0.18.100. The same agent was found eligible for installation of 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

Transfers a deployment package to the agent host and installs it there. Use this API command to perform any of the following activities:

• Upgrade a Control-M/Agent to a newer version
• Install a new plug-in (Control-M MFT or Control Application Pack) on an existing Agent
• Upgrade a plug-in (Control-M MFT or Control Application Pack) on the Agent

CLI Syntax

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

Where:

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

See REST API reference.

In the following curl example, note that the path to the configuration file is prefixed with an @ character.

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

Configuration file for provision upgrade or rollback

You need a configuration file in the following scenarios:

• If you are using a REST API command, use the configuration file to specify values for the various upgrade parameters or rollback parameters (which can be included in a CLI command). These parameters include several required parameters (ctm, agent, type, and version) and the optional activityName.

• To specify values for the following additional parameters. These parameters cannot be included in the CLI command:

  Parameter	Description
  installUser	The user account used to perform the installation of the package. This parameter is required if all of the following conditions exist: The Control-M/Agent is hosted on a Windows computer. The Control-M/Agent is currently at a version earlier than 9.0.00.300 (version 9.0.00, fix pack 3). The Control-M/Agent's security setting "Logon as User" is set to Yes. For more information, see Security parameters in the Control-M Online Help. In all other cases, the user is set automatically, and any value that you set through this parameter is ignored. NOTE: Due to JSON character escaping, if the user name includes a backslash, each backslash must be doubled (for example, "domain\\userName").
  notifyAddress	A list of email addresses of recipients of notifications regarding this upgrade or rollback process. Use the semicolon character (;) to separate multiple email addresses.
  description	A description for the upgrade activity.

The following sample configuration file contains all possible parameters (including the optional parameters and the parameters that you could alternatively set through the CLI command):

{
  "ctm": "localControlM",
  "agent": "agent1",
  "type": "Agent",
  "version": "9.0.18.100",   
  "activityName": "Agent1 upgrade for localControlM",
  "installUser": "user3",
  "notifyAddress": "joe@example.com;jane@example.com",
  "description": "Upgrading the agent to version 9.0.18.100"
}

Response

The installation package is deployed and installed, and an upgradeID is returned. The upgradeID has the following format: <ctm>:<activityNumber> (for example, LocalControlM:12)

provision upgrade::uninstall

Uninstalls an upgrade deployment package at the target Control-M/Agent. Use this API command to perform any of the following activities:

• Roll back the newest version of a Control-M/Agent
• Roll back the newest version of a plug-in (Control-M MFT or Control Application Pack)
• Remove the Control-M MFT plug-in from the Agent (if no previous version was installed)

CLI Syntax

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

Where:

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

See REST API reference.

In the following curl example, note that the path to the configuration file is prefixed with an @ character.

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

Response

The installation package is uninstalled, and an upgradeID is returned. The upgradeID has the following format: <ctm>:<activityNumber> (for example, LocalControlM:12)

provision upgrade::get

Obtains status details for a specific upgrade activity.

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

CLI Syntax

ctm provision upgrade::get <upgradeID>

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

REST API Syntax

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID"

provision upgrades::get

Obtains status details for all upgrade activities or for multiple upgrade activities based on specified filters.

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

CLI Syntax

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

Where <query string> can contain any of the following fields.

Note: For multiple values, use commas. As wildcards, you can use question mark and asterisk characters (? and *).

The following example command will return 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

See REST API reference. 

curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrades?agent=Agent2&toVersion=9.0.18*" 

provision upgrade:output::get

Retrieves output log messages from the Control-M/Agent regarding a specific upgrade activity. The output log messages are displayed on-screen.

CLI Syntax

ctm provision upgrade:output::get <upgradeID>

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

REST API Syntax

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID/output"

provision upgrade::retry

Retries to run an upgrade activity that failed previously.

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

CLI Syntax

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

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID/retry"

provision upgrade::delete

Deletes the record of an upgrade activity that has finished running (that is, an upgrade activity in status Completed, Cancelled, or Failed).

CLI Syntax

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

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" -X DELETE $endpoint/provision/upgrade/$upgradeID

provision upgrade::cancel

Aborts an upgrade activity that is currently running (that is, an upgrade activity in status Running or TransferCompleted).

CLI Syntax

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

See REST API reference.

upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" -X POST $endpoint/provision/upgrade/$upgradeID/cancel

Provisioning a Control-M/Server

Provisioning of a Control-M/Server 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 machine to another (server rehydration).

When provisioning a Control-M/Server you can choose betwen running two separate commands or one command:

An additional command is available for uninstalling a Control-M/Server from the host machine.

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

The images used during provisioning are JSON code too. Each image contains a list of installation packages in the order that they are installed. Default images are provided with the base installation of Control-M Automation API, and you can create additional custom images (for example, for installation of a newer version of the Control-M/Server). To prepare for provisioning, you must obtain the installation packages that are referenced within the images. You can also (optionally) customize the location in which to save these packages (for example, you might want to save the packages in a JFrog Artifactory repository, in Amazon S3 Buckets, or in your local file system). For more information about these preparatory tasks, see the Control-M Administrator Guide in the Control-M Online Help.

provision server::setup  

Installs a Control-M/Server and registers it in the Control-M environment.

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

CLI Syntax

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

Where:

provision server::install

Combines the image and the setup commands into one action. Downloads the Control-M/Server, installs it, and registers it in the Control-M environment.

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

CLI Syntax

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

Where:

provision server::uninstall

Uninstalls a Control-M/Server from this user account and unregisters it from the Control-M environment.

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

CLI Syntax

ctm provision server::uninstall [ctm]

Where:

_{Back to top}