Notification enhancement
Subscribe

From OpenNMS

Jump to: navigation, search
OpenNMS version 1.1.4
2004-10-7
Version 1
David Hustace
The OpenNMS Group, Inc.

Contents

Elimination of non-Java dependencies

An OpenNMS objective to become a 100% Java application, requires elimination of the following dependencies:

  • /bin/mail
  • Perl
  • metamail package

These dependencies are used for two functions of the OpenNMS application: Notification and Availability reporting. This narrative discusses these changes with respect to using the new Java Mail API and how Java developers can extend the new notification interface.

Using the new Java Mail API implementation

Java Mail notifications.

Installing a fresh copy of OpenNMS will now use the Java Mail API by default. Upgrade installs will create 2 new files that the user will have to merge into their existing configurations: destinationPaths.xml.rpmnew and notficationCommands.xml.rpmnew

$OPENNMS_HOME/etc/javamail-configuration.properties

This new properties file should be modified to specify the sender's address and the SMTP server address. This file also provides support for SMTP servers requiring user and password authentication.

org.opennms.core.utils.useJMTA 
If set to true a non-queueing Java-based MTA will be used. It performs mail exchanger (MX) record lookup and sends email directly to the appropriate mail server. If set to false, all email will be delivered to the smart host specified by org.opennms.core.utils.mailHost, which will need to relay the email to the appropriate mail server. If use need to always send mail to a specific host and/or authenticate to the mail host, you must set useJMTA to false. Defaults to true.
org.opennms.core.utils.fromAddress 
Defaults to "root@[127.0.0.1] ".
org.opennms.core.utils.mailHost 
This option only makes sense when useJMTA is set to false. If useJMTA is set to true, this option is ignored. Defaults to "127.0.0.1".
org.opennms.core.utils.mailer 
Defaults to "smtpsend".
org.opennms.core.utils.transport 
Defaults to "smtp".
org.opennms.core.utils.debug 
Defaults to true.
org.opennms.core.utils.authenticate 
Set to "true" to enable authentication to mail servers. This option only makes sense when useJMTA is set to false. If useJMTA is set to true, this option is ignored. Defaults to false.
org.opennms.core.utils.authenticateUser 
User to authenticate as. This option only makes sense when useJMTA is set to false. If useJMTA is set to true, this option is ignored. Defaults to "opennms".
org.opennms.core.utils.authenticatePassword 
Password to authenticate with. This option only makes sense when useJMTA is set to false. If useJMTA is set to true, this option is ignored. Defaults to "opennms".


Gmail example javamail-configuration.properties (sends a notification to a gmail account).

$OPENNMS_HOME/etc/notificationCommands.xml

The schema definition for this file has changed requiring that the <command> tag now has an attribute called 'binary' and a value of either "true" or "false". This flag indicates to the OpenNMS notification processes that the command definition is either a system command (as it always has been prior to this release) or an OpenNMS Java class (see deveolper notes below). The 1.1.4 version of this file now has added the following new command definitions: 

<command binary="false">
  <name>javaPagerEmail</name>
  <execute>org.opennms.netmgt.notifd.JavaMailNotificationStrategy</execute>
  <comment>class for sending pager email notifications</comment>
  <argument streamed="false">
    <switch>-subject</switch>
  </argument>
  <argument streamed="false">
    <switch>-pemail</switch>
  </argument>
  <argument streamed="false">
    <switch>-tm</switch>
  </argument>
</command>

<command binary="false">
  <name>javaEmail</name>
  <execute>org.opennms.netmgt.notifd.JavaMailNotificationStrategy</execute>
  <comment>class for sending email notifications</comment>
  <argument streamed="false">
    <switch>-subject</switch>
  </argument>
  <argument streamed="false">
    <switch>-email</switch>
  </argument>
  <argument streamed="false">
    <switch>-tm</switch>
  </argument>
</command>

Notice a few changes:

  • The <command> tag now has an attribute called 'binary' that when set to "true" will cause the notification process to attempt to execute a system command specified in the <execute> tag. When not set or set to anything other than "true", the notification process assumes it is an OpenNMS notification class and will instantiate it and execute its 'send()' method. By convention, the "binary" attribute will be set to "false" when new notification classes are implemented.
  • The <substitution> arguments are not used for notification classes but are still supported for notification commands. These "substitution" arguments (allthough not gramatially intuitive) are passed to system commands as a command line argument when the 'binary' attribute is set to "true" and is otherwise ignored. Example: 
    <command binary="true">
        <name>externalCommand</name>
        <execute>/path/to/external/command</execute>
        <argument streamed="false">
            <substitution>argument_one</substitution>
        </argument>
        <argument streamed="false">
            <substitution>argument_two</substitution>
        </argument>
    </command
  • The <execute> tag now allows the specification of an OpenNMS Java class name. This class name must implement the NotificationStrategy interface (see developer notes below). The new JavaMailNotificationStrategy class accepts the following <switch> tags: -subject, -email, -pemail, -tm.

$OPENNMS_HOME/etc/destinationPaths.xml

This file has changed making the default email and pager email notifications use the new Java Mail API. All 'email' and 'pagerEmail' <command> tags have been changed to the new 'javaEmail' and 'javaPagerEmail' commands in $OPENNMS_HOME/etc/notificationCommands.xml.

Developer notes

Work completed

The Sun Java Mail API jar files were added to the OpenNMS project and two new interfaces were created following the "strategy" design pattern. The ExecutorStrategy interfaces requires an 'execute()' method and the NotificationStrategy inteface requires a 'send()' method be implemented.

ExecutorStrategy class

Which implementation of the ExecutorStrategy is used is determined by the setting of the 'binary' attribute of the command being processed. When 'binary' is set to "false", ClassExecutor is instantiated and the ClassExecutor.execute() method is called otherwise the CommandExecutor is instantiated and its CommandExecutor.execute() method is called. 

if (command.getExecute.equals("false")) {
    ExecutorStrategy command = new ClassExecutor();
} else {
    ExecutorStrategy command = new CommandExecutor();
}
command.execute(commandLine, arguments);

This approach was chose to provide full backwards compatibility with the current notificationCommands.xml schema and will work with configuration files prior to 1.1.4 without any changes.

NotificationStrategy class

To create new notification classes that can be used in the notificationsCommands.xml file, the new class must implement this interface. The ClassExecutor will simply call the 'NotificationStrategy.send()' method from this implementation and it is up to the new class to process the notification in its special way and return an 'int 0' for successfull or an 'int 1' for unsuccessfull notifications. The ClassExecutor will catch exceptions and return 'int 1'.

Arguments can be passed to this new class in the form of <substitution> attributes in the notificationCommands.xml file. Place this new class in the org.opennms.netmgt.notifd package and add a notificationCommands.xml <command> entry. No changes are required to the Ant build.

Note:<switch> and <substitution> tags are reversed in their function and grammer and will be fixed soon.

NotificationManager class

This class some defines special switches, providing data for the class / command that executes (for use in notificationCommands.xml)

Internal Name Switch Name Comment
PARAM_TYPE -t binary y/n
PARAM_DESTINATION -d from notifications.xml
PARAM_TEXT_MSG -tm from notifications.xml
PARAM_NUM_MSG -nm from notifications.xml
PARAM_RESPONSE -r  ?
PARAM_NODE -nodeid from original event
PARAM_INTERFACE -interface from original event
PARAM_SERVICE -service from original event
PARAM_SUBJECT -subject from notifications.xml
PARAM_EMAIL -email from users.xml
PARAM_PAGER_EMAIL -pemail from users.xml
PARAM_XMPP_ADDRESS -xmpp from users.xml
PARAM_TEXT_PAGER_PIN -tp from users.xml
PARAM_NUM_PAGER_PIN -np from users.xml
PARAM_WORK_PHONE -wphone from users.xml
PARAM_HOME_PHONE -hphone from users.xml
PARAM_MOBILE_PHONE -mphone from users.xml
PARAM_TUI_PIN -tuipin  ?

Version History/Availability

Retrieved from "http://www.opennms.org/wiki/Notification_enhancement"