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

• 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 job::bypass

• run forecast:timeline::get

• run forecast:timeline::poll

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

The following shows the CLI syntax for the run command:

ctm run <jobDefinitionsFile> [deployDescriptorFile]

The following table describes the run command parameters.

If annotation is enabled for the Scheduling definitions category in the Configuration domain, 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:

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.

> 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

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.

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

The following table describes additional parameters that you can specify in the configuration file:

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

REST API Syntax

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

endpoint=
token=
ctm=
folderName=
 
curl -X POST -H "x-api-key: $token" --header "Content-Type: application/json" --header "Accept: application/json" -d "{
    \"ctm\": \"$ctm\",
    \"folder\": \"$folderName\",
    \"hold\": \"true\",
    \"ignoreCriteria\": \"true\",
    \"orderDate\": \"20170903\",
    \"waitForOrderDate\": \"false\",
    \"orderIntoFolder\": \"Recent\",
    \"variables\": [{\"arg\":\"12345\"}]
}" "$endpoint/run/order"

The following shows an example for ordering a z/OS job using cURL:

endpoint=
token=
ctm=M90CTM
folderName=
jobName=IOATEST
library=CTMP.V900.SCHEDULE
AuthHeader="x-api-key: $token"
# AuthHeader="Authorization: Bearer $token"  #for a session token
 
curl -X POST -H "$AuthHeader" --header "Content-Type: application/json" --header "Accept: application/json" -d "{
    \"ctm\": \"$ctm\",
    \"folder\": \"$folderName\",
    \"jobs\": \"$jobName\",
    \"library\": \"$library\",
    \"hold\": \"true\",
    \"ignoreCriteria\": \"true\",
    \"orderDate\": \"20170903\",
    \"waitForOrderDate\": \"false\",
    \"orderIntoFolder\": \"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.

> 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

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.

REST API Syntax

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

server=controlm
userDaily=myUserDaily
curl -H "x-api-key: $token" "$endpoint/run/userDaily/$userDaily/missing/list/$server"

run userDaily:missing::poll

The run userDaily:missing::poll command enables you to view a previously generated list of jobs that were not ordered because a specific Order Method (a specific User Daily job) was interrupted for various reasons, such as an operating system crash.

CLI Syntax

The following shows the CLI syntax for the run userDaily:missing::poll command:

ctm run userDaily:missing::poll <pollId>

where <pollID> is the poll ID returned by the run userDaily:missing::list command.

REST API Syntax

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

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

Response

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

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

You can reorder the pending jobs with the run userDaily:missing::poll command.

run userDaily:missing::run

The run userDaily:missing::run command enables you to reorder the jobs that did not run because a specific Order Method (a specific User Daily job) was interrupted for various reasons, such as an operating system crash.

The command returns a runId to check the job status with the run status command.

CLI Syntax

The following shows the CLI syntax for the run userDaily:missing::run command:

ctm run userDaily:missing::run <orderMethod>

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

If annotation is enabled for the Active network category in the Configuration domain, 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:

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.

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.

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.

REST API Syntax

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

curl -H "x-api-key: $token" -X POST  -F "[email protected]" -F "[email protected]" "$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.

REST API Syntax

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

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

Response

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

> ctm run status "2d4af716-e31d-48ef-a434-16575303752d"
{    
  "completion": "Completed",
  "statuses": [
    {
      "jobId": "IN01:00fhb",
      "folderId": "IN01:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow",
      "type": "Folder",
      "status": "Executing",
      "held": "false",
      "deleted": "false",
      "cyclic": "false",
      "startTime": "May 18, 2018 11:57:26 AM",
      "endTime": "",
      "estimatedStartTime": [
          "20180518121500,",
          "20180518123000,"],
      "estimatedEndTime": [
          "20180518121502,",
          "20180518123005,"],
      "outputURI": "Folder has no output"
    },
    {
      "jobId": "IN01:00fhc",
      "folderId": "IN01:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow/CommandJob",
      "type": "Command",
      "status": "Wait Host",
      "held": "false",
      "deleted": "false",
      "cyclic": "false",
      "startTime": "",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "Job didn't run, it has no output"
    },
    {
      "jobId": "IN01:00fhd",
      "folderId": "IN01:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow/ScriptJob",
      "type": "Job",
      "status": "Wait Condition",
      "held": "false",
      "deleted": "false",
      "cyclic": "false",
      "startTime": "",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "Job didn't run, it has no output"
    }
  ],
  "startIndex": 0,
  "itemsPerPage": 25
}

The following table describes the parameters in the run status response.

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.

The following table describes the query fields that you can use with -s.

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

The following example shows the REST API syntax for the run jobs:status::get command that includes a limit in cURL:

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

Response

The following example shows the parameters for one of the jobs returned in the response to the run jobs:status::get command.

{
      "jobId": "IN01:00008",
      "folderId": "IN01:00007",
      "numberOfRuns": 0,
      "name": "job1",
      "folder": "SanityCommandOk",
      "type": "Command",
      "status": "Wait Condition",
      "held": true,
      "deleted": false,
      "cyclic": "false",
      "startTime": "20231126065554",
      "endTime": "20231126065555",
      "estimatedStartTime": ["20231126123810"],
      "estimatedEndTime": ["20231126124310"],
      "orderDate": "231125",
      "ctm": "IN01",
      "description": "",
      "host": "",
      "application": "OsApp",
      "subApplication": "",
      "outputURI": "Job did not run, it has no output",
      "logURI": "http://localhost:48080/run/job/IN01:00008/log"
}

The following table describes the parameters in this sample response:

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.

If annotation is enabled for the AJF get job information category in the Configuration domain, 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:

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

run job:log::get

The run job:log::get command enables you to access the job log.

CLI Syntax

The following shows the CLI syntax for the run job:log::get command:

ctm run job:log::get <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the AJF get job information category in the Configuration domain, 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:

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

run job:status::get

The run job:status::get command enables you to view a specific job run status.

CLI Syntax

The following shows the CLI syntax for the run job:status::getcommand:

ctm run job:status::get <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

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

REST API Syntax

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

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

run job:statistics::get

The run job:statistics::get command enables you to get time statistics for the recent runs of a job.

CLI Syntax

The following shows the CLI syntax for the run job:statistics::get command:

ctm run job:statistics::get <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

Response

The response provides the following time statistics for each job run:

• Order date

• Start and end time

• Run time

• CPU time

• Average of the key time statistics from all runs

If the system collects periodic statistics for this job, it presents job run statistics separately for each period.

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

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

REST API Syntax

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

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

run job::kill

The run job::kill command enables you to terminate the job.

CLI Syntax

The following shows the CLI syntax for the run job::kill command:

ctm run job::kill <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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

run job::runNow

The run job::runNow command enables you to immediately start the job. The system does not apply job constraints when you use this command.

CLI Syntax

The following shows the CLI syntax for the run job::runNow command:

ctm run job::runNow <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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

run job::hold

The run job::hold command enables you to hold the job and stop processing it.

CLI Syntax

The following shows the CLI syntax for the run job::hold command:

ctm run job::hold <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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

run job::free

The run job::free command enables you to continue the job run from the hold state.

CLI Syntax

The following shows the CLI syntax for the run job::free command:

ctm run job::free <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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

run job::delete

The run job::delete command enables you to mark the job for deletion. The system deletes the job on the next scheduled date.

CLI Syntax

The following shows the CLI syntax for the run job::delete command:

ctm run job::delete <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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

run job::undelete

The run job::undelete command enables you to remove a deletion mark from a job.

CLI Syntax

The following shows the CLI syntax for the run job::undelete command:

ctm run job::undelete <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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

run job::confirm

The run job::confirm command enables you to run a job that is waiting for confirmation.

CLI Syntax

The following shows the CLI syntax for the run job::confirm command:

ctm run job::confirm <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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

run job::setToOk

The run job::setToOk command enables you to set job status to OK after the job is processed. You can use this command, for example, after you resolve issues that cause a job to end in status Not OK.

CLI Syntax

The following shows the CLI syntax for the run job::setToOk command:

ctm run job::setToOk <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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.

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

If you are rerunning a z/OS job, you can specify additional parameters in the configuration file:

{
  "zosParameters": {
    "from": {
      "pgm": "INPROCS2",
      "proc": "STEP1"
    },
    "to": {
      "pgm": "INPROCS3",
      "proc": "STEP2"
    },
    "cleanup": true,
    "recaptureAbend": "Y",
    "recaptureConditionCode": "N",
    "stepAdjustment": true,
    "restartParmMemberName": "IDJOB5"
  }
}

The following table describes the advanced parameters in the configuration file for a z/OS job:

"from": {
    "pgm": "STEP2",
    "proc": ""
},
"to": {
    "pgm": "STEP3",
    "proc": ""
},

//M99#STEP JOB (EE00,111,30),NOTIFY=&SYSUID,MSGCLASS=X 
//*                                                         
//STEP1   EXEC  PGM=IOATEST,PARM='WAIT=1'                   
//STEP2   EXEC  PGM=IOATEST,PARM='WAIT=1'                   
//STEP3   EXEC  PGM=IOATEST,PARM='WAIT=1'                   
//*

Num Pgm-stp  Proc-stp  Pgm=      Comp
001 STEP1              IOATEST   0000
002 STEP2              IOATEST   0004
003 STEP3              IOATEST   0000

"from": {
    "pgm": "INPROCS2",
    "proc": "STEP1"
},
"to": {
    "pgm": "INPROCS3",
    "proc": "STEP2"
},

//M99#PROC JOB (EE00,111,30),EDUC,NOTIFY=&SYSUID,MSGCLASS=X  
//*                                                          
//SAMPPROC PROC                                              
//INPROCS1  EXEC PGM=IOATEST                                  
//INPROCS2  EXEC PGM=IOATEST                                  
//INPROCS3  EXEC PGM=IOATEST                                  
//         PEND                                              
//*                                                          
//STEP1   EXEC  SAMPPROC                                      
//STEP2   EXEC  SAMPPROC                                      
//STEP3   EXEC  SAMPPROC                                      
//*

Num Pgm-stp  Proc-stp  Pgm=      Comp
001 INPROCS1 STEP1     IOATEST   0000
002 INPROCS2 STEP1     IOATEST   0004
003 INPROCS3 STEP1     IOATEST   0000
004 INPROCS1 STEP2     IOATEST   0000
005 INPROCS2 STEP2     IOATEST   0000
006 INPROCS3 STEP2     IOATEST   0000
007 INPROCS1 STEP3     IOATEST   0000
008 INPROCS2 STEP3     IOATEST   0000
009 INPROCS3 STEP3     IOATEST   0000

REST API Syntax

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

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

For a z/OS job, include the advanced parameters described above in the body of the REST request, using the -d (or --data) option.

run job::waitingInfo

The run job::waitingInfo command enables you to display the reasons why a waiting job 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:

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

run job::get

The run job::get command enables you to return the definitions of a running job in JSON format.

For a description of the returned job format, see Code Reference.

CLI Syntax

The following shows the CLI syntax for the run job::get command:

ctm run job::get <jobId>

where <jobId> is a unique identifier to reference the specific job. The jobId is returned by the following command:

ctm run status

The format of this ID is <server>:<orderId>.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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.

If annotation is enabled for the Active network category in the Configuration domain, 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:

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

run job::bypass

The run job::bypass command enables you to bypass or ignore job options such as a resource, event, or time limit when you submit a job.

CLI Syntax

The following shows the CLI syntax for the run job::bypass command:

ctm run job::bypass <jobId|folderId> -f <bypassOptions.json>

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

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

The following sample bypassOptions.json file presents the advanced bypass parameters that you can configure:

{
   "timeLimits":false,
   "waitForEvents":false,
   "resourcesFromPool":false,
   "lockResources":false,
   "workloadPolicyAndHostRestrictions":false,
   "schedulingEnvironment":false,
   "pipes":false,
   "pause":false,
   "runJobAsDummy":false,
   "runJobWithoutPostProcessing":false
}

The following table describes the advanced bypass parameters in the bypassOptions file:

REST API Syntax

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

curl -H "x-api-key: $token" -X POST -F "bypassOption.json" "$endpoint/run/job/$jobId/bypass"

run forecast:timeline::get

The run forecast:timeline::get command requests a timeline forecast for when jobs, folders, or calendars are scheduled to run.

You can use this command to test the effect of different calendars on job scheduling.

The command returns a poll ID, which you can use to track the status of the request (using the run forecast:timeline::poll command).

CLI Syntax

The following shows the CLI syntax for the run forecast:timeline::get command:

ctm run forecast:timeline::get -s <search query>

where -s runs a search with the query string format "field1=criteria1&field2=criteria2".

The following table describes the fields that you can use in the run forecast:timeline::get query.

REST API Syntax

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

ctm=controlm
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X GET "$endpoint/run/forecast/timeline?ctm=$ctm&folder=Folder1&filterType=year&year=2023"

Response

{
  "pollId": "794f74e1-ced2-415d-b836-5b7570ac90d9",
  "statusURI": "https://sqa:8443/automation-api/run/forecast/timeline/794f74e1-ced2-415d-b836-5b7570ac90d9"
}

run forecast:timeline::poll

The run forecast:timeline::poll command tracks the status of timeline generation (requested using the run forecast:timeline::get command). If timeline generation has completed, this command returns the timeline, with information about when the jobs are scheduled to run in the relevant months, years, or period covered by the rule-based calendar.

CLI Syntax

The following shows the CLI syntax for the run forecast:timeline::poll command:

ctm run forecast:timeline::poll <pollId>

where <pollId> is the poll ID returned by the run forecast:timeline::get command to track timeline generation.

REST API Syntax

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

pollId="794f74e1-ced2-415d-b836-5b7570ac90d9"
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X GET "$endpoint/run/forecast/timeline/poll/$pollId"

Response

{
   "Schedule": [
      {
         "jobPath": "Folder1/Job1",
         "when": {
            "years": [
               {
                  "year": "2020",
                  "JAN": [
                     "6-9"
                  ],
                  "FEB": [
                     "5",
                     "29"
                  ],
                  "OCT": [
                     "14"
                  ]
               }
            ]
         }
      }
   ]
}

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

• 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

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.

If annotation is enabled for the Independent AJF entities category in the Configuration domain, 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:

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.

If annotation is enabled for the Independent AJF entities category in the Configuration domain, 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:

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.

If annotation is enabled for the Independent AJF entities category in the Configuration domain, 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:

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 resources::get command:

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

where -s runs a search with the query string format "field1=criteria1&field2=criteria2".

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

The following table describes the fields that you can use in the run resources::get query.

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

Response

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

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

The following table describes the parameters in the run resources::get response.

REST API Syntax

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

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

Event Management

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

The following API commands enable you to manage Events:

• run event::add

• run event::delete

• run events::get

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.

If annotation is enabled for the Independent AJF entities category in the Configuration domain, 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:

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.

If annotation is enabled for the Independent AJF entities category in the Configuration domain, 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:

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

run events::get

The run events::get command enables you to get all events from the Server.

CLI Syntax

The following shows the CLI syntax for the run events::get command:

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

where -s runs a search with the query string format "field1=criteria1&field2=criteria2".

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

The following table describes the fields that you can use in the run events::get query.

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

REST API Syntax

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

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

Response

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

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

Service Management

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:

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.

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

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

• 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

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:

REST API Syntax

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

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

Response

The following example shows a response to the run variables::get command:

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

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.

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

If annotation is enabled for the Independent AJF entities category in the Configuration domain, 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:

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.

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

If annotation is enabled for the Independent AJF entities category in the Configuration domain, 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:

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

• run alerts:status::update

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:

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

REST API Syntax

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

curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts" -d @alertModifyValue.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.

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

REST API Syntax

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

endpoint=
alertIds=15,20

curl -H "x-api-key: $token" -H "Content-Type: application/json"
-X POST "$endpoint/run/alerts/status/$alertIds" -d @alertModifyStatus.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.

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:

run alerts:stream::open

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

CLI Syntax

The following shows the CLI syntax for the run alerts:stream::open command:

ctm run alerts:stream::open

If annotation is enabled for the Alerts Handling category in the Configuration domain , you must also provide an annotation to justify your action. For more information, see Annotation Input.

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

REST API Syntax

See Control-M Automation REST API Reference.

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

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

run alerts:stream::close

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

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.

If annotation is enabled for the Alerts Handling category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

See Control-M Automation REST API Reference.

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

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

run alerts:stream::status

The run alerts:stream::status command enables you to return the following:

• The status of the monitoring service that streams the alerts from Helix Control-M.

• The connection status to the listener process on your client.

• The most recent date and time of the last update.

CLI Syntax

The following shows the CLI syntax for the run alerts:stream::status command:

ctm run alerts:stream::status

REST API Syntax

See Control-M Automation REST API Reference.

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

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

run alerts:stream:template::set

The run alerts:stream:template::set command enables you to set a JSON template that determines what information to provide for each alert. The information includes fields of information, their names, and order of appearance. The template that you provide overrides the default combination of fields provided by Helix Control-M.

CLI Syntax

The following shows the CLI syntax for the run alerts:stream:template::set command:

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

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

For more information about the default fields and how to author the JSON template, see External Alerts Fields and Templates.

If annotation is enabled for the Alerts Handling category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

See Control-M Automation REST API Reference.

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

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

run alerts:listener::start

The run alerts:listener::start command enables you to run the Alerts Listener for the defined environment and triggers a defined alert script each time it receives an alert.

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

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.

If annotation is enabled for the Alerts Handling category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

A successful response returns a process ID for the Alerts Listener.

run alerts:listener::stop

The run alerts:stream::stop command enables you to stop the Alerts Listener for the defined environment.

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

CLI Syntax

The following shows the CLI syntax for the run alerts:stream::stop command:

ctm run alerts:listener::stop

If annotation is enabled for the Alerts Handling category in the Configuration domain, you must also provide an annotation to justify your action. For more information, see Annotation Input.

run alerts:listener:environment::set

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

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

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.

CLI Syntax

The following shows the CLI syntax for the run alerts:listener:script::set command:

ctm run alerts:listener:script::set <script_path> [<alert_type>]

The following table describes the run alerts:listener:script::set command parameters.

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.

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