The Run service enables you to run jobs and track their status, as well as manage several other types of objects used by jobs.

Job Management

Use the Run service to manage your jobs and perform various job actions, as well as track job status and view job output and logs. 

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

CLI Syntax

CLI

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

CLI Syntax

CLI

ctm run order <ctm> <folder> [jobs] [z/OS library] [-f <configuration file>]

Where:

Parameter	Description
<ctm>	Control-M/Server
<folder>	Folder name that is ordered
[jobs]	The jobs that you want to run: For most types of jobs, this parameter is optional. The default (when not defined) is all jobs in the specified folder. You can specify a single job or use the asterisk * wildcard to specify multiple jobs. For a z/OS job, specify either a single job or * for all jobs in the folder.
[z/OS library]	For a z/OS job : The name of the z/OS library that contains the jobs For example: CTMP.V900.SCHEDULE
[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	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: (Default) New: insert jobs into a new folder Recent: insert jobs into a recent folder <Folder Order ID>: insert jobs into a selected folder.  Alone: insert the jobs into a regular folder. If this option is selected, createDuplicate (the previous parameter) is not relevant. 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" 

Here is another example for ordering a z/OS job using curl:

endpoint=
token=
ctm=M90CTM
folderName=
jobName=IOATEST
library=CTMP.V900.SCHEDULE
curl -X POST -H "Authorization: Bearer $token" --header "Content-Type: application/json" --header "Accept: application/json" -d "{ \"ctm\": \"$ctm\", \"folder\": \"$folderName\", \"jobs\": \"$jobName\", \"library\": \"$library\", \"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 invoked by the same user.
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 SLA Management is installed 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 SLA Management is installed in your environment.

_{Back to top}

run jobs:status::get

This 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

CLI

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 jobid folder folderLibrary ctm application subApplication host hostGroup description runAs command filePath fileName workloadPolicy ruleBasedCalender resourceMutex resourceSemaphore	Supported wildcards are *, ? To use multiple criteria separate by using comma Wildcards are not supported for jobid jobid=<ctm>:<orderId>	jobname=job1122 jobname=job11* jobname=job11*,job77* description=*a job that* jobid=controlm:005gy
orderDateFrom orderDateTo fromTime toTime	For orderDateFrom and orderDateTo: YYMMDD For fromTime and toTime: YYYYMMDDhhmmss	orderDateFrom=180123 fromTime=20180123184500
status	Ended OK Ended Not OK Wait User Wait Resource Wait Host Wait Workload Wait Condition Executing Status Unknown To use multiple criteria, separate criteria with commas.	status=Ended OK status=Ended OK, Ended Not OK,Executing
neighborhood	Returns the status according to the dependencies between jobs. To create dependencies between jobs, use the flow object. direction, with the following possible values: depend - the jobs that depend on the specified job predecessor - the jobs that the specified job depends on radial - the jobs from both directions depth - the number of job levels from the specified job	"neighborhood&jobid =controlm:0a98&depth=1&direction=predecessor"

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

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 The following list includes valid job statuses: Ended OK Ended Not OK Wait User Wait Resource Wait Host Wait Workload Wait Condition Executing Status Unknown
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 SLA Management is installed 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 SLA Management is installed 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

_{Back to top}

run job:output::get

This command allows you to view the output from job runs. 

CLI Syntax

CLI

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"

_{Back to top}

run job:log::get

This command allows you to view the job log. 

CLI Syntax

CLI

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"

_{Back to top}

run job:status::get

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

CLI Syntax

CLI

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

For information about the response to this API command and descriptions of the job properties in this response, see the description of the run jobs:status::get response.

REST API Syntax

See REST API reference.

Example using  curl:

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

_{Back to top}

run job:statistics::get

9.0.20.000 This command returns time statistics for the recent runs of a job.

CLI Syntax

CLI

ctm run job:statistics::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 response provides time statistics for each job run (order date, start and end time, run time, and CPU time), as well as an average of the key time statistics from all runs. If periodic statistics are collected for this job, job run statistics are presented for each period separately.

Note that the job ID returned for each job run is a unique serial number assigned to the job run by the Control-M/Server. It differs from the job ID specified in the input.

The following example response contains data from two job runs. No periods were defined for data collection from the job in this example.

{ "periods": [ { "runInfo": { "averageInfo": { "startTime": "07:35:53", "cpuTime": "00:00:00", "runTime": "00:00:01" }, "runs": [ { "startTime": "06/02/2020 07:39:00", "endTime": "06/02/2020 07:39:00", "cpuTime": "00:00:00", "runTime": "00:00:01", "jobId": "75", "orderDate": "06/02/2020" }, { "startTime": "06/02/2020 07:38:00", "endTime": "06/02/2020 07:38:00", "cpuTime": "00:00:00", "runTime": "00:00:01", "jobId": "2", "orderDate": "06/02/2020" } ] } } ]
}

REST API Syntax

See REST API reference.

Example using  curl:

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

_{Back to top}

run job::kill

This command allows you to terminate the job.

CLI Syntax

CLI

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"

_{Back to top}

run job::runNow

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

CLI Syntax

CLI

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"

_{Back to top}

run job::hold 

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

CLI Syntax

CLI

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"

_{Back to top}

run job::free 

This command allows you to continue job run from hold state.

CLI Syntax

CLI

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"

_{Back to top}

run job::delete 

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

CLI Syntax

CLI

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"

_{Back to top}

run job::undelete 

This command allows you to remove a mark for deletion from a job.

CLI Syntax

CLI

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"

_{Back to top}

run job::confirm 

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

CLI Syntax

CLI

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"

_{Back to top}

run job::setToOk 

This 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

CLI

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"

_{Back to top}

run job::rerun

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

CLI Syntax

CLI

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"

_{Back to top}

run job::waitingInfo

This command displays the reasons why a waiting job has not yet been executed (for example: missing conditions, resources, hosts, users, or workloads).

CLI Syntax

CLI

ctm run job::waitingInfo <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>.

REST API Syntax

See REST API reference.

Example using  curl:

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

_{Back to top}

run job::get

This command returns the definitions of a running job in JSON format.

For a description of the returned job format, see Code Reference.

CLI Syntax

CLI

ctm run job::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 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 GET "$endpoint/run/job/$jobId/get"

_{Back to top}

run job::modify

 This command enables you to modify the definitions of a running job that is currently held (that is, a job for which processing has been stopped), based on job definitions that you define through a Job Definitions file.

Currently, you can modify running jobs of the following types:

• Command
• Script

• EmbeddedScript

• FileTransfer
• Informatica

CLI Syntax

CLI

ctm run job::modify <jobDefinitionsFile> <jobId> 

Where: 

Parameter	Description
<jobDefinitionsFile>	A JSON file that contains the details of a single job, including the properties that you want to modify. For a description of the syntax of the JSON code in this file, see Code Reference and all its child pages. Note that this JSON file contains details of only a single job. Do not include other object types (such as folder or connection profile) in this JSON file. Note: The following job properties currently do NOT support the Modify action: Host RerunSpecificTimes RunAsDummy RetroactiveOrder In addition, under the When parameter, only FromTime and ToTime support the Modify action.
<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 -F "jobDefinitionsFile=@examples/InformaticaJob.json" "$endpoint/run/job/$jobId/modify"

_{Back to top}

Resource Management

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

run resource::add

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

CLI Syntax

CLI

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

CLI

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

CLI

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 resources command allows you to get all resource records from a specific Control-M/Server.

CLI Syntax

CLI

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

Search examples

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

_{Back to top}

Event Management

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

run event::add

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

CLI Syntax

CLI

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: MMDD - specific date ODAT - represents the current Control-M date. For example, if the current Control-M date is August 7th, 2016, the ODAT converts to 0807. STAT - can be used instead of a specific date for an event that is not date specific

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

CLI

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: MMDD - specific date ODAT - represents the current Control-M date. For example, if the current Control-M date is August 7th, 2016, the ODAT converts to 0807. STAT - can be used instead of a specific date for an event that is not date specific

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

CLI

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)

Search examples

-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

CLI

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

CLI

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

CLI

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"

_{Back to top}

Service Management

9.0.19.230Services are groups of jobs that are aggregated based on criteria that you specify. Control-M Automation API can help you manage SLA services that are associated with SLA jobs (also known as Control-M BIM jobs) at the end of a job flow. Service Management in Control-M Automation API is supported for a Control-M environment with Control-M/EM version 9.0.18.200 or later.

run services:sla::get

Retrieves details of defined SLA-type services.

For more information, see Service Monitor in the Control-M Online Help.

CLI Syntax

CLI

ctm run services:sla::get

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -H "Content-Type: application/json"
-X GET "$endpoint/run/services/sla"

Response

The following example shows the parameters in the response to the ctm run services:sla::get command. This example lists just one SLA-type service.

{ "serviceLastUpdatedTime": "2020-01-26T10:19:42+00:00", "activeServices": [ { "serviceName": "SLA-BAD", "status": "Not Ok", "statusReason": "Service late,Job failure,Service actually late", "startTime": "2020-02-09T10:08:10+00:00", "endTime": "2020-02-09T10:14:20+00:00", "dueTime": "2020-02-09T08:00:05+00:00", "slackTime": "-02:14:15", "serviceOrderDateTime": "2020-02-09T07:00:05+00:00", "scheduledOrderDate": "20200209", "serviceJob": "LocalControlM:0002c", "serviceControlM": "LocalControlM", "priority": "3", "note": "", "totalJobs": "3", "jobsCompleted": "1", "jobsWithoutStatistics": "1", "completionPercentage": "33", "averageCompletionTime": "", "errors": "Job \"FindFile\" ended with failure.\nJob \"SLA-Bad\" should have started by 08:00:05 GMT+00:00 and will not start on time. The reason is: \"SLA-Bad\" is waiting for Wait Condition.", "statusByJobs": { "executed": "0", "waitCondition": "2", "waitResource": "0", "waitHost": "0", "waitWorkload": "0", "completed": "0", "error": "1" } } ]
}

In this response, serviceLastUpdatedTime specifies the most recent date and time when the services were updated. After that, for each active SLA-type service, the following parameters are displayed:

Parameter	Description
serviceName	Name of service
status	Current status of the service
statusReason	One or more reasons for the current status
startTime	Date and time when the service started to run
endTime	Date and time for when the service is estimated to stop running
dueTime	Deadline date and time by which the service must complete to be considered not late
slackTime	Difference in time between the dueTime and its estimated endTime
serviceOrderDateTime	Date and time when the service was ordered
scheduledOrderDate	Order date if rescheduled during the order
serviceJob	Job ID of the job associated with the service
serviceControlM	Control-M/Server where the service runs
priority	Priority level of the service
note	Specific service information entered as a note for the service
totalJobs	The total number of jobs in the service
jobsCompleted	The number of jobs in the service that completed
jobsWithoutStatistics	The number of jobs without statistic information
completionPercentage	Percentage of jobs in the service that completed
averageCompletionTime	An estimate of the length of time that the service will require to complete
errors	Error messages received for the jobs in the service
statusByJobs	A breakdown of how many jobs finished in each job status

_{Back to top}