Installation

Components and requirements

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

ComponentFunction and requirementsFurther 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.

The Control-M REST API is provided through the following Control-M components. For your work with the Control-M Automation API, you can choose to use one or both of these components.

Control-M Workbench

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

To install a Control-M Workbench on your personal computer, you use Oracle VirtualBox. The Workbench is imported as an Open Virtual Appliance (OVA).

Software requirements:

Control-M Workbench was tested on Oracle VirtualBox version 5.1.18. We recommend obtaining the latest version.

Port requirements:

Ports 8443 and 7005 must be free for use by the Control-M Workbench. Port 7005 is used by the provision service.

Installing the Control-M Workbench

Control-M instance

The REST API is also available through an installation of Control-M/Enterprise Manager, in any Control-M installation of version 9.0.00.200 or higher. 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 Administrator Guide.

Control-M Automation Command Line Interface (CLI)

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 version 4.x or later
    • npm version 3.x or later. npm is usually installed together with Node.js.
    • (To use the provision service) Java 8 or later, 64-bit.
  • The CLI and REST API back-end server version must be the same to initiate a connection. If necessary, you can either upgrade or downgrade the CLI version. Any upgrade to the server forces an upgrade on the CLI machine.

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

Installing the Control-M Workbench

This section describes how to install the Control-M Workbench on your personal computer through an Open Virtual Appliance (OVA). Installation of the Workbench enables you to have your own Control-M working environment without the need for a Control-M installation.

Step 1 - Install Oracle VirtualBox

Download your preferred platform package from https://www.virtualbox.org/wiki/Downloads, and follow the provided instructions to install Oracle VirtualBox on your computer.

Step 2 - Download and Install Control-M Workbench

  1. Download the Control-M Workbench appliance to your computer. 
  2. From the Oracle VM VirtualBox Manager, go to File > Import Appliance and select the workbench.ova file that you downloaded to your computer and wait for the import process to complete.
  3. From the left pane, select workbench and click Start to run the appliance. 
  4. After workbench is up and running, click https://localhost:8443/automation-api/startHere.html to get started.

Back to top

Installing the Control-M Automation CLI

You can install the Control-M Automation Command Line Interface (CLI) on any platform that supports the installation of Node.js (version 4.x or later) and Java (version 8 or later). Installation instructions for the CLI are provided separately for each of the following platforms:

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
  4. Some Node.js installers include npm version 2.x or below. If you need to upgrade npm, use the following command:

    >npm -g install npm@latest

Step 2 - Download Command Line Interface (CLI)

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

EnvironmentAddress
Control-M Workbench

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

or

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

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

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

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


Note

Use the -g argument to install 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
help:
help:    Display help for a given command
help:      help [command]
help:
help:    Commands:
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 versio

Step 5 - Install Java for the provision service

  1. Download the Java Windows Installer from http://www.java.com/en/download/manual.jsp. Ensure that you obtain 64-bit Java version 8 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.)

    >java -version
    java version "1.8.0_20"
    Java(TM) SE Runtime Environment (build 1.8.0_20-b26)
    Java HotSpot(TM) 64-Bit Server VM (build 25.20-b23, 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/package-manager/ 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
  4. Some Node.js installers include npm version 2.x or below. If you need to upgrade npm, use the following command:

    >sudo npm -g install npm@latest

Step 2 - Download Command Line Interface (CLI)

Download a ctm-cli.tgz node package from:

EnvironmentAddress
Control-M Workbenchhttps://localhost:8443/automation-api/ctm-cli.tgz 
Control-M instancehttps://<controlmEndPointHost>:8443/automation-api/ctm-cli.tgz

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

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

Note

Use the -g argument to install 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:

>ctm
help:
help:    Display help for a given command
help:      help [command]
help:
help:    Commands:
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 versio

Step 5 - Install Java to use the provision service

  1. Follow the download instructions in http://www.java.com/en/download/manual.jsp for your flavor of Linux or UNIX. Ensure that you obtain Java 8 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.)

    >java -version
    java version "1.8.0_91"
    Java(TM) SE Runtime Environment (build 1.8.0_91-b14)
    Java HotSpot(TM) 64-Bit Server VM (build 25.91-b14, 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
  4. Some Node.js installers include npm version 2.x or below. If you need to upgrade npm, use the following command:

    >sudo npm -g install npm@latest

Step 2 - Download Command Line Interface (CLI)

Download a ctm-cli.tgz node package from:

Environment

Address
Control-M Workbenchhttps://localhost:8443/automation-api/ctm-cli.tgz 
Control-M instancehttps://<controlmEndPointHost>:8443/automation-api/ctm-cli.tgz

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

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

Note

Use the -g argument to install 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:

>ctm
help:
help:    Display help for a given command
help:      help [command]
help:
help:    Commands:
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 versio

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

Related information

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

Was this page helpful? Yes No Submitting... Thank you

Comments