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

The following API commands enable you to manage your jobs, perform various job actions, track job status, and view job output and logs:

run

The run command enables you to run jobs on the Control-M environment. The command returns a runId, which you can use to check job status with the run status command.

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

Copy
> 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"
}

To get the job status using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.

CLI Syntax

Copy
ctm run <jobDefinitionsFile> [deployDescriptorFile]

The following table describes the run command parameters.

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

cURL:

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run order

The run order command enables you to run deployed jobs on the Control-M environment. The command returns a runId, which you can use to check job status with the run status command. Below is a typical command and response.

Copy
> 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"
}

To get the job status using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.

CLI Syntax

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

The following table describes the run order command parameters.

Parameter

Description

<ctm>

Control-M/Server name

<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

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.

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

Parameter

Description

variables

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

The variables that you specify can be local, global, or folder variables. Named pool variables are not supported.

For more information, see Variables.

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 placeInFolder (next parameter) is set to Recent or to a specific Order ID.

Values: true|false

Default: true

placeInFolder

Determines how to order jobs or Sub Folders that belong to a SMART Folder. Mandatory parameter.

Jobs and Sub Folders are added to a SMART Folder according to the following Order Into Folder options:

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

Default: New

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.

Here is an example of a configuration file:

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

REST API Syntax

cURL:

Copy
endpoint=
token=
ctm=
folderName=
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
 
curl -X POST -H "$AuthHeader" --header "Content-Type: application/json" --header "Accept: application/json" -d "{
    \"ctm\": \"$ctm\",
    \"folder\": \"$folderName\",
    \"hold\": \"true\",
    \"ignoreCriteria\": \"true\",
    \"orderDate\": \"20170903\",
    \"waitForOrderDate\": \"false\",
    \"placeInFolder\": \"Recent\",
    \"variables\": [{\"arg\":\"12345\"}]
}" "$endpoint/run/order"

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

Copy
endpoint=
token=
ctm=M90CTM
folderName=
jobName=IOATEST
library=CTMP.V900.SCHEDULE
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
 
curl -X POST -H "$AuthHeader" --header "Content-Type: application/json" --header "Accept: application/json" -d "{
    \"ctm\": \"$ctm\",
    \"folder\": \"$folderName\",
    \"jobs\": \"$jobName\",
    \"library\": \"$library\",
    \"hold\": \"true\",
    \"ignoreCriteria\": \"true\",
    \"orderDate\": \"20170903\",
    \"waitForOrderDate\": \"false\",
    \"placeInFolder\": \"Recent\",
    \"variables\": [{\"arg\":\"12345\"}]
}" "$endpoint/run/order"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run userDaily:missing::list

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

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

The command returns a poll ID that you can use to view the list, using the run userDaily:missing::poll command. Below is a typical command and response.

Copy
> ctm run userDaily:missing::list myUserDaily controlm
{
  "pollId": "f9f9667e-8037-45c9-bd00-36eaa4b812c8",
  "statusURI": "http://localhost:32080/run/orderMethod/myUserDaily/missing/listf9f9667e-8037-45c9-bd00-36eaa4b812c8"
}

To view the list using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.

CLI Syntax

Copy
ctm run userDaily:missing::list <userDaily> <server>

The following table describes the run userDaily:missing::list command parameters.

Parameter

Description

<userDaily>

Defines the name of the User Daily job.

<server>

Defines the Control-M/Server name.

REST API Syntax

cURL:

Copy
server=controlm
userDaily=myUserDaily
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
curl -H "$AuthHeader" "$endpoint/run/userDaily/$userDaily/missing/list/$server"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run userDaily:missing::poll

The run userDaily:missing::poll command enables you view a previously generated list of jobs that were not ordered because a specific Order Method (that is, a specific User Daily job) was interrupted for any reason (for example, an operating system crash).

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

CLI Syntax

Copy
ctm run userDaily:missing::poll <pollId>

Where <pollID> is the poll ID returned by therun userDaily:missing::list command.

REST API Syntax

cURL:

Copy
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
curl -H "$AuthHeader" "$endpoint/run/userDaily/missing/poll/$pollId"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

The following example response lists two unordered jobs and another two unordered jobs that changed after the User Daily job ran.

Copy
{
    "jobs": [
        {
           "folderName": "Folder_1",
           "jobName": "Job_1"
        },
        {
           "folderName": "Folder_2",
           "jobName": "Job_2"
        }
    ],
    "jobsChangedAfterUserDailyRun": [
        {
           "folderName": "Folder_3",
           "jobName": "Job_3"
        },
        {
           "folderName": "Folder_4",
           "jobName": "Job_4"
        }
    ]
}

You can reorder the jobs that did not yet run using the run userDaily:missing::poll command.

run userDaily:missing::run

The run userDaily:missing::run command enables you reorder the jobs that did not run because a specific Order Method (that is, a specific User Daily job) was interrupted for any reason (for example, an operating system crash).

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

The command returns a runId, which you can use to check job status with the run status command. Below is a typical command and response.

Copy
> ctm run userDaily:missing::run myUserDaily
{
  "runId": "2143811-e253-4c3f-8c21-72bd7957bb53",
  "statusURI": "http://localhost:32080/run/status/2143811-e253-4c3f-8c21-72bd7957bb53"
}

To get the job status using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.

CLI Syntax

Copy
ctm run userDaily:missing::run <orderMethod>

Where <userDaily> is the name of the User Daily job.

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

REST API Syntax

cURL:

Copy
userDaily=myUserDaily
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
curl -X POST -H "$AuthHeader" "$endpoint/run/userDaily/$userDaily/missing/run"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run ondemand

The run ondemand command enables you execute jobs immediately, without deploying them to the Control-M/EM database and without requiring the User Daily job in Control-M to trigger them. This approach can be useful for event-driven job executions.

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

  • You cannot use the deploy jobs::get command to retrieve details for such jobs, as they are not deployed to the database.

  • Such jobs cannot be scheduled, as the User Daily job is not involved. Scheduling information is ignored.

A build process takes place as part of the run.

The response returns a runID and statusURI (similar to the run and run order commands). You can use the returned runId to check job status with the run status command.

To get the job status using the statusURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.

CLI Syntax

Copy
ctm run ondemand <definitionsFile> [deployDescriptorFile]

The following table describes the run ondemand command parameters.

Parameter

Description

<jobDefinitionsFile>

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

Only Job, Folder, and Defaults objects in the definitions file are processed. Other object types, such as connection profiles or Site Standards, are not supported. If included in the definitions file, they are ignored. Scheduling properties are also ignored.

[deployDescriptorFile]

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

REST API Syntax

cURL:

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run status

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

CLI Syntax

Copy
ctm run status <runId> [startIndex]

The following table describes the run status command parameters.

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

cURL:

Copy
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token
 
curl -H "$AuthHeader" "$endpoint/run/status/$runId"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

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

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

Copy
> ctm run status "2d4af716-e31d-48ef-a434-16575303752d"
{
    "completion": "Completed",
    "statuses": [
        {
            "jobId": "controlm:00fhb",
            "folderId": "controlm:005gy",
            "numberOfRuns": 3,
            "name": "AutomationAPISampleFlow",
            "type": "Folder",
            "status": "Executing",
            "held": "false",
            "deleted": "false",
            "cyclic": "false",
            "startTime": "May 18, 2018 11:57:26 AM",
            "endTime": "",
            "estimatedStartTime": [
                "20180518121500,",
                "20180518123000,"],
            "estimatedEndTime": [
                "20180518121502,",
                "20180518123005,"],
            "outputURI": "Folder has no output"
        },
        {
            "jobId": "controlm:00fhc",
            "folderId": "controlm:005gy",
            "numberOfRuns": 3,
            "name": "AutomationAPISampleFlow/CommandJob",
            "type": "Command",
            "status": "Wait Host",
            "held": "false",
            "deleted": "false",
            "cyclic": "false",
            "startTime": "",
            "endTime": "",
            "estimatedStartTime": [],
            "estimatedEndTime": [],
            "outputURI": "Job didn't run, it has no output"
        },
        {
            "jobId": "controlm:00fhd",
            "folderId": "controlm:005gy",
            "numberOfRuns": 3,
            "name": "AutomationAPISampleFlow/ScriptJob",
            "type": "Job",
            "status": "Wait Condition",
            "held": "false",
            "deleted": "false",
            "cyclic": "false",
            "startTime": "",
            "endTime": "",
            "estimatedStartTime": [],
            "estimatedEndTime": [],
            "outputURI": "Job didn't run, it has no output"
        }
    ],
    "startIndex": 0,
    "itemsPerPage": 25
}

The following table describes additional run status command parameters.

Parameter

Description

completion

Whether the job has run — Completed | Pending.

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

jobId

A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status.

Format: <server>:<orderId>.

folderId

The folderId is used to reference a specific folder.

numberOfRuns

Number of job runs.

name

Name of job.

type

Job type.

status

Job status.

held

Whether the job was held — true | false.

deleted

Whether the job was deleted — true | false.

cyclic

Whether the job is defined as a cyclic job — true | false.

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

outputURI

URI to the job output.

To get the job output using the outputURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.

run jobs:status::get

The run jobs:status::get command enables you to track running jobs that match a search query.

CLI Syntax

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

The following table describes the run jobs:status::get command parameters.

Parameter

Description

limit

Determines the maximum number of job statuses to return.

Range of values: 1–10000

Default: 1000

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

Field

Criteria

Criteria Examples

  • jobname

  • jobid

  • folder

  • folderLibrary

  • server

  • application

  • subApplication

  • host

  • hostGroup

  • description

  • runAs

  • command

  • filePath

  • fileName

  • workloadPolicy

  • ruleBasedCalender

  • resourceLock

  • resourcePool

  • Supported wildcards are *, ?

  • To use multiple criteria separate by using comma.

  • Wildcards are not supported for jobid.

  • jobid=<server>:<orderId> .

The server field was previously named ctm (deprecated name).

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

historyRunDate

  • A single date when jobs started running, in one of the following formats:

    • YYMMDD

    • YYYYMMDD

  • Yesterday

historyRunDate=231127

historyRunDate=Yesterday

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

  • held

  • (MVS only) 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=controlm:0a98&depth=1&direction=predecessor"

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

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

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

REST API Syntax

Example of a curl request that includes a limit:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

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

Copy
{
    "jobId": "LocalControlM:00008",
    "folderId": "LocalControlM:00007",
    "numberOfRuns": 0,
    "name": "job1",
    "folder": "SanityCommandOk",
    "type": "Command",
    "status": "Wait Condition",
    "held": true,
    "deleted": false,
    "cyclic": "false",
    "startTime": "20231126065554",
    "endTime": "20231126065555",
    "estimatedStartTime": ["20231126123810"],
    "estimatedEndTime": ["20231126124310"],
    "orderDate": "231125",
    "ctm": "LocalControlM",
    "description": "",
    "host": "",
    "application": "OsApp",
    "subApplication": "",
    "outputURI": "Job did not run, it has no output",
    "logURI": "http://localhost:48080/run/job/LocalControlM:00008/log"
}

The following table describes the parameters in this sample response:

Parameter

Description

jobId

A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status.

Format: <server>:<orderId>

folderId

A unique identifier of the folder to which the job belongs.

Format: <server>:<orderId>

numberOfRuns

Number of job runs.

name

Name of job.

folder

Name of the folder to which the job belongs.

type

Job type.

status

Job status:

  • Ended OK.

  • Ended Not OK.

  • Wait User.

  • Wait Resource.

  • Wait Host.

  • Wait Workload.

  • Wait Condition.

  • Executing

  • Status Unknown.

held

Whether the job was held — true | false.

deleted

Whether the job was deleted — true | false.

cyclic

Whether the job is defined as a cyclic job — true | false.

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

ctm

Control-M/Server name.

description

A textual description of the job, as defined during job creation.

host

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

outputURI

URI to the job output.

To get the job output using the outputURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.

logURI

URI to the job log.

To get the job log using the logURI endpoint, you must specify a valid token in the request header, as described in Authentication Tokens.

run job:output::get

The run jobs:output::get command enables you to view the output from job runs.

CLI Syntax

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

The following table describes the run job:output::get command parameters.

Parameter

Description

<jobId>

A unique identifier of the job. The jobId is used to reference the specific job and is returned by ctm run status.

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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job:log::get

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

CLI Syntax

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

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job:status::get

The run job:status::get command enables you to view a specific job run status.

CLI Syntax

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

Where <jobId> is 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 <server>:<orderId>.

For information about the response to this API command and descriptions of the job properties in this response, see the description of the run jobs:status::get response.

REST API Syntax

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job:statistics::get

The run job:statistics::get command enables you to get time statistics for the recent runs of a job.

CLI Syntax

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

Where <jobId> is 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 <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 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.

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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::kill

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

CLI Syntax

Copy
ctm run job::kill <jobId>

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::runNow

The run job::runNow command enables you to immediately start the job. When you use this command, job constraints are not applied.

CLI Syntax

Copy
ctm run job::runNow <jobId>

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::hold

The run job::hold command enables you to hold (that is, stop processing) the job.

CLI Syntax

Copy
ctm run job::hold <jobId>

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::free

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

CLI Syntax

Copy
ctm run job::free <jobId>

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::delete

The run job::delete command enables you to mark the job for deletion. At the next scheduled date, the job will be deleted.

CLI Syntax

Copy
ctm run job::delete <jobId>

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::undelete

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

CLI Syntax

Copy
ctm run job::undelete <jobId>

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::confirm

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

CLI Syntax

Copy
ctm run job::confirm <jobId>

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::setToOk

The run job::setToOk command enables 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

Copy
ctm run job::setToOk <jobId>

Where <jobId> is 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 <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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::rerun

The run job::rerun command enables 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

Copy
ctm run job::rerun <jobId> [-f zosJobConfig.json]

The following table describes the run job::rerun command parameters.

Parameter

Description

<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 <server>:<orderId>.

[zosJobConfig]

z/OS job only: Full path and name of a JSON file that contains advanced restart parameters for Control-M/Restart.

To rerun a z/OS job, the job must be in one of the following statuses:

  • Ended OK

  • Ended Not OK

  • Wait User (which corresponds to Wait Confirmation in Control-M for z/OS)

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:

Copy
{
  "zosParameters": {
    "from": {
      "pgm": "INPROCS2",
      "proc": "STEP1"
    },
    "to": {
      "pgm": "INPROCS3",
      "proc": "STEP2"
    },
    "cleanup": true,
    "recaptureAbend": "Y",
    "recaptureConditionCode": "N",
    "stepAdjustment": true,
    "restartParmMemberName": "IDJOB5"
  }
}

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

Parameter

Description

from, to

Use the from and to parameters to limit job rerun to a range of steps.

Define the starting point (under from) and the end point (under to) by specifying the program step (pgm) and (optionally) the procedure step (proc) at both points.

To obtain a list of program steps, use the run job:output::get API command. The returned output includes a list of executed job steps, including those that completed successfully and those that failed.

Example 1:

In the following simple example, you want to restart from STEP2 until STEP3.

The following table shows the from and to parameters in the configuration file, along with the corresponding JCL in z/OS (for illustration purposes).

from, to in configuration file

JCL in z/OS

Copy
"from": {
    "pgm": "STEP2",
    "proc": ""
},
"to": {
    "pgm": "STEP3",
    "proc": ""
},
Copy
//M99#STEP JOB (EE00,111,30),NOTIFY=&SYSUID,MSGCLASS=X 
//*                                                         
//STEP1   EXEC  PGM=IOATEST,PARM='WAIT=1'                   
//STEP2   EXEC  PGM=IOATEST,PARM='WAIT=1'                   
//STEP3   EXEC  PGM=IOATEST,PARM='WAIT=1'                   
//*

In other Control-M products, the steps in the sample JCL are displayed in the following manner.

Of the listed steps, only those in rows 002-003 are restarted.

Copy
Num Pgm-stp  Proc-stp  Pgm=      Comp
001 STEP1              IOATEST   0000
002 STEP2              IOATEST   0004
003 STEP3              IOATEST   0000

Example 2:

In the following example, you want to restart from INPROCS2 of STEP1 until INPROCS3 of STEP2.

The following table shows the from and to parameters in the configuration file, along with the corresponding JCL in z/OS (for illustration purposes).

from, to in configuration file

JCL in z/OS

Copy
"from": {
    "pgm": "INPROCS2",
    "proc": "STEP1"
},
"to": {
    "pgm": "INPROCS3",
    "proc": "STEP2"
},
Copy
//M99#PROC JOB (EE00,111,30),EDUC,NOTIFY=&SYSUID,MSGCLASS=X  
//*                                                          
//SAMPPROC PROC                                              
//INPROCS1  EXEC PGM=IOATEST                                  
//INPROCS2  EXEC PGM=IOATEST                                  
//INPROCS3  EXEC PGM=IOATEST                                  
//         PEND                                              
//*                                                          
//STEP1   EXEC  SAMPPROC                                      
//STEP2   EXEC  SAMPPROC                                      
//STEP3   EXEC  SAMPPROC                                      
//*

In other Control-M products, the steps in the sample JCL are displayed in the following manner.

Of the listed steps, only those in rows 002-006 are restarted.

Copy
Num Pgm-stp  Proc-stp  Pgm=      Comp
001 INPROCS1 STEP1     IOATEST   0000
002 INPROCS2 STEP1     IOATEST   0004
003 INPROCS3 STEP1     IOATEST   0000
004 INPROCS1 STEP2     IOATEST   0000
005 INPROCS2 STEP2     IOATEST   0000
006 INPROCS3 STEP2     IOATEST   0000
007 INPROCS1 STEP3     IOATEST   0000
008 INPROCS2 STEP3     IOATEST   0000
009 INPROCS3 STEP3     IOATEST   0000

Note the following scenarios:

  • To rerun a single step, specify the same program step and procedure step under both from and to.

  • If you specify a starting point without an end point, the range extends all the way to the end of the job.

  • To rerun the whole job, use empty values for pgm and proc under both from and to.

  • To restart from the step that failed in the previous run, specify "pgm": "$EXERR" under from. If there is no such step, the job restarts from the beginning. For this option, ensure that you have Control-M for z/OS version 9.0.21.200 or later, or have applied APAR WW10041.

cleanup

Whether to perform data set cleanup, either true or false.

If you set this parameter to true, all other parameters described here are not relevant and should NOT be included in the configuration file.

recaptureAbend

Whether to save the abend codes from the original Job execution.

Valid values:

  • Y — Yes, save abend codes. The default.

  • N — No, do not save abend codes.

  • R — Reset abend codes.

recaptureConditionCode

Whether to save the condition codes from the original Job execution.

Valid values:

  • Y — Yes, save condition codes. The default.

  • N — No, do not save condition codes.

  • R — Reset condition codes.

stepAdjustment

Whether to enable automatic Step Adjustment.

Valid values are true and false. The default is true.

For more details about Step Adjustment, see the Control-M/Restart User Guide.

restartParmMemberName

The name of the member that contains control parameters for the Job to restart (1-8 characters only).

The default value is the member that contains the JCL of the Job.

REST API Syntax

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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

run job::waitingInfo

The run job::waitingInfo command enables you to display the reasons why a waiting job has not yet been executed (for example: missing conditions, resources, hosts, users, or workloads).

CLI Syntax

Copy
ctm run job::waitingInfo <jobId>

Where <jobId> is 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 <server>:<orderId>.

REST API Syntax

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::get

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

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

CLI Syntax

Copy
ctm run job::get <jobId>

Where <jobId> is 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 <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

cURL:

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

curl -H "$AuthHeader" -X GET "$endpoint/run/job/$jobId/get"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run job::modify

The run job::modify 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

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

The following table describes the run job::modify command parameters.

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.

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 ctm run status.

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

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

REST API Syntax

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Resource Management

A Resource Pool (previously known as 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 Resource Pool cannot run unless there are enough resources available.

The following API commands enable you to manage Resource Pools:

run resource::add

The run resource::add command enables you to add a Resource Pool to a Control-M/Server.

CLI Syntax

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

The following table describes the run resource::add command parameters.

Parameter

Description

<server>

Control-M/Server name.

<name>

Name of the resource.

Maximum: 2,048 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

cURL:

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

curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newResource\",
\"max\":5}" "$endpoint/run/resource/$server"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run resource::delete

The run resource::delete command enables you to delete a Resource Pool.

CLI Syntax

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

The following table describes the run resource::delete command parameters.

Parameter

Description

<server>

Control-M/Server name.

<name>

Name of the resource.

Maximum: 2,048 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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run resource::update

The run resource::update command enables you to update the values of a Resource Pool.

CLI Syntax

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

The following table describes the run resource::update command parameters.

Parameter

Description

<server>

Control-M/Server name.

<name>

Name of the resource.

Maximum: 2,048 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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run resources::get

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

CLI Syntax

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

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

Field

Description

server

Control-M/Server name.

This field was previously named ctm (deprecated name).

name

Name of the resource.

Maximum: 2,048 characters.

Here are several search examples:

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

Response

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

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

The following table describes additional run resource::add command parameters.

Parameter

Description

<ctm>

Control-M/Server name.

<name>

Name of the resource.

Maximum: 2,048 characters.

<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 Workload Policy Definition.

REST API Syntax

cURL:

Copy
search_criteria="name=A*&server=*"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/run/resources?$search_criteria"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Event Management

An event (previously known as a condition) is represented by a name and a date. Jobs that require an event cannot run unless the specific event exists, as described in Events. A job can add or delete an event.

The following API commands enable you to manage Events:

run event::add

The run event::add command enables you to add events to the Control-M/Server.

CLI Syntax

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

The following table describes the run event::add command parameters.

Parameter

Description

<server>

Control-M/Server name.

<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

cURL:

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

curl -H "$AuthHeader" -H "Content-Type: application/json" -X POST -d "{\"name\": \"newEvent\",\"date\":\"0505\"}"  "$endpoint/run/event/$server"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run event::delete

The run event::delete command enables you to remove an event.

CLI Syntax

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

The following table describes the run event::delete command parameters.

Parameter

Description

<server>

Control-M/Server name.

<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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run events::get

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

CLI Syntax

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

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

Field

Description

server

Control-M/Server name.

This field was previously named ctm (deprecated name).

name

Name of the event.

date

Date of event.

limit

Limits the number of returned matches.

Default: 1000 (if not defined)

Here are several search examples:

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

REST API Syntax

cURL:

Copy
search_criteria="name=A*&server=controlm"
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

curl -H "$AuthHeader" -X GET "$endpoint/run/events?$search_criteria"

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

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

Copy
[
 {
    "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. 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 Workload Policy Definition.

The following API commands enable you to manage Workload Policies:

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

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

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

Example using curl to retrieve definitions of all Workload Policies:

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

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

Example for retrieving the definitions of a specific Workload Policy:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run workloadpolicies::add

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

CLI Syntax

Copy
ctm run workloadpolicies::add <workloadPoliciesFile>

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

Example using curl:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run workloadpolicy::delete

Deletes a specific Workload Policy.

CLI Syntax

Copy
ctm run workloadpolicy::delete <policyName>

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

REST API Syntax

Example using curl:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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

Copy
ctm run workloadpolicies::get [Active|Inactive]

REST API Syntax

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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

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

The following table describes the run workloadpolicy::activate command parameters.

Parameter

Description

[policyName]

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

server

(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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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

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

The following table describes the run workloadpolicy::deactivate command parameters.

Parameter

Description

[policyName]

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

server

(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/EM 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

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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.

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

The following API command enables you to manage services.

run services:sla::get

Retrieves details of defined SLA-type services.

For more information, see Service Management.

CLI Syntax

Copy
ctm run services:sla::get

REST API Syntax

cURL:

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

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.

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

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

Parameter

Description

serviceName

Name of service.

status

Current status of the service.

statusReason

One or more reasons for the current status.

startTime

Date and time when the service started to run.

endTime

Date and time for when the service is estimated to stop running.

dueTime

Deadline date and time by which the service must complete to be considered not late.

slackTime

Difference in time between the dueTime and its estimated endTime.

serviceOrderDateTime

Date and time when the service was ordered.

scheduledOrderDate

Order date if rescheduled during the order.

serviceJob

Job ID of the job associated with the service.

serviceControlM

Control-M/Server where the service runs.

priority

Priority level of the service.

note

Specific service information entered as a note for the service.

totalJobs

The total number of jobs in the service.

jobsCompleted

The number of jobs in the service that completed.

jobsWithoutStatistics

The number of jobs without statistic information.

completionPercentage

Percentage of jobs in the service that completed.

averageCompletionTime

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

errors

Error messages received for the jobs in the service.

statusByJobs

A breakdown of how many jobs finished in each job status.

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.

The following API commands enable you to manage variables:

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

run variables::get

The run variables::get command enables you to retrieve details of defined pool variables that match a search query.

CLI Syntax

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

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.

Example: pool=* or pool=P*

Default: * (all pools)

variable

Full name of the variable.

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.

Example: variable=* or variable=V*

Default: * (all variables)

server

Control-M/Server name.

The server field is required only if you have more than one Control-M/Server. In such a case, the * wildcard is not supported.

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

REST API Syntax

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

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Response

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

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

run variables::set

The run variables::set command enables you to define new pool variables or update the definitions of existing pool variables.

CLI Syntax

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

The following table describes the run variables::set command parameters.

Parameter

Description

server

Control-M/Server name.

variablesDefinitionFile

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

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

cURL:

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

curl -H "$AuthHeader" -H "Content-Type: application/json"
-X POST "$endpoint/run/variables/$server" -d @VariablesDefinitions.json

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run variables::delete

The run variables::delete command enables you to delete variables from the server.

CLI Syntax

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

The following table describes the run variables::delete command parameters.

Parameter

Description

server

Control-M/Server name.

variablesNames

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

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

cURL:

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

curl -H "$AuthHeader" -H "Content-Type: application/json"
-X DELETE "$endpoint/run/variables/$server" -d @VariableNames.json

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

Alert Management

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

The following API commands enable you to manage alerts:

run alerts::update

The run alerts::update command enables you to update basic properties of alerts, including the urgency of the alerts and the associated comments.

CLI Syntax

Copy
ctm run alerts::update -f <configuration file>

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.

Parameter

Description

alertIds

Unique identifiers for the alerts that you want to update.

urgency

Severity of the alert, one of the following (listed in ascending level of severity):

  • Normal

  • Urgent

  • Critical

comment

A free-text comment regarding the alert.

Here is an example of a configuration file:

Copy
{
    "alertIds" : [30,31],
    "urgency":"Normal",
    "comment":"update"
}

REST API Syntax

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

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

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.

run alerts:status::update

The run alerts:status::update command enables you to update the status of the alert.

CLI Syntax

Copy
ctm run alerts:status::update <alertIds> -f <configuration file>

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

Parameter

Description

alertIds

Defines unique identifiers for the alerts that you want to update.

status

Determines one of the following alert statuses:

  • New

  • Reviewed

  • Closed

  • Undefined

Here is an example of a configuration file:

Copy
{
    "alertIds" : [20],
    "status":"Reviewed"
}

REST API Syntax

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

Copy
endpoint=
alertIds=15,20
AuthHeader="x-api-key: $token"
# AuthHeader="Authentication: Bearer $token"  #for a session token

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

For selecting the AuthHeader value ("Authentication: Bearer $token" or "x-api-key: $token"), see Authentication Tokens.