Control-M Automation API Installation

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

  • Control-M REST API: You can download Control-M REST API from Amazon S3 storage or from the EPD on a monthly basis.

  • 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.

Control-M REST API

Control-M REST API is available with a monthly download from Amazon S3 storage or EPD. Different versions of the API can reside side-by-side on the system. The system does not overwrite a newer API when you install a version of Control-M that contains an older API version.

Control-M Automation API monthly releases are compatible with Control-M 9.0.20 and higher. The current documentation indicates the specific features that require a higher version of Control-M, and the minimum version of Control-M that is compatible with each feature.

The following procedures describe how to install and uninstall Control-M REST API:

Control-M Automation API no longer supports Java 11 as of version 9.0.21.325, the monthly release of October 2024. Starting with this version of Control-M Automation API, Java 17 or higher is required. See External Java Management.

Installing Control-M REST API from Amazon S3 Storage

This procedure describes how to download and install Control-M Automation API from Amazon S3.

You can follow the same procedure to upgrade from a previous version of Control-M Automation API.

During an upgrade, the API process (the emrestsrv process) is stopped and automatically restarted.

Begin

  1. Create a temporary directory to save downloaded files.

  2. Click one of the following S3 links:

  3. Save the PADEV.9.0.22.010 file in the temporary directory.

  4. (UNIX only) Type the following command for the copied installation file to ensure that it has the necessary authorizations:

    chmod +x <full name of PADEV.9.0.22.010 file>

  5. Ensure that you are logged in with the same user account that is used to install Control-M/EM and run the .bin or .exe file.

By default, the installation extracts the files to the /tmp directory and executes several scripts from that location. You can change the path to another location if your system does not allow execution from the /tmp directory. To change the path, set up an environment variable named INST_TEMP_DIR and set its value to the relevant location. Ensure that you have sufficient disk space in the specified location to extract the file.

Installing Control-M REST API from the EPD

This procedure describes how to download and install Control-M Automation API from EPD.

You can follow the same procedure to upgrade from a previous version of Control-M Automation API.

During an upgrade, the API process (the emrestsrv process) is stopped and automatically restarted.

Begin

  1. Create a temporary directory to save downloaded files.

  2. Click Control-M/Enterprise Manager 9.0.21 download page in EPD.

    If you are not yet registered, click http://www.bmc.com/available/epd and follow the instructions until you reach the Download Files page for Control-M/Enterprise Manager version 9.0.21.

  3. Click the Products tab.

  4. Click the Control-M Automation API 9.0.22.010 installation package.

  5. Save the PADEV.9.0.22.010 file in the temporary directory.

  6. (UNIX only) Type the following command for the copied installation file to ensure that it has the necessary authorizations:

    chmod +x <full name of PADEV.9.0.22.010 file>

  7. (Windows only) Extract the downloaded zip file to the temporary directory.

  8. Ensure that you are logged in with the same user account that is used to install Control-M/EM and run the .bin or .exe file.

By default, the installation extracts the files to the /tmp directory and executes several scripts from that location. You can change the path to another location if your system does not allow execution from the /tmp directory. To change the path, set up an environment variable named INST_TEMP_DIR and set its value to the relevant location. Ensure that you have sufficient disk space in the specified location to extract the file.

Uninstalling the Control-M REST API

This procedure describes how to uninstall Control-M Automation API.

Begin

  1. Navigate to the following directory:

    <EM_HOME>/install/PADEV.9.0.22.010

  2. Run one of the following files:

    • uninstall.bin

    • uninstall.bat

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:

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:

    • Node.js: BMC recommends the long-term support (LTS) release.
      You can download it from https://nodejs.org/en/download/.

      The Node.js installer includes the npm (Node Package Manager) utility.

  • 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, a new Python-based CLI package is downloaded and run.

    • If no Python installation of the required version is 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

  1. Install Control-M Automation API CLI, as follows:

    1. Download the ctm-cli.tgz node package from one of the following locations:

      • Control-M: https://<controlmEndPointHost>:8443/automation-api/ctm-cli.tgz

        An endpoint is the URI for Control-M Automation API.

      • Control-M Workbench: https://localhost:8443/automation-api/ctm-cli.tgz

    2. From the command line, type the following command:

      cmd

    3. Type the following command from the directory where you saved the ctm-cli.tgz file:

      npm -g install ctm-cli.tgz

      The -g argument installs the package globally so any user can run Control-M Automation API CLI from any directory.

      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, type 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.

  2. Run the following command:

    ctm

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

  3. 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. Type 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 full path to 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:

    • Node.js: BMC recommends the long-term support (LTS) release.
      You can download it from https://nodejs.org/en/download/.

      The Node.js installer includes the npm (Node Package Manager) utility.

  • 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, a new Python-based CLI package is downloaded and run.

    • If no Python installation of the required version is 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

  1. Install Control-M Automation API CLI, as follows:

    1. Download the ctm-cli.tgz from one of the following locations:

      • Control-M: https://<controlmEndPointHost>:8443/automation-api/ctm-cli.tgz

        An endpoint is the URI for Control-M Automation API.

      • Control-M Workbench : https://localhost:8443/automation-api/ctm-cli.tgz

    2. From the command line, type the following command to install the ctm-cli.tgz package:

      sudo npm -g install ctm-cli.tgz

      The -g argument installs the package globally so any user can run Control-M Automation API CLI from any directory.

  2. Run the following command:

    ctm

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

  3. 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. Type 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 full path to 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:

    • Node.js: BMC recommends the long-term support (LTS) release.
      You can download it from https://nodejs.org/en/download/.

      The Node.js installer includes the npm (Node Package Manager) utility.

  • 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, a new Python-based CLI package is downloaded and run.

    • If no Python installation of the required version is 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

  1. Install Control-M Automation API CLI, as follows:

    1. Download the ctm-cli.tgz node package from one of the following locations:

      • Control-M: https://<controlmEndPointHost>:8443/automation-api/ctm-cli.tgz

        An endpoint is the URI for Control-M Automation API.

      • Control-M Workbench: https://localhost:8443/automation-api/ctm-cli.tgz

    2. From the command line, type the following command to install the ctm-cli.tgz package:

      sudo npm -g install ctm-cli.tgz

      The -g argument installs the package globally so any user can run Control-M Automation API CLI from any directory.

  2. 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

  1. 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.

  2. 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.

  3. 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

  1. On the EPD home page, click Product Download Tool.

  2. Click the Container Products filter at the top right of the page.

  3. Click Download Container Access Key.

    The container-token.bmc file downloads and contains an access key for containers.bmc.com.

  4. Copy the access key.

  5. Ensure that Docker is installed and running, and type the following command:

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

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

    The password prompt appears.

  6. Paste the key from the container-token.bmc file.

  7. Ensure that you are logged in to containers.bmc.com.

  8. Type 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.10-GA

  9. Run the following command:

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

    Change the following strings:

    • workbench:9.22.10-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.

  10. 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.