Run Service

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

Job Management

The following API commands enable you to manage your jobs, perform various job actions, track job status, and view job output and logs:

• run

• run order

• run userDaily:missing::list

• run userDaily:missing::poll

• run userDaily:missing::run

• run ondemand

• run status

• run jobs:status::get

• run job:output::get

• run job:log::get

• run job:status::get

• run job:statistics::get

• run job::kill

• run job::runNow

• run job::hold

• run job::free

• run job::delete

• run job::undelete

• run job::confirm

• run job::setToOk

• run job::rerun

• run job::waitingInfo

• run job::get

• run job::modify

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.

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

The following table describes the run command parameters.

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

REST API Syntax

curl -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. 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:8443/automation-api/run/status/e0ddf056-4497-49f7-9d8b-25758b132bd6"
}

CLI Syntax

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

The following table describes the run order command parameters.

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

In the configuration file, you can specify the following additional parameters:

Here is an example of a configuration file:

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

REST API Syntax

cURL:

endpoint=
token=
ctm=
folderName=
 
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 (that is, a specific User Daily job) was interrupted for any reason (for example, an operating system crash).

The command returns a poll ID that you can use to view the list, using the run userDaily:missing::poll command. Below is a typical command and response.

> ctm run userDaily:missing::list myUserDaily controlm
{
  "pollId": "f9f9667e-8037-45c9-bd00-36eaa4b812c8",
  "statusURI": "http://localhost:32080/run/orderMethod/myUserDaily/missing/listf9f9667e-8037-45c9-bd00-36eaa4b812c8"
}

CLI Syntax

ctm run userDaily:missing::list <userDaily> <server>

The following table describes the run userDaily:missing::list command parameters.

REST API Syntax

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 view a previously generated list of jobs that were not ordered because a specific Order Method (that is, a specific User Daily job) was interrupted for any reason (for example, an operating system crash).

CLI Syntax

ctm run userDaily:missing::poll <pollId>

Where <pollID> is the poll ID returned by therun userDaily:missing::list command.

REST API Syntax

curl -H "x-api-key: $token" "$endpoint/run/userDaily/missing/poll/$pollId"

Response

The following example response lists two unordered jobs and another two unordered jobs that changed after the User Daily job ran.

{
    "jobs": [
        {
           "folderName": "Folder_1",
           "jobName": "Job_1"
        },
        {
           "folderName": "Folder_2",
           "jobName": "Job_2"
        }
    ],
    "jobsChangedAfterUserDailyRun": [
        {
           "folderName": "Folder_3",
           "jobName": "Job_3"
        },
        {
           "folderName": "Folder_4",
           "jobName": "Job_4"
        }
    ]
}

You can reorder the jobs that did not yet run using the run userDaily:missing::poll command.

run userDaily:missing::run

The run userDaily:missing::run command enables you reorder the jobs that did not run because a specific Order Method (that is, a specific User Daily job) was interrupted for any reason (for example, an operating system crash).

The command returns a runId, which you can use to check job status with the run status command. Below is a typical command and response.

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

CLI Syntax

ctm run userDaily:missing::run <orderMethod>

Where <userDaily> is the name of the User Daily job.

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

REST API Syntax

userDaily=myUserDaily
curl -X POST -H "x-api-key: $token" "$endpoint/run/userDaily/$userDaily/missing/run"

run ondemand

The run ondemand command enables you execute jobs immediately, without deploying them to the Server database and without requiring the User Daily job in Control-M to trigger them. This approach can be useful for event-driven job executions.

A build process takes place as part of the run.

The response returns a runID and statusURI (similar to the run and run order commands). You can use the returned runId to check job status with the run status command.

CLI Syntax

ctm run ondemand <definitionsFile> [deployDescriptorFile]

The following table describes the run ondemand command parameters.

REST API Syntax

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 following command shows how to check job status using the runId.

CLI Syntax

ctm run status <runId> [startIndex]

The following table describes the run status command parameters.

REST API Syntax

cURL:

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

Response

The following example shows the parameters in the run status response.

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

run jobs:status::get

The run jobs:status::get command enables you to track running jobs that match a search query.

CLI Syntax

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

The following table describes the run jobs:status::get command parameters.

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

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

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

REST API Syntax

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

run job:output::get

The run jobs:output::get command enables you to view the output from job runs.

CLI Syntax

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

The following table describes the run job:output::get command parameters.

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

REST API Syntax

cURL:

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 the job log.

CLI Syntax

ctm run job:log::get <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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

ctm run job:status::get <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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

ctm run job:statistics::get <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

Response

The response provides time statistics for each job run (order date, start and end time, run time, and CPU time), as well as an average of the key time statistics from all runs. If periodic statistics are collected for this job, job run statistics are presented for each period separately.

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

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

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

REST API Syntax

cURL:

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

ctm run job::kill <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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. When you use this command, job constraints are not applied.

CLI Syntax

ctm run job::runNow <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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 (that is, stop processing) the job.

CLI Syntax

ctm run job::hold <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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 job run from hold state.

CLI Syntax

ctm run job::free <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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. At the next scheduled date, the job will be deleted.

CLI Syntax

ctm run job::delete <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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 mark for deletion from a job.

CLI Syntax

ctm run job::undelete <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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

ctm run job::confirm <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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 has been processed. You can use this command, for example, after resolving issues that caused a job to end in status Not OK.

CLI Syntax

ctm run job::setToOk <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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 (provided that it is not currently executing). When you use this command, the existing job constraints are applied.

CLI Syntax

ctm run job::rerun <jobId>

The following table describes the run job::rerun command parameters.

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

REST API Syntax

cURL:

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

run job::waitingInfo

The run job::waitingInfo command enables you to display the reasons why a waiting job has not yet been executed (for example: missing conditions, resources, hosts, or users).

CLI Syntax

ctm run job::waitingInfo <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

REST API Syntax

cURL:

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

ctm run job::get <jobId>

Where <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is <server>:<orderId>.

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

REST API Syntax

cURL:

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 (that is, a job for which processing has been stopped), based on job definitions that you define through a Job Definitions file.

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

• Command

• Script

• EmbeddedScript

• FileTransfer

• Informatica

CLI Syntax

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

The following table describes the run job::modify command parameters.

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

REST API Syntax

cURL:

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

Resource Management

A Resource Pool (previously known as a Quantitative Resource) is represented by a name of a resource and the maximum number of that resource which jobs can use. Jobs that require a Resource Pool cannot run unless there are enough resources available.

The following API commands enable you to manage Resource Pools:

• run resource::add

• run resource::delete

• run resource::update

• run resources::get

run resource::add

The run resource::add command enables you to add a Resource Pool to a Server.

CLI Syntax

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

The following table describes the run resource::add command parameters.

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

REST API Syntax

cURL:

server=controlm
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

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

The following table describes the run resource::delete command parameters.

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

REST API Syntax

cURL:

server=controlm
name=newResource
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

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

The following table describes the run resource::update command parameters.

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

REST API Syntax

cURL:

server=controlm
name=newResource
 
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

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

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

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

The following table describes the run resources::get command parameters.

Here are several search examples:

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

Response

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

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

The following table describes additional run resource::add command parameters.

REST API Syntax

cURL:

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

Event Management

An event (previously known as a condition) is represented by a name and a date. Jobs that require an event cannot run unless the specific event exists, as described in Events. A job can add or delete an event.

The following API commands enable you to manage Events:

• run event::add

• run event::delete

• run events::get

run event::add

The run event::add command enables you to add events to the Server.

CLI Syntax

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

The following table describes the run event::add command parameters.

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

REST API Syntax

cURL:

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

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

The following table describes the run event::delete command parameters.

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

REST API Syntax

cURL:

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

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

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

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

The following table describes the run events::get fields.

Here are several search examples:

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

REST API Syntax

cURL:

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

Response

The following example shows the parameters in the ctm run events::get response:

[
 {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2902",
    "ctm": "IN01",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2935",
    "ctm": "IN01",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2974",
    "ctm": "IN01",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_3007",
    "ctm": "IN01",
    "date": "0726"
  }
]

Service Management

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.

The following API command enables you to manage services.

run services:sla::get

Retrieves details of defined SLA-type services.

For more information, see Service Management.

CLI Syntax

ctm run services:sla::get

REST API Syntax

cURL:

curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X GET  "$endpoint/run/services/sla"

Response

The following example shows the parameters in the response to the ctm run services:sla::get command. 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:

Variable Management

Variables enable the automatic assignment of dynamic environmental values to the execution parameters of a job.

Control-M Automation API can help you manage pool-type variables. Variables of this type are organized in hierarchical groups, and they are expressed in the following manner:

%%\\<named_pool>\<variable_name>

For more information about variables, see Variables.

The following API commands enable you to manage variables:

• run variables::get

• run variables::set

• run variables::delete

run variables::get

The run variables::get command enables you to retrieve details of defined pool variables that match a search query.

CLI Syntax

ctm run variables::get -s "<query string>"

-s is used to run a search using the query string format "field1=criteria1&field2=criteria2&field3=criteria3", with the following supported fields:

REST API Syntax

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

The run variables::set command enables you to define new pool variables or update the definitions of existing pool variables.

CLI Syntax

ctm run variables::set <server> -f <variablesDefinitionFile.json>

The following table describes the run variables::set command parameters.

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

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

The run variables::delete command enables you to delete variables from the server.

CLI Syntax

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

The following table describes the run variables::delete command parameters.

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

cURL:

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 that a problem or exception has occurred for a Job or Folder. Control-M Automation API enables you to update basic properties of alerts, as well as the status of alerts. For more information, see Alerts.

The following API commands enable you to manage alerts:

• run alerts::update

• run alerts:status::update

run alerts::update

The run alerts::update command enables you to update basic properties of alerts, including the urgency of the alerts and the associated comments.

CLI Syntax

ctm run alerts::update -f <configuration file>

The configuration file contains the properties required for updating the alerts. Note that besides the mandatory alertIds parameter, you must include at least one of the other parameters in the configuration file.

Here is an example of a configuration file:

{
    "alertIds" : [30,31],
    "urgency":"Normal",
    "comment":"update"
}

REST API Syntax

Example using curl: In this example, the configuration file is named alertModifyValue.json.

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

run alerts:status::update

The run alerts:status::update command enables you to update the status of the alert.

CLI Syntax

ctm run alerts:status::update <alertIds> -f <configuration file>

The configuration file contains the properties required for updating alert status.

Here is an example of a configuration file:

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

REST API Syntax

Example using curl: In this example, the configuration file is named alertModifyStatus.json.

endpoint=
alertIds=15,20

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

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

The run alerts:stream::open command enables you to open the stream of alerts from Helix Control-M.

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

cURL:

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

run alerts:stream::close

The run alerts:stream::close command enables you to close the stream of alerts from Helix Control-M. This disconnects the active Alerts listener and enables other users to open a different stream.

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

cURL:

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

run alerts:stream::status

The run alerts:stream::status command enables you to return the 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 Control-M Automation REST API Reference.

cURL:

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

run alerts:stream:template::set

The run alerts:stream:template::set command enables you to set a JSON template that determines what information to provide for each alert — 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 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.

cURL:

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

run alerts:listener::start

The run alerts:listener::starts command enables you to run 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.

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

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 stopped run of the Alerts listener.

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

The run alerts:listener:environment::set command enables you to set the Helix Control-M Environment Service to listen to for alerts.

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

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.

CLI Syntax

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 environment (as done by run alerts:listener:environment::set) or the Alerts Listener script (as done by run alerts:listener:script::set).

CLI Syntax

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