New Documentation

   

Control-M Automation API Documentation has moved to a new location, with a new design to enhance ease of use.

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/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 "x-api-key: $token" -X POST  -F "jobDefinitionsFile=@examples/AutomationAPISampleFlow.json" -F "deployDescriptorFile=@examples/deployDescriptor.json" "$endpoint/run"

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 IN01 AutomationAPISampleFlow
{
  "runId": "e0ddf056-4497-49f7-9d8b-25758b132bd6",
  "statusURI": "https://ec2-54-201-124-17.us-west-2.compute.amazonaws.com/automation-api/run/status/e0ddf056-4497-49f7-9d8b-25758b132bd6"
}

CLI Syntax

CLI
ctm run order <ctm> <folder> [jobs] [-f <configuration file>]

Where:

Parameter

Description

<ctm>

Server name (currently IN01)
<folder>Folder name that is ordered

[jobs]

(Optional) The jobs that you want to run. You can specify a single job or use the asterisk * wildcard to specify multiple jobs.

The default (when not defined) is all jobs in the specified folder.

[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.

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

ParameterDescription
variables

Defines job variables for the run, expressed as name:value pairs.

hold

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

Values: true|false

Default: false

ignoreCriteria

Enables you to run a job when ordered, ignoring the configured scheduling criteria.

Values: true|false

Default: true

independentFlow

Determines whether a flow in a folder is ordered uniquely.

Not applicable to Sub Folders.

Values: true|false

Default: true

orderDate

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

Default: current

waitForOrderDate

Enables you to wait for the defined Order date to run.

Values: true|false

Default: false

createDuplicate

Determines whether jobs/sub-folders with the same name that already exist in the Folder are to be added to the SMART folder.

This is relevant when orderIntoFolder (next parameter) is set to Recent or to a specific Order ID.

Values: true|false

Default: true

orderIntoFolder

Determines how to order jobs or Sub Folders that belong to a 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
  • <Folder Order ID>: insert jobs into a selected folder. 
  • Alone: insert the jobs into a regular folder. If this option is selected, createDuplicate (the previous parameter) is not relevant.

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.

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 "x-api-key: $token" --header "Content-Type: application/json" --header "Accept: application/json" -d "{
  \"ctm\": \"$ctm\",
  \"folder\": \"$folderName\",
  \"hold\": \"true\",
  \"ignoreCriteria\": \"true\",
  \"orderDate\": \"20170903\",
  \"waitForOrderDate\": \"false\",
  \"orderIntoFolder\": \"Recent\",
  \"variables\": [{\"arg\":\"12345\"}]
}" "$endpoint/run/order" 	

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.

CLI Syntax

ctm run status <runId> [startIndex]

Where:

Parameter

Description

<runId>

Value returned in a run invocation. It enables job tracking during a specific run invoked by the same user.

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 "x-api-key: $token" "$endpoint/run/status/$runId"

Response

The following example shows the parameters in the 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" 
{     
  "completion": "Completed",
  "statuses": [
    {
      "jobId": "IN01:00fhb",
	  "folderId": "IN01:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow",
      "type": "Folder",
      "status": "Executing",
	  "held": "false",
	  "deleted": "false",
      "cyclic": "false",
      "startTime": "May 18, 2018 11:57:26 AM",
      "endTime": "",
      "estimatedStartTime": [
          "20180518121500,",
          "20180518123000,"],
      "estimatedEndTime": [
          "20180518121502,",
          "20180518123005,"],
      "outputURI": "Folder has no output"
    },
    {
      "jobId": "IN01:00fhc",
	  "folderId": "IN01:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow/CommandJob",
      "type": "Command",
      "status": "Wait Host",
      "held": "false",
	  "deleted": "false",
      "cyclic": "false",
      "startTime": "",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "Job didn't run, it has no output"
    },
    {
      "jobId": "IN01:00fhd",
	  "folderId": "IN01:005gy",
      "numberOfRuns": 3,
      "name": "AutomationAPISampleFlow/ScriptJob",
      "type": "Job",
      "status": "Wait Condition",
      "held": "false",
	  "deleted": "false",
      "cyclic": "false",
      "startTime": "",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "outputURI": "Job didn't run, it has no output"
    }
  ],
  "startIndex": 0,
  "itemsPerPage": 25
}

Where:

ParameterDescription
completion

Whether the job has run — Completed | Pending.

If "Pending", you can run the run status command again until value is "Completed".

jobIdA unique identifier of the job. The jobId is used to reference the specific job. The format of this ID is <server>:<orderId>.
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

cyclicWhether the job is defined as a cyclic job — 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 SLA Management is installed 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 SLA Management is installed 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=IN01: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
  • server
  • application
  • subApplication
  • host
  • hostGroup
  • description
  • runAs
  • command
  • filePath
  • fileName
  • ruleBasedCalender
  • resourceLock
  • resourcePool
  • Supported wildcards are *, ?
  • To use multiple criteria separate by using comma
  • Wildcards are not supported for jobid
  • jobid=<server>:<orderId>

jobname=job1122

jobname=job11*

jobname=job11*,job77*

description=*a job that*

jobid=IN01: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 Condition
  • Executing
  • Status Unknown

To use multiple criteria, separate criteria with commas.

status=Ended OK

status=Ended OK,
Ended Not OK,Executing

  • held
  • folderHeld
  • cyclic
  • deleted

true | false

"held=true&folderHeld=true&cyclic=false&deleted=false"
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
=IN01:0a98&depth=1&direction=predecessor"

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": "IN01:00008",
      "folderId": "IN01:00007",
      "numberOfRuns": 0,
      "name": "job1",
      "folder": "SanityCommandOk",
      "type": "Command",
      "status": "Wait Condition",
      "held": true,
      "deleted": false,
      "cyclic": "false",
      "startTime": "",
      "endTime": "",
      "estimatedStartTime": [],
      "estimatedEndTime": [],
      "orderDate": "180903",
      "ctm": "IN01",
      "description": "",
      "host": "",
      "application": "OsApp",
      "subApplication": "",
      "outputURI": "Job did not run, it has no output",
      "logURI": "http://localhost:48080/run/job/IN01:00008/log"
    }

The following table describes the parameters in this sample response:

ParameterDescription
jobId

A unique identifier of the job. The jobId is used to reference the specific job and is returned by run status. The format of this ID is <server>:<orderId>.

folderIdA unique identifier of the folder to which the job belongs. The format of this ID is <server>:<orderId>.
numberOfRunsNumber of job runs
nameName of job
folderName of the folder to which the job belongs
typeJob type
status

Job status

The following list includes valid job statuses:

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

Whether the job was held — true | false

deleted

Whether the job was deleted — true | false

cyclicWhether the job is defined as a cyclic job — 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 SLA Management is installed 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 SLA Management is installed in your environment.

orderDate

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

ctmServer name (currently IN01)
descriptionA textual description of the job, as defined during job creation
hosthost of the 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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by run status. The format of this ID is <server>:<orderId>.

[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 "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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.

Where:

REST API Syntax

See REST API reference.

Example using  curl:

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

Back to top

run job:statistics::get

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

CLI Syntax

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

Where:

Parameter

Description

<jobId>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by run status. The format of this ID is <server>:<orderId>.

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

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

See REST API reference.

Example using  curl:

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

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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:  

curl -H "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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 

See REST API reference. 

Example using  curl:

curl -H "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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 

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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 <jobId> is a unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:

curl -H "x-api-key: $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, or users).

CLI Syntax

CLI
ctm run job::waitingInfo <jobId> 

Where:

Parameter

Description

<jobId>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by run status. The format of this ID is <server>:<orderId>.

REST API Syntax

See REST API reference.

Example using  curl:

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

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

CLI
ctm run job::get <jobId> 

Where: 

Parameter

Description

<jobId>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:  

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

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

CLI
ctm run job::modify <jobDefinitionsFile> <jobId> 

Where: 

Parameter

Description

<jobDefinitionsFile>

A JSON file that contains the details of a single job, including the properties that you want to modify.

For a description of the syntax of the JSON code in this file, see Code Reference and all its child pages. Note that this JSON file contains details of only a single job. Do not include other object types (such as folder or connection profile) in this JSON file.

Note: The following job properties currently do NOT support the Modify action:

  • Host

  • RerunSpecificTimes

  • RunAsDummy

  • RetroactiveOrder

In addition, under the When parameter, only FromTime and ToTime support the Modify action.

<jobId>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by 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

See REST API reference.

Example using  curl:  

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

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 the server. 

CLI Syntax

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

Where:

Parameter

Description

<server>Server name (currently IN01)
<name>

Name of the resource

Maximum 2048 characters

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

server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newResource\",
\"max\":5}" "$endpoint/run/resource/$server"

run resource::delete

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

CLI Syntax

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

Where:

Parameter

Description

<server>Server name (currently IN01)

<name>

Name of the resource

Maximum 2048 characters

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:

server=IN01
name=newResource
curl -H "x-api-key: $token" -X DELETE "$endpoint/run/resource/$server/$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 <server> <name> <max> 

Where:

Parameter

Description

<server>Server name (currently IN01)
<name>

Name of the resource

Maximum 2048 characters

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

server=IN01
name=newResource

curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST -d "{\"max\":6}" "$endpoint/run/resource/$server/$name" 

run resources::get

The get resources command allows you to get all resource records from the 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

server

Server name (currently IN01)
name

Name of the resource

Maximum 2048 characters

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

Response 

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

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

Where:

ParameterDescription
<ctm>Server name (currently IN01)
<name>

Name of the resource

Maximum 2048 characters

<available>Number of resources available
<max>Maximum resources available

REST API Syntax

See REST API reference.

Example using  curl:

search_criteria="name=A*&server=*"
curl -H "x-api-key: $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 server.

CLI Syntax

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

Where:

Parameter

Description

<server>Server name (currently IN01)
<name>Name of the event

<date>

Date options to order the event:

  • MMDD - specific date
  • ODAT - represents the current Control-M date. For 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:

server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newEvent\",\"date\":\"0505\"}"  "$endpoint/run/event/$server"

run event::delete

The delete event command allows you to remove an event. 

CLI Syntax

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

Where:

Parameter

Description

<server>Server name (currently IN01)
<name>Name of the event

<date>

Date options to order the event:

  • MMDD - specific date
  • ODAT - represents the current Control-M date. For 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:

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

run events::get

The get events command allows you to get all events from the 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

server

Server name (currently IN01)
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 "server=IN01&name=eventA,eventB&date=0805"

REST API Syntax

See REST API reference.

Example using  curl:

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

Response 

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

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


Back to top

Service Management

Services 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.

run services:sla::get

Retrieves details of defined SLA-type services.

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

CLI Syntax

CLI
ctm run services:sla::get

REST API Syntax

See REST API reference.

Example using  curl:

curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X GET  "$endpoint/run/services/sla"

Response

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

{
  "serviceLastUpdatedTime": "2020-01-26T10:19:42+00:00",
  "activeServices": [
    {
      "serviceName": "SLA-BAD",
      "status": "Not Ok",
      "statusReason": "Service late,Job failure,Service actually late",
      "startTime": "2020-02-09T10:08:10+00:00",
      "endTime": "2020-02-09T10:14:20+00:00",
      "dueTime": "2020-02-09T08:00:05+00:00",
      "slackTime": "-02:14:15",
      "serviceOrderDateTime": "2020-02-09T07:00:05+00:00",
      "scheduledOrderDate": "20200209",
      "serviceJob": "IN01:0002c",
      "serviceControlM": "IN01",
      "priority": "3",
      "note": "",
      "totalJobs": "3",
      "jobsCompleted": "1",
      "jobsWithoutStatistics": "1",
      "completionPercentage": "33",
      "averageCompletionTime": "",
      "errors": "Job \"FindFile\" ended with failure.\nJob \"SLA-Bad\" should have started by 08:00:05 GMT+00:00 and will not start on time. The reason is: \"SLA-Bad\"  is waiting for Wait Condition.",
      "statusByJobs": {
        "executed": "0",
        "waitCondition": "2",
        "waitResource": "0",
        "waitHost": "0",
        "completed": "0",
        "error": "1"
      }
    }
  ]
}

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

ParameterDescription
serviceNameName of service
statusCurrent status of the service
statusReasonOne or more reasons for the current status
startTimeDate and time when the service started to run
endTimeDate and time for when the service is estimated to stop running
dueTimeDeadline date and time by which the service must complete to be considered not late
slackTimeDifference in time between the dueTime and its estimated endTime
serviceOrderDateTimeDate and time when the service was ordered
scheduledOrderDateOrder date if rescheduled during the order
serviceJobJob ID of the job associated with the service
serviceControlMServer where the service runs
priorityPriority level of the service
noteSpecific service information entered as a note for the service
totalJobsThe total number of jobs in the service
jobsCompletedThe number of jobs in the service that completed
jobsWithoutStatisticsThe number of jobs without statistic information
completionPercentagePercentage of jobs in the service that completed
averageCompletionTime

An estimate of the length of time that the service will require to complete

errorsError messages received for the jobs in the service
statusByJobsA breakdown of how many jobs finished in each job status

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 Helix Control-M Online Help.

run variables::get

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

CLI Syntax

CLI
ctm run variables::get -s "<query string>"

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

Field

Description

pool

Name of the pool

For example: pool=Pool1

For wildcard matching, you can specify * in the named pool string. The * wildcard can be used as either the only character or the last character.

For example: pool=* or pool=P*

The default (when not specified) is * (all pools).

variable

Full name of the variable

For example: variable=Var1

For wildcard matching, you can specify * in the variable string. The * wildcard can be used as either the only character or the last character.

For example: variable=* or variable=V*

The default (when not specified) is * (all variables).

server

Server name (currently IN01)

When you have only one server, you do not need to include this field or you can use server=* (the default).

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:

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

Response

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

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

run variables::set

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

CLI Syntax

CLI
ctm run variables::set <server> -f <variablesDefinitionFile.json>

Where:

Parameter

Description

serverServer name (currently IN01)
variablesDefinitionFile

Full path and name of a JSON file that contains definitions of variables, as in the following example:

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

Note that all backslashes are escaped in the JSON format.

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:

server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X POST "$endpoint/run/variables/$server" -d @VariablesDefinitions.json

run variables::delete

Deletes variables from the server.

CLI Syntax

CLI
ctm run variables::delete <server> -f <variablesNames.json

Where:

Parameter

Description

serverServer name (currently IN01)
variablesNames

Full path and name of a JSON file that contains a list of names of variables, as in the following example:

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

Note that all backslashes are escaped in the JSON format.

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:

server=IN01
curl -H "x-api-key: $token" -H "Content-Type: application/json" 
-X DELETE "$endpoint/run/variables/$server" -d @VariableNames.json

Back to top

External Alert Management

An alert is a message that indicates that a problem or exception has occurred (for example, in a Job or Folder). Control-M Automation API enables you to manage the monitoring of alerts through external tools. For more information, see Setting Up External Alerts.

Note

If the host of your external client uses a proxy server, ensure that the HTTP_PROXY, HTTPS_PROXY, and WSS_PROXY environment variables are defined. Values for these variables are in the format {protocol}://{host}:{port}. For example, http://172.19.0.169:3128 or https://server.com:3128. For authentication to the proxy, include logon credentials, as in the following example:
HTTP_PROXY= http://username:password@proxy.example.com:1234

If you want to opt out of proxying on specific hosts or particular destination ports, you can use the NO_PROXY environment variable, set with a comma-separated list of hosts. For example, NO_PROXY=hostname.example.com,10.1.0.0/16,172.30.0.0/16:443

The following table lists the actions that you can perform with Control-M Automation API to manage a reliable stream of alerts from Helix Control-M and to manage the listener process on your client:

Note

To listen for alerts, ensure that you have enabled external alerts in one of the following ways:

run alerts:stream::open

Opens the stream of alerts from Helix Control-M.

Note: You can have only one open Alerts stream. If you want to open another stream using a different API token, you must first close the previous stream, using the same API token that was used to open that stream.

CLI Syntax

CLI
ctm run alerts:stream::open

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

A successful response returns a WebSocket URL for the connection, as in the following example: 

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

REST API Syntax

See REST API reference.

Example using  curl:

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

run alerts:stream::close

Closes the stream of alerts from Helix Control-M. This disconnects the active Alerts listener and enables other users to open a different stream. 

Note: To close an Alerts stream, you must be connected with the same API token that was used to open the stream. Only an admin user (with Configuration access set to Update level) can close the stream of another user.

CLI Syntax

CLI
ctm run alerts:stream::close <force option>

Where the <force option> can be either true (force the closing of the stream) or false (close without forcing; the default).

If annotation is enabled for the Alerts Handling 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 "x-api-key: $token" -H "Content-Type: application/json" 
-X POST "$endpoint/run/alerts/stream/close?force=false"

run alerts:stream::status

Returns the status of the monitoring service that streams the alerts from Helix Control-M and the status of the connection to the listener process on your client, as well as the most recent date and time of the last update.

CLI Syntax

CLI
ctm run alerts:stream::status

REST API Syntax

See REST API reference.

Example using  curl:

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

run alerts:stream:template::set

Sets a JSON template that determines what information to provide for each alert — which fields of information, their names, and order of appearance. The template that you provide overrides the default combination of fields provided by Helix Control-M. 

CLI Syntax

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

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

For more information about the default fields and how to author the JSON template, see Alerts Template reference.

If annotation is enabled for the Alerts Handling 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 "x-api-key: $token" -H "Content-Type: application/json" 
-X POST -d "@alertsTemplate.json" "$endpoint/run/alerts/stream/template"

run alerts:listener::start

Runs the Alerts listener for the defined environment and triggers a defined Alert script each time an alert is received.

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

Note: 

  • This CLI command first calls the run alerts:stream::open API command and opens the Alerts stream from Helix Control-M (if it is not already open).
  • This API command is supported only through the CLI, and cannot be called through a REST API command.
  • You can have only one listener running at a time. If you want to open another listener using a different API token, you must first stop the running listener, using the same API token that was used to start that listener.

CLI Syntax

CLI
ctm run alerts:listener::start [attached]


Parameter

Description

[attached]

Enables you to start the listener in attached mode (that is, in the foreground), instead of the default detached mode (in the background).

Values: true | false

Default: false

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

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

run alerts:listener::stop

Stops the Alerts listener for the defined environment.

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

Note: 

  • This API command is supported only through the CLI, and cannot be called through a REST API command.
  • After successfully stopping the Alerts listener, this CLI command also closes the Alerts stream (that is, it performs the function of run alerts:stream::close).

CLI Syntax

CLI
ctm run alerts:listener::stop

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

run alerts:listener:environment::set

Sets the Helix Control-M environment to listen to for alerts.

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

Note: This API command is supported only through the CLI, and cannot be called through a REST API command.

CLI Syntax

CLI
ctm run alerts:listener:environment::set <environment_name>

run alerts:listener:script::set

Sets the path to an Alerts Listener script to trigger each time an alert is received. Ensure that you are authorized to execute the script.

Note: This API command is supported only through the CLI, and cannot be called through a REST API command.

CLI Syntax

CLI
ctm run alerts:listener:script::set <script_path>

run alerts:listener::configure

Configures the Alerts listener. Use this CLI command to set either environment (as done by run alerts:listener:environment::set) or the Alerts Listener script (as done by run alerts:listener:script::set).

Note: This API command is supported only through the CLI, and cannot be called through a REST API command.

CLI Syntax

CLI
ctm run alerts:listener::configure environment <environment_name>
ctm run alerts:listener::configure script <script_path>

Back to top

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

Comments