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.
|
|
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:
|
|
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:
|
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
-
Create a temporary directory where to save downloaded files.
-
Click the relevant S3 link, and save the PADEV.9.0.21.210 file in the temporary directory:
Platform
S3 Link
Linux
AIX
Solaris
Windows
-
(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.210 file>
-
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
-
Create a temporary directory where to save downloaded files.
-
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.
-
On the Products tab, click the Control-M Automation API 9.0.21.210 installation package, and save the PADEV.9.0.21.210 file in the temporary directory.
-
(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.210 file>
-
(Windows only) Extract the downloaded zip file in the temporary directory.
-
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
-
In the Control-M installation directory, navigate to <EM_HOME>/install/PADEV.9.0.21.210
-
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 Docker Hub (controlm/workbench).
Control-M Workbench enables you to have your own working Control-M environment without the need to install Control-M.
Begin
-
Pull the image with the following command:
docker pull controlm/workbench:latest
-
Start the container with the following command:
docker run --hostname workbench -dt -p 8443:8443 controlm/workbench:latest
-
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 version 4.x or higher 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
-
Download the Node.js Windows Installer from https://nodejs.org/en/download/. The Node.js installer includes the npm (Node Package Manager) utility.
-
Run the installer and follow the instructions on screen.
-
To verify that you have the required version of Node.js (4.x or later) and npm (3.x or later), enter the following commands into a command prompt.
>node -v
v18.18.0
>npm -v
9.8.1
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:
>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:
>ctm
The following menu appears:
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
-
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.
-
Run the installer and follow the instructions on screen.
-
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
-
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
-
Follow the download instructions in https://nodejs.org/en/download/ for your flavor of Linux or UNIX. It is recommended to install the latest stable Node.js . The Node.js installer includes the npm (Node Package Manager) utility.
-
Run the installer and follow the instructions on screen.
-
To verify that you have the required version of Node.js (4.x or later) and npm (3.x or later), enter the following commands into a command prompt.
>node -v
v18.18.0
>npm -v
9.8.1
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:
>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:
>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:
>ctm
The following menu appears:
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
-
Download the OpenJDK installer for Windows from http://openjdk.java.net/install/. Ensure that you obtain version 11 or later for 64-bit.
-
Run the installer and follow the instructions on screen.
-
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
-
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
Download the Node.js Mac OS X installer from https://nodejs.org/en/download/. The Node.js installer includes the npm (Node Package Manager) utility.
Run the installer and follow the instructions on screen.
To verify that you have the required version of Node.js (4.x or later) and npm (3.x or later), enter the following commands into a command prompt.
>node -v
v18.18.0
>npm -v
9.8.1
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:
>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:
>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:
Copyhelp:
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 -
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:
-
Allowing Session Tokens to Display in Responses to API Commands
-
Configuring Maximum Number of Run IDs Saved in the Control-M/EM Database
Related Information
For more information about Control-M, see the Control-M Documentation.