Run Service
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
The following API commands enable you to manage your jobs, perform various job actions, track job status, and view job output and logs:
run
The run command enables you to run jobs on the Control-M environment. The command returns a runId, which you can use to check job status with the run status command.
The following example shows a typical command and response. The build action 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"
}To get the job status using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.
CLI Syntax
ctm run <jobDefinitionsFile> [deployDescriptorFile]The following table describes the run command parameters.
|
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 definitions file. 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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST -F "jobDefinitionsFile=@examples/AutomationAPISampleFlow.json" -F "deployDescriptorFile=@examples/deployDescriptor.json" "$endpoint/run"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run order
The run order command enables you to run deployed jobs on the Control-M environment. The command returns a runId, which you can use to check job status with the run status command. 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"
}To get the job status using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.
CLI Syntax
ctm run order <ctm> <folder> [jobs] [z/OS library] [-f <configuration file>]The following table describes the run order command parameters.
|
Parameter |
Description |
|---|---|
|
<ctm> |
Control-M/Server name |
|
<folder> |
Folder name that is ordered |
|
[jobs] |
The jobs that you want to run:
|
|
[z/OS library] |
For a z/OS job : The name of the z/OS library that contains the jobs 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. The variables that you specify can be local For more information, see Variables. |
|
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 placeInFolder (next parameter) is set to Recent or to a specific Order ID. Values: true|false Default: true |
|
placeInFolder |
Determines how to order jobs or Sub Folders that
belong to a Jobs and Sub Folders are added to a
Default: New 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",
"placeInFolder": "Recent",
"orderDate": "20170903",
"waitForOrderDate": "false",
"hold": "true"
}REST API Syntax
cURL:
endpoint=
token=
ctm=
folderName=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -X POST -H "$AuthHeader" --header "Content-Type: application/json" --header "Accept: application/json" -d "{
\"ctm\": \"$ctm\",
\"folder\": \"$folderName\",
\"hold\": \"true\",
\"ignoreCriteria\": \"true\",
\"orderDate\": \"20170903\",
\"waitForOrderDate\": \"false\",
\"placeInFolder\": \"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
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -X POST -H "$AuthHeader" --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\",
\"placeInFolder\": \"Recent\",
\"variables\": [{\"arg\":\"12345\"}]
}" "$endpoint/run/order"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run userDaily:missing::list
The run userDaily:missing::list command enables you to generate a list of jobs that were not ordered because a specific Order Method (that is, a specific User Daily job) was interrupted for any reason (for example, an operating system crash).
This command requires Control-M/EM version 9.0.21.200 or later.
The command returns a poll ID that you can use to view the list, using the run userDaily:missing::poll command. Below is a typical command and response.
> ctm run userDaily:missing::list myUserDaily controlm
{
"pollId": "f9f9667e-8037-45c9-bd00-36eaa4b812c8",
"statusURI": "http://localhost:32080/run/orderMethod/myUserDaily/missing/listf9f9667e-8037-45c9-bd00-36eaa4b812c8"
}To view the list using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.
CLI Syntax
ctm run userDaily:missing::list <userDaily> <server>The following table describes the run userDaily:missing::list command parameters.
|
Parameter |
Description |
|---|---|
|
<userDaily> |
Defines the name of the User Daily job. |
|
<server> |
Defines the Control-M/Server name. |
REST API Syntax
cURL:
server=controlm
userDaily=myUserDaily
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/userDaily/$userDaily/missing/list/$server"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run userDaily:missing::poll
The run userDaily:missing::poll command enables you view a previously generated list of jobs that were not ordered because a specific Order Method (that is, a specific User Daily job) was interrupted for any reason (for example, an operating system crash).
This command requires Control-M/EM version 9.0.21.200 or later.
CLI Syntax
ctm run userDaily:missing::poll <pollId>Where <pollID> is the poll ID returned by therun userDaily:missing::list command.
REST API Syntax
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/userDaily/missing/poll/$pollId"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Response
The following example response lists two unordered jobs and another two unordered jobs that changed after the User Daily job ran.
{
"jobs": [
{
"folderName": "Folder_1",
"jobName": "Job_1"
},
{
"folderName": "Folder_2",
"jobName": "Job_2"
}
],
"jobsChangedAfterUserDailyRun": [
{
"folderName": "Folder_3",
"jobName": "Job_3"
},
{
"folderName": "Folder_4",
"jobName": "Job_4"
}
]
}You can reorder the jobs that did not yet run using the run userDaily:missing::poll command.
run userDaily:missing::run
The run userDaily:missing::run command enables you reorder the jobs that did not run because a specific Order Method (that is, a specific User Daily job) was interrupted for any reason (for example, an operating system crash).
This command requires Control-M/EM version 9.0.21.200 or later.
The command returns a runId, which you can use to check job status with the run status command. Below is a typical command and response.
> ctm run userDaily:missing::run myUserDaily
{
"runId": "2143811-e253-4c3f-8c21-72bd7957bb53",
"statusURI": "http://localhost:32080/run/status/2143811-e253-4c3f-8c21-72bd7957bb53"
}To get the job status using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.
CLI Syntax
ctm run userDaily:missing::run <orderMethod>Where <userDaily> is the name of the User Daily job.
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
cURL:
userDaily=myUserDaily
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -X POST -H "$AuthHeader" "$endpoint/run/userDaily/$userDaily/missing/run"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run ondemand
The run ondemand command enables you execute jobs immediately, without deploying them to the Control-M/EM database and without requiring the User Daily job in Control-M to trigger them. This approach can be useful for event-driven job executions.
This command requires Control-M/EM version 9.0.21.200 or later.
-
You cannot use the deploy jobs::get command to retrieve details for such jobs, as they are not deployed to the database.
-
Such jobs cannot be scheduled, as the User Daily job is not involved. Scheduling information is ignored.
A build process takes place as part of the run.
The response returns a runID and statusURI (similar to the run and run order commands). You can use the returned runId to check job status with the run status command.
To get the job status using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.
CLI Syntax
ctm run ondemand <definitionsFile> [deployDescriptorFile]The following table describes the run ondemand command parameters.
|
Parameter |
Description |
|---|---|
|
<jobDefinitionsFile> |
The file or archive that contains code for folders and jobs. Files must be in JSON format. Only Job, Folder, and Defaults objects in the definitions file are processed. Other object types, such as connection profiles or Site Standards, are not supported. If included in the definitions file, they are ignored. Scheduling properties are also ignored. |
|
[deployDescriptorFile] |
(Optional) The file that includes the rules to apply on the original definitions file. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy Descriptor. |
REST API Syntax
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST -F "definitionsFile=@definitions.json" -F "deployDescriptorFile=@deployDescriptor.json" "$endpoint/run/ondemand"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run status
The run status command enables you to track the status of running jobs. The following command shows how to check job status using the runId.
CLI Syntax
ctm run status <runId> [startIndex]The following table describes the run status command parameters.
|
Parameter |
Description |
|---|---|
|
<runId> |
Value returned in a 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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/status/$runId"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Response
The following example shows the parameters in the run status response.
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"
{
"completion": "Completed",
"statuses": [
{
"jobId": "controlm:00fhb",
"folderId": "controlm:005gy",
"numberOfRuns": 3,
"name": "AutomationAPISampleFlow",
"type": "Folder",
"status": "Executing",
"held": "false",
"deleted": "false",
"cyclic": "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",
"cyclic": "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",
"cyclic": "false",
"startTime": "",
"endTime": "",
"estimatedStartTime": [],
"estimatedEndTime": [],
"outputURI": "Job didn't run, it has no output"
}
],
"startIndex": 0,
"itemsPerPage": 25
}The following table describes additional run status command parameters.
|
Parameter |
Description |
|---|---|
|
completion |
Whether the job has run — Completed | Pending. If "Pending", you can run the run status command again until value is "Completed". |
|
jobId |
A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. Format: <server>:<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. |
|
cyclic |
Whether the job is defined as a cyclic job — 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. |
|
outputURI |
URI to the job output. To get the job output using the outputURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens. |
run jobs:status::get
The run jobs:status::get command enables you to track running jobs that match a search query.
CLI Syntax
ctm run jobs:status::get [limit] -s "<query string>"The following table describes the run jobs:status::get command parameters.
|
Parameter |
Description |
|---|---|
|
limit |
Determines the maximum number of job statuses to return. Range of values: 1–10000 Default: 1000 |
-s is used to run a search using the query string format "field1=criteria1&field2=criteria2".
|
Field |
Criteria |
Criteria Examples |
|---|---|---|
|
The server field was previously named ctm (deprecated name). |
jobname=job1122 jobname=job11* jobname=job11*,job77* description=*a job that* jobid=controlm:005gy
|
|
|
orderDateFrom=180123 fromTime=20180123184500 |
|
historyRunDate |
|
historyRunDate=231127 historyRunDate=Yesterday |
|
status |
To use multiple criteria, separate criteria with commas. |
status=Ended OK status=Ended OK, Ended Not OK,Executing |
|
true | false |
"held=true&folderHeld=true&cyclic=false&deleted=false" |
|
neighborhood |
Returns the status according to the dependencies between jobs. To create dependencies between jobs, use the Flow object.
|
"neighborhood&jobid=controlm:0a98&depth=1&direction=predecessor" |
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,ExecutingThe 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"REST API Syntax
Example of a curl request that includes a limit:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/jobs/status?jobname=jobA&status=Ended%20OK&application=A*&limit=5000"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
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,
"cyclic": "false",
"startTime": "20231126065554",
"endTime": "20231126065555",
"estimatedStartTime": ["20231126123810"],
"estimatedEndTime": ["20231126124310"],
"orderDate": "231125",
"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"
}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. Format: <server>:<orderId> |
|
folderId |
A unique identifier of the folder to which the job belongs. Format: <server>:<orderId> |
|
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. |
|
cyclic |
Whether the job is defined as a cyclic job — 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 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. To get the job output using the outputURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens. |
|
logURI |
URI to the job log. To get the job log using the logURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens. |
run job:output::get
The run jobs:output::get command enables you to view the output from job runs.
CLI Syntax
ctm run job:output::get <jobId> [runNo]The following table describes the run job:output::get command parameters.
|
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. Format: <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/job/$jobId/output?runNo=0"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job:log::get
The run job:log::get command enables you to the job log.
CLI Syntax
ctm run job:log::get <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/job/$jobId/log"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job:status::get
The run job:status::get command enables you to view a specific job run status.
CLI Syntax
ctm run job:status::get <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/job/$jobId/status"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job:statistics::get
The run job:statistics::get command enables you to get time statistics for the recent runs of a job.
CLI Syntax
ctm run job:statistics::get <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/job/$jobId/statistics"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::kill
The run job::kill command enables you to terminate the job.
CLI Syntax
ctm run job::kill <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/kill"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::runNow
The run job::runNow command enables you to immediately start the job. When you use this command, job constraints are not applied.
CLI Syntax
ctm run job::runNow <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/runNow"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::hold
The run job::hold command enables you to hold (that is, stop processing) the job.
CLI Syntax
ctm run job::hold <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/hold"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::free
The run job::free command enables you to continue job run from hold state.
CLI Syntax
ctm run job::free <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/free"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::delete
The run job::delete command enables 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 <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/delete"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::undelete
The run job::undelete command enables you to remove a mark for deletion from a job.
CLI Syntax
ctm run job::undelete <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/undelete"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::confirm
The run job::confirm command enables you to run a job that is waiting for confirmation.
CLI Syntax
ctm run job::confirm <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/confirm"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::setToOk
The run job::setToOk command enables 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 <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/setToOk"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::rerun
The run job::rerun command enables you to rerun a job (provided that it is not currently executing). When you use this command, the existing job constraints are applied.
CLI Syntax
ctm run job::rerun <jobId> [-f zosJobConfig.json]The following table describes the run job::rerun command parameters.
|
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 <server>:<orderId>. |
|
[zosJobConfig] |
z/OS job only: Full path and name of a JSON file that contains advanced restart parameters for Control-M/Restart. To rerun a z/OS job, the job must be in one of the following statuses:
|
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.
If you are rerunning a z/OS job, you can specify additional parameters through the configuration file:
{
"zosParameters": {
"from": {
"pgm": "INPROCS2",
"proc": "STEP1"
},
"to": {
"pgm": "INPROCS3",
"proc": "STEP2"
},
"cleanup": true,
"recaptureAbend": "Y",
"recaptureConditionCode": "N",
"stepAdjustment": true,
"restartParmMemberName": "IDJOB5"
}
}The configuration file for a z/OS job contains the following advance parameters:
|
Parameter |
Description |
||||||||
|---|---|---|---|---|---|---|---|---|---|
|
from, to |
Use the from and to parameters to limit job rerun to a range of steps. Define the starting point (under from) and the end point (under to) by specifying the program step (pgm) and (optionally) the procedure step (proc) at both points. To obtain a list of program steps, use the run job:output::get API command. The returned output includes a list of executed job steps, including those that completed successfully and those that failed. Example 1: In the following simple example, you want to restart from STEP2 until STEP3. The following table shows the from and to parameters in the configuration file, along with the corresponding JCL in z/OS (for illustration purposes).
In other Control-M products, the steps in the sample JCL are displayed in the following manner. Of the listed steps, only those in rows 002-003 are restarted. Copy
Example 2: In the following example, you want to restart from INPROCS2 of STEP1 until INPROCS3 of STEP2. The following table shows the from and to parameters in the configuration file, along with the corresponding JCL in z/OS (for illustration purposes).
In other Control-M products, the steps in the sample JCL are displayed in the following manner. Of the listed steps, only those in rows 002-006 are restarted. Copy
Note the following scenarios:
|
||||||||
|
cleanup |
Whether to perform data set cleanup, either true or false. If you set this parameter to true, all other parameters described here are not relevant and should NOT be included in the configuration file. |
||||||||
|
recaptureAbend |
Whether to save the abend codes from the original Job execution. Valid values:
|
||||||||
|
recaptureConditionCode |
Whether to save the condition codes from the original Job execution. Valid values:
|
||||||||
|
stepAdjustment |
Whether to enable automatic Step Adjustment. Valid values are true and false. The default is true. For more details about Step Adjustment, see the Control-M/Restart User Guide. |
||||||||
|
restartParmMemberName |
The name of the member that contains control parameters for the Job to restart (1-8 characters only). The default value is the member that contains the JCL of the Job. |
REST API Syntax
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/rerun"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
For a z/OS job, include the advanced parameters described above in the body of the REST request, using the -d (or --data) option.
run job::waitingInfo
The run job::waitingInfo command enables you to display the reasons why a waiting job has not yet been executed (for example: missing conditions, resources, hosts, users, or workloads).
CLI Syntax
ctm run job::waitingInfo <jobId>Where <jobId> is 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 <server>:<orderId>.
REST API Syntax
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" "$endpoint/run/job/$jobId/waitingInfo"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::get
The run job::get command enables you to return the definitions of a running job in JSON format.
For a description of the returned job format, see Code Reference.
CLI Syntax
ctm run job::get <jobId>Where <jobId> is 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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/run/job/$jobId/get"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run job::modify
The run job::modify 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
ctm run job::modify <jobDefinitionsFile> <jobId>The following table describes the run job::modify command parameters.
|
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. The following Job Properties currently do NOT support the Modify action:
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 <server>:<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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X POST -F "jobDefinitionsFile=@examples/InformaticaJob.json" "$endpoint/run/job/$jobId/modify"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Resource Management
A Resource Pool (previously known as 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 Resource Pool cannot run unless there are enough resources available.
The following API commands enable you to manage Resource Pools:
run resource::add
The run resource::add command enables you to add a Resource Pool to a Control-M/Server.
CLI Syntax
ctm run resource::add <server> <name> <max>The following table describes the run resource::add command parameters.
|
Parameter |
Description |
|---|---|
|
<server> |
Control-M/Server name. |
|
<name> |
Name of the resource. Maximum: 2,048 characters. |
|
<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
cURL:
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newResource\",
\"max\":5}" "$endpoint/run/resource/$server"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run resource::delete
The run resource::delete command enables you to delete a Resource Pool.
CLI Syntax
ctm run resource::delete <server> <name>The following table describes the run resource::delete command parameters.
|
Parameter |
Description |
|---|---|
|
<server> |
Control-M/Server name. |
|
<name> |
Name of the resource. Maximum: 2,048 characters. |
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
cURL:
server=controlm
name=newResource
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/run/resource/$server/$name"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run resource::update
The run resource::update command enables you to update the values of a Resource Pool.
CLI Syntax
ctm run resource::update <server> <name> <max>The following table describes the run resource::update command parameters.
|
Parameter |
Description |
|---|---|
|
<server> |
Control-M/Server name. |
|
<name> |
Name of the resource. Maximum: 2,048 characters. |
|
<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
cURL:
server=controlm
name=newResource
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST -d "{\"max\":6}" "$endpoint/run/resource/$server/$name"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run resources::get
The run resources::get command enables you to get all resource records from
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.
The following table describes the run resources::get command parameters.
|
Field |
Description |
|---|---|
|
server |
Control-M/Server name. This field was previously named ctm (deprecated name). |
|
name |
Name of the resource. Maximum: 2,048 characters. |
Here are several search examples:
-s "name=resourceA"
-s "name=A*"
-s "server=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"
},The following table describes additional run resource::add command parameters.
|
Parameter |
Description |
|---|---|
|
<ctm> |
Control-M/Server name. |
|
<name> |
Name of the resource. Maximum: 2,048 characters. |
|
<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 Workload Policy Definition. |
REST API Syntax
cURL:
search_criteria="name=A*&server=*"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/run/resources?$search_criteria"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Event Management
An event (previously known as a condition) is represented by a name and a date. Jobs that require an event cannot run unless the specific event exists, as described in Events. A job can add or delete an event.
The following API commands enable you to manage Events:
run event::add
The run event::add command enables you to add events to the Control-M/Server.
CLI Syntax
ctm run event::add <server> <name> <date>The following table describes the run event::add command parameters.
|
Parameter |
Description |
|---|---|
|
<server> |
Control-M/Server name. |
|
<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
cURL:
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newEvent\",\"date\":\"0505\"}" "$endpoint/run/event/$server"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run event::delete
The run event::delete command enables you to remove an event.
CLI Syntax
ctm run event::delete <server> <name> <date>The following table describes the run event::delete command parameters.
|
Parameter |
Description |
|---|---|
|
<server> |
Control-M/Server name. |
|
<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
cURL:
server=controlm
name=newEvent
date=0505
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X DELETE "$endpoint/run/event/$server/$name/$date"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run events::get
The run events::get command enables 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.
The following table describes the run events::get fields.
|
Field |
Description |
|---|---|
|
server |
Control-M/Server name. This field was previously named ctm (deprecated name). |
|
name |
Name of the event. |
|
date |
Date of event. |
|
limit |
Limits the number of returned matches. Default: 1000 (if not defined) |
Here are several search examples:
-s "name=eventA"
-s "name=A*&date=0805"
-s "server=controlm&name=eventA,eventB&date=0805"REST API Syntax
cURL:
search_criteria="name=A*&server=controlm"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -X GET "$endpoint/run/events?$search_criteria"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
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. You can manage the definitions of Workload Policies through a JSON file (separate from the JSON file used to define jobs and other objects). For more information about defining Workload Policies, see Workload Policies Reference. For more general information about workload policies, see Workload Policy Definition.
The following API commands enable you to manage Workload Policies:
run workloadpolicies:detailed::get
Retrieves full details of all defined Workload Policies or a specific Workload Policy.
The response contains the full JSON details, as described in Workload Policies Reference.
CLI Syntax
ctm run workloadpolicies:detailed::get [-s "name=<policyName>"]The -s option can be used to query for a specific Workload Policy. If you do not include the -s option, details are returned for all defined Workload Policies.
REST API Syntax
Example using curl to retrieve definitions of all Workload Policies:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X GET "$endpoint/run/workloadpolicies/detailed"Example for retrieving the definitions of a specific Workload Policy:
policyname=WPtest
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X GET "$endpoint/run/workloadpolicies/detailed?name=$policyname"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run workloadpolicies::add
Creates new Workload Policies from definitions provided through a JSON file, as described in Workload Policies Reference.
CLI Syntax
ctm run workloadpolicies::add <workloadPoliciesFile>Where <workloadPoliciesFile> is the name of a JSON file that contains the definitions of the Workload Policies that you want to create. For more information, see Workload Policies Reference.
REST API Syntax
Example using curl:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-F "workloadpoliciesfile=@examples/WPs.json" -X POST "$endpoint/run/workloadpolicies"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run workloadpolicy::delete
Deletes a specific Workload Policy.
CLI Syntax
ctm run workloadpolicy::delete <policyName>Where <policyName> is the name of the specific Workload Policy that you want to delete.
REST API Syntax
Example using curl:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X DELETE "$endpoint/run/workloadpolicy/$policyname"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
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
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X GET "$endpoint/run/workloadpolicies?state=Active"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
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> [<server>]The following table describes the run workloadpolicy::activate command parameters.
|
Parameter |
Description |
|---|---|
|
[policyName] |
The name of a Workload Policy or, for multiple Workload Policies, a string that contains an asterisk as a wildcard. |
|
server |
(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
cURL:
policyname=WP*
server=LocalControlM
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/run/workloadpolicy/$policyname/activate?server=$server"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
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> [<server>]The following table describes the run workloadpolicy::deactivate command parameters.
|
Parameter |
Description |
|---|---|
|
[policyName] |
The name of a Workload Policy or, for multiple Workload Policies, a string that contains an asterisk as a wildcard. |
|
server |
(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/EM 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
cURL:
policyname=WP*
server=LocalControlM
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/run/workloadpolicy/$policyname/deactivate?server=$server"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Service Management
Service Management in Control-M Automation API is supported for a Control-M environment withControl-M/EM 9.0.18.200 or later.
The following API command enables you to manage services.
run services:sla::get
Retrieves details of defined SLA-type services.
For more information, see Service Management.
CLI Syntax
ctm run services:sla::getREST API Syntax
cURL:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X GET "$endpoint/run/services/sla"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
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. |
Variable Management
Variables enable the automatic assignment of dynamic environmental values to the execution parameters of a job.
Control-M Automation API can help you manage pool-type variables. Variables of this type are organized in hierarchical groups, and they are expressed in the following manner:
%%\\<named_pool>\<variable_name>
For more information about variables, see Variables.
The following API commands enable you to manage variables:
You must have Control-M/Server and Control-M/EM version 9.0.21 or later to run Variable Management commands.
run variables::get
The run variables::get command enables you to retrieve details of defined pool variables that match a search query.
CLI Syntax
ctm run variables::get -s "<query string>"-s is used to run a search using the query string format "field1=criteria1&field2=criteria2&field3=criteria3", with the following supported fields:
|
Field |
Description |
|---|---|
|
pool |
Name of the pool. Example: pool=Pool1 For wildcard matching, you can specify * in the named pool string. The * wildcard can be used as either the only character or the last character. Example: pool=* or pool=P* Default: * (all pools) |
|
variable |
Full name of the variable. Example: variable=Var1 For wildcard matching, you can specify * in the variable string. The * wildcard can be used as either the only character or the last character. Example: variable=* or variable=V* Default: * (all variables) |
|
server |
Control-M/Server name. The server field is required only if you have more than one Control-M/Server. In such a case, the * wildcard is not supported.
|
REST API Syntax
Note that in a RST API command, all backslashes must be escaped, as in the following curl example:
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X GET "$endpoint/run/variables?server=*&variable=%%\\\\P*\\V*"For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Response
The following example shows a response to the run variables::get command. Note that all backslashes are escaped in the JSON format.
{
"variables": [
{ "%%\\\\PoolName\\AUTOVar1InPoolAddedAudit": "value1" },
{ "%%\\\\PoolName\\AUTOVar2InPoolAddedAudit": "value2" }
]
}run variables::set
The run variables::set command enables you to define new pool variables or update the definitions of existing pool variables.
CLI Syntax
ctm run variables::set <server> -f <variablesDefinitionFile.json>The following table describes the run variables::set command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Control-M/Server name. |
|
variablesDefinitionFile |
Full path and name of a JSON file that contains definitions of variables, as in the following example: Copy
Note that all backslashes are escaped in the JSON format. |
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
cURL:
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/run/variables/$server" -d @VariablesDefinitions.jsonFor selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run variables::delete
The run variables::delete command enables you to delete variables from the server.
CLI Syntax
ctm run variables::delete <server> -f <variablesNames.jsonThe following table describes the run variables::delete command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Control-M/Server name. |
|
variablesNames |
Full path and name of a JSON file that contains a list of names of variables, as in the following example: Copy
Note that all backslashes are escaped in the JSON format. |
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
cURL:
server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X DELETE "$endpoint/run/variables/$server" -d @VariableNames.jsonFor selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
Alert Management
An alert is a message that indicates that a problem or exception has occurred for a Job or Folder. Control-M Automation API enables you to update basic properties of alerts, as well as the status of alerts. For more information, see Alerts.
The following API commands enable you to manage alerts:
run alerts::update
The run alerts::update command enables you to update basic properties of alerts, including the urgency of the alerts and the associated comments.
CLI Syntax
ctm run alerts::update -f <configuration file>The configuration file contains the properties required for updating the alerts. Note that besides the mandatory alertIds parameter, you must include at least one of the other parameters in the configuration file.
|
Parameter |
Description |
|---|---|
|
alertIds |
Unique identifiers for the alerts that you want to update. |
|
urgency |
Severity of the alert, one of the following (listed in ascending level of severity):
|
|
comment |
A free-text comment regarding the alert. |
Here is an example of a configuration file:
{
"alertIds" : [30,31],
"urgency":"Normal",
"comment":"update"
}REST API Syntax
Example using curl: In this example, the configuration file is named alertModifyValue.json.
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts" -d @alertModifyValue.jsonFor selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
run alerts:status::update
The run alerts:status::update command enables you to update the status of the alert.
CLI Syntax
ctm run alerts:status::update <alertIds> -f <configuration file>The configuration file contains the properties required for updating alert status.
|
Parameter |
Description |
|---|---|
|
alertIds |
Defines unique identifiers for the alerts that you want to update. |
|
status |
Determines one of the following alert statuses:
|
Here is an example of a configuration file:
{
"alertIds" : [20],
"status":"Reviewed"
}REST API Syntax
Example using curl: In this example, the configuration file is named alertModifyStatus.json.
endpoint=
alertIds=15,20
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token" #for a session token
curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts/status/$alertIds" -d @alertModifyStatus.jsonFor selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.
YouTube
Twitter
Facebook
LinkedIn