Control-M Plug-in Technical Reference

Overview

The Control-M plug-in allows you to monitor scheduled jobs that are running on a Control-M server.

This plug-in supports Control-M versions 9.0.18 and above, and is based on Control-M's REST API.

If you are using older versions of Control-M, see the Control-M Monitoring User Guide.

Metrics and dataviews

By default, the Control-M plug-in shows all metrics in its dataview. You can add custom dataviews by filtering jobs by certain parameters, and by arranging the metrics you want to see in columns. For more information on filtering, see Job view filters.

Field Description
jobId

Unique ID that references a specific job. Each job in the run has a jobId.

This metric serves as the primary key and is always the first column in the dataview.

application

Application that a job falls under.

Applications provide a common name to a set of related jobs. These jobs do not necessarily have to run at the same time.

name Name of the job.
type

Indicates the type of job running.

Possible values:

  • Command — runs a platform command line option.
  • Script — runs a script.
  • File Transfer — performs file transfer.
  • File Watcher — monitors file activity.
  • Database — runs an SQL script.
  • Hadoop — runs a job based on Hadoop objects.
  • Dummy — always ends successfully without running any commands.
  • Folder — displays a job folder, rather than a job. This type is natively supported in Geneos.
status

Job status.

Possible values:

  • Ended OK — completed successfully.
  • Ended Not OK — ended in failure.
  • Wait User — waiting for user confirmation.
  • Wait Resource — waiting on a resource to be available.
  • Wait Host — waiting on an agent or remote host to be available.
  • Wait Workload — waiting due to a workload limit.
  • Wait Condition — waiting for a condition.
  • Executing — currently executing.
  • Status Unknown — unknown.
startTime

ISO 8601 date and timestamp of when the job starts running.

Format: yyyymmddhhmmss

endTime Date and timestamp of when the job is terminated.
elapsedTime

Time elapsed since the start time, measured in Unix time.

Note: This field is calculated based on the local time of the Netprobe against the local time of the Control-M server. If the two components are not in the same time zone, then the elapsed time may display different values.

description Description of the job.
ctm Name of Control-M server where the job is running.
deleted

Indicates if the job was deleted.

Possible values:

  • true
  • false
folder

Folder that a job falls under.

A folder is a container of jobs which share the same settings.

folderId Unique ID that references a specific folder.
held

Indicates if the job was held.

Possible values:

  • true
  • false
host Host name of the Control-M server where the job is running.
logUri URI to the job log.
numberOfRuns Number of job runs.
orderDate

Date on which the job is scheduled to run.

Format: yymmdd

outputUri URI to the job output.
subApplication

Sub-application that a job falls under.

Sub-applications provide a common name to a set of related jobs. These jobs do not necessarily have to run at the same time.

Job view filters

You can create custom dataviews which show jobs based on filters you specify. Filters can be specified for a dataview by adding pairs of parameters and their matching criteria to the Control-M sampler.

Note: When naming your dataviews on the Control-M plug-in, make sure that these have unique names. If multiple dataviews have the same name, then only one of the views will show on the state tree.

Filters are optional. If you do not specify a filter, then the Control-M plug-in displays all metrics.

Field Description
limit Number of job records to retrieve.
jobname Retrieves jobs whose name contains the string specified.
type

Retrieves jobs whose type is specified.

Note: In general, the Control-M API matches to jobs. Folders are not matched independently to most parameters. Instead, folders are matched based on the parameters of its child jobs. This parameter enables you to retrieve folders, in addition to other Control-M job types.

ctm Retrieves jobs falling under the Control-M server specified.
jobId Retrieves jobs whose ID contains the string specified.
folder Retrieves jobs falling under the folder specified.
folderLibrary Retrieves jobs whose folder is located in the folder library specified.
application Retrieves jobs falling under the specified application.
subApplication Retrieves jobs falling under the specified sub-application.
host Retrieves jobs based on their host.
hostGroup Retrieves jobs based on their host group.
description Retrieves jobs based on its description.
runAs

Retrieves jobs run by the user specified.

This parameter refers to the user on the operating system.

command

Retrieves jobs that contain the command specified.

This particularly applies to command-type jobs.

filePath

Retrieves jobs based on its associated file path.

This particularly applies to script-type jobs.

fileName

Retrieves jobs based on its associated filename.

This particularly applies to script-type jobs.

workLoadPolicy Retrieves jobs based on the workload policy that is linked to the resource.
ruleBasedCalendar

Retrieves jobs based on rule-based calendars assigned.

Format:

{
Included": ["calendar1"],
"Excluded": ["calendar2"]
}
resourceMutex

Retrieves jobs based on the mutex type.

Possible values:

  • Exclusive
  • Shared
resourceSemaphore Retrieves jobs based on the number of semaphores assigned.
orderDateFrom

Retrieves jobs that are scheduled to run after the specified date.

Format: yymmdd

orderDateTo

Retrieves jobs that are scheduled to run before the specified date.

Format: yymmdd

fromTime

Retrieves jobs that started after the time specified.

Format: hhmm

toTime

Retrieves jobs that started before the time specified.

Format: hhmm

status

Job status to retrieve.

For more information on Control-M job statuses, see Metrics and dataviews.

neighborhood

Enables you to search for predecessor and dependent jobs.

This parameters is used in conjunction with jobId, direction, and depth. If you use the neighborhood parameter without the jobId, direction, or depth, then the dataview displays no rows.

direction

Sets which relationship direction to look for when filtering related jobs.

Possible values:

  • depend — searches jobs that depend on the specified job.
  • predecessor — searches jobs that the specified job depends on.
  • radial — searches both directions

This parameter is used in conjunction with neighborhood. If the neighborhood parameter is missing, then this parameter is ignored.

depth

Number of job levels from the specified job.

This parameter is used in conjunction with neighborhood. If the neighborhood parameter is missing, then this parameter is ignored.

Filter matching behaviour

The Control-M plug-in can parse simple criteria with no operators required:

Control-M also natively supports a filtering language to help refine your criteria. For more information, see the section titled Pattern matching strings on the Control-M 9.0.18 User Guide.

Plug-in configuration

Caution: When you update the configuration of certain Java-based plug-ins, including this one, the Netprobe running it has to restart. Be aware of other potentially unrelated plug-ins that can be affected when you configure this particular plug-in.

Basic tab

The Control-M plug-in requires your organisation's Control-M credentials to run successfully. If you are setting up a Control-M plug-in for the first time, see Control-M Plug-in User Guide.

Field Description
Host

Control-M server host name or IP address.

Choose the appropriate field on the drop-down list (name or ipAddress) when specifying the host.

If you choose the name field, you can toggle between entering a text or numerical value (data) or a variable (var).

Port

Control-M server port.

You can toggle between entering a numerical value (data) or a variable (var).

Username

Control-M username to log in with.

You can toggle between entering a text or numerical value (data) or a variable (var).

Password

Control-M password to log in with.

Choose the appropriate field when specifying the password:

  • stdAES — use this to input your plaintext password. If you select stdAES, you can define your password directly in the sampler and store it in standard AES encryption hash in the Gateway.
  • var — use this to pass the password as a variable. The variable is defined in Managed entity > Advanced > Var. This is useful for situations where you have multiple samplers that use the same credentials.

Advanced tab

The Control-M plug-in has a few more configuration options in the Advanced tab:

Field Description
Timeout

Number of seconds the Control-M plug-in waits for a response from the Control-M server.

If the Control-M server takes longer than the timeout value, then the Control-M plug-in reports an error.

You can toggle between entering numerical value (data) or a variable (var).

Verify server

When ticked, enables server authentication.

When using server authentication, check that you have the Control-M server certificate in your Java TrustStore.

Further reading

If you are interested in setting up the Control-M plug-in to monitor your Control-M server, see Control-M Plug-in User Guide.