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 beginning 9.0.18, and is based on Control-M's REST API. For more information on supported Control-M versions, see the Geneos Compatibility Matrix.

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`	ISO 8601 date and timestamp of when the job is terminated. Format: `yyyymmddhhmmss`
`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.

Plugin 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 plugin 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. `extPwd` — use this for passwords provided by an external provider. For more information, see Securing your Gateway with an external password provider in Secure Passwords.

Advanced tab

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

Control-Mplug-in verify server option

Field Description

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.

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.