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 or integration plug-ins (even plug-ins developed in Control-M Application Integrator) 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).

Provision a New Control-M/Agent and Deploy 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 for the installation of 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 both image and setup).

• provision image::remove: Uninstalls an image from the user account without unregistering it.

• provision agent::uninstall: Uninstalls an image from the user account and unregisters it.

For the installation of an Agent, you can choose between the following options:

• Run the image and setup commands separately. This is useful when your architecture requires dynamic installation and setup of Agents. In this scenario, you use the image command to prepare your image (such as a VM image, a Docker image, or an AWS AMI) with the Agent inside it. Then, when required, you use the setup command to dynamically perform Agent setup and register it to the Control-M/Server.

• Run the install command to perform all installation phases. This option is useful in a more static architecture, where there is no distinction between building an image and instantiation.

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 (for the Agent, application plug-ins, or integration plug-ins and plug-ins developed in Control-M Application Integrator) 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) or 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. Returns a list of image names.

CLI Syntax

ctm provision images <os>

The following table describes the provision images command parameters.

Here is an example of 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

Example using cURL:

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

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

For selecting 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.

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.

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

ctm provision image <image> -f <configuration file>

The following table describes the provision image command parameters.

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

provision agent::setup

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

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

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

{
    "connectionInitiator": "AgentToServer",
    "tag": "abc_1234",
    "serverHostName":"ctmServer2",
    "serverPort": 7777,
    "secondaryServerHostName": "ctmServer3"
}

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

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

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 the setup commands into one action. Downloads the agent and then connects and registers it with a Control-M/Server.

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

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

{
    "connectionInitiator": "AgentToServer",
    "tag": "abc_1234",
    "serverHostName":"ctmServer2",
    "serverPort": 7777,
    "javaHome": "C:\\java\\Eclipse_Adoptium_jre-11.0.14.9-hotspot"
}

The following table describes additional provision agent::install command parameters to use in the configuration file.

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 unregistering it in Control-M.

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.

ctm provision agent::uninstall

Upgrade an Existing Control-M/Agent and Deploy 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:

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 Preparing Installation Packages for Agent Upgrades.

The Provision service offers the following commands for upgrade processes:

provision upgrades:versions::get

The provision upgrades:versions::get command enables you to obtain 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

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

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

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

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

The provision upgrades:agents::get command enables you to obtain 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.20.200:

ctm provision upgrades:agents::get -s "type=Agent&version=9.0.20.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

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"

For selecting 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 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

The provision upgrade::install command enables you to transfer 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 <server> <agent> <type> <version> [activityName] [-f <configuration file>]

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

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

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

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

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

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 (server, 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.

The following table describes additional provision upgrade::install command parameters to use in the command file.

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):

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

For example, LocalControlM:12

provision upgrade::uninstall

The provision upgrade::uninstall command enables you to uninstall 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 <server> <agent> <type> <version> [activityName] [-f <configuration file>]

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

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

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

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

For selecting 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>

For example, 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 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

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

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

For selecting 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, 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.

The following table describes the provision upgrades::get command parameters.

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

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

For selecting 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 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

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

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

For selecting 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 failed previously.

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

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

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

For selecting 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 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

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"

For selecting 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 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

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"

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

Provision 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 between 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 Control-M Automation API Provisioning. To alternatively set a different location of packages using local Automation CLI parameters, see environment configure.

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

• provision server::setup

• provision server::install

• provision server::uninstall

provision server::setup

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

CLI Syntax

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 the setup commands into one action. Downloads the Control-M/Server, installs it, and registers it in the Control-M environment.

CLI Syntax

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

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

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.

CLI Syntax

ctm provision server::uninstall [server]

Where [server] is the name of the Control-M/Server. This is required only on a Linux machine 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.