
= 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 {page-component-title}, 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 {page-component-title} 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 {page-component-title}.

== 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
** https://github.com/OpenNMS/opennms-integration-api/blob/master/api/src/main/java/org/opennms/integration/api/v1/timeseries/README.md[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:

[source, console]
----
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"
----

NOTE: 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 {page-component-title}.
<2> `assembly` builds `kar` file that can be deployed in {page-component-title}.
<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.
