Control-M (9.0.18)

Overview Copied

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.

Intended audience Copied

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 Copied

You need the following to set up the Control-M plug-in:

Java requirements Copied

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 to help you understand your Java installation.

Control-M credentials Copied

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:

Failed to connect to Control-M server: Unrecognised SSL message, plaintext connection?

Set up Control-M monitoring Copied

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 Copied

  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:
  1. Click Save current document 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 Copied

  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 to apply your changes.

Success

After you save your changes to the managed entity, the Control-Mdataview appears under the managed entity on the Active Console state tree.

Metrics and dataviews Copied

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.

Show Waiting Info Copied

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

The Output Dockable appears, displaying the applicable reason:

Control-M Show Waiting Info output

For more information, see Control-M plugin in Gateway Commands.

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.

Job view filters Copied

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.

Filter matching behaviour Copied

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.

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.

Plugin configuration Copied

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 Copied

The Control-M plugin requires your organisation’s Control-M credentials to run successfully.

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 Copied

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

Control-Mplug-in verify server option

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.
["Geneos"] ["Geneos > Netprobe"] ["User Guide"]

Was this topic helpful?