Setting Up the API
This procedure describes how to set up Control-M Automation API and connect it with Control-M SaaS.
The following video demonstrates the setup tasks that are described on this page: BMC Control-M SaaS - Automation API Getting Started.
Begin
-
Install the Control-M Automation API CLI to expose the Control-M REST API as a Command Line Interface (CLI) using one of the following methods:
-
Create your first API token for API authentication, as described in Creating Your First Token for API Authentication.
-
Set up a Control-M environment for running commands through the CLI, as described in Setting Up a Control-M Environment for the CLI.
-
As an administrator, ensure that your API users have sufficient authorizations for the various API functionalities and services, as described in Authorizations for API Functionalities and Services.
Performing a Standard Control-M Automation API CLI Installation
This procedure describes how to install the Control-M Automation API CLI using the standard installation method.
Before You Begin
-
Install the following prerequisite software:
-
Python, version 3.8.4 or later.
For AIX, choose a version from the official IBM AIX Toolbox.
Ensure that Python is included in your system path.
-
pip, version 20.1.1 or later.
If pip is not installed by the Python installer, obtain it from https://pip.pypa.io/en/stable/installation/.
-
Java LTS (Long Term Support release), 64-bit, for using the Provision service.
For a list of supported Java vendors and versions, see Control-M Compatibility with External Java Vendors.
Download and install the relevant OpenJDK package, according to the instructions in http://openjdk.java.net/install/, and set the Java environment variable to point to the external Java. For more information, see Setting the Java Environment Variable.
-
-
If you are installing Control-M Automation API CLI on a host that uses a proxy server, ensure that the proxy server settings are defined, as described in Proxy Server Configuration.
Begin
-
In Control-M SaaS, from the Configuration domain, click the orange drop-down arrow button and select Plug-ins.
-
Click Install Plug-in.
-
Select the Automation API plug-in.
-
In the textual instructions on the right, expand one of the following sections:
-
Standard Installation on Linux
-
Standard Installation on Windows
-
-
Do one of the following:
-
Linux:
-
Click cURL command or wget command to copy a command to your clipboard.
-
On the host where you want to download the DR5V3_Linux-x86_64.BIN installation file, paste the cURL command or wget command into the command line utility, and run the command.
-
Verify that the installation file has execute permissions.
-
-
Windows: Click the provided link to download the DR5V3_windows_x86_64.exe installation file to the target host.
-
-
Run the installation file and follow the on-screen instructions.
-
Ensure that the CLI installation was successful by running the ctm command.
After a successful installation, this command returns help on the various API commands and options.
-
If you installed the CLI on a Windows host that is home to other Control-M products or components, you might have more than one installation of the CLI on your host. In such a case, use the where ctm command to obtain a list of all CLI executables. Based on the output of this command, set the path for launching the CLI to the path of the ctm.cmd executable (and NOT ctm.bat).
-
To access Control-M Automation API documentation while working in the API, you can use the following API commands:
-
REST API documentation: ctm documentation restAPI
-
Web-based API documentation: ctm doc gettingStarted
-
Performing a Python Package Installation of Control-M Automation API CLI
This procedure describes how to install the Control-M Automation API CLI as a Python package.
Before You Begin
-
Install the following prerequisite software:
-
Python, version 3.8.4 or later.
For AIX, choose a version from the official IBM AIX Toolbox.
Ensure that Python is included in your system path.
-
pip, version 20.1.1 or later.
If pip is not installed by the Python installer, obtain it from https://pip.pypa.io/en/stable/installation/.
-
Java LTS (Long Term Support release), 64-bit, for using the Provision service.
For a list of supported Java vendors and versions, see Control-M Compatibility with External Java Vendors.
Download and install the relevant OpenJDK package, according to the instructions in http://openjdk.java.net/install/, and set the Java environment variable to point to the external Java. For more information, see Setting the Java Environment Variable.
-
-
If you are installing Control-M Automation API CLI on a host that uses a proxy server, ensure that the proxy server settings are defined, as described in Proxy Server Configuration.
Begin
-
In Control-M SaaS, from the Configuration domain, click the orange drop-down arrow button and select Plug-ins.
-
Click Install Plug-in.
-
Select the Automation API plug-in.
-
In the textual instructions on the right, expand one of the following sections:
-
Installation as Python package Linux
-
Installation as Python package Windows
-
-
Do one of the following:
-
Linux or macOS:
-
Click cURL command or wget command to copy a command to your clipboard.
-
On the host where you want to download the install_ctm_cli.py package, paste the cURL command or wget command into the command line utility, and run the command.
-
On a terminal, type the following command from the directory where you saved the install_ctm_cli.py file:
python install_ctm_cli.py
-
-
Windows:
-
Click the provided link to download the install_ctm_cli.py package to the target host.
-
Run cmd, and then type the following command from the directory where you saved the install_ctm_cli.py file:
python install_ctm_cli.py
-
-
-
Ensure that the CLI installation was successful by running the ctm command.
After a successful installation, this command returns help on the various API commands and options.
-
If you installed the CLI on a Windows host that is home to other Control-M products or components, you might have more than one installation of the CLI on your host. In such a case, use the where ctm command to obtain a list of all CLI executables. Based on the output of this command, set the path for launching the CLI to the path of the ctm.cmd executable (and NOT ctm.bat).
-
To access Control-M Automation API documentation while working in the API, you can use the following API commands:
-
REST API documentation: ctm documentation restAPI
-
Web-based API documentation: ctm doc gettingStarted
-
Creating Your First Token for API Authentication
This procedure describes how to create your first token for API user authentication, which must be done through Control-M SaaS
For more information, see Creating an API Token in the Control-M SaaS documentation.
Begin
-
In Control-M SaaS, from the Configuration domain, click the orange drop-down arrow button and select API Token.
-
Click Add token.
-
Enter token settings: set a name, assign the relevant roles, and set an expiration date (UTC-based).
-
Click Generate.
-
Copy the API token value and then click Done.
After generating your first token, you can generate additional tokens for your user using the Authentication Service.
Setting Up a Control-M Environment for the CLI
This procedure describes how to set up a Control-M environment so that you can run commands through the CLI. An Environment is a combination of an endPoint and token.
Begin
-
Add a new environment by running the following command:
ctm environment add <environment_name> <endPoint> <token>
where
-
endPoint is the URI for Control-M Automation API, with the following format:
https://<controlmEndPointHost>/automation-api
and controlmEndPointHost has the following format:
<tenant-name>-aapi.<zone>.controlm.com
-
token is the name of a valid API token.
The following command adds an environment named myEnvironment:
ctm environment add myEnvironment "https://tenant-123-aapi.us1.controlm.com/automation-api" "<token>"
While the environment is added, it is checked for its policy regarding certificates. If the environment is currently set to accept self-signed certificates, a warning is displayed. If you want to apply a stricter policy of accepting only certificates signed by a trusted Certificate Authority (and not accepting self-signed certificates), you can use the environment configure command to set the rootCertificateRequired parameter to true.
-
-
Set the default environment by running the following command:
ctm environment set <environment_name>
The new Control-M instance named myEnvironment is set as the default environment, and the returned response lists all existing environments.
Copy> ctm environment set myEnvironment
info: current environment: myEnvironment
info: environments: {
"prodEnvironment": {
"endPoint": "https://tenant-0001-aapi.us1.controlm.com/automation-api"
},
"myEnvironment": {
"endPoint": "https://tenant-0002-aapi.us1.controlm.com/automation-api"
}
}-
When you set up your first environment, it is automatically set as the default environment that is used by any API commands that you invoke. In such a case, you can skip this step. Later, after defining additional environments, perform this step to set the default environment of your choice.
-
After setting the default environment, if you want to run API commands against a different, non-default environment, you must include the -e <environmentName> option in any API command that you run. In addition, ensure that the version of the destination environment matches the version of the CLI.
-