In service-provider and large enterprise environments, it is common to have requisitions describing hundreds, thousands, or even tens of thousands of nodes. This article aims to address some special concerns that come into play when working with such large requisitions.
Dos and Don’ts
Generate Requisitions Programmatically
When operating at such a large scale, it’s usually the case that the nodes contained in the requisitions are sourced from some external source such as a provisioning database or CRM system. You may have noticed the term foreign source being thrown around in this domain; originally that term referred to such external systems. Whenever possible, use the APIs that your external system provides to grab the data and populate the requisitions automatically. This need not be done directly on the OpenNMS server, since Provisiond can fetch requisitions from specified URLs (pull-model) or have them updated via OpenNMS’ ReST API (push-model).
ReST API Tips
When going the push route via ReST with large requisitions, there is a very helpful but not terribly well-documented technique that can be used to add nodes piecemeal to an existing requisition. By doing a POST to the requisitions/foreignSource/nodes URL with the request body consisting of an XML document containing a single
<node> element, the requisition will have the described node appended to it. This technique saves the developer from having to request the requisition in its entirety, merge the new node or nodes in memory, and PUT the updated requisition back in its entirety. The node add use case of the
provision.pl script included in OpenNMS works in this way. For a very simple example, if we have an existing requisiton called renamed-hiphop-artists to which we want to add a single new node called snooplion, we need only craft an XML file
snooplion.xml describing the new node:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <node node-label="snooplion" foreign-id="snooplion" building="renamed-hiphop-artists"> <interface snmp-primary="N" status="1" ip-addr="18.104.22.168" descr=""> <monitored-service service-name="DNS"/> </interface> </node>
And then POST this file to the appropriate URL:
curl -v -u admin:admin -X POST -T /tmp/snooplion.xml http://localhost:8980/opennms/rest/requisitions/renamed-hiphop-artists/nodes
Only single nodes can be added in this way; wrapping multiple nodes in a
<nodes> top-level tag does not work.
Once you’re done adding nodes in this way, you may wish to tell Provisiond to synchronize only the newly-added nodes while ignoring the other 24999 nodes that it has already scanned. This is easily accomplished by appending the parameter rescanExisting=false to the PUT operation used to request that the updated requisition be synchronized. To import only the newly-added nodes for the example requisition above, this command would work:
curl -v -u admin:admin -X PUT http://localhost:8980/opennms/rest/requisitions/renamed-hiphop-artists/import?rescanExisting=false
Web Requisition Editor Not Designed for This Scale
The requisition editor in the OpenNMS web UI (Admin -> Manage Provisioning Requisitions) is designed for very small-scale usage. Do not attempt to use this interface to edit requisitions containing more than a few dozen nodes; it’s simply not designed for that use case and will fail in sometimes spectacular ways.