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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
curl -H "$AuthHeader" -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 controlm 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] [z/OS library] [-f <configuration file>]

The following table describes the run order command parameters.

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

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

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

REST API Syntax

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

endpoint=
token=
ctm=
folderName=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: 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\",
    \"hold\": \"true\",
    \"ignoreCriteria\": \"true\",
    \"orderDate\": \"20170903\",
    \"waitForOrderDate\": \"false\",
    \"placeInFolder\": \"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="Authentication: 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\",
    \"placeInFolder\": \"Recent\",
    \"variables\": [{\"arg\":\"12345\"}]
}" "$endpoint/run/order"

run userDaily:missing::list

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

This command requires Control-M/EM version 9.0.21.200 or later.

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
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
curl -H "$AuthHeader" "$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.

This command requires Control-M/EM version 9.0.21.200 or later.

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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
curl -H "$AuthHeader" "$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.

This command requires Control-M/EM version 9.0.21.200 or later.

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

REST API Syntax

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

userDaily=myUserDaily
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
curl -X POST -H "$AuthHeader" "$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 Control-M/EM database and the User Daily job does not need to trigger them. This command is useful for event-driven job executions.

This command requires Control-M/EM version 9.0.21.200 or later.

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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
curl -H "$AuthHeader" -X POST  -F "definitionsFile=@definitions.json" -F "deployDescriptorFile=@deployDescriptor.json" "$endpoint/run/ondemand"

run status

The run status command enables you to track the status of running jobs. The command shows how to check the job status with the runId.

CLI Syntax

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

ctm run status <runId> [startIndex]

The following table describes the run status command parameters.

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
 
curl -H "$AuthHeader" "$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": "controlm:00fhb",
            "folderId": "controlm: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": "controlm:00fhc",
            "folderId": "controlm: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": "controlm:00fhd",
            "folderId": "controlm: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

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$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": "LocalControlM:00008",
    "folderId": "LocalControlM: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": "LocalControlM",
    "description": "",
    "host": "",
    "application": "OsApp",
    "subApplication": "",
    "outputURI": "Job did not run, it has no output",
    "logURI": "http://localhost:48080/run/job/LocalControlM: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 Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/run/job/$jobId/output?runNo=0"

run job:log::get

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

CLI Syntax

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

ctm run job:log::get <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$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 Control-M/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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/run/job/$jobId/statistics"

run job::kill

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

CLI Syntax

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

ctm run job::kill <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/kill"

run job::runNow

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

CLI Syntax

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

ctm run job::runNow <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/runNow"

run job::hold

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

CLI Syntax

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

ctm run job::hold <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/hold"

run job::free

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

CLI Syntax

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

ctm run job::free <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/free"

run job::delete

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

CLI Syntax

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

ctm run job::delete <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/delete"

run job::undelete

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

CLI Syntax

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

ctm run job::undelete <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/undelete"

run job::confirm

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

CLI Syntax

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

ctm run job::confirm <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST "$endpoint/run/job/$jobId/confirm"

run job::setToOk

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

CLI Syntax

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

ctm run job::setToOk <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -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> [-f zosJobConfig.json]

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.

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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -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, users, or workloads).

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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" "$endpoint/run/job/$jobId/waitingInfo"

run job::get

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

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

CLI Syntax

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

ctm run job::get <jobId>

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

ctm run status

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

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X POST -F "jobDefinitionsFile=@examples/InformaticaJob.json" "$endpoint/run/job/$jobId/modify"

Resource Management

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

The following API commands enable you to manage Resource Pools:

• run resource::add

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

REST API Syntax

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

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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

REST API Syntax

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

server=controlm
name=newResource
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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

REST API Syntax

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

server=controlm
name=newResource
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -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 a specific Control-M/Server.

CLI Syntax

The following shows the CLI syntax for the run resource::update command:

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

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

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

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

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

Response

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

[
  {
    "name": "newResource",
    "ctm": "controlm",
    "available": "15",
    "max": 15,
    "workloadPolicy": "N/A"
  },
  {
    "name": "myRes",
    "ctm": "controlm",
    "available": "4",
    "max": 4,
    "workloadPolicy": "N/A"
  },

The following table describes additional run resources::get parameters for the 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=*"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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

REST API Syntax

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

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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

REST API Syntax

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

server=controlm
name=newEvent
date=0505
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X DELETE "$endpoint/run/event/$server/$name/$date"

run events::get

The run events::get command enables you to get all events from the Control-M/Server.

CLI Syntax

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

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

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

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

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

-s "name=eventA"
-s "name=A*&date=0805"
-s "server=controlm&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=controlm"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -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": "controlm",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2935",
    "ctm": "controlm",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_2974",
    "ctm": "controlm",
    "date": "0726"
  },
  {
    "name": "flow1_from_FlowAcc_goodJob_to_FlowAcc_badJob_3007",
    "ctm": "controlm",
    "date": "0726"
  }
]

Workload Policy Management

Workload Policies enable you to balance the workload on Control-M resources and hosts. A Workload Policy groups together jobs and enforces workload rules that limit resource usage by those jobs during specific time periods. You can manage the definitions of Workload Policies with a JSON file. This JSON file is separate from the file that defines jobs and other objects. For more information about defining Workload Policies, see Workload Policies Reference. For more general information about workload policies, see Workload Policy Definition.

The following API commands enable you to manage Workload Policies:

• run workloadpolicies:detailed::get

• run workloadpolicies::add

• run workloadpolicy::delete

• run workloadpolicies::get

• run workloadpolicy::activate

• run workloadpolicy::deactivate

run workloadpolicies:detailed::get

The run workloadpolicies:detailed::get command retrieves full details of all defined Workload Policies or a specific Workload Policy.

The response contains the full JSON details, as described in Workload Policies Reference.

CLI Syntax

The following shows the CLI syntax for the run workloadpolicies:detailed::get command:

ctm run workloadpolicies:detailed::get [-s "name=<policyName>"]

where -s runs a query for a specific Workload Policy. If you do not include the -s option, the system returns the details for all defined Workload Policies.

REST API Syntax

The following examples show the REST API syntax for the run workloadpolicies:detailed::get command in cURL:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json"
-X GET  "$endpoint/run/workloadpolicies/detailed"

policyname=WPtest
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json"
-X GET "$endpoint/run/workloadpolicies/detailed?name=$policyname"

run workloadpolicies::add

The run workloadpolicies::add command creates new Workload Policies from definitions in a JSON file, as described in Workload Policies Reference.

CLI Syntax

The following shows the CLI syntax for the run workloadpolicies::add command:

ctm run workloadpolicies::add <workloadPoliciesFile>

where <workloadPoliciesFile> is the name of a JSON file with the Workload Policy definitions that you want to create. For more information, see Workload Policies Reference.

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json"
-F "workloadpoliciesfile=@examples/WPs.json" -X POST "$endpoint/run/workloadpolicies"

run workloadpolicy::delete

The run workloadpolicy::delete command deletes a specific Workload Policy.

CLI Syntax

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

ctm run workloadpolicy::delete <policyName>

where <policyName> is the name of the specific Workload Policy that you want to delete.

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json"
-X DELETE "$endpoint/run/workloadpolicy/$policyname"

run workloadpolicies::get

The run workloadpolicies::get command retrieves details of defined Workload Policies, with the option to filter by status. The filter enables you to retrieve only active or inactive workload policies.

The response shows the current status of each active or inactive Workload Policy and the details of the last update to Workload Policy definitions.

CLI Syntax

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

ctm run workloadpolicies::get [Active|Inactive]

REST API Syntax

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

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json"
-X GET  "$endpoint/run/workloadpolicies?state=Active"

run workloadpolicy::activate

The run workloadpolicy::activate command activates an inactive Workload Policy.

If you want to activate multiple Workload Policies, specify a string that contains a * as a wildcard. In addition, you can optionally filter Workload Policies by an associated Control-M/Server.

CLI Syntax

The following shows the CLI syntax for the run workloadpolicy::activate command:

ctm run workloadpolicy::activate <policyName> [<server>]

The following table describes the run workloadpolicy::activate 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

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

policyname=WP*
server=LocalControlM
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/run/workloadpolicy/$policyname/activate?server=$server"

run workloadpolicy::deactivate

The run workloadpolicy::deactivate command deactivates an active Workload Policy.

If you want to deactivate multiple Workload Policies, specify a string that contains a * as a wildcard. In addition, you can optionally filter Workload Policies by an associated Control-M/Server.

CLI Syntax

The following shows the CLI syntax for the run workloadpolicy::deactivate command:

ctm run workloadpolicy::deactivate <policyName> [<server>]

The following table describes the run workloadpolicy::deactivate 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

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

policyname=WP*
server=LocalControlM
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/run/workloadpolicy/$policyname/deactivate?server=$server"

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.

Service Management in Control-M Automation API is supported for a Control-M environment withControl-M/EM 9.0.18.200 or later.

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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -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": "LocalControlM:0002c",
      "serviceControlM": "LocalControlM",
      "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",
        "waitWorkload": "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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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

REST API Syntax

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

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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

REST API Syntax

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

server=controlm
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -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:

AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -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
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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