Integrating with Provisiond

If you have another inventory system to keep track of nodes on your network, you can define a requisition to group nodes within Horizon. There are multiple ways you can add nodes to a requisition. One way is to use the REST API to automate syncing nodes from your inventory system. The ReST API provides an endpoint for defining foreign sources and requisitions.

Provisioning a group of nodes

Just as with the web UI, groups of nodes can be managed via the ReST API from an external system. The steps are:

  • Update the default foreign source definition (if not using the default) for the group.

  • Update the SNMP configuration for each node in the group as needed.

  • Create/update the group of nodes.

Example provisioning via REST API

Step 1 - Create a foreign source

To define the policies for this group of nodes, you need to create a foreign source for the group. Use the foreign sources REST API to do so:

You can embed the XML in the curl command with option -d or reference it from a file if you use @ prefix with the file name, as in this case.

Sample XML file customer-a.foreign-source.xml:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<foreign-source date-stamp="2009-10-12T17:26:11.616-04:00" name="customer-a" xmlns="http://xmlns.opennms.org/xsd/config/foreign-source">
    <scan-interval>1d</scan-interval>
    <detectors>
        <detector class="org.opennms.netmgt.provision.detector.icmp.IcmpDetector" name="ICMP"/>
        <detector class="org.opennms.netmgt.provision.detector.snmp.SnmpDetector" name="SNMP"/>
    </detectors>
    <policies>
        <policy class="org.opennms.netmgt.provision.persist.policies.MatchingIpInterfacePolicy" name="no-192-168">
            <parameter value="UNMANAGE" key="action"/>
            <parameter value="ALL_PARAMETERS" key="matchBehavior"/>
            <parameter value="~^192\.168\..*" key="ipAddress"/>
        </policy>
    </policies>
</foreign-source>

Here is an example curl command to create the foreign source with the above foreign source specification:

curl -v -u admin:admin -X POST -H 'Content-type: application/xml' -d '@customer-a.foreign-source.xml' http://localhost:8980/opennms/rest/foreignSources

Step 2 - Update the SNMP configuration

Update the community string or other data for this IP address.

See the SNMP Configuration documentation for more information.

This example changes the read community string for the IP address 10.1.1.1 to yRuSonoZ.

readCommunity is the only required element, other than specific. See the SNMP documentation for a full list of available elements and their descriptions.
Example: Update the SNMP Community string via curl (one-liner)
curl -v -u admin:admin -X PUT -H "Content-Type: application/json" -d '{ "readCommunity": "yRuSonoZ", "specific": ["10.1.1.1"] }' http://localhost:8980/opennms/api/v2/snmp-config/definition
Example: Update the SNMP Community string via curl (formatted)
curl -v -u admin:admin -X PUT \
   -H "Content-Type: application/json" \
   -d \
'{
  "readCommunity": "yRuSonoZ",
  "specific": ["10.1.1.1"]
}' \
 'http://localhost:8980/opennms/api/v2/snmp-config/definition'

Step 3 - Create/Update the Requisition

This example adds 2 nodes to the requisition customer-a. The foreign source must match the name of the requisition. In the following example, the requisitions REST API automatically creates a requisition based on the value of the foreign-source attribute specified in the XML requisition.

curl -v -u admin:admin -X POST -H "Content-Type: application/xml" -d '<?xml version="1.0" encoding="UTF-8"?><model-import xmlns="http://xmlns.opennms.org/xsd/config/model-import" date-stamp="2009-03-07T17:56:53.123-05:00" last-import="2009-03-07T17:56:53.117-05:00" foreign-source="customer-a"><node node-label="p-brane" foreign-id="1" ><interface ip-addr="10.0.1.3" descr="en1" status="1" snmp-primary="P"><monitored-service service-name="ICMP"/><monitored-service service-name="SNMP"/></interface><category name="Production"/><category name="Routers"/></node><node node-label="m-brane" foreign-id="2" ><interface ip-addr="10.0.1.4" descr="en1" status="1" snmp-primary="P"><monitored-service service-name="ICMP"/><monitored-service service-name="SNMP"/></interface><category name="Production"/><category name="Routers"/></node></model-import>' http://localhost:8980/opennms/rest/requisitions

A requisition file called etc/imports/customer-a.xml will be found on the Horizon system following the successful completion of this curl command and will also be visible via the Web UI.

Before the requisition’s nodes are populated into the database, Provisiond needs to perform an import (also referred to as synchronization). Here is an example using the curl command to import the requisition:

curl -v -u admin:admin -X PUT http://localhost:8980/opennms/rest/requisitions/customer-a/import
The REST API handles Add, Update, and Delete operations in the same manner as described in the REST API documentation.