Plugin Development with OIA

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

OIA 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 OpenNMS releases. As OIA adoption increases, users benefit from an ecosystem of plugins that can be built more quickly, validated more easily, and assured to work with future releases of OpenNMS.

Features

API users can take advantage of the following features and interfaces. See the interfaces defined in the api module for a complete list.

  • 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)

Start to build a new project with OIA

OIA 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 name myplugin, package name com.company.myplugin, and version with your own choices. Generated plugin adds some Java files and feature definitions which are only added as samples. You can update and delete them when 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 Horizon.
2 assembly builds kar file that can be deployed in Horizon.
3 karaf-features consists of feature definitions.
4 Plugin code that depends on OIA code.
5 parent pom.xml that declares the dependencies, and its versions.

Build and deploy plugin

Generated README.md file should have all the required steps for building and deploying the plugin.