Concepts

Notifications are how OpenNMS HORIZON informs users about an event that happened in the network, without the users having to log in and look at the UI. The core concepts required to understand notifications are:

  • Events and UEIs

  • Users, Groups, and On-Call Roles

  • Duty Schedules

  • Destination Paths

  • Notification Commands

These concepts fit together to form an Event Notification Definition. Also related, but presently only loosely coupled to notifications, are Alarms and Acknowledgments.

Events and UEIs

As discussed in the chapter on [ga-events], events are central to the operation of OpenNMS HORIZON. Almost everything that happens in the system is the result of, or the cause of, one or more events; Every notification is triggered by exactly one event. A good understanding of events is therefore essential to a working knowledge of notifications.

Every event has a UEI (Uniform Event Identifier), a string uniquely identifying the event’s type. UEIs are typically formatted in the style of a URI, but the only requirement is that they start with the string uei.. Most notifications are triggered by an exact UEI match (though they may also be triggered with partial UEI matches using regular expression syntax).

Users, Groups, and On-Call Roles

Users are entities with login accounts in the OpenNMS HORIZON system. Ideally each user corresponds to a person. They are used to control access to the web UI, but also carry contact information (e-mail addresses, phone numbers, etc.) for the people they represent. A user may receive a notification either individually or as part of a Group or On-Call Role. Each user has several technology-specific contact fields, which must be filled if the user is to receive notifications by the associated method.

Groups are lists of users. In large systems with many users it is helpful to organize them into Groups. A group may receive a notification, which is often a more convenient way to operate than on individual user. Groups allow to assign a set of users to On Call Roles to build more complex notification workflows.

How to create or modify membership of Users in a Group
  1. Login as a User with administrative permissions

  2. Choose Configure OpenNMS from the user specific main navigation which is named as your login user name

  3. Choose Configure Users, Groups and On-Call roles and select Configure Groups

  4. Create a new Group with Add new group or modify an existing Group by clicking the Modify icon next to the Group

  5. Select User from Available Users and use the >> to add them to the Currently in Group or select the users in the Currently in Group list and use << to remove them from the list.

  6. Click Finish to persist and apply the changes

The order of the Users in the group is relevant and is used as the order for Notifications when this group is used as Target in a Destination Path.
How to delete a Group
  1. Login as a User with administrative permissions

  2. Choose Configure OpenNMS from the user specific main navigation which is named as your login user name

  3. Choose Configure Users, Groups and On-Call roles and select Configure Groups

  4. Use the trash bin icon next to the Group to delete

  5. Confirm delete request with OK

On-Call Roles are an overlay on top of groups, designed to enable OpenNMS HORIZON to target the appropriate user or users according to a calendar configuration. A common use case is to have System Engineers in On-Call rotations with a given schedule. The On-Call Roles allow to assign a predefined Duty Schedule to an existing Group with Users. For each On-Call Role a User is assigned as a Supervisor to be responsible for the group of people in this On-Call Role.

How to assign a Group to an On-Call Role
  1. Login as a User with administrative permissions

  2. Choose Configure OpenNMS from the user specific main navigation which is named as your login user name

  3. Choose Configure Users, Groups and On-Call roles and select Configure On-Call Roles

  4. Use Add New On-Call Role and set a Name for this On-Call Role, assign an existing Group and give a meaningful description

  5. Click Save to persist

  6. Define a Duty Schedule in the calendar for the given date by click on the Plus (+) icon of the day and provide a notification time for a specific User from the associated Group

  7. Click Save to persist the Schedule

  8. Click Done to apply the changes

Duty Schedules

Every User and Group may have a Duty Schedule, which specifies that user’s (or group’s) weekly schedule for receiving notifications. If a notification should be delivered to an individual user, but that user is not on duty at the time, the notification will never be delivered to that user. In the case of notifications targeting a user via a group, the logic differs slightly. If the group is on duty at the time the notification is created, then all users who are also on duty will be notified. If the group is on duty, but no member user is currently on duty, then the notification will be queued and sent to the next user who comes on duty. If the group is off duty at the time the notification is created, then the notification will never be sent.

Destination Paths

A Destination Path is a named, reusable set of rules for sending notifications. Every destination path has an initial step and zero or more escalation steps.

Each step in a destination path has an associated delay which defaults to zero seconds. The initial step’s delay is called the initial delay, while an escalation step’s delay is simply called its delay.

Each step has one or more targets. A target may be a user, a group, an on-call role, or a one-off e-mail address.

While it may be tempting to use one-off e-mail addresses any time an individual user is to be targeted, it’s a good idea to reserve one-off e-mail addresses for special cases. If a user changes her e-mail address, for instance, you’ll need to update in every destination path where it appears. The use of one-off e-mail addresses is meant for situations where a vendor or other external entity is assisting with troubleshooting in the short term.

When a step targets one or more groups, a delay may also be specified for each group. The default is zero seconds, in which case all group members are notified simultaneously. If a longer delay is set, the group members will be notified in alphabetical order of their usernames.

Avoid using the same name for a group and a user. The destination path configuration does not distinguish between users and groups at the step level, so the behavior is undefined if you have both a user and a group named admin. It is for this reason that the default administrators group is called Admin (with a capital A) — case matters.

Within a step, each target is associated with one or more notification commands. If multiple commands are selected, they will execute simultaneously.

Each step also has an auto-notify switch, which may be set to off, on, or auto. This switch specifies the logic used when deciding whether or not to send a notice for an auto-acknowledged notification to a target that was not on duty at the time the notification was first created. If off, notices will never be sent to such a target; if on, they will always be sent; if auto, the system employs heuristics aimed at "doing the right thing".

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. The following notification commands are included in the default configuration:

callHomePhone, callMobilePhone, and callWorkPhone

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

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, SMS notifications are trivially easy to configure. Both are implemented using the in-process JavaMail notification strategy.

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. Each command is implemented with a separate, in-process notification strategy.

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.

Notification commands are customizable and extensible by editing the notificationCommands.xml file.

Use external binary notification commands sparingly to avoid fork-bombing your OpenNMS HORIZON system. Originally, all notification commands were external. Today only the numericPage and textPage commands use external programs to do their work.