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 also create custom commands to send notifications to a platform of your choice.

Default notification commands

Default Horizon notification commands
Command Description

callHomePhone

Calls the home phone number configured in the user’s contact information.
Uses the in-process Asterisk notification strategy.

callMobilePhone

Calls the mobile phone number configured in the user’s contact information.
Uses the in-process Asterisk notification strategy.

callWorkPhone

Calls the work phone number configured in the user’s contact information.
Uses the in-process Asterisk notification strategy.

ircCat

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

javaEmail

Delivers a notice to the email address listed in the user’s email contact field.
Uses the in-process JavaMail notification strategy.

javaPagerEmail

Delivers a notice to the email address listed in the user’s pagerEmail contact field. By configuring pagerEmail to target an email-to-SMS gateway, you can easily configure SMS notifications.
Uses the in-process JavaMail notification strategy.

microblogDM

Sends a notice to a user as a direct message via a microblog service with a Twitter v1-compatible API.

microblogReply

Sends a notice to a user as an at-reply via a microblog service with a Twitter v1-compatible API.

microblogUpdate

Sends a notice to everyone as an update via a microblog service with a Twitter v1-compatible API.

numericPage

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

textPage

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

xmppGroupMessage

Sends a message to an XMPP group.
Uses the in-process XMPP notification strategy.

xmppMessage

Sends a message to an XMPP user.
Uses the in-process XMPP notification strategy.

Custom notification commands

You can edit ${OPENNMS_HOME}/etc/notificationCommands.xml 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 or 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 NotificationManager

The NotificationManager class defines some special switches, providing data for the class or command that is run:

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.

Examples

SnmpTrapNotificationStrategy

This configuration sends a Horizon 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 can 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. If you define a parameter in the notification, however, you must 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 DisplayString object type.