NotificationCommands

From OpenNMS
Jump to navigation Jump to search

Introduction

This page explains the contents of the notificationCommands.xml file, found under opennms/etc folder.

This is just a stub for now.

XML Elements

Argument

streamed attribute dictates whether the the substitution text and/or switch text will be placed in the command line, or simply be placed in the input stream when the command start running.

Placing boilerplate arguments

  <argument streamed="false">
     <substitution>-D</substitution>
  </argument>

Placing dynamic values

  <argument streamed="false">
     <switch>-tm</switch>
  </argument>

Note that 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

This kind of prevents passing properties to an Ant script

Valid switches from the NotificationManager class

The NotificationManager class defines some special switches, providing data for the class / command that executes.

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 ?

Extended dynamic values

As per Notification_Configuration_How-To, you can pass arbitrary parameters from the notification to the notificationCommand via the <parameter> tag, which can then be used as required.

Examples

Example 1

Here's a good example I found explaining how to build a notification command element.

Sending SMS

To enable OpenNMS to send notifications to cellular GSM phones through SMS messages add the following XML to the notificationCommands.xml file. Additionally you must have sms_client (available at http://www.smsclient.org or the original site http://www.styx.demon.co.uk/) properly configured with a GSM modem (or a regular analog modem if your GSM provider supports such a service).

Define the destination mobile phone number in Numeric PIN (-np switch below) field in the user properties. Obviously, it could be better to create a wrapper script to truncate the notification messages down to 160 characters or something else.

<command>
  <name>mobilePhoneSMS</name>
  <execute>/usr/bin/sms_client</execute>
  <comment>for sending GSM messages (SMS)</comment>
  <argument streamed="false">
     <switch>-np</switch>
  </argument>
  <argument streamed="true">
     <switch>-tm</switch>
  </argument>
</command>

Sending SMS via an external command

Another example was to create an external command that takes some inputs, and then use that command to call a web service. This can also be achieved by HTTPNotificationStrategy, but in this case, the system wanted an HTTP GET rather than the usual POST, and would not accept spaces in the URL. The -tm field is the Message to send, and the -mphone is the mobile number to send it to, which must not have a space in it. Note the "binary=true", which indicates it's an external program rather than an internal 'strategy'.

    <command binary="true">
        <name>TextViaKapow</name>
        <execute>/usr/bin/textViaKapow.sh</execute>
        <comment>Allows for sending texts via external kapow service</comment>
        <contact-type>mobilePhone</contact-type>
        <argument streamed="false">
            <switch>-tm</switch>
        </argument>
        <argument streamed="false">
            <switch>-mphone</switch>
        </argument>
    </command>

Building the relevant file to execute is left as an exercise for the reader. Note that using NotificationCommands to fork commands in this way is bad if there's a Notification Storm: "Bad things can happen" - esh^ on IRC.

Sending Windows pop-ups

For sending Windows Pop-Up messages (eg. "net send") add the following XML lines. The destination Windows PC name is defined in the Pager Email field, -pemail, (of course it can be changed), and you must have samba installed - smbclient.

<command>
  <name>windowsPopup</name>
  <execute>/usr/bin/smbclient</execute>
  <comment>for sending messages to Windows with Samba</comment>
  <argument streamed="false">
    <substitution>-U OpenNMS</substitution>
  </argument>
  <argument streamed="false">
    <substitution>-M</substitution>
    <switch>-pemail</switch>
  </argument>
  <argument streamed="true">
    <switch>-tm</switch>
  </argument>
</command>