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

To view the full REST API reference generated with Swagger, go to the following URL:
<Automation_API_endpoint>/automation-api

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

You must be authenticated with a token to run API commands. You create your first API token in Helix Control-M and then generate additional tokens with a POST /authentication/token request. A successful response shows the token value and its 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.

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=IN01
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>/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 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>/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 update an authentication token with a PUT verb:

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

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 System Settings.

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

Control-M Automation API License Information

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