
//ui-provd: the contextual help from the external requisition screen links to this help, using the URL https://docs.opennms.com/horizon/latest/reference/provisioning/handlers/introduction.html. Ensure link in UI does not break if changing this section of docs.

[[import-handlers]]
= Import Handlers
:description: Learn how OpenNMS {page-component-title} supports import handlers to help provision nodes from external systems into a network inventory requisition.

{page-component-title} supports import handlers to help provision nodes from an external system (foreign source) into a requisition.
This is done through external requisitions that you specify in the External Requisitions and Thread Pools screen, or that you configure via the xref:development:rest/config_management.adoc[configuration management API].
ifeval::["{page-component-title}" == "Horizon"]

NOTE: Prior to {page-component-title} 30, you could create external requisitions in `provisiond-configuration.xml`.
This file is no longer available, and is automatically moved to `/etc_archive` when you upgrade to {page-component-title} 30.
Your existing configurations are migrated and appear in the web UI as existing external requisitions.
endif::[]

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:

[caption=]
.Optional parameters
[options="autowidth"]
|===
| Parameter | Description   | Default Value

| 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 xref:reference:karaf-shell/karaf-shell.adoc[Karaf shell], to show the results of an import without persisting or triggering the import:

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

. Log in to {page-component-title} as an admin user.
. Click the gear icon and click *Configure External Requisitions*.
+
You can also select menu:Info[External Requisitions] to access this screen.

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

NOTE: You can also configure thread pool sizes via the xref:development:rest/config_management.adoc#config-rest-api[config management REST API].

[[create-req-def]]
== 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.

NOTE: You can also create an external requisition via the xref:development:rest/config_management.adoc#config-rest-api[config management REST API].

. Log in to {page-component-title} as an admin user.
. Click the gear icon and click *Configure External Requisitions*.
. Click *Add External Requisition*.
. Specify a name for the external requisition.
. From the *Type* drop-down, choose *DNS*.
. Type "localhost" in the *Host* field.
. Type "localhost" as the *Zone* field.
. Type "DNS-example" in the *Requsition Name* field.
.. The URL "dns://localhost/localhost/DNS-example" appears at the bottom of the dialog.
. Choose *Daily* for the schedule type and specify 12:00 a.m. for the time.
+
NOTE: To create an advanced cron schedule, click the checkbox and add the appropriate information.

. Specify how OpenNMS should perform subsequent scans:
.. Scan all nodes
.. Scan added nodes only
.. No scanning

. The optional *Advanced Options* section lets you specify key/value pairs.
. 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 `"`.
