Import Handlers

Horizon supports import handlers to help provision nodes from an external system (foreign source) into a requisition. OpenNMS does this through external requisitions you specify in the External Requisitions and Thread Pools UI or configure via the config management REST API.

Prior to Horizon 30, you set external requisitions in the provisiond-configuration.xml file. This file is no longer available, and moved to the /etc_archive folder upon upgrade to Horizon 30. Your existing configurations were also migrated and appear in the UI as existing external requisitions.

An external requisition enables periodic inventory synchronization from external sources. Each definition contains a URL, schedule, and setting to specify the nodes to rescan.

Most commonly, these URLs are files on the file system (file:${OPENNMS_HOME}/etc/imports/<my-requisition.xml>), but they can also come from external URLs. For example, OpenNMS can use the HTTP protocol to retrieve inventory.

In addition to the standard protocols Java supports, we provide a series of custom URL handlers to help retrieve requisitions from external sources.

Generic handler

The generic handler uses URLs in the form requisition://type?param=1;param=2

Use these URLs to invoke handlers, both locally and via a Minion. In addition to type-specific parameters, all handlers support the following parameters:

Table 1. Optional parameters
Parameter Description Default

location

The name of the location at which the handler should run.

Default

ttl

The maximum number of milliseconds to wait for the handler when run remotely.

20000

Use the opennms:show-import command, available via the Karaf shell, to show the results of an import without persisting or triggering the import:

opennms:show-import -l MINION http url=http://127.0.0.1:8000/req.xml

Thread Pools

Thread pool sizes impact the performance of the provisioning subsystem. Larger systems may require larger values. To adjust them, follow these steps:

  1. Log in to Horizon as an admin user.

  2. Click the gear icon and click Configure External Requisitions and Thread Pools.

  3. In the left menu, click External Requisitions.

  4. In the Thread Pools area, select a value from the drop-down list for each item you want to update.

  5. Click Update Thread Pools.

You can also configure thread pool sizes via the config management REST API.

Create an external requisition

An external requisition defines the URL, schedule, and rescan behaviour to retrieve provisioning information from external sources such as HTTP(S), VMWare, and DNS protocol, for up-to-date inventory data.

OpenNMS constructs the URL from the parameters (host, zone, foreign source) associated with the type of external source the user defines.

The following example shows how to create an external requisition to schedule an import from a DNS server running on the localhost, requesting nodes from the "localhost" zone, "DNS-example" requisition name, and imported daily at midnight.

You can also create an external requisition via the config management REST API.

  1. Log in to Horizon as an admin user.

  2. Click the gear icon and click Configure External Requisitions and Thread Pools.

  3. In the left menu, click External Requisitions.

  4. Click Add External Requisition.

  5. Specify a name for the external requisition.

  6. From the Type drop-down, choose DNS.

  7. Type "localhost" in the Host field.

  8. Type "localhost" as the Zone field.

  9. Type "DNS-example" in the Requsition Name field.

    1. The URL "dns://localhost/localhost/DNS-example" appears at the bottom of the dialog.

  10. Choose Daily for the schedule type and specify 12:00 a.m. for the time.

    To create an advanced cron schedule, click the checkbox and add the appropriate information.

  11. Specify how OpenNMS should perform subsequent scans:

    1. Scan all nodes

    2. Scan added nodes only

    3. No scanning

  12. The optional Advanced Options section lets you specify key/value pairs.

  13. Click Save & Close.

Note the following field validation information:

  • Zone and Requisition fields cannot start or end with a space, but can have a space within the string

  • Zone field can contain alpha, digit,-, ., and space within the string

  • Requisition name cannot include the following: /, \, ?, *, ', or ".