Automation API Installation

This topic describes the tasks that you must perform to install and set up Control-M Automation API. The Control-M - Automation API Getting Started video demonstrates the setup tasks described below.

The following is a list of the Control-M Automation API components that are installed:

Components and Requirements

The following table describes the Control-M Automation API components and their requirements:

Component

Function and Requirements

Further Information

Control-M REST API

Defines a set of commands to:

  • Test, run and deploy job definitions and packages to Control-M

  • Provision a Control-M/Agent

  • Manage environments

  • The current documentation describes the specific features that require a later Control-M version. In addition, it specifies the minimum version that is compatible with each feature.

  • Different versions of the REST API can reside side-by-side on the system. If you install another version of Control-M that contains an older version of the API, the system does not overwrite the newer API.

Download, Install, or Upgrade Control-M REST API

Control-M Workbench

Defines a personal Control-M development environment to build, run, and test your job flows, without a Control-M installation.

You run Control-M Workbench on your host as a Docker image.

Running Control-M Workbench

Control-M Instance

Defines an installed instance of Control-M. You can choose to use an installed instance of Control-M instead of the Control-M Workbench.

For information about installing Control-M, see the Installation Guide.

For information about configuring Control-M Automation API in a Control-M installation, see the Control-M Automation API Administration.

Control-M Automation Command Line Interface (CLI)

Defines a Node.js package that exposes the Control-M REST API as a Command Line Interface (CLI).

Software requirements:

  • The CLI must be installed on any platform that supports the following required software:

    • Node.js: BMC recommends version 18.

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

    • Java: To use the Provision service, install Java 11 or later, 64-bit.

  • The CLI and REST API back-end server version must be the same to initiate a connection. If a difference in the versions is detected, the CLI is upgraded or downgraded automatically.

For installation instructions, see Installing the Control-M Automation CLI.

For additional setup steps that you must perform after installing the CLI, see Setting up a Control-M Environment for the CLI.

Download, Install, or Upgrade Control-M REST API

Monthly releases of Control-M REST API are available for download from an S3 storage location or from the Electronic Product Distribution (EPD) site. Use the following steps to download and install the monthly release.

Use the same steps 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.

Installing Control-M REST API from Amazon S3 Storage

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

Begin

  1. Create a temporary directory where to save downloaded files.

  2. Click the relevant S3 link as follows, and save the PADEV.9.0.21.235 file in the temporary directory:

  3. (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.21.235 file>

  4. Ensure that you are logged on with the same user account as the account used to install Control-M/Enterprise Manager, 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. If your system does not allow execution from the /tmp directory, you can change the path to any other location. To change the path, you can set up an environment variable named INST_TEMP_DIR, and set its value to the relevant location. Ensure that you have sufficient disk space for file extraction in the specified location.

Installing Control-M REST API from the Electronic Product Distribution Site

This procedure describes how to download and install Control-M Automation API from the BMC Electronic Product Distribution (EPD) site:

Begin

  1. Create a temporary directory where to save downloaded files.

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

    If you have not yet registered at the EPD site, 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. On the Products tab, click the Control-M Automation API 9.0.21.235 installation package, and save the PADEV.9.0.21.235 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.21.235 file>

  5. (Windows only) Extract the downloaded zip file in the temporary directory.

  6. Ensure that you are logged on with the same user account as the account used to install Control-M/Enterprise Manager, 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. If your system does not allow execution from the /tmp directory, you can change the path to any other location. To change the path, you can set up an environment variable named INST_TEMP_DIR, and set its value to the relevant location. Ensure that you have sufficient disk space for file extraction in the specified location.

Uninstalling the Control-M REST API

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

Begin

  1. In the Control-M installation directory, navigate to <EM_HOME>/install/PADEV.9.0.21.235

  2. Run the uninstall.bin or uninstall.bat file.

Running Control-M Workbench

This procedure describes how to run 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 working Control-M 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 8GB of free memory to the container.

Begin

  1. From 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 is downloaded. This file contains an access key for containers.bmc.com.

  4. Ensure that you have Docker installed and running, and run the following Docker command:

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

    The <username> is the username that you use to access the EPD site.

  5. When prompted for a password, paste the key from the container-token.bmc file that you downloaded in step 3.

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

  7. Pull the image with 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.21.235-GA

  8. Start the container with a Docker command such as the following:

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

    In this command, adjust the following strings:

    • workbench:9.21.235-GA: Set the most recent version of Control-M Automation API.

    • --cpus=4 -m 8g: Set explicit limits for the consumption of memory and CPU on your host machine.

  9. Wait until the container is healthy. You can check the status with the following command:

    docker ps

    The container typically starts within 3 minutes.

Your container is ready to use. For usage examples, see the GitHub repository.

Installing the Control-M Automation CLI

Control-M Automation API Command Line Interface (CLI) is installed on the Control-M/EM on Windows and Linux platforms during installation of Control-M, and it can be run from the bin directory.

To manually install the CLI, ensure that the platform supports the installation of Node.js (BMC recommends version 18 and Java version 11 or higher. Installation instructions for the CLI are provided separately for the following platforms:

  • Windows

  • Linux or UNIX

  • macOS

Installing the CLI on Windows

This procedure describes how to install the CLI on Windows.

Begin

  1. Install or upgrade Node.js as follows:

    1. Download the Node.js Windows Installer from https://nodejs.org/en/download/. BMC recommends version 18.

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

    2. Run the installer, and follow the instructions on screen.

  2. Install the Command Line Interface (CLI) as follows:

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

    2. From the command prompt, run cmd, and then 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 that the CLI can run from any directory and by any user.

      If you install 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 computer. 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).

  3. Run the following command through a command prompt to test the CLI installation:

    ctm

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

  4. 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 11 or later for 64-bit Windows.

    2. Run the installer, and follow the instructions on screen.

    3. To verify that you have the required version of Java, enter the following command into a command prompt.

      The following response is an example:

      Copy
      >java -version
      openjdk version "11" 2018-09-25
      OpenJDK Runtime Environment 18.9 (build 11+28)
      OpenJDK 64-Bit Server VM 18.9 (build 11+28, mixed mode)

      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 have defined a JAVA_HOME environment variable.

      To check for details of multiple Java instances, use the where java command.

      In this case, when verifying the Java version, specify the full path to the 64-bit Java instance, beginning with the environment variable:

      "%JAVA_HOME%"\bin\java -version

Installing the CLI on Linux or UNIX

This procedure describes how to install the CLI on Linux or UNIX.

Begin

  1. Install or upgrade Node.js as follows:

    1. Follow the download instructions in https://nodejs.org/en/download/ for Node.js on your flavor of Linux or UNIX. BMC recommends version 18.

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

    2. Run the installer and follow the instructions on screen.

  2. Install the Command Line Interface (CLI) as follows:

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

      • Control-M instance address:

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

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

      • Control-M Workbench address:

        https://localhost:8443/automation-api/ctm-cli.tgz

    2. Type the following to install the ctm-cli.tgz node package:

      sudo npm -g install ctm-cli.tgz

      The -g argument installs the package globally, so that the CLI can run from any directory and by any user.

  3. Run the following command through a command prompt to test the CLI installation:

    ctm

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

  4. 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 11 or later for 64-bit.

    2. Run the installer, and follow the instructions on screen.

    3. To verify that you have the required version of Java, enter the following command into a command prompt.

      The following response is an example:

      Copy
      >java -version
      openjdk version "11" 2018-09-25
      OpenJDK Runtime Environment 18.9 (build 11+28)
      OpenJDK 64-Bit Server VM 18.9 (build 11+28, mixed mode)

      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 have defined a JAVA_HOME environment variable.

      To check for details of multiple Java instances, use the where java command.

      In this case, when verifying the Java version, specify the full path to the 64-bit Java instance, beginning with the environment variable:

      "%JAVA_HOME%"\bin\java -version

Installing the CLI on macOS

Use the following instructions to install the CLI on a Mac OS.

Begin

  1. Install or upgrade Node.js as follows:

    1. Download the Node.js Mac OS X Installer from https://nodejs.org/en/download/. BMC recommends version 18.

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

    2. Run the installer and follow the instructions on screen.

  2. Install the Command Line Interface (CLI) as follows:

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

    2. Type the following to install the ctm-cli.tgz node package:

      sudo npm -g install ctm-cli.tgz

      The -g argument installs the package globally, so that the CLI can run from any directory and by any user.

  3. Run the following command through a command prompt to test the CLI installation:

    ctm

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

Setting up a Control-M Environment for the CLI

After all the required components are installed, you must set up the default Control-M environment for use by the CLI and verify that the CLI can successfully establish a session.

See the following sections for the necessary steps:

Advanced Automation API Server Configuration

Advanced tasks for the configuration of the Automation API server are described in Control-M Automation API Administration, including the following tasks:

Related Information

For more information about Control-M, see the Control-M Documentation.