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

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

CLI
ctm run <jobDefinitionsFile> [deployDescriptorFile]

Where:

Parameter

Description

<jobDefinitionsFile>

The file or archive that contains code for jobs. Files must be in JSON format.

[deployDescriptorFile](Optional) The file that includes the rules to apply on the original definitionsFile. The rules enable transforming Control-M JSON code properties. For detailed information, see Deploy Descriptor.

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

REST API Syntax

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. build will take place as part of the run.

> 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

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

Where:

Parameter

Description

<ctm>

Control-M/Server
<folder>Folder name that is ordered

[jobs]

The jobs that you want to run:

  • For most types of jobs, this parameter is optional. The default (when not defined) is all jobs in the specified folder.
    You can specify a single job or use the asterisk * wildcard to specify multiple jobs.
  • For a z/OS job, specify either a single job or * for all jobs in the folder.
[z/OS library]For a z/OS job : The name of the z/OS library that contains the jobs
For example: CTMP.V900.SCHEDULE
[configuration file]

(Optional) JSON file that contains additional 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.

The following is a list of the additional REST request parameters that can be used:

{ 	
  "variables": [{"arg":"12345"}],
  "hold": "true",
  "ignoreCriteria": "true",
  "independantFlow": "false",
  "orderDate": "20170903",
  "waitForOrderDate": "false",
  "createDuplicate": "false",
  "orderIntoFolder": "Recent"
}

Where:

ParameterDescription
variables

Job variable for the run

hold

Enables you to make changes to a job before it starts running.

Default: false

ignoreCriteria

Enables you to run a job when ordered, r egardless of scheduling criteria.

Default: true

independantFlow

Whether a flow in a folder is ordered uniquely.

Default: true

orderDate

The work day on which to schedule the job. This can be either "current" or a future date in YYYMMDD format.

Default: current

waitForOrderDate

Enables you to wait for the defined Order date to run

Default: false

createDuplicate

Whether jobs/sub-folders with the same name that already exist in the Folder are to be added to the SMART folder when you select Recent or Selected . Default: true

orderIntoFolder

Determines how to order jobs or Sub Folders that belong to a SMART Folder. Jobs and Sub Folders are added to a SMART Folder according to the following Order Into Folder options:

  • (Default) New: insert jobs into a new folder
  • Recent: insert jobs into a recent folder
  • OrderID: insert jobs into a selected folder. Use the Folder Order ID field to select.
  • Alone: insert the jobs into a regular folder. If this option is selected, the Create Duplicate field is disabled.

If the job or Sub Folder is inserted into an existing folder or Sub Folder that has already completed, the status of all parent folders is set to Executing. If it is not possible due to scheduling criteria, the job remains in WAIT_SCHEDULING status. This parameter is ignored if the folder that is ordered is not a SMART Folder.

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\",
  \"independantFlow\": \"false\",
  \"orderDate\": \"20170903\",
  \"waitForOrderDate\": \"false\",
  \"createDuplicate\": \"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\",
  \"independantFlow\": \"false\",
  \"orderDate\": \"20170903\",
  \"waitForOrderDate\": \"false\",
  \"createDuplicate\": \"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:

Parameter

Description

<runId>

Value returned in a ctm run invocation. It enables job tracking during a specific run.
startIndex

(Optional) enable iteration over all statuses. Result includes "itemsPerPage": 25 items from this index. If not defined, the default is 0.

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:

ParameterDescription
jobIdEach job in the run has a  jobId . The jobId  is used to reference a specific job
folderIdThe folderId is used to reference a specific folder
numberOfRunsNumber of job runs
nameName of job
typeJob type
statusJob status
held

Whether the job was held — true | false

deleted

Whether the job was deleted — true | false

startTimeThe time when the job started
endTimeThe time when the job ended
estimatedStartTime

The estimated date and time when the next job runs (up to 50) are expected to begin.

Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment.

estimatedEndTime

The estimated date and time when the next job runs (up to 50) are expected to end.

Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment


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

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

Field

Criteria

Criteria example
  • jobname
  • jobid
  • folder
  • folderLibrary
  • ctm
  • application
  • subApplication
  • host
  • hostGroup
  • description
  • runAs
  • command
  • filePath
  • fileName
  • workloadPolicy
  • ruleBasedCalender
  • resourceMutex
  • resourceSemaphore
  • Supported wildcards are *, ?
  • To use multiple criteria separate by using comma
  • Wildcards are not supported for jobid
  • jobid=<ctm>:<orderid>

jobname=job1122

jobname=job11*

jobname=job11*,job77*

description=*a job that*

jobid=controlm:005gy

  • orderDateFrom
  • orderDateTo
  • fromTime
  • toTime
  • For orderDateFrom and orderDateTo: YYMMDD
  • For fromTime and toTime: YYYYMMDDhhmmss

orderDateFrom=180123

fromTime=20180123184500

status
  • Ended OK
  • Ended Not OK
  • Wait User
  • Wait Resource
  • Wait Host
  • Wait Workload
  • Wait Condition
  • Executing
  • Status Unknown

To use multiple criteria, separate criteria with commas.

status=Ended OK

status=Ended OK,
Ended Not OK,Executing

neighborhood

Returns the status according to the dependencies between jobs. To create dependencies between jobs, use the flow object.

  • direction, with the following possible values:
    • depend - the jobs that depend on the specified job
    • predecessor - the jobs that the specified job depends on
    • radial - the jobs from both directions
  • depth - the number of job levels from the specified job

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

REST API Syntax

See REST API reference.

Example using curl:

curl -H "Authorization: Bearer $token" "$endpoint/run/jobs/status?jobname=jobA&status=Ended%20OK&application=A*"

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:

ParameterDescription
jobId A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status. The format of this ID is "Control-M/Server name:order ID of the job".
folderIdA unique identifier of the folder to which the job belongs. The format of this ID is "Control-M/Server name:order ID of the folder"
numberOfRunsNumber of job runs
nameName of job
folderName of the folder to which the job belongs
typeJob type
statusJob status
held

Whether the job was held — true | false

deleted

Whether the job was deleted — true | false

startTimeThe time when the job started
endTimeThe time when the job ended
estimatedStartTime

The estimated date and time when the next job runs (up to 50) are expected to begin.

Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment.

estimatedEndTime

The estimated date and time when the next job runs (up to 50) are expected to end.

Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment

orderDate

The work day on which the job was scheduled, in YYYMMDD format

ctmControl-M/Server name
descriptionA textual description of the job, as defined during job creation
hosthost of the Control-M/Agent where the job is running
application

The name of an application with which the job is associated. An application is a logical set of related jobs.

subApplication

The name of a sub-application with which the job is associated. A sub-application is a logical sub-category of an application.

For example, a group of payroll-related jobs are logically grouped together in a sub-application named Payroll, within an application named Finances.

outputURIURI to the job output
logURIURI to the job log


Back to top

run job:output::get

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

CLI Syntax

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

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

[runNo]

(Optional) The run number of the job to get the output. If not defined, the default is the last run.

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

REST API Syntax

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

CLI
ctm run job:log::get <jobId> 

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job:status::get <jobId>

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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:

ParameterDescription
<jobId>Each job in the run has a jobId. The jobId is used to reference the specific job and is returned by the ctm run status. The format used is Control-M/Server name ":" the order ID of the job.
<folderId>The folder run ID enables grouping runs by folder instances.
<rerun>Number of job runs
<name>Name of job
<type>Type of job
<status>

The following list includes valid job statuses:

  • Ended OK
  • Ended Not OK
  • Wait User
  • Wait Resource
  • Wait Host
  • Wait Workload
  • Wait Condition
  • Executing
  • Status Unknown
<startTime>The time when the job started
<endTime>The time when the job ended
<estimatedStartTime>

The estimated date and time when the next job runs (up to 50) are expected to begin.

Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment.

<estimatedEndTime>

The estimated date and time when the next job runs (up to 50) are expected to end.

Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment

<outputURI>URI to the job output
<logURI>URI to the job log

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

CLI
ctm run job::kill <jobId> 

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job::runNow <jobId> 

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job::hold <jobId> 

Where: 

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status

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

CLI
ctm run job::free <jobId> 

Where: 

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job::delete <jobId> 

Where: 

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job::undelete <jobId> 

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job::confirm <jobId> 

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job::setToOk <jobId> 

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job::rerun <jobId> 

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

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

CLI
ctm run job::waitingInfo <jobId> 

Where:

Parameter

Description

<jobId>

Each job in the run has a jobId. The jobId is used to reference a specific job and is returned by the ctm run status.

REST API Syntax

See REST API reference.

Example using  curl:

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

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

Where:

Parameter

Description

<ctm>Name of the Control-M/Server
<name>Name of the resource

<max>

Maximum quantity of resources available

Valid values: 0-9999

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

REST API Syntax

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

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

Where:

Parameter

Description

<ctm>Name of the Control-M/Server

<name>

Name of the resource

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

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

Where:

Parameter

Description

<ctm>Name of the Control-M/Server
<name>Name of the resource

<max>

Maximum quantity of resources available

Valid values: 0-9999

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

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

Field

Description

ctm

Name of the Control-M/Server
nameName of the resource
Search examples
-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:

ParameterDescription
<ctm>Name of the Control-M/Server
<name>Name of the resource
<available>Number of resources available
<max>Maximum resources available
<workloadPolicy>Name of workload policy that is linked to the resource. N/A indicates that the resource is not linked to a workload policy. For more information about workload policies, see the documentation on Workload Policy in the Control-M Online Help.

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

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

Where:

Parameter

Description

<ctm>Name of the Control-M/Server
<name>Name of the event

<date>

Date options to order the event:

  • MMDD - specific date
  • ODAT - represents the current Control-M date, example if the current Control-M date is August 7th, 2016, the ODAT converts to 0807.
  • STAT - can be used instead of a specific date for an event that is not date specific

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

REST API Syntax

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

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

Where:

Parameter

Description

<ctm>Name of the Control-M/Server
<name>Name of the event

<date>

Date options to order the event:

  • MMDD - specific date
  • ODAT - represents the current Control-M date, example if the current Control-M date is August 7th, 2016, the ODAT converts to 0807.
  • STAT - can be used instead of a specific date for an event that is not date specific

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

REST API Syntax

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

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

Field

Description

ctm

Name of the Control-M/Server
nameName of the event
dateDate of event
limit

Limits the number of returned matches.

Default: 1000 (if not defined)

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

CLI
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

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

Where:

Parameter

Description

[policyName]

The name of a Workload Policy or, for multiple Workload Policies, a string that contains an asterisk as a wildcard.

ctm

(Optional) The name of an associated Control-M/Server to use as a filter.

Only Workload Policies that are associated with the specified Control-M/Server are activated.

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

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

Where:

Parameter

Description

[policyName]The name of a Workload Policy or, for multiple Workload Policies, a string that contains an asterisk as a wildcard.
ctm

(Optional) The name of an associated Control-M/Server to use as a filter.

Only Workload Policies that are associated with the specified Control-M/Server are deactivated.

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

Was this page helpful? Yes No Submitting... Thank you

Comments