Control-M Automation API Installation

The following list describes the Control-M Automation API components you can install:

Control-M REST API: You install Control-M REST API with Control-M/EM or Control-M Workbench.
Control-M Automation API CLI: You can install Control-M Automation API CLI on Control-M/EM during the Control-M installation.
Control-M Workbench: You can install Control-M Workbench as a development environment to build, run, and test your job workflows without the need to install Control-M.

For advanced Control-M Automation API configuration, see Control-M Automation API Administration.

During an upgrade from a Control-M/EM version lower than 9.0.21.100, old default ports (48080 and 48081) used by Control-M REST API are changed automatically to the new default ports (32080 and 32081, respectively).

Control-M Automation API CLI

Control-M Automation API CLI is installed on Control-M/EM on Windows and Linux during the Control-M installation, and you can run it from the bin directory.

The following procedures describe how to install Control-M Automation API CLI:

Installing Control-M Automation API CLI on Windows
Installing Control-M Automation API CLI on Linux or UNIX
Installing Control-M Automation API CLI on macOS

After you install the Control-M Automation API CLI, you must set up your Control-M environment to use the CLI, as described in Setting Up a Control-M API CLI Environment.

If Control-M Automation API CLI is installed on a host that uses a proxy server, ensure that the proxy server settings are defined, as described in Proxy Server Configuration.

Installing Control-M Automation API CLI on Windows

This procedure describes how to install Control-M Automation API CLI on Windows.

Before You Begin

Verify that you have the following required software installed on your platform:
- Python: Version 3.8.4 or later.
  
  You can download and install it from https://www.python.org/downloads/.
  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/.
Ensure that your platform supports Java 17 or higher, 64-bit, for use by the Provision service.

This Java is different from the Java used by the Control-M Automation API server, as discussed in External Java Management.
Ensure that the CLI and REST API back-end server version are the same to initiate a connection.

The system automatically upgrades or downgrades the CLI when it detects different versions.
During an automatic upgrade, the CLI is also migrated from node.js to Python, if possible:
- If the CLI detects a Python installation, version 3.8.4 or later, along with a pip installation, version 20.1.1 or later, a new Python-based CLI package is downloaded and run.
- If no Python and pip installations of the required versions are detected, the node-based CLI package continues running.
  
  In this case, CLI command data (host and command type) is logged on the Automation API server in the following log file, so that you can identify which machines are still using the old node-based CLI:
  
  %EM_HOME%\emweb\automation-api\downloads\old-cli-usage.log
- If the CLI is Python-based but the server runs an older, node-based version of the CLI, the CLI checks for the existence of a node.js installation. If detected, a node-based CLI package is downloaded and run. Otherwise, the automatic CLI upgrade fails and CLI commands cannot be executed.

Begin

Install Control-M Automation API CLI, as follows:
1. Download the install_ctm_cli.py package from one of the following locations:
  - Control-M: https://<controlmEndPointHost>:8443/automation-api/install_ctm_cli.py
    
    An endpoint is the URI for Control-M Automation API.
  - Control-M Workbench: https://localhost:8443/automation-api/install_ctm_cli.py
2. From the command line, run the following command:
  
  cmd
3. Run the following command from the directory where you saved the install_ctm_cli.py file:
  
  python_executable install_ctm_cli.py
  
  If you install the CLI on a Windows host that stores other Control-M products or components, you might have more than one CLI installation on your host. If you have multiple CLI installations, run the following command for a list of all CLI executables:
  
  where ctm
  
  Based on the output of this command, set the path to the ctm.cmd executable to launch the CLI, and not ctm.bat.
Run the following command:

ctm

A successful response displays the help for the command with a list of the API Services.
Install Java for the Provision service, as follows:
1. Download the OpenJDK installer for Windows from https://developers.redhat.com/products/openjdk/download.
  
  Ensure that you obtain version 17 or higher for 64-bit Windows.
2. Run the installer and follow the instructions.
3. Run the following command to verify that you installed the required Java version:
  
  java -version
  
  The following is an example of a command and response:
  
  >java -version
  
  openjdk version "17.0.2" 2022-01-18 LTS
  
  OpenJDK Runtime Environment 21.9 (build 17.0.2+8-LTS)
  
  OpenJDK 64-Bit Server VM 21.9 (build 17.0.2+8-LTS, mixed mode, sharing)
  - If you have multiple instances of Java installed and you want the API to work with a specific instance of 64-bit Java, ensure that you defined a JAVA_HOME environment variable.
  - The following command provides details of multiple Java instances:
    
    where java
  - Create the environment variable "%JAVA_HOME%"\bin\java -version and specify the pathaname of the 64-bit Java instance to verify the Java version.

Installing Control-M Automation API CLI on Linux or UNIX

This procedure describes how to install Control-M Automation API CLI on Linux or UNIX.

Before You Begin

Verify that you have the following required software installed on your platform:
- Python: Version 3.8.4 or later.
  
  For AIX, choose a version from the official IBM AIX Toolbox.
  
  You can download and install it from https://www.python.org/downloads/.
  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/.
Ensure that your platform supports Java 17 or higher, 64-bit, for use by the Provision service.

This Java is different from the Java used by the Control-M Automation API server, as discussed in External Java Management.
Ensure that the CLI and REST API back-end server version are the same to initiate a connection.

The system automatically upgrades or downgrades the CLI when it detects different versions.
During an automatic upgrade, the CLI is also migrated from node.js to Python, if possible:
- If the CLI detects a Python installation, version 3.8.4 or later, along with a pip installation, version 20.1.1 or later, a new Python-based CLI package is downloaded and run.
- If no Python and pip installations of the required versions are detected, the node-based CLI package continues running.
  
  In this case, CLI command data (host and command type) is logged on the Automation API server in the following log file, so that you can identify which machines are still using the old node-based CLI:
  
  $HOME/ctm_em/etc/emweb/automation-api/downloads/old-cli-usage.log
- If the CLI is Python-based but the server runs an older, node-based version of the CLI, the CLI checks for the existence of a node.js installation. If detected, a node-based CLI package is downloaded and run. Otherwise, the automatic CLI upgrade fails and CLI commands cannot be executed.

Begin

Install Control-M Automation API CLI, as follows:
1. Download the install_ctm_cli.py package from one of the following locations:
  - Control-M: https://<controlmEndPointHost>:8443/automation-api/install_ctm_cli.py
    
    An endpoint is the URI for Control-M Automation API.
  - Control-M Workbench: https://localhost:8443/automation-api/install_ctm_cli.py
2. From the command line, run the following command to install the install_ctm_cli.py package:
  
  python_executable install_ctm_cli.py
Run the following command:

ctm

A successful response displays the help for the command with a list of the API Services.
Install Java to use the Provision service, as follows:
1. Download the OpenJDK installer for UNIX or Linux from http://openjdk.java.net/install/. Ensure that you obtain version 17 or higher for 64-bit.
2. Run the installer and follow the instructions.
3. Run the following command to verify that you installed the required Java version:
  
  java -version
The following is an example of a command and response:

>java -version

openjdk version "17.0.2" 2022-01-18 LTS

OpenJDK Runtime Environment 21.9 (build 17.0.2+8-LTS)

OpenJDK 64-Bit Server VM 21.9 (build 17.0.2+8-LTS, mixed mode, sharing)

If you have multiple instances of Java installed, and you want the API to work with a specific instance of 64-bit Java, ensure that you defined a JAVA_HOME environment variable.

The following command provides details of multiple Java instances:

where java

Create the environment variable "%JAVA_HOME%"\bin\java -version and specify the pathname of the 64-bit Java instance to verify the Java version.

Installing Control-M Automation API CLI on macOS

This procedure describes how to install Control-M Automation API CLI on macOS.

Before You Begin

Verify that you have the following required software installed on your platform:
- Python: Version 3.8.4 or later.
  
  You can download and install it from https://www.python.org/downloads/.
  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/.
Ensure that the CLI and REST API back-end server version are the same to initiate a connection.

The system automatically upgrades or downgrades the CLI when it detects different versions.
During an automatic upgrade, the CLI is also migrated from node.js to Python, if possible:
- If the CLI detects a Python installation, version 3.8.4 or later, along with a pip installation, version 20.1.1 or later, a new Python-based CLI package is downloaded and run.
- If no Python and pip installations of the required versions are detected, the node-based CLI package continues running.
  
  In this case, CLI command data (host and command type) is logged on the Automation API server in the following log file, so that you can identify which machines are still using the old node-based CLI:
  
  $HOME/ctm_em/etc/emweb/automation-api/downloads/old-cli-usage.log
- If the CLI is Python-based but the server runs an older, node-based version of the CLI, the CLI checks for the existence of a node.js installation. If detected, a node-based CLI package is downloaded and run. Otherwise, the automatic CLI upgrade fails and CLI commands cannot be executed.

Begin

Install Control-M Automation API CLI, as follows:
1. Download the install_ctm_cli.py package from one of the following locations:
  - Control-M: https://<controlmEndPointHost>:8443/automation-api/install_ctm_cli.py
    
    An endpoint is the URI for Control-M Automation API.
  - Control-M Workbench: https://localhost:8443/automation-api/install_ctm_cli.py
2. From the command line, run the following command to install the install_ctm_cli.py package:
  
  python_executable install_ctm_cli.py
Run the following command:

ctm

A successful response displays the help for the command with a list of the API Services.

Setting Up a Control-M API CLI Environment

This procedure describes how to set up a Control-M environment to use Control-M Automation API CLI after all the required components are installed. An environment is a combination of a REST API endpoint and API token, or a combination of an endpoint, username, and password. You can configure one default environment and multiple environments.

Begin

Run one of the following commands to add an environment:
- API token: ctm environment add <env> <endPoint> <token>
  
  where
  - endPoint is the URI for Control-M Automation API, with the following format:
    
    https://<controlmEndPointHost>:8443/automation-api
  - token is the name of a valid API token. You can obtain your first API token through the Control-M user interface, as described in Creating an API Token. For more information about API tokens, see Authentication Service.
  ctm environment add devEnvironment "https://<controlmEndPointHost>:8443/automation-api" "<token>"
- Username and password: ctm environment add <env> <endPoint> <user> [<password>]
  
  ctm environment add devEnvironment "https://<controlmEndPointHost>:8443/automation-api" "<ControlmUser>" "<ControlmPassword>"
- Control-M Workbench: ctm environment workbench::add [<endPoint>]
- To accept certificates signed by a trusted Certificate Authority and not self-signed certificates, type the environment configure command to set the rootCertificateRequired parameter to true.
- Environments are kept in the user home folder ~/.ctm/env.json on Linux and %USERPROFILE%\.ctm\env.json in Windows.
If you have multiple environments, set the default environment with one of the following commands:
- Existing environment: ctm environment set <environment>
- Control-M Workbench: ctm environment set workbench
The returned response lists all existing environments.
After setting the default environment, if you want to run API commands against a different, non-default environment, you must do the following:
- Include the -e <environment> option in all the API commands that you run.
  
  ctm deploy jobs.json -e TestEnvironment
- Ensure that the version of the destination environment matches the CLI version.
Run an API command to verify the setup.
- To retrieve information about Control-M/Servers, run the Config Service API command:
ctm config servers::get
- If you created the Control-M environment for CLI using a username and password, log in to Control-M and return a session token by running the session login API command.
For on-screen help, run one or more of the following commands:
- REST API documentation for this environment: ctm documentation restApi
- Web-based API documentation: ctm doc gettingStarted

Installing Control-M Workbench

This procedure describes how to install Control-M Workbench on your host as a Docker image. The image is hosted on containers.bmc.com.

Control-M Workbench enables you to have your own Control-M development environment without the need to install Control-M.

Before You Begin

Ensure that you have sufficient permissions to download Control-M/EM from the EPD site.
Install Docker.
Ensure that Ports 8443 and 7005 are free. The Provision service uses Port 7005.
Allocate 8 GB of free memory to the container.

Begin

On the EPD home page, click Product Download Tool.
Click the Container Products filter at the top right of the page.
Click Download Container Access Key.

The container-token.bmc file downloads and contains an access key for containers.bmc.com.
Copy the access key.
Ensure that Docker is installed and running, and run the following command:

docker login containers.bmc.com -u<username>

The <username> is the username to access the EPD site.

The password prompt appears.
Paste the key from the container-token.bmc file.
Ensure that you are logged in to containers.bmc.com.
Run the following command:

docker pull containers.bmc.com/bmc/workbench:<latest version>-GA

The <latest version> is the most recent monthly version of Control-M Automation API.

docker pull containers.bmc.com/bmc/workbench:9.22.20-GA
Run the following command:

docker run -dt --cpus=4 -m 8g -p 8443:8443 --hostname=workbench containers.bmc.com/bmc/workbench:9.22.20-GA

Change the following strings:
- workbench:9.22.20-GA: Define the most recent version of Control-M Automation API.
- --cpus=4 -m 8g: Determine the exact limits for memory and CPU consumption on your host machine.
Wait until the container is healthy and then check the status with the following command:

docker ps

The container typically starts within 3 minutes and is ready. Examples are available in the GitHub repository.