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
• Service Management 
• Variable Management
• Alert 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.

CLI Syntax

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:

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.

CLI Syntax

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:

REST API Syntax

See REST API reference.

Example using  curl:

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

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

Where:

REST API Syntax

See REST API reference.

Example using  curl:  

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. 

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. 

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

CLI Syntax

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:

Response

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

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

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:

_{Back to top}

run job:log::get

This command allows you to view the job log. 

CLI Syntax

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:

_{Back to top}

run job:status::get

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

CLI Syntax

Where:

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

See REST API reference.

Example using  curl:

_{Back to top}

run job:statistics::get

9.0.20.000 This command returns time statistics for the recent runs of a job.

CLI Syntax

Where:

Response

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

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

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

REST API Syntax

See REST API reference.

Example using  curl:

_{Back to top}

run job::kill

This command allows you to terminate the job.

CLI Syntax

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:

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

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:

_{Back to top}

run job::hold

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

CLI Syntax

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:  

_{Back to top}

run job::free

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

CLI Syntax

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:

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

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:

_{Back to top}

run job::undelete

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

CLI Syntax

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:

_{Back to top}

run job::confirm

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

CLI Syntax

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:

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

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:

_{Back to top}

run job::rerun

This command allows you to rerun a job (provided that it is not currently executing). When you use this command, the existing job constraints are applied.

CLI Syntax

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.

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

The configuration file for a z/OS job contains the following advance parameters:

REST API Syntax

See REST API reference.

Example using  curl:

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

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

Where:

REST API Syntax

See REST API reference.

Example using  curl:

_{Back to top}

run job::get

This command returns the definitions of a running job in JSON format.

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

CLI Syntax

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:  

_{Back to top}

run job::modify

This command enables you to modify the definitions of a running job that is currently held (that is, a job for which processing has been stopped), based on job definitions that you define through a Job Definitions file.

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

• Command
• Script
• EmbeddedScript
• FileTransfer
• Informatica

CLI Syntax

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:  

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

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:

run resource::delete

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

CLI Syntax

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:

run resource::update

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

CLI Syntax

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:

run resources::get

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

CLI Syntax

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

Response

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

Where:

REST API Syntax

See REST API reference.

Example using  curl:

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

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:

run event::delete

The delete event command allows you to remove an event. 

CLI Syntax

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:

run events::get

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

CLI Syntax

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

REST API Syntax

See REST API reference.

Example using  curl:

Response

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

_{Back to top}

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. You can manage the definitions of Workload Policies through a JSON file (separate from the JSON file used to define jobs and other objects). For more information about defining Workload Policies, see Workload-Policies-reference. For more general information about workload policies, see the documentation on Workload Policy in the Control-M Online Help.

run workloadpolicies:detailed::get

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 -s option can be used to query for a specific Workload Policy. If you do not include the -s option, details are returned for all defined Workload Policies.

REST API Syntax

See REST API reference.

Example using curl to retrieve definitions of all Workload Policies:

Example for retrieving the definitions of a specific Workload Policy:

run workloadpolicies::add

Creates new Workload Policies from definitions provided through a JSON file, as described in Workload-Policies-reference .

CLI Syntax

Where <workloadPoliciesFile> is the name of a JSON file that contains the definitions of the Workload Policies that you want to create. For more information, see Workload-Policies-reference.

REST API Syntax

See REST API reference.

Example using curl:

run workloadpolicy::delete

Deletes a specific Workload Policy.

CLI Syntax

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

REST API Syntax

See REST API reference.

Example using curl:

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

REST API Syntax

See REST API reference.

Example using  curl:

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

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:

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

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:

_{Back to top}

Service Management

9.0.19.230Services are groups of jobs that are aggregated based on criteria that you specify. Control-M Automation API can help you manage SLA services that are associated with SLA jobs (also known as Control-M BIM jobs) at the end of a job flow. Service Management in Control-M Automation API is supported for a Control-M environment with Control-M/EM version 9.0.18.200 or later.

run services:sla::get

Retrieves details of defined SLA-type services.

For more information, see Service Management in the Control-M Online Help.

CLI Syntax

REST API Syntax

See REST API reference.

Example using  curl:

Response

The following example shows the parameters in the response to the ctm run services:sla::get command. This example lists just one SLA-type service.

In this response, serviceLastUpdatedTime specifies the most recent date and time when the services were updated. After that, for each active SLA-type service, the following parameters are displayed:

_{Back to top}

Variable Management

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

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

For more information about variables, see Variables in the Control-M Online Help.

Note: You must have Control-M/Server and Control-M/EM version 9.0.21 or later to run Variable Management commands.

run variables::get

Retrieves details of defined pool variables that match a search query.

CLI Syntax

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

REST API Syntax

See REST API reference.

Note that in a RST API command, all backslashes must be escaped, as in the following curl example:

Response

The following example shows a response to the run variables::get command. Note that all backslashes are escaped in the JSON format.

run variables::set

Enables you to define new pool variables or update the definitions of existing pool variables.

CLI Syntax

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:

run variables::delete

Deletes variables from the server.

CLI Syntax

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:

_{Back to top}

Alert Management

9.0.20.105An alert is a message that indicates that a problem or exception has occurred for a Job or Folder. Control-M Automation API enables you to update basic properties of alerts, as well as the status of alerts. For more information, see the documentation about Alerts in the Control-M Online Help.

run alerts::update

Updates basic properties of alerts, including the urgency of the alerts and the associated comments.

CLI Syntax

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

Here is an example of a configuration file:

REST API Syntax

See REST API reference.

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

run alerts:status::update

Updates the status of the alert.

CLI Syntax

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

Here is an example of a configuration file:

REST API Syntax

See REST API reference.

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

_{Back to top}