Concepts

This page describes core concepts related to Horizon notifications. They ultimately combine to form an Event Notification Definition.

Events and UEIs

As discussed in Events, events are central to the operation of Horizon. Almost everything that happens in the system is the result of, or the cause of, one or more events. Each 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 unique string identifier (UEI), a string that uniquely identifies 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 (although they may also be triggered with partial UEI matches using regular expression syntax).

Users and groups

User accounts control access to the web UI, but also store contact information (e-mail addresses, phone numbers, and so on) for the people they represent. A user may receive notifications either individually or as part of a group or on-call role. Each user has several technology-specific contact fields, which must be filled for the user to receive notifications by the associated method.

To learn more about user accounts and how to manage them, see User Maintenance.

In large systems with many users, it might be helpful to organize them into groups. Groups may receive notifications; this is often a more convenient way to operate than configuring notifications to send to individuals. Within a group, a set of users can be assigned to on-call roles. This lets you build more complex notification workflows.

To learn more about groups and how to manage them, see Groups.

On-Call roles

On-call roles are an overlay on top of groups. They are designed to let Horizon target the appropriate users according to calendar configurations. A common use case is to have system engineers in on-call rotations with a defined schedule.

On-call roles let you assign a predefined duty schedule to an existing group. The group must have users associated with it.

For each on-call role, a user is designated as a supervisor. They are responsible for the group of people assigned to the on-call role.

See On-Call Roles for more information.

Duty schedules

Any user and group may have an associated duty schedule. The duty schedule defines the user or group’s weekly availability for receiving notifications.

If a notification should be delivered to an individual user, but they are not on duty at the time that it’s generated, the notification will not be delivered.

If a notification targets a user via a group, the logic is slightly different: if the group is on duty at the time the notification is generated, all users who are also on duty will be notified. If the group is on duty when the notification is generated, but no member users are on duty, the notification will be queued and sent to the next user who comes on duty. If the group is off duty when the notification is generated, the notification will not be delivered.

For more information on duty schedules, see Create user duty schedule.

Destination paths

A destination path is a named, reusable set of rules for sending notifications. Each destination path has a defined initial step and zero or more escalation steps. Every 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. If an alarm is cleared or acknowledged within the delay time, the notification will not be sent.

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

While it may be tempting to regularly use one-off email addresses to target individual users, it’s a good idea to reserve their use for special cases. If a user changes their email address, for example, you will need to update it in every destination path in which it appears. One-off email addresses are meant for situations where a vendor or other external party is assisting with troubleshooting in the short-term.

When a step targets one or more groups, you may specify a delay for each group. The default delay is zero seconds; this means that all group members are notified at the same time. If you set a longer delay, group members will be notified in alphabetical order, based on their usernames.

For example, defining a five minute delay will mean that when a notification is generated, the first member of the group is notified immediately. Subsequent members are then notified in five-minute increments, from the top of the list of group members to the bottom.

Avoid using the same name for a group and a user. Destination path configuration settings do not distinguish between users and groups at the step level. If you have both a user and a group named "admin," the behavior will be undefined. Because of this, the default administrators group is called "Admin"—case matters.

Within a step, each target is associated with one or more notification commands. If multiple commands are selected, they will run at the same time.

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

Variable bindings filters

Event parameters can be used to filter which events trigger a notification. By defining the vbname and vbvalue, the notification will only be sent with if the event parameter matches the given value.

Example 1:

In this example, notifications would only be triggered on SNMP Link Down events that contain the string Trunk.

Example notifications.xml definition
   <notification name="Link down notification" status="off">
      <uei>uei.opennms.org/translator/traps/SNMP_Link_Down</uei>
      <rule>(IPADDR IPLIKE *.*.*.*)</rule>
      <destinationPath>Email-Admin</destinationPath>
      <text-message>%descr%</text-message>
      <subject>Notice #%noticeid% - Link Down</subject>
      <numeric-message>111-%noticeid%</numeric-message>
      <varbind>
         <vbname>ifAlias</vbname> (1)
         <vbvalue>~^.*Trunk.*</vbvalue> (2)
      </varbind>
   </notification>
1 Event parameter name to filter
2 Value to match for the specified event parameter. If the value starts with a ~, it will be processed as a regular expression, otherwise it will be a string match.

Example 2:

In this example, Business Service Monitoring problem events would only trigger notifications if there is a parameter match with the specified business service name pattern.

Example notifications.xml definition
   <notification name="BusinessServiceMonitor notification" status="off" writeable="yes">
      <uei>uei.opennms.org/bsm/serviceProblem</uei>
      <rule>(ipaddr != '0.0.0.0')</rule>
      <destinationPath>Email-Admin</destinationPath>
      <text-message>BSM Root Cause Analysis: %parm[rootCause]%</text-message>
      <subject>%parm[businessServiceName]% is impacted</subject>
      <numeric-message>111-%noticeid%</numeric-message>
      <varbind>
         <vbname>businessServiceName</vbname> (1)
         <vbvalue>~^MailCluster.*</vbvalue> (2)
      </varbind>
   </notification>
1 Event parameter name to filter
2 Value to match for the specified event parameter. If the value starts with a ~, it will be processed as a regular expression, otherwise it will be a string match.