Plugin Development with the OpenNMS Plugin API

The OpenNMS Plugin API (formerly OIA) implements a software development kit that provides a stable base to build plugins to extend the configuration of Meridian, consume its outputs, and add new functionality.

The Plugin API clearly identifies, documents, and provides ongoing compatibility guarantees for its integration points, so plugin creators can write code that targets a clear set of interfaces and works with a broad range of Meridian releases. As adoption increases, users benefit from an ecosystem of plugins that can be built more quickly, validated more easily, and are assured to work with future releases of Meridian.

Features

API users can take advantage of the following features and interfaces:

  • Extend

    • Event configuration

    • Syslog configuration (message to event mappings)

    • SNMP data collection configuration

    • Resource type definitions (data collection)

    • Graph definitions (data collection)

    • Thresholding configuration

  • Consume

    • Runtime information

      • Version - major, minor, patch, snapshot

      • Container type - OpenNMS vs. Minion vs. Sentinel

    • Alarm lifecycle callbacks

    • DAOs

      • Node

      • SNMP interface

      • Topology (edges)

    • Coordination API

    • Events

  • Add new

    • Health checks

      • Provide custom health checks to verify the sanity of your plugin

    • Alarm persister extensions

      • Mangle alarms before they are persisted

    • Service monitors

    • Service collectors

    • Provisiond detectors

    • Ticketers

    • Time series storage

    • Graph API extensions (i.e., custom topology)

See the interfaces defined in the api module for a complete list.

Build a new project with the OpenNMS Plugin API

The Plugin API provides a Maven archetype to help bootstrap plugin creation.

Create a new plugin project using the following Maven command:

mvn archetype:generate -B -DarchetypeGroupId=org.opennms.integration.api -DarchetypeArtifactId=example-kar-plugin -DarchetypeVersion=1.0.0 -DgroupId=com.company -DartifactId=myplugin -Dversion=0.1.0-SNAPSHOT -Dpackage=com.company.myplugin -DpluginId=myplugin -DpluginName="My Plugin"
You can replace myplugin (name), com.company.myplugin (package name), and the version with your own values. The generated plugin adds some Java files and feature definitions. They are added only as samples; you can update and delete them as needed.

This plugin generates the following folder structure:

README.md (1)
assembly  (2)
karaf-features (3)
plugin   (4)
pom.xml  (5)
1 README file on how to build and deploy plugin on Meridian.
2 assembly builds kar file that can be deployed in Meridian.
3 karaf-features consists of feature definitions.
4 Plugin code that depends on OpenNMS Plugin API code.
5 Parent pom.xml that declares the dependencies, and its versions.

Build and deploy plugin

The README file should contain all steps required to build and deploy the plugin.