Merge pull request #1099 from OpenNMS/jira/HZN-915

HZN-915: Added ReST service for invoking one-time discovery scans

opennms-doc/guide-development/src/asciidoc/index.adoc

@@ -66,6 +66,7 @@ include::text/rest/emailnbi-config.adoc[]
 include::text/rest/javamail-config.adoc[]
 include::text/rest/syslognbi-config.adoc[]
 include::text/bsm/bsm-development.adoc[]
+include::text/rest/discovery.adoc[]
 
 === ReST API Examples
 include::text/rest/examples.adoc[]

opennms-doc/guide-development/src/asciidoc/text/rest/discovery.adoc

@@ -0,0 +1,63 @@
+
+==== Discovery
+This endpoint can be used to trigger a one-time discovery scan.
+
+===== POSTs (Submitting one-time scan configuration)
+
+[options="header", cols="5,10"]
+|===
+| Resource        | Description
+| `/opennms/api/v2/discovery`    | Submits an one-time scan configuration
+|===
+
+The following XML structure is used to define a scan job.
+
+.Sample configuration file `discovery.xml`
+[source,XML]
+----
+<discoveryConfiguration>
+  <specifics>
+    <specific>
+      <location>Default</location>
+      <retries>3</retries>
+      <timeout>2000</timeout>
+      <foreignSource>My-ForeignSource</foreignSource>
+      <content>192.0.2.1</content>
+    </specific>
+  </specifics>
+  <includeRanges>
+    <includeRange>
+      <location>Default</location>
+      <retries>3</retries>
+      <timeout>2000</timeout>
+      <foreignSource>My-ForeignSource</foreignSource>
+      <begin>192.0.2.10</begin>
+      <end>192.0.2.254</end>
+    </includeRange>
+  </includeRanges>
+  <excludeRanges>
+    <excludeRange>
+      <begin>192.0.2.60</begin>
+      <end>192.0.2.65</end>
+    </excludeRange>
+  </excludeRanges>
+  <includeUrls>
+    <includeUrl>
+      <location>Default</location>
+      <retries>3</retries>
+      <timeout>2000</timeout>
+      <foreignSource>My-ForeignSource</foreignSource>
+      <content>http://192.0.2.254/addresses.txt</content>
+    </includeUrl>
+  </includeUrls>
+</discoveryConfiguration>
+----
+
+The scan itself can be triggered by posting the configuration to the ReST endpoint as follows:
+
+.Trigger one-time scan
+[source, bash]
+----
+curl -H "Content-Type: application/xml" -u admin:admin -X POST -d @discovery.xml http://localhost:8980/opennms/api/v2/discovery
+----
+

opennms-webapp-rest/pom.xml

@@ -203,6 +203,14 @@
       <scope>${onmsLibScope}</scope>
     </dependency>
 
+    <!-- Discovery -->
+    <dependency>
+      <groupId>org.opennms.features</groupId>
+      <artifactId>org.opennms.features.discovery</artifactId>
+      <version>${project.version}</version>
+      <scope>${onmsLibScope}</scope>
+    </dependency>
+
     <!-- CORS support -->
     <dependency>
       <groupId>org.ebaysf.web</groupId>