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.

Copy
> 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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run command in cURL:

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

Copy
> 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, you must also provide an annotation to justify your action. For more information, see Annotation Input.

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:

  • true

  • false

Default: false

ignoreCriteria

Determines whether to run a job when it is ordered and ignore the scheduling criteria.

Valid Values:

  • true

  • false

Default: true

independentFlow

Determines whether a flow in a folder is ordered uniquely.

This parameter is not applicable to sub-folders.

Valid Values:

  • true

  • false

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:

  • true

  • false

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:

  • true

  • false

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:

  • New: Inserts jobs into a new folder.

  • Recent: Inserts jobs into a recent folder.

  • <Folder Order ID>: Inserts jobs into a selected folder.

  • Alone: Inserts jobs into a regular folder.

    The createDuplicate parameter is not relevant for this value.

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:

Copy
{
    "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:

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

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

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

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

Copy
{
    "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:

> ctm run userDaily:missing::run myUserDaily { "runId": "2143811-e253-4c3f-8c21-72bd7957bb53", "statusURI": "http://localhost:32080/run/status/2143811-e253-4c3f-8c21-72bd7957bb53" }

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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run userDaily:missing::run command in cURL:

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

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

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

Copy
> 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 additional run status command parameters.

Parameter

Description

completion

Determines whether the job ran.

Valid Values:

  • Completed

  • Pending

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:

  • true

  • false

deleted

Determines whether the job was deleted.

Valid Values:

  • true

  • false

cyclic

Determines whether the job is defined as a cyclic job.

Valid Values:

  • true

  • false

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

  • jobid (Format: <server>:<orderId>)

  • folder

  • folderLibrary

  • server

  • application

  • subApplication

  • host

  • hostGroup

  • description

  • runAs

  • command

  • filePath

  • fileName

  • ruleBasedCalender

  • resourceLock

  • resourcePool

  • Supported wildcards are *and ?.

  • Multiple criteria are separated with a comma.

  • Wildcards are not supported for jobid.

jobname=job1122

jobname=job11*

jobname=job11*,job77*

description=*a job that*

jobid=IN01:005gy

 

  • orderDateFrom

  • orderDateTo

  • fromTime

  • toTime

  • For orderDateFrom and orderDateTo: YYMMDD.

  • For fromTime and toTime: YYYYMMDDhhmmss.

orderDateFrom=180123

fromTime=20180123184500

historyRunDate

  • A single date when jobs started running in one of the following formats:

    • YYMMDD

    • YYYYMMDD

  • Yesterday

historyRunDate=231127

historyRunDate=Yesterday

status

  • Ended OK.

  • Ended Not OK.

  • Wait User.

  • Wait Resource.

  • Wait Host.

  • Wait Condition.

  • Executing

  • Status Unknown.

To use multiple criteria, separate criteria with commas.

status=Ended OK

status=Ended OK, Ended Not OK,Executing

  • held

  • folderHeld

  • cyclic

  • deleted

true | false

"held=true&cyclic=false
&deleted=false"

neighborhood

Returns the status according to the dependencies between jobs. The Flow object enables you to create dependencies between jobs.

  • direction: The following list describes the possible values:

    • depend: The jobs that depend on the specified job.

    • predecessor: The jobs that the specified job depends on.

    • radial: The jobs from both directions.

  • depth: The number of job levels from the specified job.

"neighborhood&jobid=IN01:0a98
&depth=1&direction=predecessor"

The following example shows a command to get job statuses with a search query:

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

The following example shows a command to get job statuses of a job that has linked jobs:

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

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

Copy
{
      "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:

  • Ended OK.

  • Ended Not OK.

  • Wait User.

  • Wait Resource.

  • Wait Host.

  • Wait Condition.

  • Executing

  • Status Unknown.

held

Determines whether the job was held.

Valid Values:

  • true

  • false

deleted

Determines whether the job was deleted.

Valid Values:

  • true

  • false

cyclic

Determines whether the job is defined as a cyclic job.

Valid Values:

  • true

  • false

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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run jobs:output::get command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job:log::get command in cURL:

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

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

Copy
{
  "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:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::kill command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::runNow command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::hold command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information,see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::free command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::delete command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::undelete command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::confirm command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::setToOk command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::rerun command in cURL:

Copy
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 (for example: missing conditions, resources, hosts, or users).

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:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::get command in cURL:

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

  • Host

  • RerunSpecificTimes

  • RunAsDummy

  • RetroactiveOrder

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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run job::modify command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run resource::add command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run resource::delete command in cURL:

Copy
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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

The following example shows the REST API syntax for the run resource::update command in cURL:

Copy
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 the Server.

CLI Syntax

The following shows the CLI syntax for the run resource::update 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 run resources::get command parameters.

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:

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

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

The following table describes additional run resources::get parameters for the 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:

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

  • MMDD: A specific date.

  • ODAT: The current Control-M date. For example, if the current Control-M date is August 7, 2016, the ODAT converts to 0807.

  • STAT: An alternative to a specific date for an event that is not date-specific.

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

REST API Syntax

The following example shows the REST API syntax for the run event::add command in cURL:

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

  • MMDD: A specific date.

  • ODAT: The current Control-M date. For example, if the current Control-M date is August 7, 2016, the ODAT converts to 0807.

  • STAT: An alternative to a specific date for an event that is not date-specific.

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

REST API Syntax

The following example shows the REST API syntax for the run event::delete command in cURL:

Copy
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 run events::get fields.

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:

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

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

Copy
[
 {
    "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

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

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:

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

Copy
{
  "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.

When you have only one server, you do not need to include this field or you can use the default server=*.

REST API Syntax

The following example shows the REST API syntax for the run variables::get command in cURL:

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

Copy
{
   "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
{
   "variables": [
      { "%%\\\\PoolName\\AUTOVar1InPoolAddedAudit": "value1"  },
      { "%%\\\\PoolName\\AUTOVar2InPoolAddedAudit": "value2"  }
   ]
}

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

The following example shows the REST API syntax for the run variables::set command in cURL:

Copy
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

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
{
    "variables":
    [
        "%%\\\\PoolName\\AUTOVarInPool",
        "%%\\\\PoolName\\AUTOVarInPool2"
    ]
}

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

The following example shows the REST API syntax for the run variables::delete command in cURL:

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

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

  • Normal

  • Urgent

  • Critical

comment

Defines a free-text comment about the alert.

The following example shows a configuration file:

Copy
{
    "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:

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

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

  • New

  • Reviewed

  • Closed

  • Undefined

The following example shows a configuration file:

Copy
{
    "alertIds" : [20],
    "status":"Reviewed"
}

REST API Syntax

The following example shows the REST API syntax for the run alerts:status::update command in cURL:

Copy
endpoint=
alertIds=15,20

curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts/status/$alertIds" -d @alertModifyStatus.json

The 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 you defined the following environment variables:

  • HTTP_PROXY

  • HTTPS_PROXY

  • WSS_PROXY

Values for these variables are in the format {protocol}://{host}:{port} (for example http://172.19.0.169:3128 or https://server.com:3128). For authentication to the proxy, include login credentials, as shown in the following example:
HTTP_PROXY= http://username:password@proxy.example.com:1234

If you want to opt out of proxying on specific hosts or particular destination ports, you can use the NO_PROXY environment variable, set with a comma-separated list of hosts (for example, NO_PROXY=hostname.example.com,10.1.0.0/16,172.30.0.0/16:443).

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:

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 Control-M, 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:

Copy
{
    "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:

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

  • true: Force a stream to close

  • false: Close a stream without forcing

Default: false

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 Control-M Automation REST API Reference.

The following example shows the REST API syntax for the run alerts:stream::close command in cURL:

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

Copy
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 Control-M, 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:

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

  • true

  • false

Default: false

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

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 Control-M, 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>