From OpenNMS

Contents 1 New Service Daemon with version 1.7.7-SNAPSHOT. 1.1 Workflow 1.2 Reader API 1.3 ackd-configuration.xml 1.3.1 alarm-sync 1.3.2 ack-expression 1.3.3 clear-expression 1.3.4 escalate-expression 1.3.5 unack-expression 1.3.6 notifyid-match-expression 1.3.7 alarmid-match-expression 1.3.8 readers 1.3.8.1 reader 1.3.8.1.1 enabled 1.3.8.1.2 reader-name 1.3.8.2 reader-schedule 1.3.8.2.1 interval 1.3.8.2.2 unit 1.3.8.3 parameter 1.4 Example Configuration 1.4.1 ackd-configuration.xml 1.4.2 javamail-configuration.xml (snippet) 1.5 Version History/Availability

New Service Daemon with version 1.7.7-SNAPSHOT.

Note: A new Java Mail configuration is being implemented with this enhancement in support of the JavaMail Acknowledgment Reader (JavaMailReader). The javamail-configuration.properties file is still used for sending notifications and availability reports but will be migrated to the javamail-configuration.xml file and eventually deprecated. Deprecations means that it will continue to work for a period of time (probably until the next major release) but will at some point no longer be supported.

Workflow

Ackd implements a schedule for reading replies to notifications and process them as Acknowledgments. The replies can be interpreted with one of 4 actions:

• Acknowledge
• Un-Acknowledge
• Clear
• Escalate

These replies are "out-of-band" so to speak and use the new Acknowledgment Service Layer, now in OpenNMS, for processing these Acknowledgments and records them in the "acks" table.

The configured e-mail INBOX is read and the subjects are analyzed for matches to the configured notifyid-match-expression. If the subject is matched the text of the email message is read and the action search is executed within the text of the email. The default configuration for the JavaMailReader is to search for the action solely on a single line of text.

Hint: Until Notifications support the new javamail-configuration, be sure that the JavaMailReader is configured to read replies from the account that is also sending emails. Also, do not use your personal mail account for reading replies to notifications for it could result in the deletion of personal email messages.

Reader API

Ackd provides an extension API for the processing of replies to notifications. This API structure is found throughout OpenNMS' Service Daemons and Ackd provides the API as the AckReader Java Interface. Current implementation is the Java Mail Acknowledgment Reader (JavaMailReader).

ackd-configuration.xml

Ackd configuration supplies the daemon with configuration goodies for detailing how to determine a Notification's or Alarm's ID from the acknowledgment method and how to determine the acknowledgment action. Use the following attributes:

alarm-sync

type="boolean" use="optional" default="true"

This is a boolean attribute that allows “true | false | off | on” to be defined by the user. The default is “true | on” if not defined and instructs the acknowledgement service as to whether or not any alarm(s) should be acknowledged in conjunction with an acknowledgment reply to a notification. When in the “on” state, the Acknowledgment service will search for any Alarms that are related to the same event that triggered the notification. The acknowledgment service searches for Alarms based on the AlarmID associated with the event that triggered the notification. Typically events that trigger notification are sent either by: the Poller, Thresholder, or an Automation. Note: if you send action events from an Automation that trigger notifications, be sure to include the AlarmID if applicable.

ack-expression

type="string" use="optional" default="~^ack$"

This is a string value attribute that allows the user to define the regular expression to be used by all installed Readers for matching a reply indicating the action to acknowledge the notification. This results in the Notification escalation process to stop further notifications. If the alarm-sync attribute is “on”, then the related Alarm(s) will also be acknowledged.

clear-expression

type="string" use="optional" default="~^(resolve|clear)$"

This is a string value attribute that allows the user to define the regular expression to be used by all installed Readers for matching a reply indicating the action to clear the notification. This results in the Notification escalation process to stop further notifications. If the alarm-sync attribute is “on”, then the related Alarm(s) will also be cleared. Note: This functionality is currently only effects Alarms.

escalate-expression

type="string" use="optional" default="~^esc$"

This is a string value attribute that allows the user to define the regular expression to be used by all installed Readers for matching a reply indicating the action to escalate the notification. This results in the Notification escalation process to stop further notifications. If the alarm-sync attribute is “on”, then the related Alarm(s) will also be escalated. Note: This functionality is currently only effects Alarms.

unack-expression

type="string" use="optional" default="~^unack$"

This is a string value attribute that allows the user to define the regular expression to be used by all installed Readers for matching a reply indicating the action to un-acknowledge the notification. This results in the Notification escalation process to continue further notifications. If the alarm-sync attribute is “on”, then the related Alarm(s) will also be unacknowledged. Note: This functionality is currently only effects Alarms.

notifyid-match-expression

type="string" use="optional" default="~.*Re:.*Notice #([0-9]+).*"

This is a string value attribute that allows the user to define the regular expression to be used by all installed Readers to identify the ID of the notification that will be the target of the specified acknowledgment action (ack, unack, clear, escalate). Note: The JavaMaileAckReader applies this expression to the subject of the notification reply.

alarmid-match-expression

type="string" use="optional" default="~.*Re:.*Alarm #([0-9]+).*"

This is a string value attribute that allows the user to define the regular expression to be used by all installed Readers to identify the ID of an Alarm generated notification that will be the target of the specified acknowledgment action (ack, unack, clear, escalate). Note: The JavaMaileAckReader applies this expression to the subject of the notification reply that would typically be generated by an automation. A notification sent from a event generated by an automation’s action-event should be defined to have the AlarmID in the subject as opposed to the NotificationID.

readers

Container element holding the definitions for installed readers.

reader

This element provides the user with attributes and elements to enable/disable, provide a schedule to, and pass parameters to an installed Reader.

enabled

type="boolean" use="optional" default="true"

This boolean attribute provides the user with the ability to control the state of the subject Reader. Changing the value of this attribute to one of “true | false | on | off “ and sending Ackd the reload configuration event will cause the subject Reader to change state.

reader-name

type="string" use="required"

This required String attribute’s value must match the value specified in the specifications provided of the Reader.

reader-schedule

This element provides Ackd with the user’s desired schedule for the subject Reader. Note: It is not a requirement that all Readers implement a schedule. Some Readers will be event driven vs. being a poll based Reader (such as the JavaMailReader).

interval

type="positiveInteger" use="optional" default="1"

This attribute of the reader-schedule element indicates to Ackd the interval to use when creating the schedule for the subject Reader. This attribute combined with the “unit” attribute allows the user to define how often the Reader polls the related service for Acknowledgments.

unit

type="this:schedule-units" use="optional" default="m"

This attribute of the reader-schedule element specifies a time unit of measure to be combined with the interval attribute that Ackd can apply to a Reader. This attribute is defined having a type of “schedule-unit”. The “schedule-unit” is a simple type of string with a pattern applied that restricts the input to by of the string values: “d”, “h”, “m”, “s”, “ms” (Days(d); Hours(h); Minutes(m); Seconds(s); Milliseconds(ms)).

parameter

This element of the reader provides additional free form key value pairs that can be used as optional parameters to the Reader. The JavaMailReader has one optional parameter that allows the user to specify which “read-mailer” to be used from the javamail-configuration. This parameter has the same format that you find in many OpenNMS configurations. For example:

<parameter key=”readmail-config” value=”google” />

Example Configuration

This is an example configuration implementing the JavaMailReader. At startup, Ackd initializes all installed readers and for which there is a Reader defined in its configuration. In this example, the JavaMailReader is provided a schedule of reading an email account once every minute checking for notification acknowledgements. The account being read should probably match the "from" account in the javamail-configuration.properties file. (Note: the JavaMail API is currently migrating from the .properties configuration to an XML based configuration as shown here. The Notification Strategy as well as the sending of Availability Reports will soon be migrated.)

ackd-configuration.xml

<?xml version="1.0" encoding="UTF-8"?>
<ackd-configuration 

  ack-expression="~^ack$" 
  alarm-sync="true" 
  alarmid-match-expression="~.*alarmid:([0-9]+).*" 
  clear-expression="~^(resolve|clear)$"
  escalate-expression="~^esc$" 
  notifyid-match-expression="~.*Re:.*Notice #([0-9]+).*" 
  unack-expression="~^unack$" >

  <readers>
    <reader enabled="true" reader-name="JavaMailReader">
      <reader-schedule interval="1" unit="m"/>
      <parameter key="readmail-config" value="google" />
    </reader>
  </readers>

</ackd-configuration>

javamail-configuration.xml (snippet)

<?xml version="1.0" encoding="UTF-8"?>
...
  <readmail-config name="google" attempt-interval="1000" delete-all-mail="false" mail-folder="INBOX" debug="true" >
    <readmail-host host="imap.gmail.com" port="993">
      <readmail-protocol ssl-enable="true" start-tls="true" transport="imaps"/>
    </readmail-host>

    <user-auth user-name="foo" password="bar" />
  </readmail-config>
...

Version History/Availability

• This feature was added in version 1.7.7