Notification Commands

A notification command is a named, reusable execution profile for a Java class or external program command used to convey notices to targets. Horizon includes several default notification commands. You can create custom commands to send notifications to a platform of your choice.

Default notification commands

callHomePhone, callMobilePhone, and callWorkPhone

Ring one of the phone numbers configured in the user’s contact information. All three commands are implemented using the in-process Asterisk notification strategy, and differ only by which contact field the command uses.

ircCat

Conveys a notice to an instance of the IRCcat Internet Relay Chat bot. Implemented by the in-process IRCcat notification strategy.

javaEmail and javaPagerEmail

By far the most commonly used commands, these deliver a notice to a user’s email or pagerEmail contact field value. By configuring a user’s pagerEmail contact field value to target an email-to-SMS gateway, you can easily configure SMS notifications. Both commands use the in-process JavaMail notification strategy for implementation.

microblogDM, microblogReply, and microblogUpdate

Sends a notice to a user as a direct message, at a user via an at reply, or to everybody as an update via a microblog service with a Twitter v1-compatible API. A separate, in-process notification strategy implements each command.

numericPage and textPage

Sends a notice to a user’s numeric or alphanumeric pager. Implemented as an external command using the qpage utility.

xmppGroupMessage and xmppMessage

Sends a message to an XMPP group or user. Implemented with the in-process XMPP notification strategy.

Custom notification commands

Edit the ${OPENNMS_HOME}/etc/notificationCommands.xml file to customize and extend notification commands.

Use external binary notification commands sparingly as they spawn additional process threads on your core Horizon system.

Custom command configuration

The streamed attribute dictates whether the substitution text and switch text (or both) will be placed in the command line or in the input stream when the command starts to run.

Place boilerplate arguments
   <argument streamed="false">
      <substitution>-D</substitution>
   </argument>
Place dynamic values
   <argument streamed="false">
      <switch>-tm</switch>
   </argument>
When you combine the two (substitution and switch), each is written as a separate argument in the command line. For example,

+

   <argument streamed="false">
      <substitution>-Dnodeid=</substitution>
      <switch>-nodeid</switch>
   </argument>
Translates to:
   -Dnodeid= 8
and not:
   -Dnodeid=8

Valid switches from the NotificationManager class

The NotificationManager class defines some special switches, providing data for the class or command that runs.

Internal Name Switch Name Source

PARAM_DESTINATION

-d

From notification definition

PARAM_EMAIL

-email

From user profile

PARAM_HOME_PHONE

-hphone

From user profile

PARAM_INTERFACE

-interface

From original event

PARAM_MICROBLOG_USERNAME

-ublog

From user profile

PARAM_MOBILE_PHONE

-mphone

From user profile

PARAM_NODE

-nodeid

From original event

PARAM_NUM_MSG

-nm

From notification definition

PARAM_NUM_PAGER_PIN

-np

From user profile

PARAM_PAGER_EMAIL

-pemail

From user profile

PARAM_RESPONSE

-r

From notification definition

PARAM_SERVICE

-service

From original event

PARAM_SUBJECT

-subject

From notification definition

PARAM_TEXT_MSG

-tm

From notification definition

PARAM_TEXT_PAGER_PIN

-tp

From user profile

PARAM_TUI_PIN

-tuipin

From user profile

PARAM_TYPE

-t

Binary yes or no

PARAM_TUI_PIN

-tuipin

From user profile

PARAM_WORK_PHONE

-wphone

From user profile

PARAM_XMPP_ADDRESS

-xmpp

From user profile

Extended dynamic values

You can pass arbitrary parameters from the notification to the notificationCommand via the <parameter> tag, which can then be used as required.

Examples

SnmpTrapNotificationStrategy

This configuration sends an OpenNMS trap to an external system with the nodelabel in the varbind.

    <notification name="snmpTrap" status="on">
        <uei>uei.opennms.org/nodes/nodeDown</uei>
        <rule>IPADDR IPLIKE *.*.*.*</rule>
        <destinationPath>trapNotifier</destinationPath>
        <text-message>
                All services are down on node %nodeid%.
        </text-message>
        <subject>node %nodeid% down.</subject>
        <numeric-message>111-%noticeid%</numeric-message>
        <parameter name="trapVersion" value="v1" />
        <parameter name="trapTransport" value="UDP" />
        <parameter name="trapHost" value="my-trap-host.mydomain.org" />
        <parameter name="trapPort" value="162" />
        <parameter name="trapCommunity" value="public" />
        <parameter name="trapEnterprise" value=".1.3.6.1.4.1.5813" />
        <parameter name="trapGeneric" value="6" />
        <parameter name="trapSpecific" value="1" />
        <parameter name="trapVarbind" value="Node: %nodelabel%" />
    </notification>

The parameters defined here are passed to the notification command as switches. You will see these in the notificationCommands.xml file:

    <command binary="false">
        <name>snmpTrap</name>
        <execute>org.opennms.netmgt.notifd.SnmpTrapNotificationStrategy</execute>
        <comment>Class for sending notifications as SNMP Traps</comment>
        <argument streamed="false">
                <switch>trapVersion</switch>
        </argument>
        <argument streamed="false">
                <switch>trapTransport</switch>
        </argument>
        <argument streamed="false">
                <switch>trapHost</switch>
        </argument>
        <argument streamed="false">
                <switch>trapPort</switch>
        </argument>
        <argument streamed="false">
                <switch>trapCommunity</switch>
        </argument>
        <argument streamed="false">
                <switch>trapEnterprise</switch>
        </argument>
        <argument streamed="false">
                <switch>trapGeneric</switch>
        </argument>
        <argument streamed="false">
                <switch>trapSpecific</switch>
        </argument>
        <argument streamed="false">
                <switch>trapVarbind</switch>
        </argument>
    </command>

You can define any or none of these parameters and switches. However, if you define a parameter in the notification, you must also define a corresponding switch in the notification command. The defaults are as follows:

trapVersion="v1" ("v1 or "v2c")
trapTransport="UDP" (only UDP for now)
trapHost="127.0.0.1" (any valid hostname or ip address)
trapPort="162" (any valid IP port)
trapCommunity="public" (any valid community string)
trapEnterprise=".1.3.6.1.4.1.5813" (any valid OID)
trapGeneric="6" (any valid generic ID)
trapSpecific="1" (any valid trapSpecific ID)
trapVarbind="OpenNMS Trap Notification" (any string or one or more valid %<event field>% such as "%eventUEI%" in the string)

The one allowed trap varbind will be sent with the object ID .1.3.6.1.4.1.5813.20.1 and the object type DisplayString.