Services

The Control-M Automation API allows you to automate and work interactively with Control-M. Services are groups of API commands available via either a CLI (Command Line Interface) or as REST API commands. Using the services, you can build job definitions to test whether they are valid, test-run a job to debug job definitions , combine multiple definition files into a package, deploy job definitions and packages to Control-M, provision a Control-M/Agent, manage environments, and more.

The following sections on this page will help you get started working with the Control-M Automation API services:

• Using the CLI
• Working with the REST API
• REST Verbs
• Difference between REST API and CLI Syntax
• Annotation input
• Checking REST API server status
  
• Obtaining Automation API license information
  
• Related information
  

The various services provided in Control-M Automation API are described in the following pages:

• Build service
• Deploy service
• Run service
• Package service
• Config service
• Provision service
• Reporting service
• Archive service
• Environment service
• Session service

Using the CLI

The CLI allows you to work interactively or write scripts for automation. To access the CLI, open a terminal or command window and enter ctm. The first-level help is displayed, verifying that the CLI is properly installed. See Installation.

>ctm
help:
help:    Display help for a given command
help:      help [command]
help:
help:    Commands:
help:      archive          Control-M Workload Archiving operations
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:      samples          Manage data samples
help:      session          Manually maintain Control-M user sessions
help:
help:    Options:
help:      -h, --help     output usage information
help:      -v, --version  output the application version

Getting Help

The CLI has built-in help. The following table provides instructions on obtaining the help at the various levels of the API functions.

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 , username, and password. More than one environment can be configured. You can also configure one environment as the default.

An endPoint looks like the following: 

https://<controlmEndPointHost>:8443/automation-api

The command below shows how to add an environment named devEnvironment and the reponse:

>ctm environment add devEnvironment "https://<controlmEndPointHost>:8443/automation-api" "[ControlmUser]" "[ControlmPassword]"
 
info:    Environment 'devEnvironment' was created
info:    devEnvironment:
{"endPoint":"https://<controlmEndPointHost>:8443/automation-api","user":"[ControlmUser]"}

Environments are 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 devEnvironment
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 Naming of Commands

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

_{Back to top}

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. To obtain a token, you must use the session/login request.

NOTE: 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, see REST API reference .  This REST API reference is for the newest version of Control-M Automation API, which is backward-compatible with a wide range of versions of Control-M/Enterprise Manager. In addition, you can access a local Swagger reference on your server using the following URL: https://<endpoint:8443>/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 Tutorial 103 in the tutorial samples provided through GitHub.

Authentication

Use a POST /session/login request to obtain a login token. A token is valid for 30 minutes. The credentials are posted in the request body in JSON format. POST data looks like the following:

{"username": "<controlMUser>", "password": "<controlMPassword>"}

On success, the request returns the following:

{
    "username":"<ControlMUsername>",
    "token":"E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7"
}

Any additional API calls require the HTTPS header 'Authorization': 'Bearer ' + token.  For example:

Authorization: Bearer E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7

The following example shows how to log in using curl:

endpoint=https://<controlmEndPointHost>:8443/automation-api
user=[USER]
passwd=[PASSWORD]

# Login
login=$(curl -H "Content-Type: application/json" -X POST -d "{\"username\":\"$user\",\"password\":\"$passwd\"}"   "$endpoint/session/login" )
echo $login
# trim spaces and new lines
login=$(echo ${login//[$'\t\r\n ']})
token=$(echo ${login##*token\" : \"} | cut -d '"' -f 1)
echo $token

The following example shows how to log in 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>: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']
 
r = requests.get(endPoint + '/config/servers', headers={'Authorization': 'Bearer ' + token}, verify=False)
print(r.content)
print(r.status_code)
exit(r.status_code == requests.codes.ok)

REST STATUS Codes

On success, REST returns status 200.

On failure, REST returns 400, 404 or 500 HTTPS status codes

• 400 stands for errors in the request data
• 404 is returned when the defined item wasn't found
• 405 is returned when submitting an unrecognized REST method ('login' instead of 'session login')
• 500 is for an internal error in the server.

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
		}
	]
}

_{Back to top}

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 "Authorization: Bearer $token" "$endpoint/config/servers"
 
#Get list of hostgroups of a specific $
ctm=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/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>:8443/automation-api'
r = requests.get(endPoint + '/config/servers', headers={'Authorization': 'Bearer ' + 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 
 
ctm=controlm
hostgroup=HostGroup1
agent=myhost2


curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d '{"host":"$agent"}'  $endpoint/config/server/$ctm/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 "Authorization: Bearer $token" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json" "$endpoint/deploy"

Th 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>: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={'Authorization': 'Bearer ' + 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 perform a manual failover on a Control-M/Server:

#updating a server with a manual failover

ctm=controlm

curl -H "Authorization: Bearer $token" -X PUT "$endpoint/config/server/$ctm/failover" 

DELETE a resource

The following example shows how to DELETE a resource:

#deleting an agent from a hostgroup
 
ctm=controlm
hostgroup=HostGroup1
agent=myhost1

curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$ctm/hostgroup/$hostgroup/agent/$agent"

_{Back to top}

Difference between REST API and CLI Syntax

The CLI and API can execute the same commands, but 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 of a specific '{'ctm'}' Control-M/Server. The specific Control-M/Server is a parameter that is part of the resource URL of the REST API call.

GET /config/server/{ctm}/hostgroups

Below is the equivalent CLI command where the resource path is separated using ':'  as in server:hostgroups the get action is separated using '::' and parameters are defined after the action.

>ctm config server:hostgroups::get <ctm> 

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, as described in Defining Audit and Annotation parameters in the Control-M Online Help.

To provide annotation input in API commands, use the following guidelines:

_{Back to top}

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 2019)

Server properties:
  port=48081
  config.port=48082
  workbench=false

_{Back to top}

Obtaining Automation API license information

To get Automation API license information, you can use the following URL:

 <Automation_API_endpoint>/license

_{Back to top}

Related information

For more information about Control-M, use the following resources:

• Support videos
• Online Help