Setting Up the API

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

The following video demonstrates the setup tasks that are described on this page: BMC Helix Control-M - Automation API Getting Started.

Installing the Control-M Automation API CLI

To expose the Control-M REST API as a Command Line Interface (CLI), you can choose between the following modes of installation:

Standard Installation: A full installation of the CLI along with all prerequisite components.
Node.js Package Installation: An installation of the CLI as a Node.js package, without the prerequisite components.

Performing a Standard Installation on Linux

In Helix Control-M, from the Configuration domain, click the orange drop-down arrow button and select Plug-ins.
Click Install Plug-in.
Select the Automation API plug-in.
In the textual instructions on the right, expand the Standard Installation on Linux section.
Click cURL command or wget command to copy a command to your clipboard.
On the host computer where you want to download the installation file, paste the cURL command or wget command into the command line utility, and run the command.

The DR5V3_Linux-x86_64.BIN installation file is downloaded to the host computer.
Verify that the installation file has execute permissions.
Run the installation file and follow the on-screen instructions.

Performing a Standard Installation on Windows

In Helix Control-M, from the Configuration domain, click the orange drop-down arrow button and select Plug-ins.
Click Install Plug-in.
Select the Automation API plug-in.
In the textual instructions on the right, expand the Standard Installation on Windows section.
Click the provided link to download the DR5V3_windows_x86_64.exe installation file to the target host computer.
Run the installation file and follow the on-screen instructions.

Performing a Node.js Package Installation

Installation of the CLI as a Node.js package is a thinner installation than the standard installation. However, you must first ensure that the prerequisite software are installed separately.

Before You Begin

To install the CLI you must first install the following prerequisite software:

Node.js

BMC recommends version 18 of Node.js. Follow the download instructions in https://nodejs.org/en/download/ for your operating system. The Node.js installer includes the npm (Node Package Manager) utility.
Java 11 or 17 or later, 64-bit, for using the Provision service.

Download and install the relevant OpenJDK package, according to the instructions in http://openjdk.java.net/install/.

Installing as a Node.js Package on Linux or macOS

In Helix Control-M, from the Configuration domain, click the orange drop-down arrow button and select Plug-ins.
Click Install Plug-in.
Select the Automation API plug-in.
In the textual instructions on the right, expand the Installation as nodeJS package Linux section.
Click cURL command or wget command to copy a command to your clipboard.
On the host computer where you want to download the node package, paste the cURL command or wget command into the command line utility, and run the command.

The ctm-cli.tgz node package is downloaded to the host computer.
On a terminal, type the following command from the directory where you saved the ctm-cli.tgz file:

sudo npm install -g install ctm-cli.tgz

Installing as a Node.js package on Windows

In Helix Control-M, from the Configuration domain, click the orange drop-down arrow button and select Plug-ins.
Click Install Plug-in.
Select the Automation API plug-in.
In the textual instructions on the right, expand the Installation as nodeJS package Windows section.
Click the provided link to download the ctm-cli.tgz node package to the target host computer.
Run cmd, and then type the following command from the directory where you saved the ctm-cli.tgz file:

npm install -g install ctm-cli.tgz

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

Testing the CLI Installation

To ensure that the CLI installation was successful, run the ctm command to obtain the help:

Copy

>ctm
help:
help:    Display help for a given command
help:      help [command]
help:
help:    Commands:
help:      archive          Control-M Workload Archiving operations
help:      authentication   Creates and manages authentication tokens in Control-M
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:
help:    Options:
help:      -h, --help     output usage information
help:      -v, --version  output the application version

Creating your first token for API authentication

To run API commands, you must have tokens for user authentication. You create your first API token through the Helix Control-M user interface.

In Helix Control-M, from the Configuration domain, click the orange drop-down arrow button and select API Token.
Click Add token.
Enter token settings: set a name, assign the relevant roles, and set an expiration date (UTC-based).
Click Generate.
Copy the API token value and then click Done.

For more information, see Creating an API Token in the Helix Control-M documentation.

After generating your first token, you can generate additional tokens for your user using the Authentication Service.

Setting up a Control-M environment for the CLI

The Control-M Automation API CLI requires an environment to run the commands. An Environment is a combination of an endPoint and token.

An endPoint is the URI for Control-M Automation API. The endpoint has the following format:

Copy

https://<controlmEndPointHost>/automation-api

The Helix Control-M endpoint host has the following format: <tenant-name>-aapi.<zone>.controlm.com.

To add an environment, run the following command:

Copy

ctm environment add <env_name> <endPoint> <token>

For example, the following command adds an environment named myEnvironment:

Copy

ctm environment add myEnvironment "https://tenant-123-aapi.us1.controlm.com/automation-api" "<token>"

where token is the name of a valid token.

While the environment is added, it is checked for its policy regarding certificates. If the environment is currently set to accept self-signed certificates, a warning is displayed. If you want to apply a stricter policy of accepting only certificates signed by a trusted Certificate Authority (and not accepting self-signed certificates), you can use the environment configure command to set the rootCertificateRequired parameter to true.

When you set up your first environment, it is automatically set as the default environment that is used by any API commands that you invoke. In such a case, you can skip this step. Later, after defining additional environments, perform this step to set the default environment of your choice.

In the following example, a Control-M instance named myEnvironment is set as the default environment, and the returned response lists all existing environments.

Copy

> ctm environment set myEnvironment

info:    current environment: myEnvironment
info:    environments: {
    "prodEnvironment": {
        "endPoint": "https://tenant-0001-aapi.us1.controlm.com/automation-api"
    },
    "myEnvironment": {
        "endPoint": "https://tenant-0002-aapi.us1.controlm.com/automation-api"
    }
}

After setting the default environment, if you want to run API commands against a different, non-default environment, you must include the -e <environmentName> option in any API command that you run. In addition, ensure that the version of the destination environment matches the version of the CLI.

Preparing Authorizations to Run API Commands

If you are the administrator, you must ensure that your users have sufficient authorizations for the various API functionalities and services. Through the Helix Control-M user interface, you apply authorizations to the defined roles, as described in Applying Authorizations for API Functionalities and Services.

Related Information

For more information about Helix Control-M, see the Helix Control-M Online Help.