Services
Services are groups of API commands available via Control-M Automation API CLI or as Control-M REST API commands.
The following table describes the Control-M Automation API services.
Service |
Description |
---|---|
Compiles definitions of jobs, folders, or calendars and verifies their validity. |
|
Transfers definitions of folders, jobs, or other objects, and configuration definitions, to Control-M. |
|
Runs jobs and tracks their status, and manages other types of objects for jobs. |
|
Creates a package from a directory of definition files. |
|
Manages configuration definitions in your Control-M environment. |
|
Installs and registers Control-M Agents |
|
Generates reports and obtains information about reports from Control-M Reports. |
|
Manages Control-M environments that Control-M Automation API communicates with. |
|
Manages authentication tokens for running API commands. |
|
Obtains job usage statistics for license auditing and compliance purposes. |
Running the CLI
This procedure describes how to run a Control-M Automation API CLI command.
Begin
-
Open a terminal or command window and type ctm.
The first-level help appears and verifies that Control-M Automation API CLI is properly installed.
>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
Getting Help
The CLI has built-in help.
Begin
-
Open a terminal or command window and type a CLI help command.
The following table describes the help commands for various levels of the API functions:
Level of Help
CLI Command
Main Help Page for All Services
-
ctm
(with no further parameters) -
ctm -h
Specific Service
-
ctm <ServiceName>
-
ctm <ServiceName> -h
Specific Command
ctm <ServiceName> <CommandName> -h
CLI Version Display
ctm -v
-
Managing CLI Environments
The first task when starting to work with Control-M Automation API is to configure the Control-M environment that you are going to use. An environment is a combination of a REST API endpoint and API token. More than one environment can be configured. You can also configure one environment as the default.
An endpoint has the following format:
https://<controlmEndPointHost>/automation-api
The Helix Control-M endpoint host has the following format: <tenant-name>-aapi.prod.controlm.com.
The following command adds an environment named
ctm environment add myEnvironment "https://tenant-123-aapi.prod.controlm.com/automation-api" "<token>"
Environments are kept in the user home folder ~/.ctm/env.json on Linux and %USERPROFILE%\.ctm\env.json in Windows.
Once configured, you can set a default environment for interactive work as follows:
ctm environment set myEnvironment
ctm build jobs.json
ctm run jobs.json
ctm deploy jobs.json
To automate multiple Control-M environments, you can specify a specific environment, regardless of the default, using the -e option.
ctm deploy jobs.json -e TestEnvironment
ctm deploy jobs.json -e QAEnvironment
Short CLI Command Names
You do not have to type an entire command, as long as it is unique. Entering a short version will execute the command.
ctm environment show
ctm env show
ctm env sh
CLI Return Codes
The CLI returns the following codes:
-
0: On success.
-
1: On failure.
The following example runs a Linux bash script that checks for failed deployments based on return codes.
#!/bin/bash
if ! ctm deploy jobs.json; then
printf '%s\n' 'ctm: failed!' >&2;
fi
Working with the REST API
The REST API allows you to programmatically automate Control-M via REST API requests. Request URIs are composed of a Control-M endpoint and the API command. All requests must include an authentication token in the HTTPS header, as described in Authentication Tokens.
Control-M Automation API comes with a self-signed SSL certificate. With all curl commands, you can add -k to not reject the certificate.
Control-M Automation REST API Reference
For the full REST API reference generated with Swagger, go to the following URL:
<Automation_API_endpoint>/automation-api
Getting REST Specifications as YAML
The REST API server can generate a YAML file that contains swagger.io specifications of the REST APIs. The URL for the YAML specifications is <Automation_API_endpoint>/yaml.
For more information about how you can use this feature to generate a REST client, see
Authentication Tokens
To run API commands, you must have tokens for user authentication. You create your first API token through the Helix Control-M user interface.
After generating your first token, you can generate additional tokens for your user using a POST /authentication/token request. As the input, token definitions are submitted in a .json payload file.
On success, the request returns a token value, as well as several additional token properties.
{
tokenName: "emuser1-token",
tokenValue: "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE18231A2DA0A8E8AE76D7C3CCBA0B7",
tokenType: "user",
expirationDate:"2020-12-02",
lastUpdatedDate: "2020-12-02 01:02:03",
createdDate: "2020-12-02 01:02:03",
roles: ["admin","user"]
}
All API calls require the HTTPS header 'x-api-key' + token. For example:
x-api-key: E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE18231A2DA0A8E8AE76D7C3CCBA0B7
REST STATUS Codes
On success, REST returns status 200.
On failure, REST returns the following HTTPS status codes:
-
400: There are errors in the request data.
-
403: A user is not authorized to perform a specific action or use a specific resource.
-
404: The defined item cannot be found.
-
405: An unrecognized REST method has been submitted.
-
500: There is an internal error in the server.
-
503: Service unavailable, soon after a server restart.
Return code 403 is gradually replacing return code 500 in the relevant scenarios.
JSON Returned on Error
In case of error, the returned JSON contains an array of errors in the following format:
{
message: string, // The text of the error
id: number, // An internal identifier of the error (e.g. rule number in case of validation error)
item: string, // The item referenced in the error (if relevant)
file: string, // Error location file
line: number, // Error location line number
col: number // Error location column number
}
For example, an error response to /build API:
{
"errors": [
{
"message": "MainArguments is an unknown keyword therefore it is assumed to be a an object, but it has no object syntax",
"file": "Spark.json",
"line": 5,
"col": 22
},
{
"message": "SparkCommandLineOptions is an unknown keyword therefore it is assumed to be a an object, but it has no object syntax",
"file": "Spark.json",
"line": 9,
"col": 32
}
]
}
REST Verbs
The following verbs are used:
GET Resource
The following example shows how to GET specific resource data using bash and curl:
# Get list of servers
curl -H "x-api-key: $token" "$endpoint/config/servers"
#Get list of hostgroups of a specific $
server=IN01
curl -H "x-api-key: $token" "$endpoint/config/server/$server/hostgroups"
The following example shows how to GET specific resource data using Python:
import requests # pip install requests if you don't have it already
import urllib3
urllib3.disable_warnings() # disable warnings when creating unverified requests
endPoint = 'https://<controlmEndPointHost>/automation-api'
r = requests.get(endPoint + '/config/servers', headers={'x-api-key': token}, verify=False)
print(r.content)
print(r.status_code)
exit(r.status_code == requests.codes.ok)
POST a New Resource
The following example shows how to POST new resource data:
# Adding a new agent to a hostgroup
server=IN01
hostgroup=HostGroup1
agent=myhost2
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST -d '{"host":"$agent"}' $endpoint/config/server/$server/hostgroup/$hostgroup/agent"
POST to Upload a File
The following example shows how to POST a new file of data in bash and curl.
# deploy job definition file
curl -H "x-api-key: $token" -X POST -F "definitionsFile=@examples/AutomationAPISampleFlow.json" "$endpoint/deploy"
The following example shows how to POST a new file of data with Python:
import requests # pip install requests if you don't have it already
import urllib3
urllib3.disable_warnings() # disable warnings when creating unverified requests
endPoint = 'https://<controlmEndPointHost>/automation-api'
token=<token>
# -----------------
# Built
uploaded_files = [
('definitionsFile', ('Jobs.json', open('c:\\src\Jobs.json', 'rb'), 'application/json'))
]
r = requests.post(endPoint + '/deploy', files=uploaded_files, headers={'x-api-key': token}, verify=False)
print(r.content)
print(r.status_code)
exit(r.status_code == requests.codes.ok)
PUT to Update a Resource
The following example shows how to use a PUT verb to update an authentication token:
#updating an authentication token
curl -H "x-api-key: $token" -X PUT "$endpoint/authentication/token" -d @tokenDefinition.json
DELETE a Resource
The following example shows how to DELETE a resource:
#deleting an agent from a hostgroup
server=IN01
hostgroup=HostGroup1
agent=myhost1
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup/agent/$agent"
Difference between REST API and CLI Syntax
The CLI and API can execute the same commands, but they use different syntax to represent the commands. The REST APIs are expressed in path notation, while the CLI commands are structured differently. The following examples illustrate the differences.
-
Below is an example of getting a list of host groups from a Server. The name of the Server is a parameter that is part of the resource URL of the REST API call.
CopyGET /config/server/{server}/hostgroups
Below is the equivalent CLI command where the resource path is separated using the : (colon) character as in server:hostgroups, the get action is separated using :: (two colons), and parameters are defined after the action.
Copy>ctm config server:hostgroups::get <server>
Annotation Input
When you run certain API commands, you must include a free-text annotation within the command to justify your action. This requirement depends on whether annotation was enabled for the specific category of actions through the system parameters in Control-M,
The following table describes how to provide annotation input in API commands.
Method |
Description |
---|---|
CLI Command |
Include the Copy
|
REST API Command |
Use the Copy
|
Checking REST API Server Status
To get Automation API server status, you can use the following URL:
<Automation_API_endpoint>/status
Status information includes details of server uptime along with defined server properties, as in the following sample response:
automation-api server (emrestsrv) is up and running for 7 days and 6 hours (since Mon Jul 22 12:51:31 UTC 2022)
Server properties:
port=32081
config.port=32082
Obtaining Automation API License Information
To get Automation API license information, you can use the following URL:
<Automation_API_endpoint>/license