Setting Up the API

This procedure describes how to set up Control-M Automation API and connect it with Control-M SaaS.

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

Begin

Install the Control-M Automation API CLI to expose the Control-M REST API as a Command Line Interface (CLI) using one of the following methods:
- Performing a Standard Control-M Automation API CLI Installation
- Performing a Python Package Installation of Control-M Automation API CLI
Create your first API token for API authentication, as described in Creating Your First Token for API Authentication.
Set up a Control-M environment for running commands through the CLI, as described in Setting Up a Control-M Environment for the CLI.
As an administrator, ensure that your API users have sufficient authorizations for the various API functionalities and services, as described in Authorizations for API Functionalities and Services.

Performing a Standard Control-M Automation API CLI Installation

This procedure describes how to install the Control-M Automation API CLI using the standard installation method.

Before You Begin

Install the following prerequisite software:
- Python, version 3.8.4 or later.
  
  For AIX, choose a version from the official IBM AIX Toolbox.
  
  Ensure that Python is included in your system path.
- pip, version 20.1.1 or later.
  
  If pip is not installed by the Python installer, obtain it from https://pip.pypa.io/en/stable/installation/.
- Java LTS (Long Term Support release), 64-bit, for using the Provision service.
  
  For a list of supported Java vendors and versions, see Control-M Compatibility with External Java Vendors.
  
  Download and install the relevant OpenJDK package, according to the instructions in http://openjdk.java.net/install/, and set the Java environment variable to point to the external Java. For more information, see Setting the Java Environment Variable.
If you are installing Control-M Automation API CLI on a host that uses a proxy server, ensure that the proxy server settings are defined, as described in Proxy Server Configuration.

Begin

In Control-M SaaS, 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 one of the following sections:
- Standard Installation on Linux
- Standard Installation on Windows
Do one of the following:
- Linux:
  1. Click cURL command or wget command to copy a command to your clipboard.
  2. On the host where you want to download the DR5V3_Linux-x86_64.BIN installation file, paste the cURL command or wget command into the command line utility, and run the command.
  3. Verify that the installation file has execute permissions.
- Windows: Click the provided link to download the DR5V3_windows_x86_64.exe installation file to the target host.
Run the installation file and follow the on-screen instructions.
Ensure that the CLI installation was successful by running the ctm command.

After a successful installation, this command returns help on the various API commands and options.

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 host. 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).
To access Control-M Automation API documentation while working in the API, you can use the following API commands:
- REST API documentation: ctm documentation restAPI
- Web-based API documentation: ctm doc gettingStarted

Performing a Python Package Installation of Control-M Automation API CLI

This procedure describes how to install the Control-M Automation API CLI as a Python package.

Before You Begin

Install the following prerequisite software:
- Python, version 3.8.4 or later.
  
  For AIX, choose a version from the official IBM AIX Toolbox.
  
  Ensure that Python is included in your system path.
- pip, version 20.1.1 or later.
  
  If pip is not installed by the Python installer, obtain it from https://pip.pypa.io/en/stable/installation/.
- Java LTS (Long Term Support release), 64-bit, for using the Provision service.
  
  For a list of supported Java vendors and versions, see Control-M Compatibility with External Java Vendors.
  
  Download and install the relevant OpenJDK package, according to the instructions in http://openjdk.java.net/install/, and set the Java environment variable to point to the external Java. For more information, see Setting the Java Environment Variable.
If you are installing Control-M Automation API CLI on a host that uses a proxy server, ensure that the proxy server settings are defined, as described in Proxy Server Configuration.

Begin

In Control-M SaaS, 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 one of the following sections:
- Installation as Python package Linux
- Installation as Python package Windows
Do one of the following:
- Linux or macOS:
  1. Click cURL command or wget command to copy a command to your clipboard.
  2. On the host where you want to download the install_ctm_cli.py package, paste the cURL command or wget command into the command line utility, and run the command.
  3. On a terminal, type the following command from the directory where you saved the install_ctm_cli.py file:
    
    python install_ctm_cli.py
- Windows:
  1. Click the provided link to download the install_ctm_cli.py package to the target host.
  2. Run cmd, and then type the following command from the directory where you saved the install_ctm_cli.py file:
    
    python install_ctm_cli.py
Ensure that the CLI installation was successful by running the ctm command.

After a successful installation, this command returns help on the various API commands and options.

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 host. 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).
To access Control-M Automation API documentation while working in the API, you can use the following API commands:
- REST API documentation: ctm documentation restAPI
- Web-based API documentation: ctm doc gettingStarted

Creating Your First Token for API Authentication

This procedure describes how to create your first token for API user authentication, which must be done through Control-M SaaS

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

Begin

In Control-M SaaS, 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.

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

This procedure describes how to set up a Control-M environment so that you can run commands through the CLI. An Environment is a combination of an endPoint and token.

Begin

Add a new environment by running the following command:

ctm environment add <environment_name> <endPoint> <token>

where
- endPoint is the URI for Control-M Automation API, with the following format:
  
  https://<controlmEndPointHost>/automation-api
  
  and controlmEndPointHost has the following format:
  
  <tenant-name>-aapi.<zone>.controlm.com
- token is the name of a valid API token.
The following command adds an environment named myEnvironment:

ctm environment add myEnvironment "https://tenant-123-aapi.us1.controlm.com/automation-api" "<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.
Set the default environment by running the following command:

ctm environment set <environment_name>
The new 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"
    }
}
```
- 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.
- 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.