Control-M Automation API Guidelines

Control-M Automation API CLI and Control-M REST API execute the same commands, but they use a different syntax to represent the commands.

REST APIs are expressed in path notation and the CLI commands utilize spaces and colons.

CLI 

The Control-M Automation API CLI utility enables you to run services and commands in CLI format.

The following topics provide reference materials when you run commands in Control-M Automation API CLI:

• CLI Help

• Short CLI Command Names

• CLI Return Codes

To set up the CLI utility in Control-M Automation API, see Setting Up a Control-M API CLI Environment.

CLI Help

The following table describes the help commands for the API functions:

Short CLI Command Names

You can type shortened versions of the full Control-M Automation API CLI command names. If you shorten a command, it must be unique.

ctm  environment show
ctm  env         show
ctm  env         sh

CLI Return Codes

Control-M Automation API CLI returns the following codes:

• 0: Success

• 1: Failure

#!/bin/bash
if ! ctm deploy jobs.json; then
printf '%s\n' 'ctm: failed!' >&2;
fi

REST API

Control-M REST API allows you to 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.

The following topics provide reference materials when you run commands in Control-M REST API:

• Control-M Automation REST API Reference

• REST Specifications as YAML

• Authentication Tokens

Control-M Automation REST API Reference

The REST API reference is for the latest version of Control-M Automation API, which is backwards-compatible with different Control-M/EM versions. In addition, you can access a local Swagger reference on your server with the following URL:
https://<endpoint:8443>/automation-api

To view the full REST API reference generated with Swagger, see REST API reference.

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.

To generate a REST client, see Tutorial 103 in the tutorial samples provided in GitHub.

Authentication Tokens

The following describes the different token type options that you must include in the HTTPS header of any API request that you submit:

• API tokens: API tokens grant access permissions to specific roles for a time period that you can pre-define. The token expiration date is based on the UTC time zone. This token type requires Control-M/EM version 9.0.21 or higher. BMC recommends that you create an API token.

  You can create an API token with the authentication token::create API call or in Control-M Web. You must include this API token in the HTTPS header of subsequent API calls in the following format:

  x-api-key: <token>

  x-api-key: E14A4F8E45406977B31A1B091E5E04237D81AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7

• Session tokens: Session tokens are valid for a specific user for only 30 minutes.

  You can create a Session token with the session login API call. You must include this Session token in the HTTPS header of subsequent API calls in the following format:

  Authorization: Bearer <token>

  Authorization: Bearer E14A4F8E45406977B31A1B091E252AEFE63ADE182E5702F5A913A2DA0A8E8AE76D7C3CCBA0B7

REST STATUS Codes

REST returns status 200 if the status is successful.

REST returns the following HTTPS status codes if there are failures:

• 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 after a server restart.

JSON Returned on Error

If an error occurs, 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
}

{
    "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

A REST verb defines an action that is performed on a single resource or a group of resources.

The following list contains the Control-M Automation API verbs:

• GET Resource

• POST a New Resource

• POST to Upload a File

• PUT to Update a Resource

• DELETE a Resource

GET Resource

The following example shows how to GET specific resource data with bash and cURL:

# Get list of servers
curl -H "x-api-key: $token" "$endpoint/config/servers"
                 
#Get list of hostgroups of a specific $
server=controlm
curl -H "x-api-key: $token" "$endpoint/config/server/$server/hostgroups"

The following example shows how to GET specific resource 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>:8443/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=controlm
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 data file with 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 data file 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>:8443/automation-api'
 
user = '<ControlMUser>'
passwd = '<ControlMPassword>'
 
# -----------------
# login
r_login = requests.post(endPoint + '/session/login', json={"username": user, "password": passwd}, verify=False)
print(r_login.content)
print(r_login.status_code)
if r_login.status_code != requests.codes.ok:
exit(1)
 
token = r_login.json()['token']
 
# -----------------
# Built
uploaded_files = [
('definitionsFile', ('Jobs.json', open('c:\\src\ctmdk\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 perform a manual failover on a Control-M/Server with the PUT verb:

#updating a server with a manual failover
                 
server=controlm
curl -H "x-api-key: $token" -X PUT "$endpoint/config/server/$server/failover"

DELETE a Resource

The following example shows how to DELETE a resource:

#deleting an agent from a hostgroup
                 
server=controlm
hostgroup=HostGroup1
agent=myhost1
                 
curl -H "x-api-key: $token" -X DELETE "$endpoint/config/server/$server/hostgroup/$hostgroup/agent/$agent"

Annotation Input

Some API commands require a free-text annotation in the command to justify an action. This requirement depends on whether annotation is enabled for the specific category of actions, as described in Defining Audit and Annotation Parameters.

The following list describes how to provide annotation input in API commands:

• CLI: Include the -a option and provide values for a pair of fields, subject and description.

  Copy

  ctm run workloadpolicy::activate WP1 
  -a "subject=Workload update&description=Activating WP1" 

• REST API: Provide the -H option to include a pair of custom headers, Annotation-Subject and Annotation-Description.

  Copy

  curl -H "x-api-key: %token%" -H "Content-Type: application/json"
  -H "Annotation-Subject: Workload update" -H "Annotation-Description: Activating WP1"
  -X POST "%endpoint%/run/workloadpolicy/WP1/activate"

REST API Server Status

The following URL provides the Control-M Automation API server status:
<Automation_API_endpoint>/status

The status information includes the details of server uptime and defined server properties.

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
workbench=false

Control-M Automation API License Information

The following URL shows the Control-M Automation API license information:
<Automation_API_endpoint>/license