--- title: "Control-M (9.0.18)" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/control-m-9-0-18/index.html" --- ## 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](https://docs.itrsgroup.com/docs/all/geneos/7x-geneos-compat-matrix/index.html#application-and-plugin-specific-information). ## Intended audience This guide is directed towards Geneos users who want to set up a plug-in to monitor an existing Control-M solution. As a user, you should be familiar with general administration of the Control-M solution, as well as its terminologies. ## Prerequisites You need the following to set up the Control-M plug-in: ### Java requirements - You must have Java installed on the machine running the Netprobe. For information on supported Java versions, see [Java support in Geneos Compatibility Matrix](https://docs.itrsgroup.com/docs/all/geneos/7x-geneos-compat-matrix/index.html#java-support). - Once you have Java installed, configure the environment variables required by the Netprobe so that it can locate the required resource files. For guidance, see [Configure the Java environment](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/configure-the-java-environment/index.html). The Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. It is recommended to read [Configure the Java environment](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/configure-the-java-environment/index.html) to help you understand your Java installation. ### Control-M credentials - Control-M server host name or IP address **Note** Hosts defined in the **Host** fields, either in the [plugin configuration](#basic-tab) or in [job view filters](#job-view-filters), are trusted by default. It is strongly recommended to enable [server verification](#advanced-tab) under the **Advanced** configuration to ensure configured hosts are properly secured and verified before use. - Control-M server port - Control-M username and password The Netprobe does not allow plaintext connections to the Control-M server, as it enforces an SSL connection to the Control-M server API. If you attempt to connect to a non-SSL port, this causes a connection timeout and displays this error message: **Error** Failed to connect to Control-M server: Unrecognised SSL message, plaintext connection? ## Set up Control-M monitoring Setup involves two main tasks: 1. Create the Control-M sampler. 2. Associate the Control-M sampler with a managed entity. ### Create the Control-M sampler 1. In the Gateway Setup Editor, create a new sampler by right-clicking the **Samplers** folder and selecting **New Sampler**. 2. Enter a name for this sampler. For example, enter the name "ctrl-m" in the **Name** field. 3. Under the **Plugin** field, click the drop-down list and select `control-m`. 4. In the **Basic** tab below the **Plugin** field, enter the Control-M server information for the following fields: - In the **Host** field, select either `name` or `ipAddress`, then enter the host name or IP address. - In the **Port** field, enter the port number. - In the **Username** field, enter the username. - In the **Password** field, select either `stdAES` to set your password directly in the sampler, or `var` to enter the password you set in the managed entity. **Note** You can toggle between `data` and `var` for the host **Name**, **Port**, and **Username** fields. This toggle option allows you to define either a text or numerical value (`data`) or variable (`var`) for these fields. 5. Click **Save current document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/save16x16.png "icon") to apply your changes. **Success** The sampler can now be associated with a managed entity. This sampler provides the default **JobView** dataview, which shows all jobs running in the Control-M server. The **JobView** dataview appears by default when you do not specify any **Dataviews** in the Control-M sampler. You can define your own dataviews based on filters of the Control-M parameters. ### Associate the Control-M sampler with a managed entity 1. In the Gateway Setup Editor, create a new managed entity by right-clicking the **Managed entities** folder and selecting **New Managed entity**. 2. Enter a name for this managed entity. For example, enter the name "ctrl-m" in the **Name** field. 3. In the **Options** field, select the probe on which you want the sampler to run. 4. Under the **Sampler** field, click `Add new`. 5. In the text field under **Ref**, select the sampler you just created from the drop-down list. 6. Click **Save current document** ![](https://docscdn.itrsgroup.com/geneos/images/Icons/save16x16.png "icon") to apply your changes. **Success** After you save your changes to the managed entity, the Control-M dataview appears under the managed entity on the Active Console state tree. ## 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/control-m-9-0-18/index.html#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
estimatedStartTime

Estimated date and time when the next job runs are expected to begin. Up to 50 queued job runs can be estimated in advance.

Estimations are based on run times of previous jobs runs, and are available only if the Batch Impact Manager or Control-M Forecast is active in your environment.

Format: yyyymmddhhmmss
estimatedEndTime

Estimated date and time when the next job runs are expected to end. Up to 50 queued job runs can be estimated in advance.

Estimations are based on run times of previous jobs runs, and are available only if Batch Impact Manager or Control-M Forecast is active in your environment.

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.
### Show Waiting Info Beginning Control-M version 9.0.19.220, a parameter called `Waiting Info` is available. This parameter displays the reason for why a job in waiting has not been executed yet. You can look at the waiting info from the dataview for a job in waiting. Right-click the row and select **Show Waiting Info**: ![Control-M Show Waiting Info](https://docscdn.itrsgroup.com/geneos/images/plug-ins/control-m-show-waiting-info.png) The Output dockable appears, displaying the applicable reason: ![Control-M Show Waiting Info output](https://docscdn.itrsgroup.com/geneos/images/plug-ins/control-m-show-waiting-info-output.png) For more information, see [Control-M plugin in Gateway Commands](/collection/../processing/monitoring-and-alerts/geneos_commands_tr/#control-m-plugin). ## 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. ![test](https://docscdn.itrsgroup.com/geneos/images/netprobe/control-m-images/control-m-dataview-filters-ui-refresh.png) 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: ![test](https://docscdn.itrsgroup.com/geneos/images/netprobe/control-m-images/control-m-parameters-criteria-ui-refresh.png) Control-M also natively supports a filtering language to help refine your criteria. For more information, see [Pattern matching strings](https://documents.bmc.com/supportu/9.0.21.000/en-US/Documentation/Pattern-Matching_Strings.htm). ## Plugin configuration **Caution** When you update the configuration of certain Java-based plugins, including this one, the Netprobe running it has to restart. Be aware of other potentially unrelated plugins that can be affected when you configure this particular plugin. ### Basic tab The Control-M plugin requires your organisation's Control-M credentials to run successfully. ![Control-M plugin Basic tab](https://docscdn.itrsgroup.com/geneos/images/netprobe/control-m-images/controlm-plugin-basic-tab.png) | 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](https://docs.itrsgroup.com/docs/geneos/7.11.0/security/access-controls/gateway_secure_passwords/index.html#securing-your-gateway-with-an-external-password-provider). | | Dataviews | You can add custom dataviews by filtering jobs by certain parameters and by arranging the metrics you want to see in columns. See [Job view filters](#job-view-filters). | ### Advanced tab The Control-M plug-in has a few more configuration options in the Advanced tab: ![Control-M plugin Advanced tab](https://docscdn.itrsgroup.com/geneos/images/netprobe/control-m-images/controlm-plugin-advanced-tab-7-9.png) | 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 a numerical value (`data`) or a variable (`var`). | | Verify server | When ticked, it enables server authentication. When using server authentication, check that you have the Control-M server certificate in your Java TrustStore. **Tip** Enabling server verification is strongly recommended to ensure a secure and reliable connection. | | Row limit | Specifies the maximum number of rows displayed in the dataview. Default value: `200` Mandatory: No |