Run Service
The Run service enables you to run jobs and track their status, as well as manage several other types of objects for 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/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
The following shows the CLI syntax for the run command:
ctm run <jobDefinitionsFile> [deployDescriptorFile]
The following table describes the run command parameters.
|
Parameter |
Description |
|---|---|
|
jobDefinitionsFile |
Defines the file or archive that contains code for jobs. Files must be in JSON format. |
|
deployDescriptorFile |
(Optional) Defines the file that includes the rules to apply to 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 the
REST API Syntax
The following example shows the REST API syntax for the run command in cURL:
curl -H "x-api-key: $token" -X POST -F "jobDefinitionsFile=@examples/AutomationAPISampleFlow.json" -F "deployDescriptorFile=@examples/deployDescriptor.json" "$endpoint/run"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.
The following example shows a typical command and response.
> ctm run order IN01 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
The following shows the CLI syntax for the run order command:
ctm run order <ctm> <folder> [jobs] [-f <configuration file>]
The following table describes the run order command parameters.
|
Parameter |
Description |
|---|---|
|
ctm |
Defines Server name. |
|
folder |
Defines the folder name that is ordered. |
|
jobs |
(Optional) Defines the jobs that you want to run. You can specify a single job or use the * wildcard to specify multiple jobs. The default (when not defined) is all jobs in the specified folder. |
|
configuration file |
(Optional) Defines the JSON file that contains additional parameters. |
If annotation is enabled for the Active network category in the
The following table describes the parameters that you can specify in the configuration file:
|
Parameter |
Description |
|---|---|
|
variables |
Defines variables for the job run, expressed as name:value pairs. The variables that you specify can be local or folder variables. Named pool variables are not supported. For more information, see Variables. |
|
hold |
Determines whether to make changes to a job before it starts running. Valid Values:
Default: false |
|
ignoreCriteria |
Determines whether to run a job when it is ordered and ignore the scheduling criteria. Valid Values:
Default: true |
|
independentFlow |
Determines whether a flow in a folder is ordered uniquely. This parameter is not applicable to sub-folders. Valid Values:
Default: true |
|
orderDate |
Determines the current or future workday to schedule the job. The format is YYYYMMDD. Default: current |
|
waitForOrderDate |
Determines whether to wait for the defined order date to run a job. Valid Values:
Default: false |
|
createDuplicate |
Determines whether jobs or sub-folders with the same name that already exist in the folder are added to the SMART folder. This is relevant when the placeInFolder parameter is set to Recent or to a specific Order ID. Valid Values:
Default: true |
|
placeInFolder |
Determines how to order jobs or sub-folders that belong to a Folder. This is a mandatory parameter. Jobs and sub-folders are added to a Folder according to the Order Into Folder options. Valid Values:
Default: New If the job or sub-folder is inserted into an existing folder or sub-folder that is already complete, 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. |
The following 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
The following example shows the REST API syntax for the run order command in cURL:
endpoint=
token=
ctm=
folderName=
curl -X POST -H "x-api-key: $token" --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"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 (a specific User Daily job) was interrupted for various reasons, such as an operating system crash.
The command returns a poll ID to view the list with the run userDaily:missing::poll command.
The following is an example of 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"
}You must specify a valid token in the request header to view the list with the statusURI endpoint, as described in Authentication Tokens.
CLI Syntax
The following shows the CLI syntax for the run userDaily:missing::list command:
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 Server name. |
REST API Syntax
The following example shows the REST API syntax for the run userDaily:missing::list command in cURL:
server=controlm
userDaily=myUserDaily
curl -H "x-api-key: $token" "$endpoint/run/userDaily/$userDaily/missing/list/$server"run userDaily:missing::poll
The run userDaily:missing::poll command enables you to view a previously generated list of jobs that were not ordered because a specific Order Method (a specific User Daily job) was interrupted for various reasons, such as an operating system crash.
CLI Syntax
The following shows the CLI syntax for the run userDaily:missing::poll command:
ctm run userDaily:missing::poll <pollId>
where <pollID> is the poll ID returned by the run userDaily:missing::list command.
REST API Syntax
The following example shows the REST API syntax for the run userDaily:missing::poll command in cURL:
curl -H "x-api-key: $token" "$endpoint/run/userDaily/missing/poll/$pollId"Response
The following example shows a response that 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 pending jobs with the run userDaily:missing::poll command.
run userDaily:missing::run
The run userDaily:missing::run command enables you to reorder the jobs that did not run because a specific Order Method (a specific User Daily job) was interrupted for various reasons, such as an operating system crash.
The command returns a runId to check the job status with the run status command.
The following example is a typical command and response:
You must specify a valid token in the request header to get the job status with the statusURI endpoint, as described in Authentication Tokens.
CLI Syntax
The following shows the CLI syntax for the run userDaily:missing::run command:
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 the
REST API Syntax
The following example shows the REST API syntax for the run userDaily:missing::run command in cURL:
userDaily=myUserDaily
curl -X POST -H "x-api-key: $token" "$endpoint/run/userDaily/$userDaily/missing/run"run ondemand
The run ondemand command enables you to execute jobs immediately. You do not need to deploy the jobs to the Server database and the User Daily job does not need to trigger them. This command is useful for event-driven job executions.
-
You cannot use the deploy jobs::get command to retrieve details for these jobs since they are not deployed to the database.
-
You cannot schedule these jobs because the User Daily job does not trigger them. The system ignores the scheduling information.
A build process takes place as part of the run.
The response returns a runID and statusURI like the run and run order commands. The runId enables you to check the job status with the run status command.
You must specify a valid token in the request header to get the job status with the statusURI endpoint, as described in Authentication Tokens.
CLI Syntax
The following shows the CLI syntax for the run ondemand command:
ctm run ondemand <definitionsFile> [deployDescriptorFile]
The following table describes the run ondemand command parameters.
|
Parameter |
Description |
|---|---|
|
jobDefinitionsFile |
Defines the file or archive that contains code for folders and jobs. Files must be in JSON format. The system only processes Job, Folder, and Defaults objects in the definitions file. The system ignores other object types, such as connection profiles or Site Standards, and scheduling properties. |
|
deployDescriptorFile |
(Optional) Defines the file that includes the rules applied to the original definitions file. The rules enable you to transform Control-M JSON code properties. For detailed information, see Deploy Descriptor. |
REST API Syntax
The following example shows the REST API syntax for the run ondemand command in cURL:
curl -H "x-api-key: $token" -X POST -F "definitionsFile=@definitions.json" -F "deployDescriptorFile=@deployDescriptor.json" "$endpoint/run/ondemand"run status
The run status command enables you to track the status of running jobs. The command shows how to check the job status with the runId.
CLI Syntax
The following shows the CLI syntax for the run status command:
ctm run status <runId> [startIndex]
The following table describes the run status command parameters.
|
Parameter |
Description |
|---|---|
|
runId |
Defines the value returned in a run invocation. It enables job tracking during a specific run invoked by the same user. |
|
startIndex |
(Optional) Defines iterations over every status. The result includes itemsPerPage: 25 items from this index. Default: 0 |
REST API Syntax
The following example shows the REST API syntax for the run status command in cURL:
curl -H "x-api-key: $token" "$endpoint/run/status/$runId"Response
The following example shows the parameters in the run status response.
The system checks and returns the status of each job when there is more than one job in the flow.
> ctm run status "2d4af716-e31d-48ef-a434-16575303752d"
{
"completion": "Completed",
"statuses": [
{
"jobId": "IN01:00fhb",
"folderId": "IN01: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": "IN01:00fhc",
"folderId": "IN01: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": "IN01:00fhd",
"folderId": "IN01: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 the parameters in the run status response.
|
Parameter |
Description |
|---|---|
|
completion |
Determines whether the job ran. Valid Values:
If the value is Pending, you can run the run status command again until the value changes to Completed. |
|
jobId |
Defines a unique identifier to reference a specific job. The jobId is returned by the following command: ctm run status Format: <server>:<orderId> |
|
folderId |
Defines the folderId to reference a specific folder. |
|
numberOfRuns |
Determines the number of job runs. |
|
name |
Defines the name of a job. |
|
type |
Determines the job type. |
|
status |
Defines the job status. |
|
held |
Determines whether the job was held. Valid Values:
|
|
deleted |
Determines whether the job was deleted. Valid Values:
|
|
cyclic |
Determines whether the job is defined as a cyclic job. Valid Values:
|
|
startTime |
Defines the time when the job started. |
|
endTime |
Defines the time when the job ended. |
|
estimatedStartTime |
Defines the estimated date and time when the next job runs are expected to begin. The estimates are based on the run times of previous jobs. The maximum number of job runs is 50. You must have SLA Management installed in your environment. |
|
estimatedEndTime | see Annotation Input.
Defines the estimated date and time when the next job runs are expected to end. The estimates are based on the run times of previous job runs. The maximum number of job runs is 50. You must have SLA Management installed in your environment. |
|
outputURI |
Defines the URI for the job output. You must specify a valid token in the request header to get the job output with the outputURI endpoint, 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
The following shows the CLI syntax for the run jobs:status::get command:
ctm run jobs:status::get [limit] -s "<query string>"
where -s is used to run a search with the query string format "field1=criteria1&field2=criteria2".
The following table describes the run jobs:status::get command parameters.
|
Parameter |
Description |
|---|---|
|
limit |
Determines the maximum number of job statuses to return. Valid values: 1–10000 Default: 1000 |
The following table describes the query fields that you can use with -s.
|
Field |
Criteria |
Query Examples |
|---|---|---|
|
|
jobname=job1122 jobname=job11* jobname=job11*,job77* description=*a job that* jobid=IN01: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&cyclic=false |
|
neighborhood |
Returns the status according to the dependencies between jobs. The Flow object enables you to create dependencies between jobs.
|
"neighborhood&jobid=IN01:0a98 |
The following example shows a command to get job statuses with a search query:
ctm run jobs:status::get -s "jobname=Finance*&application=app1,app2&status=Ended OK,Ended Not OK,ExecutingThe following example shows a command to get job statuses of a job that has linked jobs:
ctm run jobs:status::get -s "neighborhood&jobid=IN01:0a98&depth=1&direction=predecessor"REST API Syntax
The following example shows the REST API syntax for the run jobs:status::get command that includes a limit in cURL:
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 run jobs:status::get command.
{
"jobId": "IN01:00008",
"folderId": "IN01: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": "IN01",
"description": "",
"host": "",
"application": "OsApp",
"subApplication": "",
"outputURI": "Job did not run, it has no output",
"logURI": "http://localhost:48080/run/job/IN01:00008/log"
}The following table describes the parameters in this sample response:
|
Parameter |
Description |
|---|---|
|
jobId |
Defines a unique identifier to reference a specific job. The jobId is returned by the following command: ctm run status Format: <server>:<orderId> |
|
folderId |
Defines a unique identifier of the folder with the job. Format: <server>:<orderId> |
|
numberOfRuns |
Defines the number of job runs. |
|
name |
Defines the name of the job. |
|
folder |
Defines the name of the folder with the job. |
|
type |
Defines a job type. |
|
status |
Determines the job status. Valid Values:
|
|
held |
Determines whether the job was held. Valid Values:
|
|
deleted |
Determines whether the job was deleted. Valid Values:
|
|
cyclic |
Determines whether the job is defined as a cyclic job. Valid Values:
|
|
startTime |
Defines the time when the job started. |
|
endTime |
Defines the time when the job ended. |
|
estimatedStartTime |
Defines the estimated date and time when the next job runs are expected to begin. The estimates are based on the run times of previous jobs. The maximum number of job runs is 50. You must have SLA Management installed in your environment. |
|
estimatedEndTime |
Defines the estimated date and time when the next job runs are expected to end. The estimates are based on the run times of previous jobs. The maximum number of job runs is 50. You must have SLA Management installed in your environment. |
|
orderDate |
Defines the scheduled workday for the job in YYMMDD format. |
|
ctm |
Defines the Server name. |
|
description |
Defines a text-based description of the job, as defined during job creation. |
|
host |
Defines the host of the Agent where the job is running. |
|
application |
Defines the name of an application associated with the job. An application is a logical set of related jobs. |
|
subApplication |
Defines the name of a sub-application associated with the job. A sub-application is a logical sub-category of an application. A group of payroll-related jobs are logically grouped together in a sub-application named Payroll, within an application named Finances. |
|
outputURI |
Defines the URI to the job output. You must specify a valid token in the request header to get the job output with the outputURI endpoint, as described in Authentication Tokens. |
|
logURI |
Defines the URI to the job log. You must specify a valid token in the request header to get the job log with the logURI endpoint, 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
The following shows the CLI syntax for the run jobs:output::get command:
ctm run job:output::get <jobId> [runNo]
The following table describes the run job:output::get command parameters.
|
Parameter |
Description |
|---|---|
|
jobId |
Defines a unique identifier to reference a specific job. The jobId is returned by the following command: ctm run status Format: <server>:<orderId>. |
|
runNo |
(Optional) Defines the run number of the job to get the output. If the run number is not defined, the default is the last run. |
If annotation is enabled for the AJF get job information category in the
REST API Syntax
The following example shows the REST API syntax for the run jobs:output::get command in cURL:
curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/output?runNo=0"run job:log::get
The run job:log::get command enables you to access the job log.
CLI Syntax
The following shows the CLI syntax for the run job:log::get command:
ctm run job:log::get <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the AJF get job information category in the
REST API Syntax
The following example shows the REST API syntax for the run job:log::get command in cURL:
curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/log"run job:status::get
The run job:status::get command enables you to view a specific job run status.
CLI Syntax
The following shows the CLI syntax for the run job:status::getcommand:
ctm run job:status::get <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
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
The following example shows the REST API syntax for the run job:status::get command in cURL:
curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/status"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
The following shows the CLI syntax for the run job:statistics::get command:
ctm run job:statistics::get <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
Response
The response provides the following time statistics for each job run:
-
Order date
-
Start and end time
-
Run time
-
CPU time
-
Average of the key time statistics from all runs
If the system collects periodic statistics for this job, it presents job run statistics separately for each period.
The jobId returned for each job run is a unique serial number assigned to the job run by the Server. It differs from the jobId specified in the input.
The following is a response example with data from two job runs. There are no periods 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
The following example shows the REST API syntax for the run job:statistics::get command in cURL:
curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/statistics"run job::kill
The run job::kill command enables you to terminate the job.
CLI Syntax
The following shows the CLI syntax for the run job::kill command:
ctm run job::kill <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::kill command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/kill"run job::runNow
The run job::runNow command enables you to immediately start the job. The system does not apply job constraints when you use this command.
CLI Syntax
The following shows the CLI syntax for the run job::runNow command:
ctm run job::runNow <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::runNow command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/runNow"run job::hold
The run job::hold command enables you to hold the job and stop processing it.
CLI Syntax
The following shows the CLI syntax for the run job::hold command:
ctm run job::hold <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::hold command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/hold"run job::free
The run job::free command enables you to continue the job run from the hold state.
CLI Syntax
The following shows the CLI syntax for the run job::free command:
ctm run job::free <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::free command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/free"run job::delete
The run job::delete command enables you to mark the job for deletion. The system deletes the job on the next scheduled date.
CLI Syntax
The following shows the CLI syntax for the run job::delete command:
ctm run job::delete <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::delete command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/delete"run job::undelete
The run job::undelete command enables you to remove a deletion mark from a job.
CLI Syntax
The following shows the CLI syntax for the run job::undelete command:
ctm run job::undelete <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::undelete command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/undelete"run job::confirm
The run job::confirm command enables you to run a job that is waiting for confirmation.
CLI Syntax
The following shows the CLI syntax for the run job::confirm command:
ctm run job::confirm <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::confirm command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/confirm"run job::setToOk
The run job::setToOk command enables you to set job status to OK after the job is processed. You can use this command, for example, after you resolve issues that cause a job to end in status Not OK.
CLI Syntax
The following shows the CLI syntax for the run job::setToOk command:
ctm run job::setToOk <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::setToOk command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/setToOk"run job::rerun
The run job::rerun command enables you to rerun a job that it is not currently in execution. The system applies existing job constraints when you use this command.
CLI Syntax
The following shows the CLI syntax for the run job::rerun command:
ctm run job::rerun <jobId>
The following table describes the run job::rerun command parameters.
|
Parameter |
Description |
|---|---|
|
jobId |
Defines a unique identifier to reference the specific job. The jobId is returned by the following command: ctm run status Format: <server>:<orderId> |
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::rerun command in cURL:
curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/rerun"run job::waitingInfo
The run job::waitingInfo command enables you to display the reasons why a waiting job was not yet executed
CLI Syntax
The following shows the CLI syntax for the run job::waitingInfo command:
ctm run job::waitingInfo <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
REST API Syntax
The following example shows the REST API syntax for the run job::waitingInfo command in cURL:
curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/waitingInfo"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
The following shows the CLI syntax for the run job::get command:
ctm run job::get <jobId>
where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:
ctm run status
The format of this ID is <server>:<orderId>.
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::get command in cURL:
curl -H "x-api-key: $token" -X GET "$endpoint/run/job/$jobId/get"run job::modify
The run job::modify command enables you to modify the definitions of a running job that is currently held and the processing is stopped, based on job definitions in a Job Definitions file.
Currently, you can modify the following types of running jobs:
-
Command
-
Script
-
EmbeddedScript
-
FileTransfer
-
Informatica
CLI Syntax
The following shows the CLI syntax for the run job::modify command:
ctm run job::modify <jobDefinitionsFile> <jobId>
The following table describes the run job::modify command parameters.
|
Parameter |
Description |
|---|---|
|
jobDefinitionsFile |
Defines a JSON file that contains the details of a single job with 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 a 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 |
Defines a unique identifier to reference the specific job. The jobId is returned by the following command: ctm run status The format of this ID is <server>:<orderId>. |
If annotation is enabled for the Active network category in the
REST API Syntax
The following example shows the REST API syntax for the run job::modify command in cURL:
curl -H "x-api-key: $token" -X POST -F "jobDefinitionsFile=@examples/InformaticaJob.json" "$endpoint/run/job/$jobId/modify"Resource Management
A Resource Pool is represented by the name of a resource and the maximum amount 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 Server.
CLI Syntax
The following shows the CLI syntax for the run resource::add command:
ctm run resource::add <server> <name> <max>
The following table describes the run resource::add command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Defines the Server name. |
|
name |
Defines the resource. The maximum number of characters is 2,048 characters. |
|
max |
Determines the maximum quantity of resources available. Valid values: 0-9999 |
If annotation is enabled for the Independent AJF entities category in the
REST API Syntax
The following example shows the REST API syntax for the run resource::add command in cURL:
server=controlm
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newResource\",
\"max\":5}" "$endpoint/run/resource/$server"run resource::delete
The run resource::delete command enables you to delete a Resource Pool.
CLI Syntax
The following shows the CLI syntax for the run resource::delete command:
ctm run resource::delete <server> <name>
The following table describes the run resource::delete command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Defines the Server name. |
|
name |
Defines the resource name. The maximum number of characters is 2,048. |
If annotation is enabled for the Independent AJF entities category in the
REST API Syntax
The following example shows the REST API syntax for the run resource::delete command in cURL:
server=controlm
name=newResource
curl -H "x-api-key: $token" -X DELETE "$endpoint/run/resource/$server/$name"run resource::update
The run resource::update command enables you to update the values of a Resource Pool.
CLI Syntax
The following shows the CLI syntax for the run resource::update command:
ctm run resource::update <server> <name> <max>
The following table describes the run resource::update command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Defines the Server name. |
|
name |
Defines the resource name. The maximum number of characters is 2,048. |
|
max |
Defines the maximum quantity of resources available. Valid values: 0-9999 |
If annotation is enabled for the Independent AJF entities category in the
REST API Syntax
The following example shows the REST API syntax for the run resource::update command in cURL:
server=controlm
name=newResource
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST -d "{\"max\":6}" "$endpoint/run/resource/$server/$name"run resources::get
The run resources::get command enables you to get all resource records from
CLI Syntax
The following shows the CLI syntax for the run resources::get command:
ctm run resources::get -s [search query]
where -s runs a search with the query string format "field1=criteria1&field2=criteria2".
Criteria may contain a * for wildcard matching and comma separator to specify multiple values.
The following table describes the fields that you can use in the run resources::get query.
|
Field |
Description |
|---|---|
|
server |
Defines the Server name. |
|
name |
The resource name. The maximum number of characters is 2,048 characters. |
The following are search examples:
-s "name=resourceA"
-s "name=A*"
-s "server=IN01*&name=resourceA,resourceB"Response
The following example shows the parameters in the ctm run resources::get response:
[
{
"name": "newResource",
"ctm": "IN01",
"available": "15",
"max": 15
},
{
"name": "myRes",
"ctm": "IN01",
"available": "4",
"max": 4
}
]The following table describes the parameters in the run resources::get response.
|
Parameter |
Description |
|---|---|
|
ctm |
Defines the Server name. |
|
name |
Defines the resource name. The maximum number of characters is 2,048 characters. |
|
available |
Defines the number of resources available. |
|
max |
Defines the maximum number of resources available. |
REST API Syntax
The following example shows the REST API syntax for the run resources::get command in cURL:
search_criteria="name=A*&server=*"
curl -H "x-api-key: $token" -X GET "$endpoint/run/resources?$search_criteria"Event Management
An event 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 Server.
CLI Syntax
The following shows the CLI syntax for the run event::add command:
ctm run event::add <server> <name> <date>
The following table describes the run event::add command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Defines the Server name. |
|
name |
Defines the event name. |
|
date |
Determines the date options to order the event: Valid values:
|
If annotation is enabled for the Independent AJF entities category in the
REST API Syntax
The following example shows the REST API syntax for the run event::add command in cURL:
server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newEvent\",\"date\":\"0505\"}" "$endpoint/run/event/$server"run event::delete
The run event::delete command enables you to remove an event.
CLI Syntax
The following shows the CLI syntax for the run event::delete command:
ctm run event::delete <server> <name> <date>
The following table describes the run event::delete command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Defines the Server name. |
|
name |
Defines the event name. |
|
date |
Determines the date options to order the event: Valid values:
|
If annotation is enabled for the Independent AJF entities category in the
REST API Syntax
The following example shows the REST API syntax for the run event::delete command in cURL:
server=IN01
name=newEvent
date=0505
curl -H "x-api-key: $token" -X DELETE "$endpoint/run/event/$server/$name/$date"run events::get
The run events::get command enables you to get all events from the Server.
CLI Syntax
The following shows the CLI syntax for the run events::get command:
ctm run events::get -s [search query]
where -s runs a search with the query string format "field1=criteria1&field2=criteria2".
Criteria may contain a * for wildcard matching and comma separator to specify multiple values.
The following table describes the fields that you can use in the run events::get query.
|
Field |
Description |
|---|---|
|
server |
Defines the Server name. |
|
name |
Defines the event name. |
|
date |
Defines the event date. |
|
limit |
Defines the limits of the number of returned matches. Default: 1000 (if not defined) |
The following are search examples:
-s "name=eventA"
-s "name=A*&date=0805"
-s "server=IN01&name=eventA,eventB&date=0805"REST API Syntax
The following example shows the REST API syntax for the run events::get command in cURL:
search_criteria="name=A*&server=IN01"
curl -H "x-api-key: $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": "IN01",
"date": "0726"
},
{
"name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2935",
"ctm": "IN01",
"date": "0726"
},
{
"name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2974",
"ctm": "IN01",
"date": "0726"
},
{
"name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_3007",
"ctm": "IN01",
"date": "0726"
}
]
Service Management
The following API command enables you to manage services.
run services:sla::get
The run services:sla::get command retrieves details of defined SLA-type services.
For more information, see Service Management.
CLI Syntax
The following shows the CLI syntax for the run services:sla::get command:
ctm run services:sla::get
REST API Syntax
The following example shows the REST API syntax for the run services:sla::get command in cURL:
curl -H "x-api-key: $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.
The following example lists a single 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": "IN01:0002c",
"serviceControlM": "IN01",
"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",
"completed": "0",
"error": "1"
}
}
]
}In this response, serviceLastUpdatedTime specifies the most recent date and time when the services are updated. After that, the response displays the following parameters for each active SLA-type service:
|
Parameter |
Description |
|---|---|
|
serviceName |
Defines the service name. |
|
status |
Defines the current status of the service. |
|
statusReason |
Defines one or more reasons for the current status. |
|
startTime |
Defines the date and time when the service started to run. |
|
endTime |
Defines the date and time for when the service is estimated to stop running. |
|
dueTime |
Defines the deadline with the date and time when the service must complete to be considered not late. |
|
slackTime |
Defines the difference in time between the dueTime and its estimated endTime. |
|
serviceOrderDateTime |
Defines the date and time when the service is ordered. |
|
scheduledOrderDate |
Defines the order date if it is rescheduled during the order. |
|
serviceJob |
Defines the job ID of the job associated with the service. |
|
serviceControlM |
Defines the Server where the service runs. |
|
priority |
Defines the priority level of the service. |
|
note |
Defines the specific service information provided as a note for the service. |
|
totalJobs |
Defines the total number of jobs in the service. |
|
jobsCompleted |
Defines the number of completed jobs in the service. |
|
jobsWithoutStatistics |
Defines the number of jobs without statistical information. |
|
completionPercentage |
Defines the percentage of completed jobs in the service. |
|
averageCompletionTime |
Defines a time estimate for the service to complete. |
|
errors |
Defines the error messages received for the jobs in the service. |
|
statusByJobs |
Defines a breakdown of the number of completed jobs in each job status. |
Variable Management
Variables automatically assign dynamic environmental values to the job execution parameters.
Control-M Automation API helps manage pool-type variables. These variables are organized in hierarchical groups. 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:
run variables::get
The run variables::get command enables you to retrieve details of defined pool variables that match a search query.
CLI Syntax
The following shows the CLI syntax for the run variables::get command:
ctm run variables::get -s "<query string>"
where -s runs a search with the query string format "field1=criteria1&field2=criteria2&field3=criteria3" and the following supported fields:
|
Field |
Description |
|---|---|
|
pool |
Defines the name of the pool. pool=Pool1 For wildcard matching, you can specify a * in the named pool string. The * wildcard can be used as the only character or the last character. Default: * (all pools) pool=* or pool=P* |
|
variable |
Defines the full name of the variable. variable=Var1 For wildcard matching, you can specify a * in the variable string. The * wildcard can be used as the only character or the last character. Default: * (all variables) variable=* or variable=V* |
|
server |
Defines the Server name.
|
REST API Syntax
The following example shows the REST API syntax for the run variables::get command in cURL:
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X GET "$endpoint/run/variables?server=*&variable=%%\\\\P*\\V*"In a REST API command, all backslashes must be escaped.
Response
The following example shows a response to the run variables::get command:
{
"variables": [
{ "%%\\\\PoolName\\AUTOVar1InPoolAddedAudit": "value1" },
{ "%%\\\\PoolName\\AUTOVar2InPoolAddedAudit": "value2" }
]
}All backslashes are escaped in the JSON format.
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
The following shows the CLI syntax for the run variables::set command:
ctm run variables::set <server> -f <variablesDefinitionFile.json>
The following table describes the run variables::set command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Defines the Server name. |
|
variablesDefinitionFile |
Defines the full path and name of a JSON file with the variable definitions. Copy
All backslashes are escaped in the JSON format. |
If annotation is enabled for the Independent AJF entities category in the
REST API Syntax
The following example shows the REST API syntax for the run variables::set command in cURL:
server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/variables/$server" -d @VariablesDefinitions.jsonrun variables::delete
The run variables::delete command enables you to delete variables from the server.
CLI Syntax
The following shows the CLI syntax for the run variables::delete command:
ctm run variables::delete <server> -f <variablesNames.json
The following table describes the run variables::delete command parameters.
|
Parameter |
Description |
|---|---|
|
server |
Defines the Server name. |
|
variablesNames |
Defines the full path and name of a JSON file with a list of variable names. Copy
All backslashes are escaped in the JSON format. |
If annotation is enabled for the Independent AJF entities category in the
REST API Syntax
The following example shows the REST API syntax for the run variables::delete command in cURL:
server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X DELETE "$endpoint/run/variables/$server" -d @VariableNames.jsonAlert Management
An alert is a message that indicates a problem or exception in a job or folder. Control-M Automation API enables you to update basic alert properties and alert status. 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 alert properties, including urgency and associated comments.
CLI Syntax
The following shows the CLI syntax for the run alerts::update command:
ctm run alerts::update -f <configuration file>
The configuration file contains the properties required to update the alerts. You must include in the configuration file the mandatory alertIds parameter and at least one of the other relevant parameters.
The following table describes the parameters for the run alerts::update command:
|
Parameter |
Description |
|---|---|
|
alertIds |
Defines the unique identifiers for the alerts that you want to update. |
|
urgency |
Determines the severity of the alert. Valid values:
|
|
comment |
Defines a free-text comment about the alert. |
The following example shows a configuration file:
{
"alertIds" : [30,31],
"urgency":"Normal",
"comment":"update"
}REST API Syntax
The following example shows the REST API syntax for the run alerts::update command in cURL:
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts" -d @alertModifyValue.jsonThe configuration file is named alertModifyValue.json.
run alerts:status::update
The run alerts:status::update command enables you to update the alert status.
CLI Syntax
The following shows the CLI syntax for the run alerts:status::update command:
ctm run alerts:status::update <alertIds> -f <configuration file>
The configuration file contains the properties required to update the alert status.
The following table describes the run alerts:status::update command parameters.
|
Parameter |
Description |
|---|---|
|
alertIds |
Defines unique identifiers for the alerts that you want to update. |
|
status |
Determines the alert status. Valid values:
|
The following example shows a configuration file:
{
"alertIds" : [20],
"status":"Reviewed"
}REST API Syntax
The following example shows the REST API syntax for the run alerts:status::update command in cURL:
endpoint=
alertIds=15,20
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts/status/$alertIds" -d @alertModifyStatus.jsonThe configuration file is named alertModifyStatus.json.
External Alert Management
An alert is a message that indicates a problem or an exception (for example, in a job or folder). Control-M Automation API enables you to perform alert management with external tools. For more information, see Setting Up External Alerts.
If the host of your external client uses a proxy server, ensure that the proxy server settings are defined, as described in Proxy Server Configuration
The following table lists actions that you can perform to manage a reliable alerts stream from Helix Control-M and the listener process on your client:
|
Alerts Stream |
Alerts Listener |
|---|---|
If you want to listen for alerts, ensure that you enabled external alerts in one of the following ways:
-
In Config Service, set the enableExternalAlerts property to true, as described in System Settings Configuration.
-
In Helix Control-M, through the System Settings in the Configuration domain, as described in Defining System Settings .
run alerts:stream::open
The run alerts:stream::open command enables you to open the alerts stream from Helix Control-M.
You can have only one open alerts stream. If you want to open another stream with a different API token, you must first close the previous stream and utilize the same API token used to open that stream.
CLI Syntax
The following shows the CLI syntax for the run alerts:stream::open command:
ctm run alerts:stream::open
If annotation is enabled for the Alerts Handling category in the Configuration domain , you must also provide an annotation to justify your action. For more information, see Annotation Input.
The following example shows a successful response that returns a WebSocket URL for the connection:
{
"url": "wss://xyz-66095-alerts.us1.ci.ctmsaas.com"
}REST API Syntax
See Control-M Automation REST API Reference.
The following example shows the REST API syntax for the run alerts:stream::open command in cURL:
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts/stream/open"run alerts:stream::close
The run alerts:stream::close command enables you to close the alerts stream from Helix Control-M. This disconnects the active Alerts Listener and enables other users to open a different stream.
To close an alerts stream, you must be connected with the same API token used to open the stream. Only an admin user with Configuration access set to Update level can close the stream of another user.
CLI Syntax
The following shows the CLI syntax for the run alerts:stream::close command:
ctm run alerts:stream::close <force option>
The following table describes the run alerts:stream::close command parameter.
|
Parameter |
Description |
|---|---|
|
force option |
Determines whether to force a stream to close. Valid values:
Default: false |
If annotation is enabled for the Alerts Handling category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.
REST API Syntax
See Control-M Automation REST API Reference.
The following example shows the REST API syntax for the run alerts:stream::close command in cURL:
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts/stream/close?force=false"run alerts:stream::status
The run alerts:stream::status command enables you to return the following:
-
The status of the monitoring service that streams the alerts from Helix Control-M.
-
The connection status to the listener process on your client.
-
The most recent date and time of the last update.
CLI Syntax
The following shows the CLI syntax for the run alerts:stream::status command:
ctm run alerts:stream::status
REST API Syntax
See Control-M Automation REST API Reference.
The following example shows the REST API syntax for the run alerts:stream::status command in cURL:
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts/stream/status"run alerts:stream:template::set
The run alerts:stream:template::set command enables you to set a JSON template that determines what information to provide for each alert. The information includes fields of information, their names, and order of appearance. The template that you provide overrides the default combination of fields provided by Helix Control-M.
CLI Syntax
The following shows the CLI syntax for the run alerts:stream:template::set command:
ctm run alerts:stream:template::set -f <template file>
where the -f switch specifies the path to the JSON template file that lists the information fields for the alerts.
For more information about the default fields and how to author the JSON template, see External Alerts Fields and Templates.
If annotation is enabled for the Alerts Handling category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.
REST API Syntax
See Control-M Automation REST API Reference.
The following example shows the REST API syntax for the run alerts:stream:template::set command in cURL:
curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST -d "@alertsTemplate.json" "$endpoint/run/alerts/stream/template"run alerts:listener::start
The run alerts:listener::start command enables you to run the Alerts Listener for the defined environment and triggers a defined alert script each time it receives an alert.
The response returns the process ID (PID) for the initiated Alerts Listener run.
-
This CLI command first calls the run alerts:stream::open API command and opens the alerts stream from Helix Control-M if it is not already open.
-
This API command is supported only through the CLI and cannot be called through a REST API command.
-
You can have only one listener running at a time. If you want to open another listener using a different API token, you must first stop the running listener and utilize the same API token used to start that listener.
CLI Syntax
The following shows the CLI syntax for the run alerts:listener::start command:
ctm run alerts:listener::start [attached]
The following table describes the run alerts:listener::start command parameter.
|
Parameter |
Description |
|---|---|
|
attached |
(Optional) Determines whether to start the listener in attached mode in the foreground instead of the default detached mode in the background. Valid values:
Default: false |
If annotation is enabled for the Alerts Handling category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.
A successful response returns a process ID for the Alerts Listener.
run alerts:listener::stop
The run alerts:stream::stop command enables you to stop the Alerts Listener for the defined environment.
The response specifies the process ID (PID) of the Alerts Listener run that stopped.
-
This API command is supported only through the CLI and cannot be called through a REST API command.
-
After successfully stopping the Alerts Listener, this CLI command also closes the alerts stream. It performs the function of run alerts:stream::close.
CLI Syntax
The following shows the CLI syntax for the run alerts:stream::stop command:
ctm run alerts:listener::stop
If annotation is enabled for the Alerts Handling category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.
run alerts:listener:environment::set
The run alerts:listener:environment::set command enables you to set the Helix Control-M Environment Service to listen for alerts.
This setting is stored locally and applied to the specific machine where the Alerts Listener runs.
This API command is supported only through the CLI and cannot be called through a REST API command.
CLI Syntax
The following shows the CLI syntax for the run alerts:listener:environment::set command:
ctm run alerts:listener:environment::set <environment_name>
run alerts:listener:script::set
The run alerts:listener:script::set command sets the path to an Alerts Listener script to trigger each time it receives an alert. Ensure that you are authorized to execute the script.
This API command is supported only through the CLI and cannot be called through a REST API command.
CLI Syntax
The following shows the CLI syntax for the run alerts:listener:script::set command:
ctm run alerts:listener:script::set <script_path>
run alerts:listener::configure
The run alerts:listener::configure command enables you to configure the Alerts Listener. Use this CLI command to set either the environment by run alerts:listener:environment::set or the Alerts Listener script by run alerts:listener:script::set.
This API command is supported only through the CLI and cannot be called through a REST API command.
CLI Syntax
The following shows the CLI syntax for the run alerts:listener::configure command:
ctm run alerts:listener::configure environment <environment_name>
ctm run alerts:listener::configure script <script_path>
YouTube
Twitter
Facebook
LinkedIn