Microblog Notifications

From OpenNMS
Jump to navigation Jump to search

Sending OpenNMS Notifications via a Microblog Service

Starting with version 1.7.93 (1.8.0rc4) OpenNMS can send notifications via a microblog service.

Supported microblog services

Any microblog service with a Twitter-compatible API should work. This feature has been tested with:

  1. Identica
  2. StatusNet (Identica is an instance of StatusNet)
  3. Twitter

Ways to send notifications

Three microblog notification strategies exist:

Update strategy 
Posts a plain update whose body is the text message field of the configured event notification.
Reply strategy 
Posts an at-reply update whose body is prepended with the microblog username of the OpenNMS user to whom the notification was sent.
DM strategy 
Sends a direct message or private message to the microblog username of the OpenNMS user to whom the notification was sent. Note that the sending and receiving users must be friends (mutually following or subscribed to each other) in order for this strategy to work.

Prerequisites

Microblog service profile

You must create a profile describing the microblog service you wish to use to send notifications. These profiles are configured in the file microblog-configuration.xml and have the following mandatory attributes:

name 
A short name for this profile.
service-url 
The URL to use to communicate with the Twitter-compatible API on this microblog service. For Twitter, this is https://twitter.com/; for Identica, it is https://identi.ca/api/ (note that the trailing slashes are mandatory).
authen-username 
The username with which OpenNMS will authenticate to the microblog service. This is typically the same as the microblog username from which the notices will appear. Currently only basic authentication is supported; OAuth support is expected in a post-1.8 release.
authen-password 
The password corresponding to the account identified in authen-username.

If you will use only a single microblog service with OpenNMS, you can set the default-microblog-profile-name attribute of the top-level microblog-configuration element to match the name of the profile describing that service. If you have multiple profiles defined, the microblog notification strategies will first try to use a profile called notifd. If no such profile exists, the strategies will fall back to the default profile.

Notification command

The default notificationCommands.xml contains commands that use each of the three strategies identified above, so you should not need to do anything in this regard unless you want to change the command names. See Configuring notifications for more information on notification commands.

Destination path

You'll need to include one of the microblog notification commands (microblogUpdate, microblogReply, or microblogDM) in a destination path, and set your event notification definition to send to that destination path. See Configuring notifications for more information on destination paths.

Pictorial walkthrough

Configure a microblog profile for the microblog service of your choice:

MicroblogConfigXml.png

In the OpenNMS web UI, go to Admin -> Configure Users, Groups, and Roles -> Configure Users. Configure one or more users with a microblog username for the service configured above:

UserMicroblogContactInfo.png

In the OpenNMS web UI, go to Admin -> Configure Notifications -> Configure Destination Paths. Create a new destination path:

CreateNewDestinationPath.png

Type a name for the destination path, then click the Edit button to edit which users and groups are included in the destination path. Here we'll select just the one user that we set up with a microblog username above. You could choose multiple users, or groups, or on-call roles if you wish:

SelectDestinationPathUsers.png

Click Next >>>. In the next screen, select one or more of the microblog notification commands. Here I've selected just microblogReply:

SelectDestinationPathCommands.png

Click Next >>>, then Finish:

FinishDestinationPath.png

Now in the OpenNMS web UI, go to Admin -> Configure Notifications -> Configure Event Notifications. Edit an existing notification or create a new one; here we'll edit the node down notification:

EditNodeDownNotification.png

In the notification wizard, skip past the Choose Event page without changing the event that the notification pertains to; just click Next >>>. Skip past the Build Rule page as well by clicking Skip results validation.

In the Choose Path page, select the destination path that you created above from the drop-down list. Also edit the Text Message field, shortening it to fit into the length allowed by your chosen microblog service. Click Finish:

ChooseNotificationDestinationPath.png

Finally, go to the main Admin menu in the OpenNMS web UI and make sure that notifications are enabled (they're disabled globally by default).

You're done. The next time a node goes down, your OpenNMS instance will let you know via your chosen microblog service:

IdentifoxNodeDownNotification.png