Skip to end of metadata
Go to start of metadata

Introduction

This article describes individual configuration parameters and provides examples of their use with monitors such as op5 and Zabbix and using of the mail und JMS interfaces.

Configuration Editor

We recommend that the XML Editor is used generate monitoring configuration objects. This editor automatically uses an XSD Schema to generate configuration suggestions and validate configurations, and its use is intended to provide a significant reduction in the time required to develop and test a configuration.

Configuration

JobScheduler

Activation of Monitoring Interface 

Note: SystemMonitorNotification_<MonitorSystem>.xml file(s) (see below) must be configured before activtion.

SystemMonitorNotification files

Location: <scheduler_install>/config/notification

FileDescription
SystemMonitorNotification_v1.0.xsd

The XML Schema file defines which values are allowed in your XML files for the JobScheduler monitoring.

That means that to configure the JobScheduler objects you want to monitor and the System Monitor you just have to modify your SystemMonitorNotification_<MonitorSystem>.xml files but not the XML schema file.

SystemMonitorNotification_<MonitorSystem>.xml

 Configuration file for each System Monitor.

  • Specifies the delivery way to System Monitor.
  • Specifies notification for error or success conditions
  • Specifies notification to measure performance of JobScheduler objects
 

SystemMonitorNotificationTimers.xml

Configuration file for all System Monitors.

  • Specifies notification to measure performance of JobScheduler objects

This file is optional and contains the definitions of the SystemMonitorNotification / Timer elements.

 

SystemMonitorNotification Elements

The configuration element descriptions are organized into the following major categories:

ElementElement descriptionDescription
SystemMonitorNotificationTop Level ElementConfiguration for notifications to be sent to a system monitor.
NotificationRequired, multiple use allowed inside the SystemMonitorNotification elementSpecifies a system monitor notification that includes a command line invocation and the JobScheduler objects.
TimerOptional or multiple use allowed inside the SystemMonitorNotification elementPerformance measurement definition.
SystemMonitorNotification

JITL-230 - JobScheduler Monitoring Interface jobs should consider updated Timer elements Released

SystemMonitorNotification supports the following attributes:

Note:

  • attribute system_id 
    • in case of the SystemMonitorNotificationTimers.xml the value of this attribute is not important and can have any value.

      • e.g.: timers

AttributeUsageDescription
system_idrequired

System Monitor identifier.

See JobScheduler - Job Chains customization 

Example  Expand source


SystemMonitorNotification / Notification

Notification supports the following attributes:

AttributeUsageDescription
nameoptionalNotification description

 

Example  Expand source

 

The following elements may be nested inside a Notification element:

ElementElement descriptionDescription
NotificationMonitorRequired, only once inside the Notification elementSpecifies the System Monitor interface that is being used for messages: either by a Plug-in Interface or by command line invocation
NotificationObjectsRequired, only once inside the Notification elementSpecifies the Job Chain and the Timer definitions
SystemMonitorNotification / Notification / NotificationMonitor

The JobScheduler Interface Monitor can be used to monitor the messages for the 3 use cases:

  • error case
    • an error has occured / been recovered during a job chain / job execution
      • the service_name_on_error setting is responsible for this monitoring case
  • success case
    • a job chain / job ends succesfully
      • the service_name_on_success setting is responsible for this monitoring case
  • performance check (see Timer)
    • usually the service_name_on_error setting is responsible for this monitoring case but the performance check will also work if only the service_name_on_success setting has been defined.

 

In addition, the service_name_on_error / service_name_on_success attributes have the following meaning:

  • NotificationInterface
    • The setting must match the corresponding service name in the System Monitor such as Nagios or op5.
  • NotificationCommand
    • Freely selectable, has no further meaning than to identify a notification.
  • NotificationMail
    • Freely selectable, has no further meaning than to identify a notification.
  • NotificationJMS
    • The setting must match the corresponding queue/topic name in the JMS Server.

Note:

  • attributes service_name_on_error and service_name_on_success
    • at least one of these attributes must be configured
    • both attributes can be configured together
    •  the use of this settings must be unique within one SystemNotification

NotificationMonitor supports the following attributes:

AttributeUsageDescription
service_name_on_errorOptional

See explanation above.

service_name_on_successOptional

See explanation above.

service_status_on_errorOptional

This setting specifies the service status code for error messages.

Default: CRITICAL

service_status_on_successOptional

This setting specifies the service status code for success messages

Default: OK

Example  Expand source

One of the following elements must be nested inside a NotificationMonitor element:

ElementElement descriptionDescription
NotificationInterfaceOptional or only once inside the NotificationMonitor elementNSCA plug-in Interface to be executed for System Monitor notification
NotificationCommandOptional or only once inside the NotificationMonitor elementCommand line to be executed for System Monitor notification
NotificationMailOptional or only once inside the NotificationMonitor elementMail interface to be executed for System Monitor notification
NotificationJMSOptional or only once inside the NotificationMonitor elementJMS interface to be executed for System Monitor notification

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationInterface

NSCA plug-in Interface to be executed for System Monitor notification.

NotificationInterface supports the following attributes:

AttributeUsageDescription
monitor_hostRequiredThis setting specifies the host name or ip address of System Monitor host.
monitor_portRequiredThis setting specifies the TCP port that the System Monitor would listen to.
monitor_passwordOptional

This setting specifies the password

  • for NSCA - password configured in the ncsa.cfg file.
monitor_connection_timeoutOptional

This setting specifies the connection timeout in ms.

Default: 5000

monitor_response_timeoutOptionalThis setting specifies the response timeout in ms.
monitor_encryptionOptional

This setting specifies that the communication with the System Monitor is encrypted. By default no encryption is used.

  • NONE             - no encryption
  • XOR            - XOR encryption
  • TRIPLE_DES - use of triple des algorithm for encryption
service_hostRequiredThis setting specifies the name of the host that executes the passive check. The name must match the corresponding setting in the System Monitor.
pluginOptional

Default:

    • JobScheduler version 1.9.x, 1.10.x

      • com.sos.scheduler.notification.plugins.notifier.SystemNotifierSendNscaPlugin
    • JobScheduler version 1.11.x

      • com.sos.jitl.notification.plugins.notifier.SystemNotifierSendNscaPlugin

See : Message, Examples

Example  Expand source

System Monitor: Opsview

Icon

In case you are using Opsview as the monitoring tool, the plugin used in NotificationInterface will not work, since Opsview supports 20 types of encryption, which are not supported by this plugin. You could only use it in case you use no encryption (type: NONE) and that will work.

Instead, you should use the XML element NotificationCommand and indicate there the exact command to send passive checks to your Opsview from a remote machine (see example for op5 or example for zabbix).

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationCommand

Command line to be executed for System Monitor notification.

NotificationCommand supports the following attributes:

AttributeUsageDescription
pluginOptional

Default:

  • JobScheduler version 1.9.x, 1.10.x 
    • com.sos.scheduler.notification.plugins.notifier.SystemNotifierProcessBuilderPlugin
  • JobScheduler version 1.11.x

    • com.sos.jitl.notification.plugins.notifier.SystemNotifierProcessBuilderPlugin


See : Message, Examples

Example  Expand source
SystemMonitorNotification / Notification / NotificationMonitor / NotificationMail

JS-1388 - Add e-mail as a monitor service for the JobScheduler Monitoring Interface Released

The Mail interface to be executed for System Monitor notification.

The Mail interface reads the following values from the configuration files:

  • config/factory.ini
    • Section spooler
      • log_mail_from
      • log_mail_to
      • log_mail_cc
      • log_mail_bcc
      • smtp
      • mail_queue_dir
      • mail_queue_only
    • Section smtp
      • mail.smtp.user
      • mail.smtp.password
      • mail.smtp.port
      • mail.smtp.connectiontimeout
      • mail.smtp.timeout
  • config/private/private.conf
    • joc.url

NotificationMail supports the following attributes:

AttributeUsageDescription
content_typeOptional

Content type of the e-mail.

Possible values:

  • text/plain
  • text/html.

 

Default: text/html

charsetOptional

Charset of the e-mail.

 

Default: ISO-8859-1

encodingOptional

Encoding of the e-mail.

Possible values:

  • 7bit
  • Quoted-Printable
  • Base64.

 

Default: 7bit

priorityOptional

Priority of the e-mail.

Possible values:

  • Highest
  • High
  • Normal.

 

Default: Normal

pluginOptional

Java class of the plugin implementation (extends com.sos.jitl.notification.plugins.notifier.SystemNotifierCustomPlugin)

 

Default: com.sos.jitl.notification.plugins.notifier.SystemNotifierSendMailPlugin

The following elements can be nested inside a NotificationMail element:

ElementElement descriptionDescription
FromOptional or only once inside of the NotificationMail element  E-mail address of the account that sends e-mail.
ToOptional or only once inside of the NotificationMail elementE-mail address of the recipient(s) of a notification e-mail.
CCOptional or only once inside of the NotificationMail elementE-mail address of the recipient(s) of a carbon copy notification e-mail.
BCCOptional or only once inside of the NotificationMail elementE-mail address of recipient(s) of a blind carbon copy notification e-mail.
SubjectRequired, only once inside of the NotificationMail elementSubject of an e-mail notification.
BodyRequired, only once inside of the NotificationMail elementBody of an e-mail notification.
SystemMonitorNotification / Notification / NotificationMonitor / NotificationMail / From

E-mail address of the account that sends the e-mail.

The mail notification interface uses the value of the log_mail_from entry (configuration file config/factory.ini) when this element is not set.

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationMail / To

E-mail address of the recipient(s) of a notification e-mail.

When this element

  • is not set
    • log_mail_to will be used
  • is set
    •   log_mail_to, log_mail_cc, log_mail_bcc are not used

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationMail / CC

E-mail address of the recipient(s) of a carbon copy notification e-mail.

When this element

  • is not set
    • log_mail_cc will be used (if the NotificationMail/To element is not defined - see above)
  • is set
    •   log_mail_cc, log_mail_bcc are not used
SystemMonitorNotification / Notification / NotificationMonitor / NotificationMail / BCC

E-mail address of recipient(s) of a blind carbon copy notification e-mail.

When this element

  • is not set
    • log_mail_bcc will be used (if the NotificationMail/To or NotificationMail/CC elements are not defined - see above)
  • is set
    •   log_mail_bcc are not used

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationMail / Subject

Subject of an e-mail notification.

The Subject can contain the JobScheduler Monitoring Interface variables.

See : Message, Examples

Example  Expand source

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationMail / Body

Body of an e-mail notification.

The Body can contain the JobScheduler Monitoring Interface variables.

See : Message, Examples

Example  Expand source


SystemMonitorNotification / Notification / NotificationMonitor / NotificationJMS

JITL-280 - Add JMS support to the JobScheduler Monitoring Interface Released

JMS Interface to be executed for System Monitor notification.

Note: the provider-specific queue or topic name will be defined with the service_name_on_error / service_status_on_succes attribute of the parent SystemMonitorNotification / Notification / NotificationMonitor element.

NotificationJMS supports the following attributes: 

AttributeUsageDescription
client_idOptional

The client identifier for this connection.

See: Connection.setClientID

destinationOptional

A Destination object encapsulates a provider-specific address.

Possible values:

  • Queue
  • Topic.

See: Destination

 

Default: Queue

acknowledge_modeOptional

Session acknowledgment mode.

Possible values: 

  • Session.AUTO_ACKNOWLEDGE
  • Session.CLIENT_ACKNOWLEDGE
  • Session.AUTO_ACKNOWLEDGE

See: Session

 

Default: Session.CLIENT_ACKNOWLEDGE

delivery_modeOptional

Delivery mode.

Possible values: 

  • DeliveryMode.NON_PERSISTENT
  • DeliveryMode.PERSISTENT

See:

 

Default: DeliveryMode.PERSISTENT

priorityOptional

The producer's default priority.

See: MessageProducer.setPriority

 

Default: 4

time_to_liveOptional

Sets the default length of time in milliseconds from its dispatch time that a produced message should be retained by the message system.

See: MessageProducer.setTimeToLive

Possible values:

  • <n> - duration in milliseconds
    • e.g.: 60000
  • <n>s - duration in seconds
    • e.g.: 30s
  • <n>m - duration in minutes
    • e.g.: 30m
  • <n>h - duration in hours
    • e.g.: 24h
  • <n>d - duration in days
    • e.g.: 30d
  • <n>w - duration in weeks
    • e.g.: 4w
  • Combined values (with blank space as separator):
    • e.g.: 1w 1d 1h

Default: 0

pluginOptional

Java class of the plugin implementation (extends com.sos.jitl.notification.plugins.notifier.SystemNotifierCustomPlugin)

 

Default: com.sos.jitl.notification.plugins.notifier.SystemNotifierSendJMSPlugin

 

One of the following elements must be nested inside a NotificationJMS element:

ElementElement descriptionDescription
ConnectionFactoryOptional or only once inside the NotificationJMS elementSpecifies use of a JMS ConnectionFactory implementation
ConnectionJNDIOptional or only once inside the NotificationJMS elementSpecifies use of a JNDI properties file to create a JNDI IntialContextFactory


JMS message:

ElementElement descriptionDescription
MessageRequired, only once inside of NotificationJMS elementBody of a JMS notification

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationJMS / ConnectionFactory

Specifies use of a JMS ConnectionFactory implementation.

ConnectionFactory supports the following attributes:  

AttributeUsageDescription
java_classRequired

Java class of the JMS ConnectionFactory

e.g.: org.apache.activemq.ActiveMQConnectionFactory

user_nameOptionalThe caller's user name
passwordOptionalThe caller's password

 The following element can be nested inside a ConnectionFactory element:

ElementElement descriptionDescription
ConstructorArgumentsOptional or only once inside of ConnectionFactory element   

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationJMS / ConnectionFactory / ConstructorArguments

The following elements can be nested inside a ConstructorArguments element:

ElementElement descriptionDescription
ArgumentRequired, multiple use allowed inside the ConstructorArguments element  JMS ConnectionFactory constructor argument

 

Example: ActiveMQConnectionFactory with 1 constructor argument  Expand source

 

Example: ActiveMQConnectionFactory with 3 constructor arguments  Expand source

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationJMS / ConnectionFactory / ConstructorArguments / Argument

 Argument supports the following attributes: 

Attribute
Usage
Description
typeRequired

Java type of a constructor argument.

Possible values:

  • boolean
  • double
  • float
  • int
  • long
  • short
  • java.lang.Boolean
  • java.lang.Double
  • java.lang.Float
  • java.lang.Integer
  • java.lang.Long
  • java.lang.Short
  • java.lang.String

 

Default: java.lang.String

The value of the constructor argument will be stored as CDATA node.

Example  Expand source

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationJMS / ConnectionJNDI

Specifies use of a JNDI properties file to create a JNDI IntialContextFactory.

See: Connecting to the JMS Server by Using JNDI

ConnectionJNDI supports the following attributes:  

AttributeUsageDescription
fileRequiredPath of the JNDI properties file
lookup_nameOptional

Name to lookup JMS connection factory objects

 

Default: ConnectionFactory

 

Example: content of the JNDI properties file for ActiveMQ  Expand source

 

SystemMonitorNotification / Notification / NotificationMonitor / NotificationJMS / Message

Body of a JMS notification.

See : Message, Examples


SystemMonitorNotification / Notification / NotificationObjects

One of the following elements must be nested inside a NotificationObjects element:

ElementElement descriptionDescription
Job Optional or multiple use allowed inside the NotificationObjects element  Restricts notifications for order or standalone jobs 
JobChainOptional or multiple use allowed inside the NotificationObjects elementRestricts notifications for job chains
TimerRefOptional or multiple use allowed inside the NotificationObjects elementRestricts notifications for performance checks (Timer)
Example  Expand source

 

SystemMonitorNotification / Notification / NotificationObjects / Job 

Note:

This element specifies the order-controlled or standalone jobs for which notifications are being sent to a system monitor.

Support for standalone jobs starting with JITL-400 - JobScheduler Monitoring Interface should support standalone jobs Released .

 

Job supports the following attributes:

AttributeUsageDescription
notifications

Optional

Integer

Specifies the number of transfers the same notification to a System Monitor.

Default: 1

scheduler_idOptional

Notifications are restricted to the JobScheduler instance with the given identification. By default notifications will be sent for all JobScheduler instances that log into the same database.

Regular expression can be used.

nameOptional

Job name including possible folder names.

Regular expression can be used.

JITL-353 - Monitoring Interface should recognize the configured JobChain/Job/TimerJobChain with the leading "/" character Released

return_code_from Optional Restricts notifications for jobs for a particular return code range. 
return_code_from Optional  Restricts notifications for jobs for a particular return code range.  
Example  Expand source

 

SystemMonitorNotification / Notification / NotificationObjects / JobChain

JobChain supports the following attributes:

AttributeUsageDescription
notifications

Optional

Integer

Specifies the number of transfers the same notification to a System Monitor.

Default: 1

scheduler_idOptional

Notifications are restricted to the JobScheduler instance with the given identification. By default notifications will be sent for all JobScheduler instances that log into the same database.

Regular expression can be used.

nameOptional

Job chain name including possible folder names.

Regular expression can be used.

JITL-353 - Monitoring Interface should recognize the configured JobChain/Job/TimerJobChain with the leading "/" character Released

return_code_from Optional Restricts notifications for job chains  for a particular return code range. 
return_code_from Optional  Restricts notifications for job chains for a particular return code range.  
step_fromOptionalRestricts notifications for job chains to a sequence of job nodes that are specified with the step_from and step_to attributes.
step_toOptionalRestricts notifications for job chains to a sequence of job nodes that are specified with the step_from and step_to attributes.
excluded_stepsOptionalSpecifies the steps which will be excluded from the analyzing (separated by semicolon)
Example  Expand source

 

SystemMonitorNotification / Notification / NotificationObjects / TimerRef

TimerRef supports the following attributes:

AttributeUsageDescription
notifications

Optional

Integer

Specifies the number of transfers the same notification to a System Monitor.

Default: 1

refOptionalCorresponds with Timer name setting defined in the SystemMonitorNotification / Timer element
notify_on_error

 

Optional

Boolean

Send timer check notification when the configured job chain contains the error notifications.

Default: false

Example  Expand source

 

SystemMonitorNotification / Timer 

The following elements must be nested inside a Timer element:

ElementElement descriptionDescription
TimerJob Optional or multiple use allowed inside the Timer element 

Restricts notifications for order-controlled or standalone jobs.

JITL-401 - JobScheduler Monitoring Interface should support the job timers Released  

TimerJobChainOptional or multiple use allowed inside the Timer elementRestricts notifications for job chains
MinimumOptional or only once inside the Timer elementMinimum required execution time for job chains or selected job nodes. Allows script code to be executed that returns the minimum execution time in seconds.
MaximumOptional or only once inside the Timer elementMaximum allowed execution time for job chains or selected job nodes. Allows script code to be executed that returns the maximum execution time in seconds.
Example  Expand source

Timer supports the following attributes:

AttributeUsageDescription
 nameRequired

Corresponds to Timer used in the SystemMonitorNotification / Notification / NotificationObjects / TimerRef element.

The name must be unique across all timers definitions.

Example  Expand source

 

SystemMonitorNotification / Timer / TimerJob

JITL-401 - JobScheduler Monitoring Interface should support the job timers Released

TimerJob supports the following attributes: 

AtributeUsageDescription
 scheduler_idOptional

Notifications are restricted to the JobScheduler instance with the given identification. By default notifications will be sent for all JobScheduler instances that log into the same database.

Regular expression can be used.

 nameOptional

Job name including possible folder names.

Regular expression can be used.

 

 

Example  Expand source

 

SystemMonitorNotification / Timer / TimerJobChain

TimerJobChain supports the following attributes:

AttributeUsageDescription
 scheduler_idOptional

Notifications are restricted to the JobScheduler instance with the given identification. By default notifications will be sent for all JobScheduler instances that log into the same database.

Regular expression can be used.

 nameOptional

Job chain name including possible folder names.

Regular expression can be used.

JITL-353 - Monitoring Interface should recognize the configured JobChain/Job/TimerJobChain with the leading "/" character Released

 step_fromOptionalRestricts checks for job chains to a sequence of job nodes that are specified with the step_from and step_to attributes.
 step_toOptionalRestricts checks for job chains to a sequence of job nodes that are specified with the step_from and step_to attributes.
Example  Expand source

 

SystemMonitorNotification / Timer / Minimum

The following elements must be nested inside a Minimum element:

ElementElement descriptionDescription
ScriptRequired, only once inside the Minimum elementScript code in one of the supported languages
Example  Expand source

 

SystemMonitorNotification / Timer / Maximum

The following elements must be nested inside a Maximum element:

ElementElement descriptionDescription
ScriptRequired, only once inside the Maximum elementScript code in one of the supported languages
Example  Expand source

 

SystemMonitorNotification / Timer / Minimum|Maximum / Script

Script supports the following attributes:

AttributeUsageDescription
 languageRequired

Script language name

Supported languages:

  • javascript
  • ECMAScript 

 The Script element can contain:

  • a fixed value
  • a calculation based on the job/order parameters
Fixed value

A fixed value is the time allowed in seconds for the specific Minimum or Maximum definition

Example (fixed value)  Expand source
Calculation

The calculation is to result in the time in seconds for the specific Minimum or Maximum definition.

This example calculates the execution time depending on the ${file_size} parameter that was set by a specific job (see the example below)´.

Example (calculation)  Expand source

 

This example job calculates and creates a new order parameter file_size.

To store the parameters into database (table SCHEDULER_MON_RESULTS) :

  • set the scheduler_notification_result_parameters parameter (see job documentation jobs/JobSchedulerNotificationStoreResultsJob.xml)
  • set the StoreResultsJobJSAdapterClass as monitor
    • JobScheduler version 1.9.x, 1.10.x
      • com.sos.scheduler.notification.jobs.result.StoreResultsJobJSAdapterClass
    • JobScheduler version 1.11.x

      • com.sos.jitl.notification.jobs.result.StoreResultsJobJSAdapterClass
Example (order job)  Expand source

 

Message

Usage

The Message can be configured on the following parent nodes as a CDATA element :

  • SystemMonitorNotification / Notification / NotificationInterface
  • SystemMonitorNotification / Notification / NotificationCommand
  • SystemMonitorNotification / Notification / NotificationMail 
    • Subject
    • Body
  • SystemMonitorNotification / Notification / NotificationJMS / Message

The Message can contain: 

  • Fixed values
  • Variables

Example: <![CDATA[ scheduler id = ${MON_N_SCHEDULER_ID}  ]]>

Variables

All variables (except OS environment variables) must be defined by using of the

${<variable name>}

syntax.

Note:

  • Syntax for the JobScheduler version 1.10.6 and higher. Syntax for the JobScheduler version 1.10.4, 1.10.5 (see below) is still supported.
  • Syntax for the JobScheduler version 1.10.4, 1.10.5:  {<variable name>}
  • Syntax for the JobScheduler previous versions: %<variable name>%

The order of the substitution the variables values is:

  1. Table variables.
  2. Service variables.
  3. JOC Cockpit variables.
  4. OS environment variables.

Table variables
 Variables: table SCHEDULER_MON_NOTIFICATIONS

 Table of the history of steps of processed orders / jobs.

NameDescription  Note
${MON_N_ID}
Unique notification id 
${MON_N_SCHEDULER_ID} Id of the JobScheduler 
${MON_N_TASK_ID}Id of the JobScheduler task  
${MON_N_STEP} Consecutive number of the order step 
${MON_N_ORDER_HISTORY_ID} Id of the JobScheduler order  
${MON_N_JOB_CHAIN_NAME} Name of the job chain of the order  
${MON_N_JOB_CHAIN_TITLE}Title of the job chain of the order   
${MON_N_ORDER_ID} Unique (within the job chain) id of the order  
${MON_N_ORDER_TITLE} Title of the order  
${MON_N_ORDER_START_TIME} Timestamp of the start of the order 
${MON_N_ORDER_END_TIME} Timestamp of the end of the order 
${MON_N_ORDER_TIME_ELAPSED} The time or difference in seconds between a beginning time and an ending time of the order 
${MON_N_ORDER_STEP_STATE} State of the order inside the job chain 
${MON_N_ORDER_STEP_START_TIME}Timestamp of the start of the order step  
${MON_N_ORDER_STEP_END_TIME} Timestamp of the end of the order step  
${MON_N_ORDER_STEP_TIME_ELAPSED}The time or difference in seconds between a beginning time and an ending time of the order step  
${MON_N_JOB_NAME}Name of the job  
${MON_N_JOB_TITLE}Title of the job 
${MON_N_TASK_START_TIME}Timestamp of the job task start  
${MON_N_TASK_END_TIME} Timestamp of the job task end 
${MON_N_TASK_TIME_ELAPSED} The time or difference in seconds between a beginning time and an ending time of the job task 
${MON_N_RECOVERED} 

0 = dependent of the ${MON_N_ERROR} - ok or error was not recovered,

1 = error was recovered  

 
${MON_N_RETURN_CODE}Return code number  
${MON_N_AGENT_URL}JobScheduler Agent uri 

available with release 1.11.2

JITL-351 - Add Agent identification to Monitoring Interface Released

${MON_N_CLUSTER_MEMBER_ID} ID of the Scheduler cluster member (only used in cluster mode)

available with release 1.11.2

JITL-352 - Add Cluster member identification to Monitoring Interface Released

${MON_N_ERROR}

0 = ok

1 = error 

 
${MON_N_ERROR_CODE} Exception-code of the job error  
${MON_N_ERROR_TEXT}Exception message of the job (that processed the order)  
${MON_N_CREATED} Timestamp of the notification initial record  
${MON_N_MODIFIED}Timestamp of the latest changes to this notification record  

 

Example  Expand source
 Variables: table SCHEDULER_MON_SYSNOTIFICATIONS

 Table of the history of notifications sent to a system monitor.

NameDescription
${MON_SN_ID}Unique system notification id 
${MON_SN_NOTIFICATION_ID}

Reference to the SCHEDULER_MON_NOTIFICATIONS.ID  table

${MON_SN_CHECK_ID}

Reference to the SCHEDULER_MON_CHECKS.ID   table

${MON_SN_SYSTEM_ID} 

Reference to the element attribute

SystemMonitorNotification / @system_id

defined in the XML configuration file

${MON_SN_SERVICE_NAME}

Reference to one of both element attributes

  • SystemMonitorNotification / Notification / NotificationMonitor / @service_name_on_error
  • SystemMonitorNotification / Notification / NotificationMonitor / @service_name_on_success

defined in the XML configuration file 

${MON_SN_OBJECT_TYPE}

NotificationObject type

  0 = JobChain

  1 = Job

100 = dummy code for interlal using 

${MON_SN_RETURN_CODE_FROM} 

Reference to the element attribute

SystemMonitorNotification / Notification / NotificationObjects / JobChain / @return_code_from

defined in the XML configuration file

${MON_SN_RETURN_CODE_TO}

Reference to the element attribute

SystemMonitorNotification / Notification / NotificationObjects / JobChain / @return_code_to

defined in the XML configuration file 

${MON_SN_STEP_FROM}

Reference to the element attribute

SystemMonitorNotification / Notification / NotificationObjects / JobChain / @step_from

defined in the XML configuration file 

${MON_SN_STEP_TO}

Reference to the element attribute

SystemMonitorNotification / Notification / NotificationObjects / JobChain / @step_to

defined in the XML configuration file 

${MON_SN_STEP_FROM_START_TIME}Timestamp for the start of the order step 
${MON_SN_STEP_TO_END_TIME}Timestamp for the end of the order step  
${MON_SN_STEP_TIME_ELAPSED} The elapsed time or the difference in seconds between the start and end times of the order step  
${MON_SN_NOTIFICATIONS}

Reference to element attribute

SystemMonitorNotification / Notification / NotificationObjects / JobChain / @notifications

defined in the XML configuration file  

${MON_SN_CURRENT_NOTIFICATION}Number of notifications that already sent to a System Monitor
${MON_SN_MAX_NOTIFICATIONS}

0 = notifications counter was not reached

1 = notifications counter was reached, all configured notifications were sent

${MON_SN_ACKNOWLEDGED}

0 = not acknowledged

1 = acknowledged 

${MON_SN_RECOVERED}

0 = recovery not sent

1 = recovery sent

${MON_SN_SUCCESS}

0 = Notification onError, SystemMonitorNotification / Notification / NotificationMonitor / @service_name_on_error

1 = Notification onSuccess, SystemMonitorNotification / Notification / NotificationMonitor / @service_name_on_success

${MON_SN_CREATED}Timestamp of the initial system notification record  
${MON_SN_MODIFIED}Timestamp of the latest changes to this system notification record  
Example  Expand source
 Variables: table SCHEDULER_MON_CHECKS

 Table of the history of executed checks (Timer)

NameDescription
${MON_C_ID}Unique check id  
${MON_C_NOTIFICATION_ID}

Reference to table SCHEDULER_MON_NOTIFICATIONS.ID   

${MON_C_NAME}

Reference to element attribute

SystemMonitorNotification / Timer / @name

defined in the XML configuration file 

${MON_C_STEP_FROM} 

Reference to element attribute

SystemMonitorNotification / Timer / TimerJobChain / @step_from

defined in the XML configuration file

 
${MON_C_STEP_TO}

Reference to element attribute

SystemMonitorNotification / Timer / TimerJobChain / @step_to

defined in the XML configuration file

${MON_C_STEP_FROM_START_TIME} Timestamp of the start of the order step  
${MON_C_STEP_TO_END_TIME} Timestamp of the end of the order step  
${MON_C_STEP_TIME_ELAPSED} The time or difference in seconds between a beginning time and an ending time of the order step   
${MON_C_CHECK_TEXT} Message of the check  
${MON_C_CREATED}Timestamp of the check initial record  
${MON_C_MODIFIED}Timestamp of the latest changes to this check record 
Example  Expand source


Service variables
 Variables
NameDescription
${SERVICE_NAME}

Current service name. One of both element attributes:

  • SystemMonitorNotification / Notification / NotificationMonitor / @service_name_on_error
  • SystemMonitorNotification / Notification / NotificationMonitor / @service_name_on_success
${SERVICE_STATUS}

Current service status. One of both element attributes or default: 

  • SystemMonitorNotification / Notification / NotificationMonitor / @service_status_on_error
  • SystemMonitorNotification / Notification / NotificationMonitor / @service_status_on_success
  • default CRITICAL error
  • default OK       success
${SERVICE_MESSAGE_PREFIX}

Message prefix

  • ERROR       error
  • RECOVERED     error recovery
  • TIMER       performance check
Example  Expand source

 

JOC Cockpit variables

JS-1388 - Add e-mail as a monitor service for the JobScheduler Monitoring Interface Released

Note:

  • the JOC Cockpit variables will be substituted only when the NotificationMail interface is used.

Requirement:

  •  config/private/private.conf configuration file is active and contains the configured joc.url entry.


 Variables
NameDescription
${JOC_HREF_JOB_CHAIN}Link href to the job chain object in the JOC Cockpit
${JOC_HREF_ORDER}Link href to the order object in the JOC Cockpit
${JOC_HREF_JOB}Link href to the job object in the JOC Cockpit

 

Example  Expand source

 

OS environment variables 

 All existing OS environment variables can be defined by message using the syntax %<variable name>% (Windows) or $<variable name> (Unix).

Example Windows  Expand source

 

Notification environment variables

The default SystemNotifierProcessBuilderPlugin plugin used by the SystemMonitorNotification / Notification / NotificationCommand element sets the following variables as environment variables:

  1. Table variables
  2. Service variables

These variables can be used when the NotificationCommand calls the notification client - not directly but via a shell script that makes the logical implementation for sending the notification messages.

Table variables
 Variables

All table variables (see Table variables explanation) are set as environment variables with the prefix:

  • SCHEDULER_MON_TABLE_

e.g.:

  • SCHEDULER_MON_TABLE_MON_N_ID
  • SCHEDULER_MON_TABLE_MON_N_SCHEDULER_ID
  • ...
Service variables
 Variables
NameDescription

SCHEDULER_MON_SERVICE_NAME

Current service name. One of both element attributes:

  • SystemMonitorNotification / Notification / NotificationMonitor / @service_name_on_error
  • SystemMonitorNotification / Notification / NotificationMonitor / @service_name_on_success

SCHEDULER_MON_SERVICE_STATUS

Current service status. One of both element attributes or default:

  • SystemMonitorNotification / Notification / NotificationMonitor / @service_status_on_error
  • SystemMonitorNotification / Notification / NotificationMonitor / @service_status_on_success
  • default CRITICAL error
  • default OK       success

SCHEDULER_MON_SERVICE_MESSAGE_PREFIX

  • ERROR      error                           
  • RECOVERED    error recovery                            
  • TIMER             performance check 

SCHEDULER_MON_SERVICE_COMMAND

 Content of the SystemMonitorNotification / Notification / NotificationCommand after substitution

  

Sample NotificationCommand Unix. Script file (/tmp/command.sh).  Expand source
Sample NotificationCommand Windows. Script file (C:/temp/command.cmd).  Expand source

Examples

Message on error


Message on success


Message on performance check (Timer)


Examples System Monitoring
NotificationInterface ( Nagios / OP5 )

The following is an except from an XML file used to notify a specific System Monitor (op5 Monitor) via the NotificationInterface:

SystemMonitorNotification_op5.xml  Expand source
NotificationCommand ( Nagios / OP5 )

The following is an except from an XML file used to notifying a specific System Monitor (op5 Monitor) via the NotificationCommand on Windows:

SystemMonitorNotification_OP5.xml  Expand source
 NotificationCommand ( Zabbix )

The following is an except from an XML file used to notify a specific System Monitor (Zabbix Monitor) and using NotificationCommand

SystemMonitorNotification_zabbix.xml  Expand source

 

Examples Mail
NotificationMail content_type="text/html"
Mail: on failed job chain  Expand source
Mail: on successful job chain  Expand source
Mail: on failed job  Expand source
Mail: on successful job  Expand source

 

JobScheduler - Store parameters to database

The Monitoring Interface provide functionality to store the job/order parameters of the specific jobs into database (table SCHEDULER_MON_RESULTS).

See explanation : Calculation

JobScheduler - Job Chains

The following job chains are provided and should be configured accordingly:

sos / notification / CheckHistory (JobScheduler version 1.9.x, 1.10.x)

See <scheduler_install>/jobs/JobSchedulerNotificationCheckHistoryJob.xml

  • This is the main job that analyze the JobScheduler history tables und write results into the notification tables.
    • Job read all history entries for the job chains, configured in the SystemMonitorNotification XML files.
    • Job execute the performance checks for the defined Timers
  • Order Check
    • configure repeat interval for order run time, e.g. every two minutes.

sos / notification / CheckHistory (JobScheduler version 1.11.x)

  • Job chain removed
  • Set param sos.use_notification true (config/scheduler.xml)

JobScheduler version 1.11.x config/scheduler.xml  Expand source

 

sos / notification / SystemNotifier

See <scheduler_install>/jobs/JobSchedulerNotificationSystemNotifierJob.xml

  • Sends notifications to a specific System Monitor.
  • Order MonitorSystem
    • JobScheduler version 1.9.x, 1.10.x
      • configures a repeat interval for the order run time that is not less than the interval that has been chosen for triggering the job chain sos/notification/CheckHistory

sos / notification / CleanupNotifications

See <scheduler_install>/jobs/JobSchedulerNotificationCleanupNotificationsJob.xml

  • Removes notifications that have expired. 
  • Order Cleanup
    • configure start time for order run time, e.g. 24:00

sos / notification / ResetNotifications

See <scheduler_install>/jobs/JobSchedulerNotificationResetNotificationsJob.xml

  • Some System Monitors may provide an "acknowledge" operation, that signaling has known problem.
  • Should an "acknowledge" operation have been performed for a specific service in the System Monitor then job chain ResetNotifications would stop JobScheduler from sending notifications for that service for errors that have already occurred.
  • Do not configure the order run time for this job chain, as job chain will be triggered by the System Monitor's "acknowledge" operation via add_order XML command.
Examples
Example ResetNotifications <add_order> XML command

The following example shows the XML command sent from a monitoring system to the JobScheduler to call the sos/notification/ResetNotifications job chain and set the relevant service name as acknowledged.

ResetNotifications OP5 add_order  Expand source

Key to the above code:

ElementAttributeValue Description
add_order   XML Command to add the new order to the specified job chain on the JobScheduler.
 job_chainsos/notification/ResetNotifications Job chain path must correspond with the path of the ResetNotifications job chain installed on the JobScheduler.
 id  Order identifier.
 title  Order title.
param   3 following parameters must be set:
 nameservice_name
JobScheduler Monitoring Error
Relevant service name to set all already occured service errors in JobScheduler Interface Monitor as acknowledged.
 namesystem_idop5

System identification.

Corresponds with SystemMonitorNotification/@system_id setting in the  SystemMonitorNotification_<MonitorSystem>.xml configuration file.

 nameoperationacknowledgeFixed value. Operation name to execute the acknowledgement in the JobScheduler Monitoring Interface.
Example ResetNotifications <add_order> XML command via Perl script for op5 monitor system

This example shows the integration of a Perl script into op5 monitor system that automatically sends the above XML command to the JobScheduler sos/notification/ResetNotifications job chain.

The "Acknowledgment" on the op5 Monitor side works as follows:

  1. Contact "acknowledgment" + Event Handler:
    • it first of all requires a contact, that receives the Notifications in the same way as the other contacts. However, an event notification for this contact is not received via Mail but an Event Handler, i.e.  an XML command will be executed instead of a mail being received. (Please see the next point, Notification Command.)
  2. The "svc_notify_ack_handle" Notification Command:
    • this command will always be executed for the services that are specified for the contact. This command is executed when the service status changes (for example, by a change from OK to Critical or Acknowledgment of an Error).
    • The command executes a check_acknowledge.pl script.
  3. The check_acknowledge.pl Script (see the example below): this script is executed by the command and first of all checks whether the command is a response to an Acknowledgment:
    • If the command is not a response to an Acknowledgment: then nothing happens
    • If the command is a response to an Acknowledgment      : then the script causes the JobScheduler to be contacted and sent am XML query, that instructs the JobScheduler to start a specific job chain (the sos/notification/ResetNotifications chain)

check_acknowledge.pl  Expand source

JobScheduler - Job Chains customization

The default name of the monitor system used in the configuration files and stored in the JobScheduler database is "MonitorSystem".

The default configuration can be changed to allow better customization of the monitoring systems used.

Example customization for the op5 system monitor:

  • <scheduler_install>/config/notification/SystemMonitorNotification_MonitorSystem.xml
    • rename this file to  SystemMonitorNotification_op5.xml
    • set system_id attribute to op5
      • e.g. <SystemMonitorNotification system_id="op5">
  • <scheduler_install>/config/live/sos/notification/SystemNotifier,MonitorSystem.order.xml
    • rename this file to SystemNotifier,op5.order.xml
    • set system_configuration_file attribute to SystemMonitorNotification_op5.xml
      • e.g. <param name="system_configuration_file" value="config/notification/SystemMonitorNotification_op5.xml"/>
  •  <scheduler_install>/config/live/sos/notification/ResetNotifications,AcknowledgeMonitorSystem.order.xml
    • rename this file to ResetNotifications,Acknowledgeop5.order.xml
    • set system_id attribute to op5
      • e.g. <param name="system_id" value="op5"/>

JobScheduler - Cluster

See Cluster Operation

In case of Cluster Operation please modify the job_chain element definition for all notification job chain files

  • add distributed="yes" attribute.
    • e.g: <job_chain distributed="yes" ...
  • remove orders_recoverable="no" attribute if exists

Following job chain files must be modified in the notification directory <scheduler_install>/config/live/sos/notification/:

  • CheckHistory.job_chain.xml
  • CleanupNotifications.job_chain.xml
  • ResetNotifications.job_chain.xml
  • SystemNotifier.job_chain.xml

Use Cases

Workflow Execution takes too long

Initial Situation

A Job Chain is triggered and it could not end, it hang in a step, taking longer than expected.

Problem

Execution time was too long

Handling

A timer for this Job Chain has been set and the System Monitor notified about it. The expiration times for the Job Chains are configured with enough time for processing. This is usually used for cases where the Job Chain could hang in a specific step.

Configuration

SFTP connection refused

Initial Situation

Consider a Job Chain that uses SFTP for transferring files. You have a setback configured in this step of the Job Chain, so that if the connection to the SFTP server fails, this step is retried after a specified time.

Problem

The SFTP server is not available anymore.

Handling

The System Monitor will be notified to the service related to the Job Chain with the message error. However, you don't want to have repeated notifications for a Job Chain when is an external factor, the connection to the SFTP Server, is producing the error.

Configuration

Thresholds

Initial Situation

Consider the situation where a workflow has to be executed successfully a specific number of times before a specific point in time. This means that a specific value has to be monitored in order to determine if this quote was reached.

Handling

A new History service is configured, so that the workflow executions (Job Chains in the JobScheduler vocabulary) send the information that they have been successfully executed to the System Monitor.

Configuration

Acknowledgment

Initial Situation

An alert for a Service has been sent to the System Monitor, which has sent a Mail to the Service Desk (Support Team) notifying them about the alert.

Handling

The problem is known to the Service Desk and they "acknowledge" the problem. The acknowledgment will cause the JobScheduler to be notified not to send any more notifications for this Service to the System Monitor until the Service has been recovered.

Configuration

 

Recoverable Errors

Initial Situation

You have a setback configured in one of the steps of the Job Chain, so that if the step execution fails, this step is retried after a specified time.

Problem

The step has ended with an error, but recovered after setback

Handling

If the error message has been sent to the System Monitor, in case of error recovery JobScheduler will automatically sent the recovery message on the same service with the same error message and the prefix RECOVERED.

Configuration

Change Management References

Loading
T Key Linked Issues Fix Version/s Status P Summary Updated
Feature JS-1600 1.9.11, 1.10.4, 1.11 Released Minor Monitoring Interface is capable of routing Return Codes Apr 22, 2016
Feature JS-1446 JS-1445 2.0 Clarify Minor Log entries that are not dependent from JobScheduler objects should be available for JobScheduler Monitoring Interface Dec 08, 2017
Feature JS-1388 1.12 Released Major Add e-mail as a monitor service for the JobScheduler Monitoring Interface Dec 21, 2017
Feature JS-684 JS-1291 , JS-1589 , JS-1426 , JS-1410 , JS-1480 1.10 Released Major System Monitor (Nagios, op5) should notify if a JobScheduler Universal Agent is not available Feb 10, 2016
Fix JITL-435 1.11.6, 1.12 Released Minor JobScheduler Monitoring Interface should handle next steps after sending the recovery message Jan 30, 2018
Feature JITL-427 1.11.6, 1.12 Released Minor JobScheduler Montitorig Interface. Performance improvement for SystemNotifier job. Feb 01, 2018
Feature JITL-401 1.11.5, 1.12 Released Minor JobScheduler Monitoring Interface should support the job timers Nov 11, 2017
Feature JITL-400 1.11.5, 1.12 Released Minor JobScheduler Monitoring Interface should support standalone jobs Nov 11, 2017
Feature JITL-353 1.11.2, 1.12 Released Minor Monitoring Interface should recognize the configured JobChain/Job/TimerJobChain with the leading "/" character Dec 21, 2017
Feature JITL-352 1.11.2, 1.12 Released Minor Add Cluster member identification to Monitoring Interface Dec 21, 2017
Feature JITL-351 1.11.2, 1.12 Released Minor Add Agent identification to Monitoring Interface Dec 21, 2017
Feature JITL-280 1.12 Released Minor Add JMS support to the JobScheduler Monitoring Interface Dec 21, 2017
Feature JITL-264 JS-1132 , JS-1562 2.0 Deferred Minor Add selected job and order parameters to the JobScheduler Reporting Interface Nov 13, 2017
Feature JITL-230 1.9.8, 1.10.2, 1.11 Released Minor JobScheduler Monitoring Interface jobs should consider updated Timer elements Dec 17, 2015
Feature JITL-166 1.9 Released Minor JobScheduler Monitoring Interface should use batch insert for improved performance Dec 10, 2015