Automation API Installation

This topic discusses 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.

Components and Requirements

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

Component

Function and Requirements

Further Information

Control-M REST API

A set of commands that enables you to test, run and deploy job definitions and packages to Control-M. The REST API also enables you to provision a Control-M/Agent, manage environments, and more.

  • Specific features that require a later version of Control-M are indicated in the current documentation, and the minimum version of Control-M that is compatible with each feature is specified.

  • Different versions of the REST API can live side-by-side. If, at any point, you install another version of Control-M that contains an older version of the API, the newer API is not overwritten.

Download, Install, or Upgrade Control-M REST API

Control-M Workbench

A personal Control-M development environment that enables you to build, run, and test your job flows, without the need for a Control-M installation.

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

Requirements:

  • Docker installed

  • Free ports: 8443 and 7005. Port 7005 is used by the Provision service.

  • 8GB free memory allocated to the container

Using Control-M Workbench

Control-M instance

For your work with the Control-M Automation API, 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 configuration of the Control-M Automation API in a Control-M installation, see the Control-M Automation API Administration.

Control-M Automation Command Line Interface (CLI)

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

Software requirements:

  • You can install the CLI on any platform that supports the installation of the following required software:

    • Node.js: BMC recommends version 18.

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

    • (To use the Provision service) 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 version 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 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.

Downloading and Installing 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, and save the PADEV.9.0.21.235 file in the temporary directory:

    Platform

    S3 Link

    Linux

    https://controlm-appdev.s3.us-west-2.amazonaws.com/release/v9.21.235/output/Unix/PADEV.9.0.21.235_Linux-x86_64_INSTALL.BIN

    AIX

    https://controlm-appdev.s3.us-west-2.amazonaws.com/release/v9.21.235/output/Unix/PADEV.9.0.21.235_AIX_INSTALL.BIN

    Windows

    https://controlm-appdev.s3.us-west-2.amazonaws.com/release/v9.21.235/output/Windows/PADEV.9.0.21.235_windows_x86_64.exe

  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.

Downloading and Installing 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. Go to the Control-M/Enterprise Manager 9.0.21 download page in the EPD site.

    Alternatively, if you have not yet registered at the EPD site, go to 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.

Using Control-M Workbench

This procedure describes how to run Control-M Workbench on your personal computer 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

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:

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

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

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

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

    Copy 
    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, as necessary:

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

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

Step 1 - Install or Upgrade Node.js

  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.

Step 2 - Download Command Line Interface (CLI)

Download a ctm-cli.tgz node package from the following location:

Environment

Address

Control-M instance

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

or

Click Download from https://localhost:8443/automation-api/startHere.html

Step 3 - Install the CLI

To install the ctm-cli.tgz node package, run cmd, and then type the following command from the directory where you saved the ctm-cli.tgz file:

Copy 
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).

Step 4 - Test the CLI Installation

Run the following command through a command prompt:

Copy 
ctm

The following menu appears:

Copy 
help:
help:    Display help for a given command
help:      help [command]
help:
help:    Commands:
help:      archive          Control-M Workload Archiving operations
help:      build            Compile definitions to verify they are valid for Control-M
help:      config           Configure the Control-M environment
help:      deploy           Submit definitions to Control-M
help:      documentation    Get documentation
help:      environment      Define and select the Control-M environment
help:      package          Package a directory of definition files into a deployable archive
help:      provision        Install Control-M components
help:      reporting        Generate Control-M reports
help:      run              Run and track Control-M jobs
help:      session          Manually maintain Control-M user sessions
help:
help:    Options:
help:      -h, --help     output usage information
help:      -v, --version  output the application version

Step 5 - Install Java for the Provision Service

  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

  4. Perform the setup steps described in Setting up a Control-M Environment for the CLI.

Installing the CLI on Linux or UNIX

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

Step 1 - Install or Upgrade Node.js

  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.

Step 2 - Download Command Line Interface (CLI)

Download a ctm-cli.tgz node package from the following location:

Environment

Address

Control-M instance

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

or

Click Download from https://localhost:8443/automation-api/startHere.html

You can use a command such as the following:

Copy 
wget https://vm-ctm-ep1:8443/automation-api/ctm-cli.tgz

Step 3 - Install the Command Line Interface (CLI)

Use the following command to install the ctm-cli.tgz node package:

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

Step 4 - Test the CLI Installation

Run the following command through a command prompt:

Copy 
ctm

The following menu appears:

Copy 
help:
help:    Display help for a given command
help:      help [command]
help:
help:    Commands:
help:      archive          Control-M Workload Archiving operations
help:      build            Compile definitions to verify they are valid for Control-M
help:      config           Configure the Control-M environment
help:      deploy           Submit definitions to Control-M
help:      documentation    Get documentation
help:      environment      Define and select the Control-M environment
help:      package          Package a directory of definition files into a deployable archive
help:      provision        Install Control-M components
help:      reporting        Generate Control-M reports
help:      run              Run and track Control-M jobs
help:      session          Manually maintain Control-M user sessions
help:
help:    Options:
help:      -h, --help     output usage information
help:      -v, --version  output the application version

Step 5 - Install Java to use the Provision service

  1. Download the OpenJDK installer for Windows 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

  4. Perform the setup steps described in Setting up a Control-M Environment for the CLI.

Installing the CLI on macOS

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

Step 1 - Install or Upgrade Node.js

  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.

Step 2 - Download Command Line Interface (CLI)

Download a ctm-cli.tgz node package from the following location:

Environment

Address

Control-M instance

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

or

Click Download from https://localhost:8443/automation-api/startHere.html

You can use a command such as the following:

Copy 
curl --insecure --output ~/ctm-cli.tgz \
   https://vm-ctm-ep1:8443/automation-api/ctm-cli.tgz

Step 3 - Install the Command Line Interface (CLI)

Use the following command to install the ctm-cli.tgz node package:

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

Step 4 - Test the CLI Installation

  1. Run the following command through a command prompt:

    Copy 
    ctm

    The following menu appears:

    Copy 
    help:
    help:    Display help for a given command
    help:      help [command]
    help:
    help:    Commands:
    help:      archive          Control-M Workload Archiving operations
    help:      build            Compile definitions to verify they are valid for Control-M
    help:      config           Configure the Control-M environment
    help:      deploy           Submit definitions to Control-M
    help:      documentation    Get documentation
    help:      environment      Define and select the Control-M environment
    help:      package          Package a directory of definition files into a deployable archive
    help:      provision        Install Control-M components
    help:      reporting        Generate Control-M reports
    help:      run              Run and track Control-M jobs
    help:      session          Manually maintain Control-M user sessions
    help:
    help:    Options:
    help:      -h, --help     output usage information
    help:      -v, --version  output the application version

  2. Perform the setup steps described in Setting up a Control-M Environment for the CLI.

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.