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.
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:
Parameter | Description |
---|---|
<definitionsFile> | The file or archive that contains code for jobs. Valid formats are:
|
[deployDescriptorFile] | (Optional) The file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy Descriptor. |
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)
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:
Parameter | Description |
---|---|
<jobDefinitionsFile> | The file or archive that contains code for jobs. Files must be in JSON format. |
[deployDescriptorFile] | (Optional) The file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy Descriptor. |
If annotation is enabled for the Scheduling definitions category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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"
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:
Parameter | Description |
---|---|
<ctm> | Control-M/Server |
<folder> | Folder name that is ordered |
[jobs] | (Optional) Can use wildcard *. If not defined, the entire folder is ordered |
[configuration file] | (Optional) JSON file that contains additional parameters. |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
In the configuration file, you can specify the following additional parameters:
Parameter | Description |
---|---|
variables | Defines job variables for the run, expressed as name:value pairs. |
hold | Enables you to make changes to a job before it starts running. Values: true|false Default: false |
ignoreCriteria | Enables you to run a job when ordered, ignoring the configured scheduling criteria. Values: true|false Default: true |
independentFlow | Determines whether a flow in a folder is ordered uniquely. Not applicable to Sub Folders. Values: true|false Default: true |
orderDate | Determines the work day on which to schedule the job. This can be either "current" or a future date in YYYYMMDD format. Default: current |
waitForOrderDate | Enables you to wait for the defined Order date to run Values: true|false Default: false |
createDuplicate | Whether jobs/sub-folders with the same name that already exist in the Folder are to be added to the SMART folder when you select Recent orSelected. Default: true Determines whether jobs/sub-folders with the same name that already exist in the Folder are to be added to the SMART folder. This is relevant when orderIntoFolder (next parameter) is set to Recent or to a specific Order ID. Values: true|false Default: true |
orderIntoFolder | Determines how to order jobs or Sub Folders that belong to a SMART Folder. Jobs and Sub Folders are added to a SMART Folder according to the following Order Into Folder options:
If the job or Sub Folder is inserted into an existing folder or Sub Folder that has already completed, the status of all parent folders is set to Executing. If it is not possible due to scheduling criteria, the job remains in WAIT_SCHEDULING status. This parameter is ignored if the folder that is ordered is not a SMART Folder. |
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:
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"
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:
Parameter | Description |
---|---|
<runId> | Value returned in a ctm run invocation. It enables job tracking during a specific run. |
startIndex | (Optional) enable iteration over all statuses. Result includes "itemsPerPage": 25 items from this index. If not defined, the default is 0. |
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, 2018 11:57:26 AM",
"endTime": "",
"estimatedStartTime": [
"20180518121500,",
"20180518123000,"],
"estimatedEndTime": [
"20180518121502,",
"20180518123005,"],
"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": "",
"estimatedStartTime": [],
"estimatedEndTime": [],
"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": "",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "Job didn't run, it has no output"
}
],
"startIndex": 0,
"itemsPerPage": 25
}
Where:
Parameter | Description |
---|---|
jobId | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
folderId | The folderId is used to reference a specific folder |
numberOfRuns | Number of job runs |
name | Name of job |
type | Job type |
status | Job status |
held | Whether the job was held — true | false |
deleted | Whether the job was deleted — true | false |
startTime | The time when the job started |
endTime | The time when the job ended |
estimatedStartTime | The estimated date and time when the next job runs (up to 50) are expected to begin. Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment. |
estimatedEndTime | The estimated date and time when the next job runs (up to 50) are expected to end. Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment |
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:
Field | Criteria | Criteria example |
---|---|---|
|
| jobname=job1122 jobname=job11* jobname=job11*,job77* description=*a job that* jobid=controlm:005gy |
|
| orderDateFrom=180123 fromTime=20180123184500 |
status |
To use multiple criteria, separate criteria with commas. | status=Ended OK status=Ended OK, |
neighborhood | Returns the status according to the dependencies between jobs. To create dependencies between jobs, use the flow object.
| "neighborhood&jobid |
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"
Response
The following example shows the parameters for one of the jobs returned in the response to the jobs status get command.
{
"jobId": "LocalControlM:00008",
"folderId": "LocalControlM:00007",
"numberOfRuns": 0,
"name": "job1",
"folder": "SanityCommandOk",
"type": "Command",
"status": "Wait Condition",
"held": true,
"deleted": false,
"startTime": "",
"endTime": "",
"estimatedStartTime": [],
"estimatedEndTime": [],
"orderDate": "180903",
"ctm": "LocalControlM",
"description": "",
"host": "",
"application": "OsApp",
"subApplication": "",
"outputURI": "Job did not run, it has no output",
"logURI": "http://localhost:48080/run/job/LocalControlM:00008/log?token=a3be0b6b63bed01f1e11da24319ba133_81C95551"
}
The following table describes the parameters in this sample response:
Parameter | Description |
---|---|
jobId | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
folderId | A unique identifier of the folder to which the job belongs. The format of this ID is "Control-M/Server name:order ID of the folder" |
numberOfRuns | Number of job runs |
name | Name of job |
folder | Name of the folder to which the job belongs |
type | Job type |
status | Job status |
held | Whether the job was held — true | false |
deleted | Whether the job was deleted — true | false |
startTime | The time when the job started |
endTime | The time when the job ended |
estimatedStartTime | The estimated date and time when the next job runs (up to 50) are expected to begin. Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment. |
estimatedEndTime | The estimated date and time when the next job runs (up to 50) are expected to end. Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment |
orderDate | The work day on which the job was scheduled, in YYMMDD format |
ctm | Control-M/Server name |
description | A textual description of the job, as defined during job creation |
host | host of the Control-M/Agent where the job is running |
application | The name of an application with which the job is associated. An application is a logical set of related jobs. |
subApplication | The name of a sub-application with which the job is associated. A sub-application is a logical sub-category of an application. For example, a group of payroll-related jobs are logically grouped together in a sub-application named Payroll, within an application named Finances. |
outputURI | URI to the job output |
logURI | URI to the job log |
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
[runNo] | (Optional) The run number of the job to get the output. If not defined, the default is the last run. |
If annotation is enabled for the AJF get job information category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/output/?runNo=0"
run job:log::get
The run log command allows you to view the job log.
CLI Syntax
>ctm run job:log::get <jobId>
Where:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the AJF get job information category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/log"
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
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",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "http://localhost:48080/run/output/controlm:00fhc?token=a9f54556167ee2c3e5ecf543ff1415a5_B006F108",
"logURI": "http://localhost:48080/run/log/controlm:00fhc?token=a9f54556167ee2c3e5ecf543ff1415a5_B006F108"
}
Where:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
<folderId> | The folder run ID enables grouping runs by folder instances. |
<rerun> | Number of job runs |
<name> | Name of job |
<type> | Type of job |
<status> | The following list includes valid job statuses:
|
<startTime> | The time when the job started |
<endTime> | The time when the job ended |
<estimatedStartTime> | The estimated date and time when the next job runs (up to 50) are expected to begin. Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment. |
<estimatedEndTime> | The estimated date and time when the next job runs (up to 50) are expected to end. Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment |
<outputURI> | URI to the job output |
<logURI> | URI to the job log |
REST API Syntax
Example using curl:
curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/status"
run job::kill
The run kill command allows you to terminate the job.
CLI Syntax
>ctm run job::kill <jobId>
Where:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/kill"
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/runNow"
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/hold"
run job::free
The run free command allows you to continue job run from hold state.
CLI Syntax
>ctm run job::free <jobId>
Where:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/free"
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/delete"
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/undelete"
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/confirm"
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/setToOk"
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:
Parameter | Description |
---|---|
<jobId> | A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "<ctm>:<orderid>". |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/rerun"
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<name> | Name of the resource |
<max> | Maximum quantity of resources available Valid values: 0-9999 |
If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<name> | Name of the resource |
If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<name> | Name of the resource |
<max> | Maximum quantity of resources available Valid values: 0-9999 |
If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Field | Description |
---|---|
ctm | Name of the Control-M/Server |
name | Name of the resource |
-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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<name> | Name of the resource |
<available> | Number of resources available |
<max> | Maximum resources available |
<workloadPolicy> | Name of workload policy that is linked to the resource. N/A indicates that the resource is not linked to a workload policy. For more information about workload policies, see the documentation on Workload Policy in the Control-M Online Help. |
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"
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<name> | Name of the event |
<date> | Date options to order the event:
|
If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<name> | Name of the event |
<date> | Date options to order the event:
|
If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Field | Description |
---|---|
ctm | Name of the Control-M/Server |
name | Name of the event |
date | Date of event |
limit | Limits the number of returned matches. Default: 1000 (if not defined) |
-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"
}
]
Workload Policy Management
Workload Policies enable you to balance the workload on Control-M resources and hosts. A Workload Policy groups together any number of jobs and enforces workload rules that limit resource usage by those jobs during specific time periods. For more information about workload policies, see the documentation on Workload Policy in the Control-M Online Help.
run workloadpolicies::get
Retrieves details of defined Workload Policies, with the option of filtering by status (that is, retrieving only active workload policies or only inactive workload policies).
Details in the response include the current status of each Workload Policy (whether active or inactive) and details of the last update to Workload Policy definitions.
CLI Syntax
>ctm run workloadpolicies::get [Active|Inactive]
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X GET "$endpoint/run/workloadpolicies?state=Active"
run workloadpolicy::activate
Activates a Workload Policy that is currently inactive.
To activate multiple Workload Policies, you can specify a string that contains an asterisk as a wildcard. In addition, you can optionally filter Workload Policies by associated Control-M/Server.
CLI Syntax
>ctm run workloadpolicy::activate <policyName> [<ctm>]
Where:
Parameter | Description |
---|---|
[policyName] | The name of a Workload Policy or, for multiple Workload Policies, a string that contains an asterisk as a wildcard. |
ctm | (Optional) The name of an associated Control-M/Server to use as a filter. Only Workload Policies that are associated with the specified Control-M/Server are activated. |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
policyname=WP*
ctm=LocalControlM
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/workloadpolicy/$policyname/activate?ctm=$ctm"
run workloadpolicy::deactivate
Deactivates a Workload Policy that is currently active.
To deactivate multiple Workload Policies, you can specify a string that contains an asterisk as a wildcard. In addition, you can optionally filter Workload Policies by associated Control-M/Server.
CLI Syntax
>ctm run workloadpolicy::deactivate <policyName> [<ctm>]
Where:
Parameter | Description |
---|---|
[policyName] | The name of a Workload Policy or, for multiple Workload Policies, a string that contains an asterisk as a wildcard. |
ctm | (Optional) The name of an associated Control-M/Server to use as a filter. Only Workload Policies that are associated with the specified Control-M/Server are deactivated. |
If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
policyname=WP*
ctm=LocalControlM
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/workloadpolicy/$policyname/deactivate?ctm=$ctm"
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:
Parameter | Description |
---|---|
<host> | Control-M/Server host name |
<ctm> | Control-M/Server name |
<id> | Defines a unique 3-character code to identify the Control-M/Server |
[port] | (Optional) Control-M/Server port Default:2369 |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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>
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
name | Control-M/Server name |
host | Control-M/Server host name |
state | Determines the state of the Control-M/Server Options:
|
message | Description of the state or error message. Possible values: Connected, Disconnected, "", error message |
config server::failover
The failover command enables you to perform a manual failover of a Control-M/Server to a secondary host, provided that High Avilability (HA) is set up for this server.
For more information, see the section about High Availability in the Control-M Administrator Guide in the Control-M Online Help.
CLI Syntax
>ctm config server::failover <ctm>
Where <ctm> is the name of the Control-M/Server.
If annotation is enabled for the High availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
ctm=controlm
curl -H "Authorization: Bearer $token" -X PUT "$endpoint/config/server/$ctm/failover"
config server::setasprimary
The setasprimary command enables you to set a secondary server as the primary Control-M/Server.
Use this command only after performing a successful manual failover on the server that functioned as the primary server until now. You must have High Availability (HA) set up for these servers.
For more information, see the section about High Availability in the Control-M Administrator Guide in the Control-M Online Help.
CLI Syntax
>ctm config server::setasprimary <ctm>
Where <ctm> is the name of the Control-M/Server.
If annotation is enabled for the High availability category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
ctm=controlm
curl -H "Authorization: Bearer $token" -X PUT "$endpoint/config/server/$ctm/setasprimary"
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<remotehost> | Name of host or alias of the remote host |
[port] | (Optional) SSH port number. Default value: 22 |
[configuration file] | (Optional) JSON file that contains additional parameters. |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
agents | Control-M/Agents that manage the remote host. If not defined, the default Control-M/Agent will be used. Default: local |
port | Default: 22 |
encryptAlgorithm | Encryption algorithm type used to encrypt data between the Control-M/Agent and the remote host. The options are:
Default: BLOWFISH |
compression | true | false Default: false |
authorize | Enables you to add the machine to the SSH remote host authorization list. If true, you will not be prompted to connect at each attempted connection. true | false Default: true |
REST API Syntax
See REST API reference.
Example using curl:
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<remotehost> | Name of host or alias of the remote host |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<remotehost> | Name of host or alias of the remote host |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
REST API Syntax
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:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<remotehost> | Name of host or alias of the remote host |
REST API Syntax
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<host> | Name of host or alias of the Control-M/Agent. This will be registered in Control-M/Server as the logical name of the Control-M/Agent. |
<port> | Number of port for communiation from Control-M/Server to Control-M/Agent. Valid values are between 1025 and 65535. For example, 7006. |
[configuration file] | (Optional) JSON file that contains additional parameters |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
The following is a list of the additional parameters that can be used in the configuration file:
{
"persistentConnection": true
}
Where:
Parameter | Description |
---|---|
persistentConnection | Creates a permanent connection between Control-M/Server and Control-M/Agent for a firewall environment. true | false Default: false |
REST API Syntax
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<agent> | Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<agent> | Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<agent> | Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
<name> | Name of parameter |
<value> | Value of parameter |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<agent> | Name of Control-M/Agent |
[configuration file] | (Optional) JSON file that contains additional parameters. |
The following is a list of the additional parameters that can be used in the configuration file:
{ "discover": true,"timeout":60}
Where:
Parameter | Description |
---|---|
discover | When true, the Control-M/Agent is added to the Control-M/Server when the ping status is unavailable. true | false Default: false |
timeout | Maximum time (in seconds) to wait for a ping response Default : 60 |
REST API Syntax
See REST API reference.
Example using curl:
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. You can optionally filter the list for Agents that match a specific pattern.
The states supported are:
- Available
- Unavailable
- Disabled
- Discovering
CLI Syntax
>ctm config server:agents::get <ctm> ["agent=<agent_pattern>"]
Where:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<agent_pattern> | (Optional) Filter the list to include only agents that match a specified pattern. As wildcards, use asterisks (*). For example: |
REST API Syntax
See REST API reference.
Example using curl:
ctm=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/agents?agent=Agent*1*"
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:
Parameter | Description |
---|---|
ctm | Name of Control-M/Server |
agent | Name of Control-M/Agent |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
ctm | Name of Control-M/Server |
agent | Name of Control-M/Agent |
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
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>
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<hostgroup> | Name of host group |
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<hostgroup> | Name of host group |
<host> | Name of host or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
[configuration file] | (Optional) JSON file that contains additional parameters |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
host | Name of host or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. | ||||||||||
hostgroupAgentParticipation | Only if event occurs, the host will be part of host group | ||||||||||
orderDate | The work day on which to schedule the requested action. Possible values:
| ||||||||||
event | Name of an event |
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<hostgroup> | Name of host group |
<host> | Name of host or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:runasuser::add
Adds a new user to the list of users that are available for running jobs on an agent. Whenever you define a job, you can choose a "run as" user from the list of predefined users.
Tips
Before adding a new "run as" user, you might want to use the config server:runasuser::test command to test the connection to the user and verify the authentication details that you defined in your configuration file.
The following video demonstrates how to manage "run as" users: https://youtu.be/Xfv-2UStyBE
CLI Syntax
>ctm config server:runasuser::add <ctm> <agent> <user> [password] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent, or "All" for all agents |
<user> | Name of user |
[password] | A valid password for the specified user NOTE: You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence. |
[configuration file] | Full path to a JSON file that contains authentication details for the "run as" user. You can choose one of the following options: |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
Content of configuration file
The following example configuration file contains a password in plain text.
{
"password": "pass1"
}
The following example configuration file contains the name of a predefined secret instead of a password.
{
"password": "Secret:topSecretPassword"
}
The following example configuration file contains key authentication details for an SSH connection. In this example, the passphrase is specified as a predefined secret.
{
"key": {
"keyname": "keyName",
"passphrase": "Secret:topSecretPassphrase"
}
}
REST API Syntax
See REST API reference.
In the following curl example, note that the path to the configuration file is prefixed with an @ character.
ctm=controlm
curl -H "Authorization: Bearer $token"
-H "Content-Type: application/json" --data "@runasUserDefinition.json"
-X POST "$endpoint/config/server/$ctm/runasuser"
When using a REST API command to add a "run as" user, the configuration file must contain full user credentials, including the agent and user name, as shown in the following example. In this example, authentication details are for an SSH connection to a remote host (based on a key and passphrase).
{
"user": "user1",
"agent": "All",
"key": {
"keyname": "keyName",
"passphrase": "passphrase1"
}
}
config server:runasuser::get
Retrieves the details of a specific "run as" user. You can use this command to verify that a certain user exists in the list of defined users. Each "run as" user is uniquely identified by its combination of agent and user name.
CLI Syntax
>ctm config server:runasuser::get <ctm> <agent> <user>
Where:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent, or "All" for all agents |
<user> | Name of user Note: If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. |
REST API Syntax
See REST API reference.
Example using curl:
ctm=controlm
curl -H "Authorization: Bearer $token"
$endpoint/config/server/$ctm/runasuser/realAgent/user1
config server:runasuser::update
Updates the authentication parameters of an existing "run as" user. Each "run as" user is uniquely identified by its combination of agent and user name.
Tip
Before updating the "run as" user, you might want to use the server:runasuser::test command to test the connection to the user and verify the validity of the user's authentication details.
CLI Syntax
>ctm config server:runasuser::update <ctm> <agent> <user> [password] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent, or "All" for all agents |
<user> | Name of user Note: If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. |
[password] | A new valid password for the specified user NOTE: You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence. |
<configuration file> | Full path to a JSON file that contains authentication details that you want to update for the "run as" user. You can choose one of the following options:
For example contents of a configuration file, see the description under the runasuser::add command. |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
The REST API command specifies the agent and user, and the configuration file contains only the authentication details (either a password or a key and passphrase). In the following curl example, note that the path to the configuration file is prefixed with an @ character.
ctm=controlm
curl -H "Authorization: Bearer $token"
-H "Content-Type: application/json" --data "@runasUserDefinition.json"
-X POST "$endpoint/config/server/$ctm/runasuser/realAgent/user1"
config server:runasuser::delete
Deletes a "run as" user from the list of users that are available for running jobs on an agent. Each "run as" user is uniquely identified by its combination of agent and user name.
CLI Syntax
>ctm config server:runasuser::delete <ctm> <agent> <user>
Where:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent, or "All" for all agents |
<user> | Name of user Note: If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
ctm=controlm
curl -H "Authorization: Bearer $token"
-X DELETE $endpoint/config/server/$ctm/runasuser/realAgent/user1
config server:runasuser::test
Tests the connection for a "run as" user that you specify. You can use this command in the following ways:
- Specify the agent and user name in the command line, but do not specify authentication credentials. This is especially useful for verifying the validity of the credentials of a defined "run as" user before updating the user's authentication parameters.
- Specify also the password in the command line or specify authentication details in a configuration file. This is especially useful for verifying the validity and connectivity of a user before adding the user to the list of "run as" users.
CLI Syntax
>ctm config server:runasuser::test <ctm> <agent> <user> [password] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent Note: The "All" value is not supported when testing a "run as" user. If this "run as" user is associated with all agents, you can test it against any individual agent. In this case, the password is required. |
<user> | Name of user Note: If the user name contains special characters, in a REST API command use URL encoding for any special characters in the user name. |
[password] | A password to test for the specified user NOTE: You can instead specify the password in a configuration file. If you specify the password in both the command line and the configuration file, the command line takes precedence. |
<configuration file> | Full path to a JSON file that contains authentication details of the "run as" user. For example contents of a configuration file, see the description under the runasuser::add command. |
REST API Syntax
See REST API reference.
Examples using curl:
Example for testing an existing user:
ctm=controlm curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" --data "{}" -X POST $endpoint/config/server/$ctm/runasuser/realAgent/user1/test
For this test, a configuration file is not necessary, because authentication details are not required.
Example for testing a user that has not yet been added:
ctm=controlm curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" --data "@runasUserDefinition.json" -X POST "$endpoint/config/server/$ctm/runasuser/realAgent/user1/test
For this test, the REST API command specifies the agent and user, and the configuration file contains only the authentication details (either a password or a key and passphrase). The path to the configuration file is prefixed with an @ character.
config server:runasusers::get
Retrieves details about all "run as" users that match a specified search criteria.
CLI Syntax
>ctm config server:runasusers::get <ctm> [-s <query string>]
Where:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<query string> | A string to search for, with the following format: "field1=criteria1&field2=criteria2" You can include the following fields in the query string:
For example: |
REST API Syntax
See REST API reference.
Example using curl:
ctm=controlm
curl -H "Authorization: Bearer $token" "$endpoint/config/server/$ctm/runasusers?agent=agent1&user=user1"
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:
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
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:
Parameter | Description |
---|---|
<paramName> | The system parameter defined in the Control-M/Enterprise Manager, one of the following supported system parameters:
|
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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"
Config Authorization
Config authorization enables you to manage the authorizations of users, roles, and LDAP groups, limiting their access to various Control-M entities and actions.
Configuration of authorizations is available in a Control-M environment with Control-M/Enterprise Manager version 9.0.19.000 or later.
The following table summarizes the actions that you can take for each authorization entity:
Role | User | LDAP Group |
---|---|---|
Tip
The following videos demonstrate how to manage authorizations:
https://youtu.be/ooVUsgws570 — Managing roles and authorizations
https://youtu.be/gxZ9coj48M0 — Creating users and assigning roles to users and LDAP groups
config authorization:role::add
Creates a new role based on role settings that you define through a role data file.
CLI Syntax
>ctm config authorization:role::add <roleFile>
Where <roleFile> is the full path and name of a .json payload file that contains role definitions, as described in Role data for authorization configuration.
If annotation is enabled for the Account management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -F "roleFile=@roleDefinition.json"
-X POST $endpoint/config/authorization/role
config authorization:role::get
Retrieves the details of an existing role, as defined in the role data file.
Note: Only parameters that are set to non-default values are retrieved and displayed in the output.
CLI Syntax
>ctm config authorization:role::get <role>
Where <role> is the name of the role.
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
curl -H "Authorization: Bearer $token"
"$endpoint/config/authorization/role/$roleName"
config authorization:role::update
Updates the definitions of an existing role based on role settings that you define through a role data file.
Note
Besides applying all settings that are explicitly defined in the role data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
- Obtain ALL current role settings by running the config authorization:role::get command.
- Use the output from the previous step to create your role data file, a .json file.
- In the role data file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all role settings, see Role data for authorization configuration. - Proceed with running the Update command.
CLI Syntax
>ctm config authorization:role::update <role> <roleFile>
Where:
Parameter | Description |
---|---|
<role> | Name of the role that you want to update |
<roleFile> | Full path and name of a .json payload file that contains role definitions, as described in Role data for authorization configuration |
If annotation is enabled for the Account management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
curl -H "Authorization: Bearer $token" -F "roleFile=@roleDefinition.json"
-X POST "$endpoint/config/authorization/role/$roleName"
config authorization:role::delete
Deletes an existing role and disassociates all users who were associated with the role.
CLI Syntax
>ctm config authorization:role::delete <role>
Where <role> is the name of the role.
If annotation is enabled for the Account management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/authorization/role/$roleName"
config authorization:roles::get
Retrieves a list of names of configured roles.
CLI Syntax
>ctm config authorization:roles::get [-s <search query>]
The optional -s switch can be used to filter for roles by role name or description (or both). The format for the query string is "field1=criteria1&field2=criteria2", according to the following guidelines:
Fields | Criteria | Examples |
---|---|---|
|
|
|
If you include multiple fields in the query, separate them with an ampersand (&). |
REST API Syntax
See REST API reference.
Example using curl:
roleName=Adm*
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/roles?role=$roleName
config authorization:user::add
Creates a new user based on user settings that you define through a user data file.
CLI Syntax
>ctm config authorization:user::add <userFile>
Where <userFile> is the full path and name of a .json payload file that contains user definitions, as described in User data for authorization configuration.
If annotation is enabled for the Account management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" -F "userFile=@userDefinition.json"
-X POST $endpoint/config/authorization/user
config authorization:user::get
Retrieves the details of an existing user, as defined in the user data file.
Note:
- Only parameters that are set to non-default values are retrieved and displayed in the output.
- For security reasons, the user's password is returned as KEEP_EXISTING. When you use the output from this command to prepare a user data file (a .json file) for the Update command, you can keep this value in the user data file.
CLI Syntax
>ctm config authorization:user::get <user>
Where <user> is the name of the user.
REST API Syntax
See REST API reference.
Example using curl:
userName=myUser
curl -H "Authorization: Bearer $token"
"$endpoint/config/authorization/user/$userName"
config authorization:user::update
Updates the definitions of an existing user based on user settings that you define through a user data file.
Note
Besides applying all settings that are explicitly defined in the user data file, the Update process also sets all remaining settings to default values. Therefore, as a best practice, perform the following sequence of steps:
- Obtain ALL current user settings by running the config authorization:user::get command.
- Use the output from the previous step to create your user data file, a .json file.
- In the user data file, change the specific settings that you want to update, and keep all other content in the file.
For full details about all user settings, see User data for authorization configuration. - Proceed with running the Update command.
CLI Syntax
>ctm config authorization:user::update <user> <userFile>
Where:
Parameter | Description |
---|---|
<user> | Name of the user that you want to update |
<userFile> | Full path and name of a .json payload file that contains user definitions, as described in User data for authorization configuration |
If annotation is enabled for the Account management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
userName=myuser
curl -H "Authorization: Bearer $token" -F "userFile=@userDefinition.json"
-X POST "$endpoint/config/authorization/user/$userName"
config authorization:user::delete
Deletes an existing user and disassociates it from all roles with which it was associated.
CLI Syntax
>ctm config authorization:user::delete <user>
Where <user> is the name of the user.
If annotation is enabled for the Account management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
Example using curl:
userName=myuser
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/config/authorization/user/$userName"
config authorization:users::get
Retrieves a list of names of configured users.
CLI Syntax
>ctm config authorization:users::get [-s <search query>]
The optional -s switch can be used to filter for users by user name, full name of user, or description (or any combination of these fields). The format for the query string is "field1=criteria1&field2=criteria2", according to the following guidelines:
Fields | Criteria | Examples |
---|---|---|
|
|
|
If you include multiple fields in the query, separate them with an ampersand (&). |
REST API Syntax
See REST API reference.
Example using curl:
userName=emuser*
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/users?name=$userName
config authorization:user:role::add
Assigns a role to a user.
CLI Syntax
>ctm config authorization:user:role::add <user> <role>
Where:
Parameter | Description |
---|---|
<user> | Name of user |
<role> | Name of role |
REST API Syntax
See REST API reference.
Example using curl:
userName=myuser
roleName=myRole
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X POST "$endpoint/config/authorization/user/$userName/role/$roleName"
config authorization:user:role::delete
Removes a role from a user.
CLI Syntax
>ctm config authorization:user:role::delete <user> <role>
Where:
Parameter | Description |
---|---|
<user> | Name of user |
<role> | Name of role |
REST API Syntax
See REST API reference.
Example using curl:
userName=myuser
roleName=myRole
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X DELETE "$endpoint/config/authorization/user/$userName/role/$roleName"
config user:password::adminUpdate
Changes the password for a user.
CLI Syntax
>ctm config user:password::adminUpdate <user> [newPassword] [-p]
Where:
Parameter | Description |
---|---|
<user> | Name of user whose password you want to change |
[newPassword] | A new password for the user, either of the following:
|
The newPassword parameter is optional because you can, alternatively, use the -p
(or -prompt
) option through the CLI. With this option, you do not need to enter the password in the command. Instead, you are prompted for the password (twice) after you enter the command. Note that if you use both the newPassword parameter and the -p
option, the password that you enter through the command prompt overrides the password that you specify in the command.
REST API Syntax
See REST API reference.
When using a REST API command, you must provide the password (or secret) in a payload .json file. In the following curl example, note that the path to the payload file is prefixed with an @ character.
userName=myuser
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-d "@c:\tmp\data.json" -X POST "$endpoint/config/user/$userName/password/adminUpdate"
Here is an example of the contents of a payload .json file, with the password specified as a predefined secret:
{
"newPassword":"Secret:secretKey"
}
config authorization:ldap:role::add
Adds a role to an LDAP group, so that any user in the LDAP group will inherit the permissions and authorizations defined for the role.
CLI Syntax
>ctm config authorization:ldap:role::add <ldapGroup> <role>
Where:
Parameter | Description |
---|---|
<ldapGroup> | Name of LDAP group |
<role> | Name of role |
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
ldapGroup=myGroup
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X POST "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"
config authorization:ldap:role::delete
Deletes a role from an LDAP group.
CLI Syntax
>ctm config authorization:ldap:role::delete <ldapGroup> <role>
Where:
Parameter | Description |
---|---|
<ldapGroup> | Name of LDAP group |
<role> | Name of role |
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
ldapGroup=myGroup
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X DELETE "$endpoint/config/authorization/ldap/$ldapGroup/role/$roleName"
config authorization:ldap:roles::get
Retrieves a list of roles that are associated with a specific LDAP group.
CLI Syntax
>ctm config authorization:ldap:roles::get <ldapGroup> [-s "role=<query pattern>"]
Where:
Parameter | Description |
---|---|
<ldapGroup> | Name of LDAP group |
<query pattern> | (Optional) A pattern for filtering role names. The pattern contains a wildcard (* or ?). For multiple patterns in the same query, use commas. |
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
ldapGroup=myGroup
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/ldap/$ldapGroup/roles?role=$roleName
config authorization:role:associates
Retrieves a list of all users and LDAP groups to which a specific role is associated.
CLI Syntax
>ctm config authorization:role:associates <role>
Where <role> is the name of the role.
REST API Syntax
See REST API reference.
Example using curl:
roleName=myRole
curl -H "Authorization: Bearer $token"
$endpoint/config/authorization/role/$roleName/associates
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>
Parameter | Description |
---|---|
<name> | Name of the secret |
<value> | Value of the secret |
If annotation is enabled for the Scheduling definitions category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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>
Parameter | Description |
---|---|
<name> | Name of the secret |
If annotation is enabled for the Scheduling definitions category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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>
Parameter | Description |
---|---|
<name> | Name of the secret |
<value> | New value of secret |
If annotation is enabled for the Scheduling definitions category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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"
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]
Parameter | Description |
---|---|
<definitionsFile> | The definitions file name Valid file formats are:
|
[deployDescriptorFile] | (Optional) The file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy Descriptor. |
If annotation is enabled for the Scheduling definitions, Configuration management, or Control-M security category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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>
Parameter | Description |
---|---|
format | The format in which to return the output, one of the following:
|
-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:
Field | Criteria | Criteria example |
---|---|---|
|
| ctm=*&folder=* ctm=*&folder=Auto* ctm=workbench&folder=AutomationAPISampleFlow |
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:
Field | Criteria | Criteria example |
---|---|---|
|
| ctm=workbench&agent=agent&type=Database |
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>
Parameter | Description |
---|---|
<ctm> | Name of Control-M/Server |
<agent> | Host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent |
<type> | Type of connection profile, one of the following:
|
<name> | Name of the connection profile |
If annotation is enabled for the Control-M security category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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>
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<folderName> | Name of the folder to delete |
If annotation is enabled for the Scheduling definitions category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
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:
Parameter | Description |
---|---|
<definitionsFile> | The file or archive that contains code for jobs. Valid formats are:
|
<deployDescriptorFile> | The file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy Descriptor. |
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"
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.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm package <zipOutputFilename> <deploymentFilesDirectory>
Parameter | Description |
---|---|
<zipOutputFilename> | The filename of package |
<deploymentFilesDirectory> | The directory where the source files reside Valid file formats are:
|
The Provision Service
For Control-M to run and monitor jobs on your application host, a Control-M/Server and Control-M/Agent should be installed. The Provision service allows you access to the full cycle of the following setup processes for agents and servers:
- Provisioning a new installation of a new Control-M/Agent, including the option of deploying application plug-ins to the Agent during provisioning
- Upgrading an existing Control-M/Agent and deploying certain plug-ins to an existing Agent
- Provisioning a Control-M/Server, either as a new server or by transferring an existing Control-M/Server from one machine to another (server rehydration)
Provisioning a new Control-M/Agent
For a new installation, 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 with the base installation of Control-M Automation 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.
provision 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:
Parameter | Description |
---|---|
<os> | OS can be one of the following:
|
Here is an example of requesting a list of available images and a typical response:
>ctm provision images Linux -e devEnvironment
[
"Agent.Linux",
"Agent_18.Linux",
"ApplicationsAgent.Linux",
"BigDataAgent.Linux",
"Server.Linux"
]
REST API Syntax
Example using curl:
os=Linux
curl -H "Authorization: Bearer $token" $endpoint/provision/images/$os
provision image
Downloads an image and prepares it for installation.
In the case of an Agent image, this command also installs the image into the current user account, but does not configure it or register it with a Control-M/Server.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm provision image <image>
Where:
Parameter | Description |
---|---|
<image> | The image that you want to prepare for installation, one of the images returned by the provision images command |
provision agent::setup
Connects and registers an image with a Control-M environment.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm provision agent::setup [ctm] [name] [port] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
[ctm] | The agent registers to this Control-M/Server. If omitted or empty and only one Control-M/Server exists in the system, it will be selected. |
[name] | The host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. If omitted or empty, the machine's name will be used. |
[port] | This port is used as the Control-M/Agent listening TCP/IP port. If omitted or empty, an available free port will be used. |
[configuration file] | (Optional) JSON file that contains additional parameters. |
The following is a list of the additional parameters that can be used in the configuration file:
{
"connectionInitiator": "AgentToServer"
}
Where:
connectionInitiator | The component that initiates the connection between the Control-M/Agent and Control-M/Server. The values supported are:
|
For example:
provision agent::setup
provision agent::setup "" "" 2056
provision agent::setup "controlm1" "" 2056
provision agent::setup "" "alias1" 2056
provision agent::setup -f persistent.json
provision agent::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.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm provision agent::install <image> [ctm] [name] [port] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<image> | The image that you want to install (one of the images returned by the provision images command) |
[ctm] | The agent registers to this Control-M/Server. If omitted or empty and only one Control-M/Server exists in the system, it will be selected. |
[name] | The host name or alias of the Control-M/Agent. This is the logical name of the Control-M/Agent. If omitted or empty, the machine's name will be used. |
[port] | This port is used as the Control-M/Agent listening TCP/IP port. If omitted or empty, an available free port will be used. |
[configuration file] | (Optional) JSON file that contains additional parameters. |
The following is a list of the additional parameters that can be used in the configuration file:
{
"connectionInitiator": "AgentToServer"
}
Where:
Parameter | Description |
---|---|
connectionInitiator | The component that initiates the connection between the Control-M/Agent and Control-M/Server. The values supported are:
|
provision image::remove
Uninstalls a Control-M image from this user account without unregistering it in Control-M.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm provision image::remove
provision agent::uninstall
Uninstalls a Control-M image from this user account and unregisters it from the Control-M/Server.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm provision agent::uninstall
Upgrading an existing Control-M/Agent
You can use API commands to perform various upgrade activities on existing Control-M/Agents, including agent upgrades and plug-in deployments. The following table lists the various activities that you can perform using the provision upgrade
group of API commands:
Control-M/Agent | Control-M Managed File Transfer (MFT) | Control-M Application Pack | |
---|---|---|---|
Upgrade to a new version | |||
Roll back to a previous version | |||
Install new plug-in on existing Agent | NA | ||
Remove plug-in from Agent | NA |
To prepare for provisioning, you must obtain the Control-M/Agent installation packages that you plan to use in your upgrades and place them in the <EM_HOME>/AUTO_DEPLOY directory. You must also ensure that the <EM_HOME>/CM_DEPLOY directory contains packages that are available for deployment, from your installations of Control-M MFT and Control-M Application Pack. For more information about preparing the packages, see the Control-M Administrator Guide in the Control-M Online Help.
The Provision service offers the following commands for upgrade processes:
Command | Description |
---|---|
provision upgrades:versions::get | Obtains a list of upgrades that are available, based on the installation packages that you have in your directories. |
provision upgrades:agents::get | Obtains a list of agents in your environment that are eligible for an upgrade. |
provision upgrade::install | Transfers a deployment package and installs it. |
provision upgrade::uninstall | Rollls back an upgrade deployment package at the target Control-M/Agent. |
provision upgrade::get | Obtains status details for a specific upgrade activity. |
provision upgrades::get | Obtains status details for all upgrade activities or for multiple upgrade activities based on specified filters. |
provision upgrade:output::get | Retrieves output log messages from the Control-M/Agent regarding a specific upgrade activity. |
provision upgrade::retry | Retries to run an upgrade activity that failed previously. |
provision upgrade::delete | Deletes the record of an upgrade activity that has finished running. |
provision upgrade::cancel | Aborts an upgrade activity that is currently running. |
provision upgrades:versions::get
Obtains a list of upgrades that are available, based on the installation packages that are currently stored in your directories — Control-M/Agent packages in <EM_HOME>/AUTO_DEPLOY, Control-M MFT and Control-M Application Pack packages in <EM_HOME>/CM_DEPLOY.
CLI Syntax
>ctm provision upgrades:versions::get
REST API Syntax
See REST API reference.
curl -H "Authorization: Bearer $token" $endpoint/provision/upgrades/versions
Response
The response lists all available upgrades according to type (Agent, MFT, or AppPack) and target version, as in the following example:
[
{
"type": "Agent",
"version": "9.0.18.200"
},{
"type": "AppPack",
"version": "9.0.18.100"
},{
"type": "MFT",
"version": "9.0.18.100"
}
]
provision upgrades:agents::get
Obtains a list of agents in your environment that are eligible for upgrade using any of the packages that are found in your directories. You can optionally limit the list to upgrades of a certain type (Agent, MFT, or AppPack) and target version.
CLI Syntax
>ctm provision upgrades:agents::get [-s <query string>]
Where <query string> can contain one or both of the following fields:
Field | Values |
---|---|
type | Agent, MFT, or AppPack |
version | Target version to which you want to upgrade For example: 9.0.00, 9.0.00.100, 9.0.18.000, or 9.0.18.200 |
The following example command will return details for agents that can be upgraded to version 9.0.18.200:
>ctm provision upgrades:agents::get -s "type=Agent&version=9.0.18.200"
The following example command will return details for agents on which Control-M MFT can be deployed (installed or upgraded):
>ctm provision upgrades:agents::get -s "type=MFT"
REST API Syntax
See REST API reference.
curl -H "Authorization: Bearer $token"
"$endpoint/provision/upgrades/agents?type=Agent&version=9.0.18.000"
Response
The response provides details for each agent and each possible upgrade that can be performed on it. In the following example, one agent was found eligible for upgrade from version 9.0.00 to version 9.0.18.100. The same agent was found eligible for installation of Control-M MFT version 9.0.18.000 (which is currently not installed).
[
{
"agent": "vw-one-ae65",
"ctm": "vw-one-ae65",
"type": "Agent",
"platform": "windows_x86_64",
"fromVersion": "9.0.00",
"toVersion": "9.0.18.100"
},{
"agent": "vw-tlv-one-ae65",
"ctm": "vw-tlv-one-ae65",
"type": "MFT",
"platform": "windows_x86_64",
"fromVersion": "",
"toVersion": "9.0.18.000"
}
]
provision upgrade::install
Transfers a deployment package to the agent host and installs it there. Use this API command to perform any of the following activities:
- Upgrade a Control-M/Agent to a newer version
- Install a new plug-in (Control-M MFT or Control Application Pack) on an existing Agent
- Upgrade a plug-in (Control-M MFT or Control Application Pack) on the Agent
CLI Syntax
>ctm provision upgrade::install <ctm> <agent> <type> <version> [activityName] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent |
<type> | Type of upgrade — Agent, MFT, or AppPack |
<version> | Target version to which to upgrade |
[activityName] | (Optional) A name for this upgrade activity. If you do not specify an activity name, the default activity name is "<ctm>, <agent>, <type>". |
[configuration file] | Full path to a JSON file that contains installation details For more details about this configuration file, see Configuration file for provision upgrade or rollback. |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
In the following curl example, note that the path to the configuration file is prefixed with an @ character.
curl -H "Authorization: Bearer $token"
-H "Content-Type:application/json" --data "@installConfigurationFile.json"
-X POST $endpoint/provision/upgrade/install
Configuration file for provision upgrade or rollback
You need a configuration file in the following scenarios:
- If you are using a REST API command, use the configuration file to specify values for the various upgrade parameters or rollback parameters (which can be included in a CLI command). These parameters include several required parameters (ctm, agent, type, and version) and the optional activityName.
To specify values for the following additional parameters. These parameters cannot be included in the CLI command:
Parameter Description installUser The user account used to perform the installation of the package. This parameter is required if all of the following conditions exist:
- The Control-M/Agent is hosted on a Windows computer.
- The Control-M/Agent is currently at a version earlier than 9.0.00.300 (version 9.0.00, fix pack 3).
- The Control-M/Agent's security setting "Logon as User" is set to Yes. For more information, see Security parameters in the Control-M Online Help.
In all other cases, the user is set automatically, and any value that you set through this parameter is ignored.
NOTE: Due to JSON character escaping, if the user name includes a backslash, each backslash must be doubled (for example, "domain\\userName").
notifyAddress A list of email addresses of recipients of notifications regarding this upgrade or rollback process. Use the semicolon character (;) to separate multiple email addresses.
description A description for the upgrade activity.
The following sample configuration file contains all possible parameters (including the optional parameters and the parameters that you could alternatively set through the CLI command):
{
"ctm": "localControlM",
"agent": "agent1",
"type": "Agent",
"version": "9.0.18.100",
"activityName": "Agent1 upgrade for localControlM",
"installUser": "user3",
"notifyAddress": "joe@example.com;jane@example.com",
"description": "Upgrading the agent to version 9.0.18.100"
}
Response
The installation package is deployed and installed, and an upgradeID is returned. The upgradeID has the following format: <ctm>:<activityNumber> (for example, LocalControlM:12)
provision upgrade::uninstall
Uninstalls an upgrade deployment package at the target Control-M/Agent. Use this API command to perform any of the following activities:
- Roll back the newest version of a Control-M/Agent
- Roll back the newest version of a plug-in (Control-M MFT or Control Application Pack)
- Remove the Control-M MFT plug-in from the Agent (if no previous version was installed)
CLI Syntax
>ctm provision upgrade::uninstall <ctm> <agent> <type> <version> [activityName] [-f <configuration file>]
Where:
Parameter | Description |
---|---|
<ctm> | Name of the Control-M/Server |
<agent> | Name of host or alias of the Control-M/Agent |
<type> | Type of upgrade that you are uninstalling — Agent, MFT, or AppPack |
<version> | Version to uninstall |
[activityName] | (Optional) A name for this upgrade activity. If you do not specify an activity name, the default activity name is "<ctm>, <agent>, <type>". |
[configuration file] | Full path to a JSON file that contains uninstallation details For more details about this configuration file, see Configuration file for provision upgrade or rollback. |
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
In the following curl example, note that the path to the configuration file is prefixed with an @ character.
curl -H "Authorization: Bearer $token"
-H "Content-Type:application/json" --data "@installConfigurationFile.json"
-X POST $endpoint/provision/upgrade/uninstall
Response
The installation package is uninstalled, and an upgradeID is returned. The upgradeID has the following format: <ctm>:<activityNumber> (for example, LocalControlM:12)
provision upgrade::get
Obtains status details for a specific upgrade activity.
The response provides the status of the upgrade activity, as well as various additional details (such as UTC timestamps of certain phases during the upgrade activity).
CLI Syntax
>ctm provision upgrade::get <upgradeID>
Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).
REST API Syntax
See REST API reference.
upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID"
provision upgrades::get
Obtains status details for all upgrade activities or for multiple upgrade activities based on specified filters.
The response provides the status of each upgrade activity, as well as various additional details (such as timestamps of certain phases during the upgrade activity).
CLI Syntax
>ctm provision upgrades::get [-s <query string>]
Where <query string> can contain any of the following fields.
Note: For multiple values, use commas. As wildcards, you can use question mark and asterisk characters (? and *).
Field | Description |
---|---|
ctm | Name of the Control-M/Server |
agent | Name of host or alias of the Control-M/Agent |
fromVersion | Source version (before the upgrade activity was performed) For example: 9.0.00.100 |
toVersion | Target version For example: 9.0.18.200 |
acivity | Type of upgrade activity, either Install or Uninstall |
status | Status of the activity; one of the following:
|
activityName | Name of the upgrade activity |
The following example command will return status details for upgrades or rollbacks to version 9.0.18 and its fix packs on Agent1 and Agent2:
>ctm provision upgrades::get -s "agent=Agent1,Agent2&toVersion=9.0.18*"
REST API Syntax
See REST API reference.
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrades?agent=Agent2&toVersion=9.0.18*"
provision upgrade:output::get
Retrieves output log messages from the Control-M/Agent regarding a specific upgrade activity. The output log messages are displayed on-screen.
CLI Syntax
>ctm provision upgrade:output::get <upgradeID>
Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).
REST API Syntax
See REST API reference.
upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID/output"
provision upgrade::retry
Retries to run an upgrade activity that failed previously.
Note: The original upgrade activity was already assigned an upgradeID, and the retry activity does not create a new one. The response only returns a message that the retry has started.
CLI Syntax
>ctm provision upgrade::retry <upgradeID>
Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" "$endpoint/provision/upgrade/$upgradeID/retry"
provision upgrade::delete
Deletes the record of an upgrade activity that has finished running (that is, an upgrade activity in status Completed, Cancelled, or Failed).
CLI Syntax
>ctm provision upgrade::delete <upgradeID>
Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" -X DELETE $endpoint/provision/upgrade/$upgradeID
provision upgrade::cancel
Aborts an upgrade activity that is currently running (that is, an upgrade activity in status Running or TransferCompleted).
CLI Syntax
>ctm provision upgrade::cancel <upgradeID>
Where <upgradeID> is the ID returned by the upgrade activity (install or uninstall).
If annotation is enabled for the Configuration management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.
REST API Syntax
See REST API reference.
upgradeID="ctm1:3"
curl -H "Authorization: Bearer $token" -X POST $endpoint/provision/upgrade/$upgradeID/cancel
Provisioning a Control-M/Server
Provisioning of a Control-M/Server is supported on Windows with an MS SQL database and on Linux with an Oracle database. You can create a new Control-M/Server or you can transfer an existing Control-M/Server from one machine to another (server rehydration).
When provisioning a Control-M/Server you can choose betwen running two separate commands or one command:
Method | Typical scenario | Commands |
---|---|---|
Two separate commands | Dynamic installation: An image (such as a VM image) is prepared with the Control-M/Server ready inside it. Setup is performed at a later time, when required. | |
One command | A more static architecture, with no distinction between building an image and instantiation. |
|
An additional command is available for uninstalling a Control-M/Server from the host machine.
Setup or installation of a Control-M/Server is based on settings that you define in a configuration file (a payload JSON file). For the full description of this configuration file, see Server Provisioning configuration.
The images used during provisioning are JSON code too. Each image contains a list of installation packages in the order that they are installed. Default images are provided with the base installation of Control-M Automation API, and you can create additional custom images (for example, for installation of a newer version of the Control-M/Server). 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.
Note
Image-related commands are used to manage images of both Control-M/Agents and Control-M/Servers. For details of these commands see their descriptions above:
- provision images — list all existing images
- provision image — download and prepare an image
- provision image::remove — remove an image from the user account
provision server::setup
Installs a Control-M/Server and registers it in the Control-M environment.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm provision server::setup -f <configuration file>
Where:
Parameter | Description |
---|---|
<configuration file> | JSON file that contains Control-M/Server definitions. For the full description of this configuration file, see Server Provisioning configuration. |
provision server::install
Combines the image and the setup commands into one action. Downloads the Control-M/Server, installs it, and registers it in the Control-M environment.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm provision server::install <image> -f <configuration file>
Where:
Parameter | Description |
---|---|
<image> | The image that you want to install (one of the images returned by the provision images command) |
<configuration file> | JSON file that contains Control-M/Server definitions. For the full description of this configuration file, see Server Provisioning configuration. |
provision server::uninstall
Uninstalls a Control-M/Server from this user account and unregisters it from the Control-M environment.
Note: This functionality is supported only through the CLI, and cannot be called through a REST API command.
CLI Syntax
>ctm provision server::uninstall [ctm]
Where:
Parameter | Description |
---|---|
ctm | For a Linux machine that has multiple Control-M/Servers installed: Name of the Control-M/Server |
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>"}
environment show
Returns a list of all defined environments.
CLI Syntax
>ctm environment show
environment add
Adds a new environment for a Control-M instance.
CLI Syntax
>ctm environment add <env> <endPoint> <user> <password>
Where:
Parameter | Description |
---|---|
<env> | Environment name |
<endPoint> | Control-M REST API endPoint |
<user> | Control-M username Note: If you specify an LDAP user, prefix the username with the domain: <domain>\<user> |
<password> | Control-M password |
environment workbench::add
Adds an environment for the installed Control-M Workbench.
CLI Syntax
>ctm environment workbench::add [<endPoint>]
Where:
Parameter | Description |
---|---|
[<endPoint>] | REST API endPoint for the Control-M Workbench. By default, the Workbench endpoint is https://localhost:8443/automation-api, with "workbench" as the user name and password. You can use this parameter if you installed the Workbench on a different host. |
environment 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.
Note
When no environments are defined and you add the very first environment (using the environment add or the environment workbench::add command), that first environment is automatically set as the default. Later, after additional environments have been defined, use this command to set a new default.
CLI Syntax
>ctm environment set <env>
Where:
Parameter | Description |
---|---|
<env> | Environment name |
environment delete
Deletes an environment.
CLI Syntax
>ctm environment delete <env>
Where:
Parameter | Description |
---|---|
<env> | Environment name |
environment 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:
Parameter | Description |
---|---|
<env> | Environment name |
<name> | Can be one of the following:
For more information about these properties, see environment add. |
<value> | Parameter value |
environment copy
Duplicates an environment.
CLI Syntax
>ctm environment <env> <newEnv>
Where:
Parameter | Description |
---|---|
<env> | Environment name |
<newEnv> | Name of the new environment |
environment 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:
Parameter | Description |
---|---|
<enviromentsFile> | An env.json file |
environment configure
This command allows you to set parameters for all environments.
CLI Syntax
>ctm environment configure <setting name> [setting value]
Where:
Parameter | Description |
---|---|
<setting name> | Parameter name |
[setting value] | Parameter value |
Possible parameters:
Parameter | Value | Default | Description |
---|---|---|---|
rootCertificateRequired | false | true | false | Disable API calls that use a self-signed HTTPS certificate, and allow only certificates that are signed by a trusted Certificate Authority. By default, self-signed certificates are allowed. |
The Reporting Service
The Reporting service enables you to generate reports that were set up through Control-M Reports. You can generate reports either synchronously or asynchronously.
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.
Synchronous report generation (reporting report::get)
The reporting report::get
command enables you to generate a report synchronously. In the command, you specify the name of the report, as set up in Control-M Reports. For the report format, you can choose between a CSV file or a PDF file. In the command response, you receive a URL for accessing the report through a browser. You can also choose to download the report to a file.
CLI Syntax
>ctm reporting report::get <report_name> [format] [-o <file_path>]
Where:
Parameter | Description |
---|---|
<report_name> | Name of the Control-M report NOTE: The report name that you specify cannot contain special characters. For example, if the name of the report contains a space character, use %20 in the API command, instead of the space character. If the report is shared, add |
[format] | (Optional) The format of the report, either csv or pdf Default value: csv |
<file_path> | (Optional) The full path to the file that you want to create, if you want to download the report to a file |
The following example shows a typical CLI command and response:
>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'
Note
The REST API command for synchronous generation of reports has been deprecated in this version:
curl -H "Authorization: Bearer $token" $endpoint/reporting/report/$report_name?format=pdf
Use the REST API commands for asynchronous generation of reports instead (reporting/report and then reporting/status/$reportID).
Asynchronous report generation (reporting report)
The reporting report
command enables you to send a request to generate a report asynchronously. In the command, you specify the name of the report, as set up in Control-M Reports. For the report format, you can choose between a CSV file or a PDF file.
The command response provides a summary of basic report statistics and generation status, including a report ID that you can use to check the status of asynchronous report generation (using the reporting status::get command).
CLI Syntax
>ctm reporting report <report_name> [format]
Where:
Parameter | Description |
---|---|
<report_name> | Name of the Control-M report NOTE: The report name that you specify cannot contain special characters. For example, if the name of the report contains a space character, use %20 in the API command, instead of the space character. If the report is shared, add |
[format] | (Optional) The format of the report, either csv or pdf Default value: csv |
The following example shows a typical CLI command and response:
>ctm reporting report Alerts_1 pdf
{
"reportId": "52ddeded-7234-4ec3-8588-945db0f961c0",
"name": "Alerts_1",
"format": "pdf",
"status": "PROCESSING",
"url": ""
}
REST API Syntax
See REST API reference.
Example using curl:
curl -H "Authorization: Bearer $token" \
-H "Content-Type: application/json" \
-X POST -d "{"name": "Alerts_1", "format": "pdf"}" \
"$endpoint/reporting/report"
Get report status (reporting status::get)
The reporting status::get
command enables you to check the status of report generation for a report that you requested asynchronously (using the reporting report command). You identify the report by specifying its report ID.
The command response provides a summary of basic report statistics and generation status. If report generation has completed successfully, you receive a URL for downloading the report.
CLI Syntax
>ctm reporting status::get <reportID>
Where <reportID> is the report ID that you received when you requested asynchronous generation of the report using the the reporting report command.
The following example shows a typical CLI command and response:
>ctm reporting status::get 52ddeded-7234-4ec3-8588-945db0f961c0
{
"reportId": "52ddeded-7234-4ec3-8588-945db0f961c0",
"name": "Alerts_1",
"format": "pdf",
"status": "SUCCEEDED",
"url": "http://server1:18080/RF-Server-Files/52ddeded-7234-4ec3-8588-945db0f961c0.pdf"
}
REST API Syntax
See REST API reference.
Example using curl:
reportID="52ddeded-7234-4ec3-8588-945db0f961c0"
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" \
-X GET "$endpoint/reporting/status/$reportID"
After receiving the URL for the report, you 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 APIcurl -H "Authorization:Bearer $token" -O $dowload_url
The -o option downloads the report to a directory and file that you specify.
REST APIcurl -H "Authorization:Bearer $token" -o $report_path $dowload_url
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. In addition, the Session service allows users to change their own password.
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": "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7",
"version": "9.18.1"
}
>ctm config servers::get -t "E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7"
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>
Field | Description |
---|---|
<token> | The token obtained by the session login request |
Example using curl:
endpoint=https://<controlmEndPointHost>:8443/automation-api
token=E14A4F8E45406977B31A1B091E5E04237D81C91B47AA1CE0F3FFAE252AEFE63ADE182E5702F5A9131A2DA0A8E8AE76D7C3CCBA0B7
curl -g -k -H "Authorization: Bearer $token" -X POST "$endpoint/session/logout"
session user:password::update
Enables a user to change his or her own password.
CLI Syntax
>ctm session user:password::update [currentPassword] [newPassword] [-p]
Where:
Parameter | Description |
---|---|
[currentPassword] | The user's current password, either of the following:
|
[newPassword] | A new password for the user, either of the following:
|
The password parameters are optional because you can, alternatively, use the -p
(or -prompt
) option through the CLI. With this option, you do not need to enter passwords in the command. Instead, after you enter the command, you are prompted for the current password and (twice) for the new password. Note that if you use both the password parameters and the -p
option, the passwords that you enter through the command prompt override the passwords that you specify in the command.
REST API Syntax
See REST API reference.
When using a REST API command, you must provide your user name and passwords (or secrets) in a payload .json file. In the following curl example, note that the path to the payload file is prefixed with an @ character.
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-d "@data.json" -X POST "$endpoint/session/user/password/update"
Here is an example of the contents of a payload .json file, with the current password specified as text and the new password as a predefined secret:
{
"user":"user1",
"currentPassword":"********",
"newPassword":"Secret:secretKey"
}
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:
Method | Description |
---|---|
CLI command | Include the For example:
|
REST API command | Use the For example:
|
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.
Level of help | CLI command |
---|---|
Main Help page for all services | One of the following:
|
Specific service | One of the following:
|
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 , 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
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
}
]
}
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"
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:
Comments
Log in or register to comment.