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
• Resource Management
• Event Management
• Service Management 
• Variable Management
  
• External Alert Management

Job Management

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

run

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

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

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

CLI Syntax

ctm run <jobDefinitionsFile> [deployDescriptorFile]

Where:

If annotation is enabled for the Scheduling definitions category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

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

run order

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

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

CLI Syntax

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

Where:

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:

Here is an example of a configuration file:

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

REST API Syntax

See REST API reference.

Example using  curl:

endpoint=
token=
ctm=
folderName=

curl -X POST -H "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\",
  \"orderIntoFolder\": \"Recent\",
  \"variables\": [{\"arg\":\"12345\"}]
}" "$endpoint/run/order" 	

run status

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

CLI Syntax

ctm run status <runId> [startIndex]

Where:

REST API Syntax

See REST API reference.

Example using  curl:  

curl -H "x-api-key: $token" "$endpoint/run/status/$runId"

Response

The following example shows the parameters in the run status response

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

> ctm run status "2d4af716-e31d-48ef-a434-16575303752d" 
{     
  "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
}

Where:

_{Back to top}

run jobs:status::get

This command allows you to track running jobs that match a search query. 

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

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

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

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

CLI Syntax

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

Limit refers to the maximum number of job statuses returned.

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

Where:

REST API Syntax

See REST API reference.

Example of a curl request that includes a limit:

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

Response

The following example shows the parameters for one of the jobs returned in the response to the 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": "",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "orderDate": "180903",
      "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:

_{Back to top}

run job:output::get

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

CLI Syntax

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

Where:

If annotation is enabled for the AJF get job information category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/output/?runNo=0"

_{Back to top}

run job:log::get

This command allows you to view the job log. 

CLI Syntax

ctm run job:log::get <jobId> 

Where:

If annotation is enabled for the AJF get job information category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/log"

_{Back to top}

run job:status::get

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

CLI Syntax

ctm run job:status::get <jobId>

Where:

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.

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/status"

_{Back to top}

run job:statistics::get

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

CLI Syntax

ctm run job:statistics::get <jobId>

Where:

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. It differs from the job ID specified in the input.

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

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/statistics"

_{Back to top}

run job::kill

This command allows you to terminate the job.

CLI Syntax

ctm run job::kill <jobId> 

Where:

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/kill"

_{Back to top}

run job::runNow

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

CLI Syntax

ctm run job::runNow <jobId> 

Where:

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/runNow"

_{Back to top}

run job::hold 

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

CLI Syntax

ctm run job::hold <jobId> 

Where: 

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:  

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/hold"

_{Back to top}

run job::free 

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

CLI Syntax

ctm run job::free <jobId> 

Where: 

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax 

See REST API reference. 

Example using  curl:

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/free"

_{Back to top}

run job::delete 

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

CLI Syntax

ctm run job::delete <jobId> 

Where: 

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax 

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/delete"

_{Back to top}

run job::undelete 

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

CLI Syntax

ctm run job::undelete <jobId> 

Where:

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/undelete"

_{Back to top}

run job::confirm 

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

CLI Syntax

ctm run job::confirm <jobId> 

Where:

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/confirm"

_{Back to top}

run job::setToOk 

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

CLI Syntax

ctm run job::setToOk <jobId> 

Where:

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/setToOk"

_{Back to top}

run job::rerun

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

CLI Syntax

ctm run job::rerun <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -X POST "$endpoint/run/job/$jobId/rerun"

_{Back to top}

run job::waitingInfo

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

CLI Syntax

ctm run job::waitingInfo <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" "$endpoint/run/job/$jobId/waitingInfo"

_{Back to top}

run job::get

 This command obtains the details of an active job.

CLI Syntax

ctm run job::get <jobId> 

Where: 

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:  

curl -H "x-api-key: $token" -X GET "$endpoint/run/job/$jobId/get"

_{Back to top}

run job::modify

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

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

• Command
• Script

• EmbeddedScript

• FileTransfer
• Informatica

CLI Syntax

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

Where: 

If annotation is enabled for the Active network category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:  

curl -H "x-api-key: $token" -X POST -F "jobDefinitionsFile=@examples/InformaticaJob.json" "$endpoint/run/job/$jobId/modify"

_{Back to top}

Resource Management

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

run resource::add

The add resource command allows you to add a quantitative resource to the server. 

CLI Syntax

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

Where:

If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

server=IN01
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 delete resource command allows you to delete a quantitative resource. 

CLI Syntax

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

Where:

If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

server=IN01
name=newResource
curl -H "x-api-key: $token" -X DELETE "$endpoint/run/resource/$server/$name"

run resource::update

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

CLI Syntax

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

Where:

If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

server=IN01
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 get resources command allows you to get all resource records from the server.

CLI Syntax

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

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

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

Where:

-s "name=resourceA"
-s "name=A*"
-s "server=IN01*&name=resourceA,resourceB"

Response 

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

[
  {
    "name": "newResource",
    "ctm": "IN01",
    "available": "15",
    "max": 15
  },
  {
    "name": "myRes",
    "ctm": "IN01",
    "available": "4",
    "max": 4
  },

Where:

REST API Syntax

See REST API reference.

Example using  curl:

search_criteria="name=A*&server=*"
curl -H "x-api-key: $token" -X GET "$endpoint/run/resources?$search_criteria" 

_{Back to top}

Event Management

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

run event::add

The add event command allows you to add events to the server.

CLI Syntax

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

Where:

If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

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 delete event command allows you to remove an event. 

CLI Syntax

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

Where:

If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

server=IN01
name=newEvent
date=0505
curl -H "x-api-key: $token" -X DELETE "$endpoint/run/event/$server/$name/$date"

run events::get

The get events command allows you to get all events from the server.

CLI Syntax

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

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

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

Where:

-s "name=eventA"
-s "name=A*&date=0805"
-s "server=IN01&name=eventA,eventB&date=0805"

REST API Syntax

See REST API reference.

Example using  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 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"
  }
]

_{Back to top}

Service Management

Services are groups of jobs that are aggregated based on criteria that you specify. Control-M Automation API can help you manage SLA services that are associated with SLA jobs (also known as Control-M BIM jobs) at the end of a job flow.

run services:sla::get

Retrieves details of defined SLA-type services.

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

CLI Syntax

ctm run services:sla::get

REST API Syntax

See REST API reference.

Example using  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 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": "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 were updated. After that, for each active SLA-type service, the following parameters are displayed:

_{Back to top}

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 in the Helix Control-M Online Help.

run variables::get

Retrieves 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:

REST API Syntax

See REST API reference.

Note that in a RST API command, all backslashes must be escaped, as in the following curl example:

curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X GET  "$endpoint/run/variables?server=*&variable=%%\\\\P*\\V*"

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

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>

Where:

{
  "variables": [
    { "%%\\\\PoolName\\AUTOVar1InPoolAddedAudit": "value1"  },
    { "%%\\\\PoolName\\AUTOVar2InPoolAddedAudit": "value2"  }
  ]
}

If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X POST "$endpoint/run/variables/$server" -d @VariablesDefinitions.json

run variables::delete

Deletes variables from the server.

CLI Syntax

ctm run variables::delete <server> -f <variablesNames.json

Where:

{
  "variables":
    [
        "%%\\\\PoolName\\AUTOVarInPool",
        "%%\\\\PoolName\\AUTOVarInPool2"
    ]
}

If annotation is enabled for the Independent AJF entities category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X DELETE "$endpoint/run/variables/$server" -d @VariableNames.json

_{Back to top}

External Alert Management

An alert is a message that indicates that a problem or exception has occurred (for example, in a Job or Folder). Control-M Automation API enables you to manage the monitoring of alerts through external tools. For more information, see Setting Up External Alerts.

The following table lists the actions that you can perform with Control-M Automation API to manage a reliable stream of alerts from Helix Control-M and to manage the listener process on your client:

run alerts:stream::open

Opens the stream of alerts from Helix Control-M.

Note: You can have only one open Alerts stream. If you want to open another stream using a different API token, you must first close the previous stream, using the same API token that was used to open that stream.

CLI Syntax

ctm run alerts:stream::open

If annotation is enabled for the Alerts Handling category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

A successful response returns a WebSocket URL for the connection, as in the following example: 

{
  "url": "wss://xyz-66095-alerts.us1.ci.ctmsaas.com"
}

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X POST "$endpoint/run/alerts/stream/open"

run alerts:stream::close

Closes the stream of alerts from Helix Control-M. This disconnects the active Alerts listener and enables other users to open a different stream. 

Note: To close an Alerts stream, you must be connected with the same API token that was 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

ctm run alerts:stream::close <force option>

Where the <force option> can be either true (force the closing of the stream) or false (close without forcing; the default).

If annotation is enabled for the Alerts Handling category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X POST "$endpoint/run/alerts/stream/close?force=false"

run alerts:stream::status

Returns the status of the monitoring service that streams the alerts from Helix Control-M and the status of the connection to the listener process on your client, as well as the most recent date and time of the last update.

CLI Syntax

ctm run alerts:stream::status

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X POST "$endpoint/run/alerts/stream/status"

run alerts:stream:template::set

Sets a JSON template that determines what information to provide for each alert — which 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

ctm run alerts:stream:template::set -f <template file>

The -f switch specifies the path to the JSON-format template file that lists the fields of information for alerts. 

For more information about the default fields and how to author the JSON template, see Alerts Template reference.

If annotation is enabled for the Alerts Handling category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X POST -d "@alertsTemplate.json" "$endpoint/run/alerts/stream/template"

run alerts:listener::start

Runs the Alerts listener for the defined environment and triggers a defined Alert script each time an alert is received.

The response returns the process ID (PID) for the initiated run of the Alerts listener. 

Note: 

• 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, using the same API token that was used to start that listener.

CLI Syntax

ctm run alerts:listener::start [attached]

If annotation is enabled for the Alerts Handling category in Control-M, 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

Stops the Alerts listener for the defined environment.

The response specifies the process ID (PID) of the stopped run of the Alerts listener. 

Note: 

• 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 (that is, it performs the function of run alerts:stream::close).

CLI Syntax

ctm run alerts:listener::stop

If annotation is enabled for the Alerts Handling category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation input.

run alerts:listener:environment::set

Sets the Helix Control-M environment to listen to for alerts.

This setting is stored locally and applied to the specific machine where the Alerts listener runs.

Note: This API command is supported only through the CLI, and cannot be called through a REST API command.

CLI Syntax

ctm run alerts:listener:environment::set <environment_name>

run alerts:listener:script::set

Sets the path to an Alerts Listener script to trigger each time an alert is received. Ensure that you are authorized to execute the script.

Note: This API command is supported only through the CLI, and cannot be called through a REST API command.

CLI Syntax

ctm run alerts:listener:script::set <script_path>

run alerts:listener::configure

Configures the Alerts listener. Use this CLI command to set either environment (as done by run alerts:listener:environment::set) or the Alerts Listener script (as done by run alerts:listener:script::set).

Note: This API command is supported only through the CLI, and cannot be called through a REST API command.

CLI Syntax

ctm run alerts:listener::configure environment <environment_name>
ctm run alerts:listener::configure script <script_path>

_{Back to top}