Services

Introduction

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.

See below more information on how to work with the CLI and REST API. 

The Build Service

The build service allows you to compile job definitions and verify that they are valid for your Control-M environment. Control-M validation includes basic Control-M rules such as length of fields, allowed characters, and mandatory fields. Build will also check that the JSON is valid. If Control-M Change Manager is part of your solution, definitions will be evaluated against the relevant site standard. build can receive definition files in .json format or packages of multiple job definition files in .zip or .tar.gz format.

CLI Syntax

>ctm build <definitionsFile> [deployDescriptorFile]

Where:

REST API Syntax

See REST API reference.

Example using curl:

curl -H "Authorization: Bearer $token" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json" -F "deployDescriptorFile=@examples/deployDescriptor.json" "$endpoint/build"

The following example shows how to use the build command in a Python function :

token = r_login.json()['token']
 
# -----------------
# Built
uploaded_files = [
        ('definitionsFile', ('Jobs.json', open('examples/AutomationAPISampleFlow.json', 'rb'), 'application/json'))
]
 
r = requests.post(endPoint + '/build', files=uploaded_files, headers={'Authorization': 'Bearer ' + token}, verify=False)
print(r.content)
print(r.status_code)
exit(r.status_code == requests.codes.ok)

_{Back to top}

The Run Service

The Run Service allows you to run jobs and track their status. You can also use the service to debug your job definitions.

The service allows you to view job output and logs, and to perform job actions. You can also use this service to manage resources and events.

run

Use the run command to run jobs on the Control-M environment. The returned runId can be used to check job status.

The following example shows a typical command and response. build takes place as part of the run.

>ctm run examples/AutomationAPISampleFlow.json
{
  "runId": "2d4af716-e31d-48ef-a434-16575303752d",
  "statusURI": "https://ec2-54-187-1-168.us-west-2.compute.amazonaws.com:8443/run/status/2d4af716-e31d-48ef-a434-16575303752d"
}

CLI Syntax

>ctm run <jobDefinitionsFile> [deployDescriptorFile]

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST  -F "jobDefinitionsFile=@examples/AutomationAPISampleFlow.json" -F "deployDescriptorFile=@examples/deployDescriptor.json" "$endpoint/run"

_{Back to top}

run order

Allows you to run deployed jobs on the Control-M environment. The returned runId is used to check job status. Below is a typical command and response.

>ctm run order controlm AutomationAPISampleFlow
{
  "runId": "e0ddf056-4497-49f7-9d8b-25758b132bd6",
  "statusURI": "https://ec2-54-201-124-17.us-west-2.compute.amazonaws.com:8443/automation-api/run/status/e0ddf056-4497-49f7-9d8b-25758b132bd6?token=948220e4f1f4143591d71bd79a61c4c8_A5360B11"
}

CLI Syntax

>ctm run order <ctm> <folder> [jobs] [-f <configuration file>]

Where:

In the configuration file, you can specify the following additional parameters:

Here is an example of a configuration file:

{     
  "variables": [
        {"arg": "1234"},
        {"arg2": "abcd"},
        {"arg3": "0000"}
  ],
  "ignoreCriteria": "true",
  "orderIntoFolder": "Recent",
  "orderDate": "20170903",
  "waitForOrderDate": "false",
  "hold": "true"
}

REST API Syntax

See REST API reference.

Example using  curl:

The additional parameters are included in this command through a -d option.

endpoint=
token=
ctm=
folderName=

curl -X POST -H "Authorization: Bearer $token" --header "Content-Type: application/json" --header "Accept: application/json" -d "{
  \"ctm\": \"$ctm\",
  \"folder\": \"$folderName\",
  \"hold\": \"true\",
  \"ignoreCriteria\": \"true\",
  \"orderDate\": \"20170903\",
  \"waitForOrderDate\": \"false\",
  \"orderIntoFolder\": \"Recent\",
  \"variables\": [{\"arg\":\"12345\"}]
}" "$endpoint/run/order" 	

_{Back to top}

run status

The run status command allows you to track the status of running jobs. The following command shows how to check job status using the runId.

NOTE: To get a valid output from the outputURI and logURI fields when running commands through the CLI, you must use the token from the ctm session login . Copy the token and paste it in the ctm run status command as the input of the -t option. 

CLI Syntax

>ctm run status <runId> [startIndex]

Where:

REST API Syntax

See REST API reference.

Example using  curl:  

curl -H "Authorization: Bearer $token" "$endpoint/run/status/$runId"

Response

The following example shows the parameters in the ctm run status response

NOTE: When there is more than one job in the flow, the status of each job is checked and returned. 

>ctm run status "2d4af716-e31d-48ef-a434-16575303752d" 
{
  "statuses": [
    {
      "jobId": "controlm:00fhb",
	  "folderId": "controlm:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow",
      "type": "Folder",
      "status": "Executing",
	  "held": "false",
	  "deleted": "false",
      "startTime": "May 18, 2016 11:57:26 AM",
      "endTime": "",
      "outputURI": "Folder has no output"
    },
    {
      "jobId": "controlm:00fhc",
	  "folderId": "controlm:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow/CommandJob",
      "type": "Command",
      "status": "Wait Host",
      "held": "false",
	  "deleted": "false",
      "startTime": "",
      "endTime": "",
      "outputURI": "Job didn't run, it has no output"
    },
    {
      "jobId": "controlm:00fhd",
	  "folderId": "controlm:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow/ScriptJob",
      "type": "Job",
      "status": "Wait Condition",
      "held": "false",
	  "deleted": "false",
      "startTime": "",
      "endTime": "",
      "outputURI": "Job didn't run, it has no output"
    }
  ],
  "startIndex": 0,
  "itemsPerPage": 25
}

Where:

_{Back to top}

run jobs:status::get

The jobs status get command allows you to track running jobs that match a search query. 

The following command shows how to get job statuses using a search query. 

>ctm run jobs:status::get -s "jobname=Finance*&application=app1,app2&status=Ended OK,Ended Not OK,Executing

The following command shows how to get job statuses of a job's linked jobs.

>ctm run jobs:status::get -s "neighborhood&jobid=controlm:0a98&depth=1&direction=predecessor"

CLI Syntax

>ctm run jobs:status::get [limit] -s "<query string>"	

Limit refers to the maximum number of job statuses returned.

-s  is used to run a search using the query string format "field1=criteria1&field2=criteria2".

Where:

REST API Syntax

See REST API reference.

Example of a curl request that includes a limit:

curl -H "x-api-key: $token" "$endpoint/run/jobs/status?jobname=jobA&status=Ended%20OK&application=A*&limit=5000"

_{Back to top}

run job:output::get

The run output command allows you to view the output from job runs. 

CLI Syntax

>ctm run job:output::get <jobId> [runNo]

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/output/?runNo=0"

_{Back to top}

run job:log::get

The run log command allows you to view the job log. 

CLI Syntax

>ctm run job:log::get <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/log"

_{Back to top}

run job:status::get

The run status command allows you to view a specific job run status.

CLI Syntax

>ctm run job:status::get <jobId>

Where:

Response

The following example shows the parameters in the ctm run job:status::get response:

{
      "jobId": "controlm:00fhc",
      "folderId": "controlm:005gy",
      "rerun": 1,
      "name": "AutomationAPISampleFlow/CommandJob",
      "type": "Command",
      "status": "Ended OK",
      "startTime": "Aug 4, 2016 1:53:30 PM",
      "endTime": "Aug 4, 2016 2:00:30 PM",
      "outputURI": "http://localhost:48080/run/output/controlm:00fhc?token=a9f54556167ee2c3e5ecf543ff1415a5_B006F108",
      "logURI": "http://localhost:48080/run/log/controlm:00fhc?token=a9f54556167ee2c3e5ecf543ff1415a5_B006F108"
    }

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/status"

_{Back to top}

run job::kill

The run kill command allows you to terminate the job.

CLI Syntax

>ctm run job::kill <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/kill"

_{Back to top}

run job::runNow

The run runNow command allows you to immediately start the job. When you use this command, job constraints are not applied.

CLI Syntax

>ctm run job::runNow <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/runNow"

_{Back to top}

run job::hold 

The run hold command allows you to hold (that is, stop processing) the job.

CLI Syntax

>ctm run job::hold <jobId> 

Where: 

REST API Syntax

See REST API reference.

Example using  curl:  

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/hold"

_{Back to top}

run job::free 

The run free command allows you to continue job run from hold state.

CLI Syntax

>ctm run job::free <jobId> 

Where: 

REST API Syntax 

See REST API reference. 

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/free"

_{Back to top}

run job::delete 

The run delete command allows you to mark the job for deletion. At the next scheduled date, the job will be deleted.

CLI Syntax

>ctm run job::delete <jobId> 

Where: 

REST API Syntax 

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/delete"

_{Back to top}

run job::undelete 

The run undelete command allows you to remove a mark for deletion from a job.

CLI Syntax

>ctm run job::undelete <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/undelete"

_{Back to top}

run job::confirm 

The run confirm command allows you to run a job that is waiting for confirmation.

CLI Syntax

>ctm run job::confirm <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/confirm"

_{Back to top}

run job::setToOk 

The run setToOk command allows you to set job status to OK, after the job has been processed. You can use this command, for example, after resolving issues that caused a job to end in status Not OK.

CLI Syntax

>ctm run job::setToOk <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/setToOk"

_{Back to top}

run job::rerun

The rerun command allows you to rerun the job. When you use this command, the existing job constraints are applied.

CLI Syntax

>ctm run job::rerun <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/rerun"

_{Back to top}

Resource Management

A quantitative resource is represented by a name of a resource and the maximum number of that resource which jobs can use. Jobs that require a quantitative resource cannot run unless there are enough resources available. 

run resource::add

The add resource command allows you to add a quantitative resource to a Control-M/Server. 

CLI Syntax

>ctm run resource::add <ctm> <name> <max> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm

curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newResource\",
\"max\":5}" "$endpoint/run/resource/$ctm"

run resource::delete

The delete resource command allows you to delete a quantitative resource. 

CLI Syntax

ctm run resource::delete <ctm> <name> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
name=newResource
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/run/resource/$ctm/$name"

run resource::update

The update resource command allows you to update the values of a quantitative resource. 

CLI Syntax

ctm run resource::update <ctm> <name> <max> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
name=newResource

curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"max\":6}" "$endpoint/run/resource/$ctm/$name" 

run resources::get

The get resource command allows you to get all resource records from a specific Control-M/Server.

CLI Syntax

ctm run resources::get -s [search query]

-s  is used to run a search using the query string format "field1=criteria1&field2=criteria2".

Criteria may contain "*" for wildcard matching and comma separator to specify multiple values. 

Where:

-s "name=resourceA"
-s "name=A*"
-s "ctm=controlm*&name=resourceA,resourceB"

Response 

The following example shows the parameters in the ctm run resources::get response:

[
  {
    "name": "newResource",
    "ctm": "controlm",
    "available": "15",
    "max": 15,
    "workloadPolicy": "N/A"
  },
  {
    "name": "myRes",
    "ctm": "controlm",
    "available": "4",
    "max": 4,
    "workloadPolicy": "N/A"
  },

Where:

REST API Syntax

See REST API reference.

Example using  curl:

search_criteria="name=A*&ctm=*"
curl -H "Authorization: Bearer $token" -X GET "$endpoint/run/resources?$search_criteria" 

_{Back to top}

Event Management

An event (AKA a condition) is represented by a name and a date. Jobs that require an event cannot run unless the specific event exists. A job can add or delete an event.

run event::add

The add event command allows you to add events to the Control-M/Server.

CLI Syntax

>ctm run event::add <ctm> <name> <date> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newEvent\",\"date\":\"0505\"}"  "$endpoint/run/event/$ctm"

run event::delete

The delete event command allows you to remove an event. 

CLI Syntax

>ctm run event::delete <ctm> <name> <date> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

>ctm=controlm
>name=newEvent
>date=0505
>curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/run/event/$ctm/$name/$date"

run events::get

The get events command allows you to get all events from the Control-M/Server.

CLI Syntax

>ctm run events::get -s [search query]

-s  is used to run a search using the query string format "field1=criteria1&field2=criteria2".

Criteria may contain "*" for wildcard matching and comma separator to specify multiple values. 

Where:

-s "name=eventA"
-s "name=A*&date=0805"
-s "ctm=controlm&name=eventA,eventB&date=0805"

REST API Syntax

See REST API reference.

Example using  curl:

search_criteria="name=A*&ctm=controlm" 
curl -H "Authorization: Bearer $token" -X GET "$endpoint/run/events?$search_criteria" 

Response 

The following example shows the parameters in the ctm run events::get response:

[
 {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2902",
    "ctm": "controlm",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2935",
    "ctm": "controlm",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2974",
    "ctm": "controlm",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_3007",
    "ctm": "controlm",
    "date": "0726"
  }
]

_{Back to top}

The Config Service

The config service allows you to configure the Control-M environment.  You can access, update, and add configuration data. For example, you can list available Control-M/Servers, add agents, and manage host groups.

config server::add

Add a Control-M/Server to a Control-M environment (the Control-M/Server will be registered on the Control-M/Enterprise Manager).

To verify the Control-M/Server is up and running, run the config servers::get command to check the status of the Control-M/Server.

config server::add <host> <ctm> <id> [port]

Where:

REST API Syntax

See REST API reference.

Example using  curl:

host=`hostname`
id=123
ctm=myserver
port=2369
 
curl -X POST $endpoint/config/server/ -H 'accept: application/json' -H 'authorization: Bearer &token' -H 'content-type: 
application/json' -d '{"host": "host": "$host","id": "$id","ctm": "$ctm","port": $port}'

config server::delete

Deletes a Control-M/Server from the Control-M environment (the Control-M/Server will be un-registered from the Control-M/Enterprise Manager).

config server::delete <ctm> 

REST API Syntax

See REST API reference.

Example using  curl:

endpoint=https://<controlm>:8443/automation-api
token=
ctm= 
curl -X DELETE -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm"

config servers::get

Returns a list of Control-M/Servers. 

CLI Syntax

>ctm config servers::get

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" "$endpoint/config/servers"

Response

The following example shows the parameters in the config servers::get response. In this example, the operational state of the Control-M/Server is up and connected.

  {
    "name": "controlm",
    "host": "myhost",
    "state": "Up",
    "message": "Connected"
  }

Where:

config server:remotehost::add

The remotehost add command enables you to add a remote host to a Control-M/Server. 

CLI Syntax

>ctm config server:remotehost::add <ctm> <remotehost> [port] [-f <configuration file>]

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{
    "remotehost" : "xx", 
    "port" : 22,
    "agents": [
        "<local>"
    ],
    "encryptAlgorithm": "BLOWFISH",
    "compression": "false",
    "authorize": "true"
}

Where:

REST API Syntax

See REST API reference.

Example using curl:

The additional parameters are included in this command through a -d option.

ctm=controlm
remotehost=myhost
agent=realAgent
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST 
-d "{\"agents\": [ \"$agent\" ], \"compression\": true, \"encryptAlgorithm\": \"BLOWFISH\"}" 
"$endpoint/config/server/$ctm/remotehost/$remotehost?port=22"

config server:remotehost::authorize

The remotehost authorize command enables you to add the machine to the SSH remote host authorization list (if this was not already done when the machine was added to the Control-M/Server).

CLI Syntax

>ctm config server:remotehost::authorize <ctm> <remotehost>

Where:

REST API Syntax

See REST API reference.

Example using curl:

ctm=controlm
remotehost=myhost
curl -H "Authorization: Bearer %token%" -H "Content-Type: application/json" -X POST 
"%endpoint%/config/server/$ctm/remotehost/$remotehost/authorize"

config server:remotehost::delete

Deletes a remote host from the Control-M/Server. 

CLI Syntax

>ctm config server:remotehost::delete <ctm> <remotehost>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
remotehost=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$ctm/remotehost/$remotehost"

config server:remotehosts::get

Returns a list of all remote hosts registered to the Control-M/Server. 

CLI Syntax

>ctm config server:remotehosts::get <ctm>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/remotehosts"

config server:remotehost::get

Returns the remote host configuration properties from the Control-M/Server. 

CLI Syntax

>ctm config server:remotehost::get <ctm> <remotehost>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
remotehost=myhost
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/remotehost/$remotehost"

config server:agent::add

Adds a Control-M/Agent to a specific Control-M/Server. This allows the Control-M/Server to run jobs on this host where the agent is installed. Also, it verifies the connectivity between the Control-M/Server and the Control-M/Agent.

CLI Syntax

>ctm config server:agent::add <ctm> <host> <port> [-f <configuration file>]

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{    
	"persistentConnection": true
} 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
host=myhost
port=7006

curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"host\":\"$host\",\"port\":\"$port\"}" "$endpoint/config/server/$ctm/agent"

config server:agent::delete

Deletes a Control-M/Agent from the Control-M/Server database. This removes the Control-M/Agent from a Control-M/Server without shutting the agent down.

CLI Syntax

>ctm config server:agent::delete <ctm> <agent>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

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

config server:agent:params::get

Get parameters of a Control-M/ Agent registered to a Control-M/Server. Returns a list of Control-M/Agent parameters. Each entry is a pair which consists of parameter name and value. 

CLI Syntax

>ctm config server:agent:params::get <ctm> <agent>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
agent=host
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/agent/$agent/params"

config server:agent:param::set

Set the value of a specific Control-M/Agent parameter.

CLI Syntax

>ctm config server:agent:param::set <ctm> <agent> <name> <value>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
agent=quickstart
name=LIMIT_LOG_VERSIONS
value=10
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"value\":\"$value\"}" "$endpoint/config/server/$ctm/agent/$agent/param/$name"

config server:agent::ping

Checks if the Control-M/Agent is available.

>ctm config server:agent::ping <ctm> <agent> [-f <configuration file>]

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{     "discover": true,"timeout":60}

Where:

REST API Syntax

See REST API reference.

Example using  curl:

The additional parameters are included in this command through a -d option.

ctm=controlm
agent=quickstart
curl -X POST -H "Authorization: Bearer $token"  -H "Content-Type: application/json" -d "{\"discover\": false, \"timeout\":60}" "$endpoint/config/server/$ctm/agent/$agent/ping"

config server:agents::get

Returns a list of all Control-M/Agents registered to the Control-M/Server and the state of each agent.

The states supported are:   

• Available

• Unavailable

• Disabled

• Discovering

CLI Syntax

>ctm config server:agents::get <ctm>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/agents"

config server:agent::disable

Disables Control-M/Agent from Control-M/Server. New jobs cannot run on the Control-M/Agent.

CLI Syntax

>ctm config server:agent::disable <ctm> <agent>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

endpoint=https://<yourhost>:8443/automation-api
token=
ctm=
agent=

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

config server:agent::enable

Enables jobs to run on the Control-M/Agent. 

CLI Syntax

>ctm config server:agent::enable <ctm> <agent>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

endpoint=https://<yourhost>:8443/automation-api
token=
ctm=
agent=

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

config server:hostgroups::get

Returns a list of host groups defined in the Control-M/Server. Each entry is a host group name.

CLI Syntax

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

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/hostgroups"

config server:hostgroup:agents::get

Returns a list of agents of a host group. Each entry is the logical name of an agent.

CLI Syntax

>ctm config server:hostgroup:agents::get <ctm> <hostgroup>

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
hostgroup=HostGroup1 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/hostgroup/$hostgroup/agents"

config server:hostgroup:agent::add

Adds a Control-M/Agent to a host group and creates the host group if it does not exist.

CLI Syntax

>ctm config server:hostgroup:agent::add <ctm> <hostgroup> <host> [-f <configuration file>]

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{  
   "host":"agent3",
   "hostgroupAgentParticipation":{  
      "event":"agent3Cond",
      "orderDate":"AnyDate"
   }
}

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
hostgroup=mygroup 
host=myhost
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d  "{\"host\":  \"$host\",  \"hostgroupAgentParticipation\":{ \"event\": \"agent3Cond\", \"orderDate\": \"AnyDate\"}}" "$endpoint/config/server/$ctm/hostgroup/$hostgroup/agent"

config server:hostgroup:agent::delete

Removes a Control-M/Agent from a hostgroup. If the group is empty after the deletion, it is also deleted.

CLI Syntax

>ctm config server:hostgroup:agent::delete <ctm> <hostgroup> <host>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
hostgroup=mygroup 
host=myhost
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/server/$ctm/hostgroup/$hostgroup/agent/$host"

config server:params::get

Returns a list of parameters of a Control-M/Server. The following fields are returned:

• name
• value
• defaultValue

CLI Syntax

>ctm config server:params::get <ctm>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm 
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/params"

config em:param::set

Set the value of a Control-M/Enterprise Manager system parameter. Supports only a select group of system parameters. The user can set this value only if they have permissions to that specific environment.

CLI Syntax

>ctm config em:param::set <paramName> <value>

Where:

REST API Syntax

See REST API reference.

Example using  curl:

paramName=api_key
value=true
curl -H "Authorization: Bearer $token" -X POST -d "{\"value\":\"$value\"}" "$endpoint/config/em/param/$paramName"

_{Back to top}

Config Secrets

Config secrets allows you to add, delete, or update named secrets in the Control-M vault. The Control-M vault is a secured collection of name and value pairs of secrets.

To learn how to use Secrets in Code, see Secrets in Code.

config secret::add

Creates a pair which consists of named secret and value in the Control-M vault.

>ctm config secret::add <name> <value>

REST API Syntax

See REST API reference.

Example using  curl:

>curl -H "Authorization: Bearer $token"  -X POST -d "{\"name\":\"$name\",\"value\":\"$value\"}" "$endpoint/config/secret"

config secret::delete

Deletes the pair of named secret and value from the Control-M vault.

>ctm config secret::delete <name> 

REST API Syntax

See REST API reference.

Example using  curl:

>curl -H "Authorization: Bearer $token"  -X DELETE  "$endpoint/config/secret/$name"

config secret::update

Updates the value of the named secret in the Control-M vault.

>ctm config secret::update <name> <value>

REST API Syntax

See REST API reference.

Example using  curl:

>curl -H "Authorization: Bearer $token"  -X POST -d "{\"value\":\"$value\"}" "$endpoint/config/secret/$name"

config secrets::get

Returns a list of names of defined secrets.

>ctm config secrets::get 

REST API Syntax

See  REST API reference .

Example using  curl:

>curl -H "Authorization: Bearer $token"  "$endpoint/config/secrets"

_{Back to top}

The Deploy Service

The deploy service allows you to transfer job and configuration definitions to Control-M. Once a job is deployed, it will be scheduled by Control-M according to its scheduling criteria and dependencies. The deploy overwrites any existing definition of the same name.

deploy

Deploy the provided definition file to Control-M. Build will take place as part of the deploy to ensure code validity. deploy can receive definition files in .json format or Control-M import/export .xml format, or a package of multiple job definition files in .zip or .tar.gz format.

CLI Syntax

>ctm deploy <definitionsFile> [deployDescriptorFile]

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json" -F "deployDescriptorFile=@examples/deployDescriptor.json"  "$endpoint/deploy" 

deploy jobs::get

Returns the definition of jobs and folders in the requested format that match the search criteria.

CLI Syntax

>ctm deploy jobs::get [format] -s <search query>

-s  is used to run a search using the query string format. The following table includes the fields that can be used in the search query:

For example, the following command shows how to get a job in a JSON format for all the folders that start with Automation:

>ctm deploy jobs::get -s "ctm=*&folder=Automation*"

REST API Syntax

See REST API reference.

>curl -k  -H "Authorization: Bearer $token"  "$endpoint/deploy/jobs?ctm=*&folder=Auto*"
 
>curl -k  -H "Authorization: Bearer $token"  "$endpoint/deploy/jobs?ctm=*&folder=Auto*&format=XML"

deploy connectionprofiles::get

Returns the connection profiles that match the search criteria.

CLI Syntax

>ctm deploy connectionprofiles::get -s <search query>

 Use the required -s option to specify a query string to search for. The following table includes the fields that can be used in the search query:

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
ctm=
agent=
type=
curl -X GET-H "Authorization: Bearer $token"  "$endpoint/deploy/connectionprofiles?ctm=$ctm&agent=$agent&type=$type"

deploy connectionprofile::delete

Deletes the connection profile.

CLI Syntax

>ctm deploy connectionprofile::delete <ctm> <agent> <type> <name>

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
ctm=
agent=
type=
name=
curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/connectionprofile/$ctm/$agent/$type/$name"

deploy folder::delete

The delete folder command enables you to delete a folder

CLI Syntax

>ctm deploy folder::delete <ctm> <folderName>

REST API Syntax

See REST API reference.

endpoint=https://<controlm>:8443/automation-api
token=
ctm=
folder=
curl -X DELETE -H "Authorization: Bearer $token"  "$endpoint/deploy/folder/$ctm/$folder"

deploy transform

The transform command enables you to apply the rules of the deployDescriptorsFile to the original definitionsFile.  The rules define the method to use that change the values of the JSON code properties in the original defintionsFile. 

CLI Syntax

>ctm deploy transform <definitionsFile> <deployDescriptorFile>

Where:

REST API Syntax

See REST API reference.

curl -H "Authorization: Bearer $token" -X POST  -F "definitionsFile=@examples/AutomationAPISampleFlow.json" -F "deployDescriptorFile=@examples/deployDescriptor.json"  "$endpoint/deploy/transform"

deploy deployed (deprecated)

Exports a deployed folder or folders in a Control-M import/export .xml format. You can use "*"as wildcard character. For example, setting the folder name to "*" will export all folders. Setting the folder name to "A*" will export all folders whose name starts with "A".

This command has been deprecated. Use deploy jobs::get instead.

CLI Syntax

>ctm deploy deployed <controlM> <folderName>

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
folderName=A* 
curl -H "Authorization: Bearer $token" "$endpoint/deploy/deployed/$ctm/$folderName" 

_{Back to top}

The Package Service

Create a package from a directory of .json and .xml definition files. It returns a .zip archive. This package can be deployed, run, or built by these respective services.

CLI Syntax

>ctm package <zipOutputFilename> <deploymentFilesDirectory>

_{Back to top}

The Provision Service

For Control-M to run and monitor jobs on your application host, a Control-M/Agent should be installed. The provision service allows you access to the full cycle of installing and setting up a new Control-M/Agent. 

The Provision service includes the following major commands:

• Image: prepares the file system installation of the Agent
• Setup: registers and configures the Agent with a Control-M/Server
• Install: runs image and setup in a single step

Separating the Image and Setup phases can help in a situation in which installing and setting up Agents dynamically is required by your architecture. In this scenario, you can prepare your image (whether it is a VM image, a Docker image, AWS AMI, etc.) with the Agent inside it. Then when required, use the setup command to dynamically perform Agent setup and register it to the Control-M/Server.

For a more static architecture, where there is no distinction between building an image and instantiation, you can use the provision install command, which allows you to install in a single step.

Additional commands are available for removing an image and for uninstalling a Control-M/Agent from the application host.

The images used during provisioning are JSON code too. Each image contains a list of installation packages in the order that they are installed. Several default images are provided by the API, and you can create additional custom images (for example, for installation of a newer version of the Control-M/Agent). To prepare for provisioning, you must obtain the installation packages that are referenced within the images. You can also (optionally) customize the location in which to save these packages (for example, you might want to save the packages in a JFrog Artifactory repository, in Amazon S3 Buckets, or in your local file system). For more information about these preparatory tasks, see the Control-M Administrator Guide in the Control-M Online Help.

Here is an example of requesting a list of available images and installing one of them.

>ctm provision images Linux -e devEnvironment
[
  "Agent.Linux",
  "BigDataAgent.Linux"
]
 
>ctm provision install Agent.Linux
info:    downloading https://endpoint:8443/automation-api/utils/control-m.services.provision-1.0.0.jar into C:\Users\user\.ctm\control-m.services.provision-9.0.4.jar
0MB/10MB precent: 2%
...

images

Get a list of the images available for a specific OS. Returns a list of image names.

CLI Syntax

>ctm provision images <os>

Where:

image

Downloads and installs an image into the current user account. The image is not configured or registered with a Control-M/Server.

CLI Syntax

>ctm provision image <image>

Where:

setup  

Connects and registers an image with a Control-M environment.

CLI Syntax

>ctm provision setup [ctm] [name] [port] [-f <configuration file>]

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{
    "connectionInitiator": "AgentToServer"
}

Where:

For example:

provision setup
provision setup ""          ""       2056
provision setup "controlm1" ""       2056
provision setup ""          "alias1" 2056
provision setup -f persistent.json

install 

Combines the image and the setup commands into one action. Downloads the agent and then connects and registers it with a Control-M/Server.

CLI Syntax

>ctm provision install <image> [ctm] [name] [port]  [-f <configuration file>]

Where:

The following is a list of the additional parameters that can be used in the configuration file:

{
    "connectionInitiator": "AgentToServer"
}

Where:

image::remove

Uninstalls a Control-M image from this user account. The image is removed without unregistering it from a Control-M/Server.

CLI Syntax

>ctm provision image::remove

uninstall

Uninstalls a Control-M image from this user account and unregisters it from the Control-M/Server.

CLI Syntax

>ctm provision uninstall

_{Back to top}

The Environment Service

The environment service enables you to manage environments, including defining and selecting the Control-M environment to use. An environment is a combination of an endPoint, username, and password. 

An endPoint looks like the following: 

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

Environments are saved in an env.json file located in the home user with read/write permissions only for the logged in user under .ctm folder.

env.json is encrypted.

For example, to add an environment and name it devEnvironment, use the command below:

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

show

Returns a list of all defined environments.

CLI Syntax

 >ctm environment show

add

Adds a new environment.

CLI Syntax

 >ctm environment add <env> <endPoint> <user> <password>

Where:

set 

Sets the default environment for interactive work. All commands are sent to this environment unless a different environment is defined using the -e option.

CLI Syntax

 >ctm environment set <env>

Where:

delete

Deletes an environment.

CLI Syntax

 >ctm environment delete <env>

Where:

update

Updates an environment property. The property <name> can be an endPoint, username, or password. If an environment does not exist, it will be created.

CLI Syntax

 >ctm environment update <env> <name> <value>

Where:

copy 

Duplicates an environment. 

CLI Syntax

 >ctm environment <env> <newEnv>

Where:

load 

This command allows you to load a predefined env.json to your environment definitions. 

The file that you are importing must include passwords that are decoded. When saved to the user's env.json file, the passwords are encrypted.

CLI Syntax

 >ctm environment load <enviromentsFile>

Where:

configure

This command allows you to set  parameters for all environments.

CLI Syntax

 >ctm environment configure <setting name> [setting value]

Where:

Possible parameters:

_{Back to top}

The Reporting Service

The Reporting service enables you to generate reports that were set up through Control-M Reports.

NOTE: To generate a report through the Control-M Automation API, the user running the command must be the same as the Control-M/EM user who created the report in Control-M Reports. 

The following example shows a typical CLI command and response. The report is made available at the specified URL for access through a browser, and you can also choose to download it to a file.

>ctm reporting report::get Alerts_1 pdf -o C:\BMC\test.pdf
{
  "reportURL": "http://VW-C363:18080/RF-Server/Alerts_1_8d1a2cd5-62f3-4823-b1ab-4da67ab66237.pdf"
}
Downloading 'http://VW-C363:18080/RF-Server/Alerts_1_8d1a2cd5-62f3-4823-b1ab-4da67ab66237.pdf'
into 'C:\BMC\test.pdf'

CLI Syntax

>ctm reporting report::get <report_name> [format] [-o <file_path>]

Where:

REST API Syntax

See REST API reference.

In the following curl example, report format is set to pdf through a query parameter:

curl -H "Authorization: Bearer $token" $endpoint/reporting/report/$report_name?format=pdf

This curl command returns a download URL for the report.

You now have the option of running a second curl command to download the report from the specified download URL to a file. For the location of the file, you can choose from the following options:

• The -O option downloads the report to a file in the current directory (from which you ran curl).

  REST API

  curl -H "Authorization:Bearer $token" -O $dowload_url

• The -o option downloads the report to a directory and file that you specify.

  REST API

  curl -H "Authorization:Bearer $token" -o $report_path $dowload_url

_{Back to top}

The Session Service

Session service allows you to log in and log out of Control-M and receive a token that can be reused in subsequent requests.

session login

Log in to Control-M and return a session token that can later be used for subsequent requests using the -t option. 

A token is valid for 30 minutes.

Example for CLI:

>ctm session login
{
  "username": "emuser",
  "token": "d6ad05ecbee1dd74bf100447ed2be5d6_D749761E",
  "version": "9.0.5"
}

>ctm config servers::get -t "d6ad05ecbee1dd74bf100447ed2be5d6_D749761E"

Example 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

session logout

Log out from the user session defined by the given token.

Using CLI:

>ctm session logout <token>

Example using curl:

endpoint=https://<controlmEndPointHost>:8443/automation-api
token=E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7

curl -g -k -H "Authorization: Bearer $token" -X POST "$endpoint/session/logout"

_{Back to top}

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:      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":"97357564b0de945c6cdb482d61cbbd7c_96DBD659"
}

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

Authorization: Bearer 97357564b0de945c6cdb482d61cbbd7c_96DBD659

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)

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> 

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 

Related information

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

• Support videos
• Online Help