Installation

This topic discusses the tasks that you must perform to install and set up Control-M Automation API.

Components and requirements

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

Installing the Control-M Workbench

This section describes how to install the Control-M Workbench on your personal computer using a Docker. Installation of the Workbench enables you to have your own Control-M working environment without the need for a Control-M installation.

1. Download the compressed Docker image.
2. Load the image using the following command:
   docker load -i controlm-workbench-9.20.000.xz
   The image is loaded under the name controlm-workbench:9.20.000.

3. Run the image using the following command:
   docker run -dt --hostname=workbench  -p 8443:8443 -p 7005:7005 controlm-workbench:9.20.000
   

   Note

   To run the docker container on Windows, enable the Use the WSL 2 based engine setting in your Docker Desktop and switch to the Linux containers engine in Docker Desktop settings.

   To use the Provision service, all hostnames of agents that you intend to provision should be known from the container. To add a hostname (an action that is equivalent to editing the /etc/hosts file in the container), you can use the --add-host option, as in the following example command:
   docker run -dt --hostname=workbench  -p 8443:8443 -p 7005:7005 --add-host “hostname1:<ipaddress1>” --add-host “hostname2:<ipaddress2>” controlm-workbench:9.20.000

4. After the container is up and ready for use (this typically takes about one minute), get started by going to:
   https://<WorkbenchIP>:8443/automation-api/startHere.html

_{Back to top}

Installing the Control-M Automation CLI

As of version 9.0.19 of Control-M, the Control-M Automation 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. For such platforms, you can skip to Step 4 - Test the CLI Installation.

To manually install the CLI, ensure that the platform supports the installation of Node.js version 4.x or later and Java version 8. Installation instructions for the CLI are provided separately for each of the following platforms:

• Windows
• Linux or UNIX
• macOS

CLI installation for Windows

Use the following instructions to install the CLI on a Windows machine.

Step 1 - Install or Upgrade Node.js

1. Download the Node.js Windows Installer from https://nodejs.org/en/download/. The Node.js installer includes the npm (Node Package Manager) utility.
2. Run the installer and follow the instructions on screen.

3. 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. (The following responses are examples.)
   

   >node -v
   v6.2.0
   >npm -v
   3.8.9

Step 2 - Download Command Line Interface (CLI)

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

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

Step 4 - Test the CLI Installation

Run the following command through a command prompt:

>ctm
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:      samples          Manage data samples
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 8 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.)
   

   >java -version
   openjdk version "1.8.0_222-4-redhat"
   OpenJDK Runtime Environment (build 1.8.0_222-4-redhat-b10)
   OpenJDK 64-Bit Server VM (build 25.222-b10, mixed mode)

   Note

   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

Where to go from here

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

_{Back to top}

CLI installation for Linux or UNIX

Use the following instructions to install the CLI on a Linux or UNIX machine.

Step 1 - Install or Upgrade Node.js

1. 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.
2. Run the installer and follow the instructions on screen.

3. 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. (The following responses are examples.)

   >node -v
   v6.2.0
   >npm -v
   3.8.9

Step 2 - Download Command Line Interface (CLI)

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

For example, 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

Step 4 - Test the CLI Installation

Run the following command:

>ctm
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:      samples          Manage data samples
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 relevant OpenJDK package, as discussed in http://openjdk.java.net/install/. Ensure that you obtain version 8 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.)

   >java -version
   openjdk version "1.8.0_222-4-redhat"
   OpenJDK Runtime Environment (build 1.8.0_222-4-redhat-b10)
   OpenJDK 64-Bit Server VM (build 25.222-b10, mixed mode)

   Note

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

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

   In this case, when verifying the Java version, specify the full path to the Java instance, beginning with the environment variable:
   >$JAVA_HOME/bin/java -version

Where to go from here

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

_{Back to top}

CLI installation for 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/. The  Node.js installer includes the npm (Node Package Manager) utility.
2. Run the installer and follow the instructions on screen.

3. 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. (The following responses are examples.)

   >node -v
   v6.2.0
   >npm -v
   3.8.9

Step 2 - Download Command Line Interface (CLI)

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

For example, 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

Step 4 - Test the CLI Installation

Run the following command:

>ctm
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:      samples          Manage data samples
help:      session          Manually maintain Control-M user sessions
help:
help:    Options:
help:      -h, --help     output usage information
help:      -v, --version  output the application version

Where to go from here

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

_{Back to top}

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:

1. Setting up a Control-M environment
2. Setting the environment as default
3. Verifying the setup by logging in to a session
4. Accessing the documentation from the API

_{Back to top}

Advanced Automation API Server configuration

Advanced tasks for the configuration of the Automation API server are described in the Control-M Administrator Guide in the Control-M Online Help, including the following tasks:

• Changing the Automation API server port
  
• Limiting incoming traffic through an API gateway
  
• Limiting API connections to a specific GUI server
  
• Configuring Automation API session timeout
• Allowing session tokens to display in responses to API commands
  
• Configuring Control-M Web Server to HTTPS
• Setting annotations as optional in API commands
• Configuring maximum number of run IDs saved in the Control-M/EM database
  

_{Back to top}

Related information

For more information about Control-M, use the following resources:

• Support videos
• Online Help