From OpenNMS

Contents 1 Summary 1.1 Prerequisites 1.2 Strategy 1.3 RPC Format 1.4 Acceptance Criteria 1.4.1 Step 1 1.4.2 Step 2 1.4.3 Step 3 1.4.3.1 Before 1.4.3.2 After 1.4.4 Step 4 1.4.5 Step 5

Summary

The current level of Hyperic HQ integration with OpenNMS provides transmission of new alerts from Hyperic HQ to OpenNMS. This integration will be expanded to provide updates to the status of Hyperic alerts in OpenNMS when alerts are acknowledged or marked as "fixed" on the Hyperic HQ instance where the alert originated.

Prerequisites

• Ackd

Strategy

To provide a reliable mechanism for checking for alert statuses, we will implement an AckReader class for Ackd that queries Hyperic HQ for current statuses of outstanding alerts. If the status has changed, the AckReader will trigger status updates to the local alert records stored in OpenNMS.

This solution will consist of two components:

• A Groovy servlet in Hyperic that will return current statuses for a given list of alert IDs
• An AckReader class in OpenNMS's Ackd daemon that will periodically query each Hyperic HQ service to determine if the status of alerts that originated on that service has changed

RPC Format

When the AckReader implementation queries the Hyperic service, it will issue a request to the following URL on the HypericServer:

http://<hyperic_server>/hqu/opennms/alertStatus/list.hqu

The request will limit the alerts that are returned by specifying a list of alert IDs in the HTTP id parameter. Therefore, a full query URL might look like:

http://<hyperic_server>/hqu/opennms/alertStatus/list.hqu?id=1&id=2&id=4&id=5

This service will return records in the following format:

<?xml version="1.0" encoding="UTF-8"?>
<hyperic-alert-statuses>
  <alert id="1" ack="true" ackUser="hqadmin" ackTime="2010-01-24T05:00:00-05:00" fixed="true" fixUser="hqadmin" fixTime="2010-01-24T10:00:00-05:00"/>
  <alert id="2" ack="true" ackUser="hqadmin" ackTime="2010-01-24T05:00:00-05:00" fixed="false"/>
  <alert id="4" ack="false" fixed="true" fixUser="hqadmin" fixTime="2010-01-24T10:00:00-05:00"/>
  <alert id="5" ack="false" fixed="false"/>
</hyperic-alert-statuses>

Acceptance Criteria

Step 1

User sets up Hyperic HQ and OpenNMS, monitoring an overlapping set of devices with each service. The user should also go through the existing documentation for integrating Hyperic and OpenNMS's monitored nodes:

Hyperic OpenNMS Integration

OpenNMS White Paper: Hyperic Integration

If multiple Hyperic HQ servers are being integrated with one OpenNMS instance, then the user need to edit the model export service and notification service on each Hyperic installation to provide a unique "foreign source" attribute that acts as a key identifying that Hyperic installation to OpenNMS.

Step 2

The user should allow discovery, data collection, and Hyperic alarm generation to proceed to verify that existing levels of integration work as expected with devices and alerts being imported into OpenNMS.

Step 3

To enable alarm state integration, the user should edit ackd-configuration.xml inside OpenNMS and enable the HypericReader class.

Before

...
    <reader enabled="false" reader-name="HypericReader">
      <reader-schedule interval="180" unit="s"/>
      <!-- This parameter associates Hyperic platform IDs with URLs that provide alert status lists -->
      <parameter key="source:HQ" value="http://127.0.0.1:7080/hqu/opennms/alertStatus/list.hqu" />
    </reader>
...

After

...
    <reader enabled="true" reader-name="HypericReader">
      <reader-schedule interval="180" unit="s"/>
      <!-- This parameter associates Hyperic platform IDs with URLs that provide alert status lists -->
      <parameter key="source:My-Hyperic-Source-Value" value="http://hyperic.mycompany.com:7080/hqu/opennms/alertStatus/list.hqu" />
    </reader>
...

Step 4

To enable alert status output from Hyperic, the user should copy the AlertStatusController.groovy file from the OpenNMS contrib directory into their Hyperic webapp.

cp -i /opt/opennms/contrib/hyperic-integration/opennms/app/AlertStatusController.groovy \
      /opt/hyperic/server-current/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/opennms/app/AlertStatusController.groovy

Step 5

After restarting Hyperic and OpenNMS, alert statuses should be periodically sync'd by Ackd according to the schedule specified in ackd-configuration.xml.