Run service

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

• Job Management
• Resource Management
• Event Management
• Workload Policy Management
  

Job Management

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

run

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

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

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

CLI Syntax

ctm run <jobDefinitionsFile> [deployDescriptorFile]

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

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

_{Back to top}

run order

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

> ctm run order 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

ctm run order <ctm> <folder> [jobs] [z/OS library] [-f <configuration file>]

Where:

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

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

Here is an example of a configuration file:

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

REST API Syntax

See REST API reference.

Example using  curl:

endpoint=
token=
ctm=
folderName=

curl -X POST -H "Authorization: Bearer $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" 	

Here is another example for ordering a z/OS job using curl:

endpoint=
token=
ctm=M90CTM
folderName=
jobName=IOATEST
library=CTMP.V900.SCHEDULE

curl -X POST -H "Authorization: Bearer $token" --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"

_{Back to top}

run status

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

NOTE: To get a valid output from the outputURI and logURI fields when running commands through the CLI, you must use the token from the ctm session login. Copy the token and paste it in the ctm run status command as the input of the -t option. 

CLI Syntax

ctm run status <runId> [startIndex]

Where:

REST API Syntax

See REST API reference.

Example using  curl:  

curl -H "Authorization: Bearer $token" "$endpoint/run/status/$runId"

Response

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

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

> ctm run status "2d4af716-e31d-48ef-a434-16575303752d" 
{
  "statuses": [
    {
      "jobId": "controlm:00fhb",
	  "folderId": "controlm:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow",
      "type": "Folder",
      "status": "Executing",
	  "held": "false",
	  "deleted": "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",
      "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",
      "startTime": "",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "Job didn't run, it has no output"
    }
  ],
  "startIndex": 0,
  "itemsPerPage": 25
}

Where:

_{Back to top}

run jobs:status::get

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

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

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

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

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

CLI Syntax

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

Limit refers to the maximum number of job statuses returned.

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

Where:

REST API Syntax

See REST API reference.

Example of a curl request that includes a limit:

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

 Response

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

{
      "jobId": "LocalControlM:00008",
      "folderId": "LocalControlM:00007",
      "numberOfRuns": 0,
      "name": "job1",
      "folder": "SanityCommandOk",
      "type": "Command",
      "status": "Wait Condition",
      "held": true,
      "deleted": false,
      "startTime": "",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "orderDate": "180903",
      "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:

_{Back to top}

run job:output::get

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

CLI Syntax

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

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/output/?runNo=0"

_{Back to top}

run job:log::get

This command allows you to view the job log. 

CLI Syntax

ctm run job:log::get <jobId> 

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/log"

_{Back to top}

run job:status::get

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

CLI Syntax

ctm run job:status::get <jobId>

Where:

Response

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

{
      "jobId": "controlm:00fhc",
      "folderId": "controlm:005gy",
      "rerun": 1,
      "name": "AutomationAPISampleFlow/CommandJob",
      "type": "Command",
      "status": "Ended OK",
      "startTime": "Aug 4, 2016 1:53:30 PM",
      "endTime": "Aug 4, 2016 2:00:30 PM",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "http://localhost:48080/run/output/controlm:00fhc",
      "logURI": "http://localhost:48080/run/log/controlm:00fhc"
    }

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/status"

_{Back to top}

run job::kill

This command allows you to terminate the job.

CLI Syntax

ctm run job::kill <jobId> 

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/kill"

_{Back to top}

run job::runNow

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

CLI Syntax

ctm run job::runNow <jobId> 

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/runNow"

_{Back to top}

run job::hold 

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

CLI Syntax

ctm run job::hold <jobId> 

Where: 

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

REST API Syntax

See REST API reference.

Example using  curl:  

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/hold"

_{Back to top}

run job::free 

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

CLI Syntax

ctm run job::free <jobId> 

Where: 

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

REST API Syntax 

See REST API reference. 

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/free"

_{Back to top}

run job::delete 

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

CLI Syntax

ctm run job::delete <jobId> 

Where: 

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

REST API Syntax 

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/delete"

_{Back to top}

run job::undelete 

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

CLI Syntax

ctm run job::undelete <jobId> 

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/undelete"

_{Back to top}

run job::confirm 

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

CLI Syntax

ctm run job::confirm <jobId> 

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/confirm"

_{Back to top}

run job::setToOk 

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

CLI Syntax

ctm run job::setToOk <jobId> 

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/setToOk"

_{Back to top}

run job::rerun

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

CLI Syntax

ctm run job::rerun <jobId> 

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" -X POST "$endpoint/run/job/$jobId/rerun"

_{Back to top}

run job::waitingInfo

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

CLI Syntax

ctm run job::waitingInfo <jobId> 

Where:

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "Authorization: Bearer $token" "$endpoint/run/job/$jobId/waitingInfo"

_{Back to top}

Resource Management

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

run resource::add

The add resource command allows you to add a quantitative resource to a Control-M/Server. 

CLI Syntax

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

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newResource\",
\"max\":5}" "$endpoint/run/resource/$ctm"

run resource::delete

The delete resource command allows you to delete a quantitative resource. 

CLI Syntax

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

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
name=newResource
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/run/resource/$ctm/$name"

run resource::update

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

CLI Syntax

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

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
name=newResource

curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"max\":6}" "$endpoint/run/resource/$ctm/$name" 

run resources::get

The get resources command allows you to get all resource records from a specific Control-M/Server.

CLI Syntax

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

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

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

Where:

-s "name=resourceA"
-s "name=A*"
-s "ctm=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"
  },

Where:

REST API Syntax

See REST API reference.

Example using  curl:

search_criteria="name=A*&ctm=*"
curl -H "Authorization: Bearer $token" -X GET "$endpoint/run/resources?$search_criteria" 

_{Back to top}

Event Management

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

run event::add

The add event command allows you to add events to the Control-M/Server.

CLI Syntax

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

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newEvent\",\"date\":\"0505\"}"  "$endpoint/run/event/$ctm"

run event::delete

The delete event command allows you to remove an event. 

CLI Syntax

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

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

ctm=controlm
name=newEvent
date=0505
curl -H "Authorization: Bearer $token" -X DELETE "$endpoint/run/event/$ctm/$name/$date"

run events::get

The get events command allows you to get all events from the Control-M/Server.

CLI Syntax

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

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

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

Where:

-s "name=eventA"
-s "name=A*&date=0805"
-s "ctm=controlm&name=eventA,eventB&date=0805"

REST API Syntax

See REST API reference.

Example using  curl:

search_criteria="name=A*&ctm=controlm" 
curl -H "Authorization: Bearer $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": "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 any number of jobs and enforces workload rules that limit resource usage by those jobs during specific time periods. For more information about workload policies, see the documentation on Workload Policy in the Control-M Online Help.

run workloadpolicies::get

Retrieves details of defined Workload Policies, with the option of filtering by status (that is, retrieving only active workload policies or only inactive workload policies).

Details in the response include the current status of each Workload Policy (whether active or inactive) and details of the last update to Workload Policy definitions.

CLI Syntax

ctm run workloadpolicies::get [Active|Inactive]

REST API Syntax

See REST API reference.

Example using  curl:

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

run workloadpolicy::activate

Activates a Workload Policy that is currently inactive.

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

CLI Syntax

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

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

policyname=WP*
ctm=LocalControlM
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" 
-X POST "$endpoint/run/workloadpolicy/$policyname/activate?ctm=$ctm"

run workloadpolicy::deactivate

Deactivates a Workload Policy that is currently active.

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

CLI Syntax

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

Where:

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

REST API Syntax

See REST API reference.

Example using  curl:

policyname=WP*
ctm=LocalControlM
curl -H "Authorization: Bearer $token" -H "Content-Type: application/json" 
-X POST "$endpoint/run/workloadpolicy/$policyname/deactivate?ctm=$ctm"

_{Back to top}