Documentation

The components from left to right are described as followed:

The latest release of PRIS can be downloaded from the github release page of the project. It is recommended to extract the tar.gz content to /opt/opennms-pris. The examples and the documentation are built based on this file structure. It is possible to install PRIS in a different directory, but you have to take care about adapting the paths in this documentation.

After extracting the archive the file structure should look like this:

PRIS needs at minimum two configuration files. The first is called global.properties, and controls the general behavior of the provisioning integration server. A requisition is just a directory in the application server directory requisitions and has to contain a file called requisition.properties. The directory name is used to access the requisition.

You can create multiple requisitions using different sources, by creating a directory for each requisition with a requisition.properties inside. The global.properties, the requisitions directory and the start script has to be in the same folder. By default we suggest to install your PRIS archive to /opt/opennms-pris. If you want to provide the OpenNMS requisitions via HTTP from the built-in Jetty web server as a background daemon, you can use the init scripts in the root directory of PRIS.

It is recommended to use a Linux distribution using Systemd. Install the opennms-pris.service to /etc/systemd/system/opennms-pris.service and run systemctl daemon-reload. To enable or start and stop the daemon the systemctl enable | start | stop opennms-pris.service commands can be used.

In case there is an old Linux distribution with SysV init scripts is used, the opennms-pris.init script needs to be copied to /etc/init.d. To control the daemon behavior the service start | stop commands are supported.

In other cases the opennms-pris.sh or opennms-pris.bat scripts run the daemon in foreground on all other Linux systems or Microsoft Windows. If you want to run PRIS on Microsoft Windows you probably have to look into a wrapper for the opennms-pris.bat file.

This driver offers the ability to generate an OpenNMS requisition directly into the filesystem. To use the file driver you have to set the parameters in the global.properties:

The HTTP driver starts PRIS as a web server to provide the OpenNMS requisition over HTTP.

Access to the requisition can be tested with a browser to URL http://<your-ip>:<port>8000/requisitions/<name-requisition-cfg>;. The path name-requisition-cfg is the folder name which runs the requisition configuration located in your PRIS server directory.

The file source allows to read a requisition file from the filesystem.

This source reads an already-defined requisition from an XML file. The file to read has to be a valid OpenNMS requisition already.

This source is similar to the file source. Instead of reading from a local file, it can read a requisition via HTTP from another OpenNMS instance. The location for the requisition is given by an OpenNMS provisioning ReST URL. It is possible to provide authentication credentials to be able to consume the ReST service.

The given example configuration reads the requisition from the publicly available OpenNMS demo system.

The JDBC source provides the ability to run an SQL Query against an external system and map the result to an OpenNMS requisition.

The following column-headers will be mapped from the result set to the OpenNMS requisition:

This source also supports all asset fields by using Asset_ as a prefix followed by the asset-field-name. The city field of the assets can be addressed like this: yourvalue AS Asset_City and is not case-sensitive.

Every row of the result set will be checked for the listed column headers. The provided data will be added to the corresponding node. Multiple result rows with matching Foreign_Id will be added to the same node.

The merge source allows to merge two provided requisitions accessed by URLs. You can also use provided resources by PRIS recursively. The example below shows how to configure the merge requisition for two requisitions A and B.

This source is reading two already defined requisitions via HTTP and merges them into one new requisition. By default the resulting requisition will contain all nodes that are present in both requisitions, identified by the foreignId. The A-Node (from requisition A) is enriched with the data from B-Node.

This source is provided to give you the flexibility of building your own source without the need to compile from source. The source uses JSR-223 Scripting Engine. The script language can be changed by setting the property source.lang in your requisition.properties file. By default groovy 2.3.3 and beanshell 2.0b5 are ready to use. If you want to use other supported languages, you might need to provide the language jar in the lib folder of PRIS.

You can find a working Groovy source in the examples/source/scriptExample directory. A custom parameter name count is passed into the Groovy script.

The xls reads an XLS spreadsheet file and creates an OpenNMS requisition based on the worksheet content.

The structure of the spreadsheet has to follow these rules. The source reads from a sheet named after the requisition you are requesting. The first row of each sheet is reserved for column names. These column names have to start with certain prefixes to be recognized.

This source also supports all asset-fields by using Asset_ as a prefix followed by the asset-field-name. The city field of the assets can be addressed like this: Asset_City. This is not case-sensitive.

To add a node with multiple interfaces, add a subsequent row with the same node label (Node_). This row will be added as a new interface based on the data from the IP_, MgmtType_, svc_ columns.

The order in which the columns are arranged is irrelevant. Also additional columns can be present.

OCS-Inventory NG is an inventory and software management software. It handles computers and SNMP devices as separate entity types in its APIs. For that reason there are two different sources available to import nodes from OCS. Some parameters are part of both sources and described first.

The echo mapper is a mapper that forwards the result of the source verbatim. That requires the source to provide a ready-to-use requisition and not a custom model. This mapper does not change the result of the source.

The null mapper is a special mapper that just provides an empty requisition. This can be useful to handle the entire mapping between the result of the source and the OpenNMS requisition in a script step.

Mappers are used to map the bifurcated OCS data model centered around computers and SNMP devices to the unified OpenNMS data model for provisioning nodes, interfaces, services and assets. The OCS integration provides one default mapper for computers and one for SNMP devices out of the box. Additionally it provides for script-based mapping via script steps. The default mappers for OCS are a simple way to map computers and SNMP devices to OpenNMS nodes.

This mapper is used to give you the flexibility of building your own mapper without the need to compile from source. The source uses JSR-223 Scripting Engine. The script language can be changed by setting the property mapper.lang in your requisition.properties file. The following example runs your script in the the JavaScript Rhino engine:

If you don’t set the language lang property the script engine tries to detect the language by evaluating the file extension.

You can find a working example in Groovy in the configs/examples/script.mapper directory.

In addition to any other mapper, a final script mapper can be used by specifying script.file in your requisition.properties` file. The specified script will run after the configured mapper and can be used to transform the mapper’s output further.

To specify the scripting language, the script.lang property can be used (see mapper.lang).

Provisiond can be configured to provision a requisition from an URL on a configurable schedule. To configure Provisiond to provision a requisition from PRIS via http a configuration entry like the following can be used.

A special OpenNMS Event can be sent to OpenNMS to trigger provisioning of a requisition right away. Sending an event to OpenNMS in general can be achieved via the OpenNMS WebUI or the send-event.pl script. The following example demonstrates the use of send-event.pl to emit the provisioning event.

The example assumes that OpenNMS is running on the system on which send-event.pl is called. The url parameter references the url that offers the requisition via PRIS. Please check the send-event.pl documentation for additional information.

OpenNMS provides an extensive RestAPI that covers provisioning. Please follow the OpenNMS RestAPI documentation for further information.

The configuration mechanism of PRIS supports basic variable substitution. Therefore it is possible to add properties to the global.properties file and reference the property values in any requisition.properties file. Properties defined in the global.properties can be overwritten in a requisition.properties file. It is also possible to use properties defined in a requisition.properties in a different part of the same requisition.properties again. An implicit property requisition is also available in requisition.properties by default.

The following examples demonstrate the use of properties as variables in PRIS configurations:

The documentation for OpenNMS PRIS is organized in as Maven Module. After building, the documentation is generated as HTML output on the file system. The output is generated in the target/generated sources folder. Asciidoc documents have the .asciidoc file extension.

The structure is organized as the following:

Note that different ways to add documentation works best for different cases:

If you want to contribute a patch to the documentation, just fork the project on github. Make your changes in the branch called develop and send us a pull request. After the review of the pull request we will merge it and your change is in the next release.

Each document starts over with headings from level zero (the document title). Each document should have an id. In some cases sections in the document need to have id’s as well, this depends on where they fit in the overall structure. To be able to link to content, it has to have an id. Missing id’s in mandatory places will fail the build.

This is how a document should start:

To push the headings down to the right level in the output, the leveloffset attribute is used when including the document inside of another document.

Subsequent headings in a document should use the following syntax:

Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences.

To link to other parts of the manual the id of the target is used. This is how such a reference looks:

Which will render like: Overall Flow

If you need to link to another document with your own link text, this is what to do:

External links are added like this:

Which renders like: Link text here

For short links it may be better not to add a link text, just do:

Which renders like: http://www.opennms.org/

These are very useful and should be used where appropriate. Choose from the following (write all caps and no, we can’t easily add new ones):

Here’s how it’s done:

A multiline variation:

Which is rendered as:

Common attributes you can use in documents: 1.1.7-SNAPSHOT * {docVersion} - rendered as "1.1.7-SNAPSHOT"

These can substitute part of URLs that point to for example APIdocs or source code. Note that opennms-git-tag also handles the case of snapshot/master.

Sample Asciidoc attributes which can be used:

There’s a separate build including comments. The comments show up with a yellow background. This build doesn’t run by default, but after a normal build, you can use make annotated to build it. You can also use the resulting page to search for content, as the full manual is on a single page.

Here’s how to write a comment:

The comments are not visible in the normal build. Comment blocks won’t be included in the output of any build at all. Here’s a comment block: