Merge pull request #61 from OpenNMS/feature/PRIS-160

PRIS-160: Allow CSV files as source for provisioning

docs/modules/sources/examples/csv/global.properties

@@ -0,0 +1,8 @@
+### File: global.properties
+# Start web server
+# The web server listens on all interfaces and can be accessed on TCP port 8000
+# URL: http://${your-ip}:8000/requisitions/${name-requisition-cfg}
+
+driver = http
+host = 0.0.0.0
+port = 8000

docs/modules/sources/examples/csv/requisitions/myinventory-noheaders/myinventory-noheaders.csv

@@ -0,0 +1,6 @@
+bbone-gw1,10.0.23.1,P,ICMP;SNMP,Backbone
+bbone-gw2,10.0.23.2,P,ICMP;SNMP,Backbone
+rt-01,172.16.23.1,P,ICMP;SNMP,Office
+rt-02,172.16.23.2,P,ICMP;SNMP,Office
+rt-02,172.16.23.3,S,ICMP;StrafePing,
+rt-02,192.168.30.1,N,,

docs/modules/sources/examples/csv/requisitions/myinventory-noheaders/requisition.properties

@@ -0,0 +1,12 @@
+### File: myRouter/requisition.properties
+# This example imports devices from a spreadsheet
+# named "myRouter" from the myInventory.xls file
+# Path to the XLS fils is relative to
+# requisitions.properties
+source = xls
+source.file = ./myinventory-noheaders.csv
+
+source.org.opennms.pris.spreadsheet.fields=Node_Label,IP_Management,MgmtType_,svc_Forced,cat_Environment
+
+### default no-operation mapper
+mapper = echo

docs/modules/sources/examples/csv/requisitions/myinventory/myinventory.csv

@@ -0,0 +1,7 @@
+Node_Label,IP_Management,MgmtType_,svc_Forced,cat_Environment
+bbone-gw1,10.0.23.1,P,ICMP;SNMP,Backbone
+bbone-gw2,10.0.23.2,P,ICMP;SNMP,Backbone
+rt-01,172.16.23.1,P,ICMP;SNMP,Office
+rt-02,172.16.23.2,P,ICMP;SNMP,Office
+rt-02,172.16.23.3,S,ICMP;StrafePing,
+rt-02,192.168.30.1,N,,

docs/modules/sources/examples/csv/requisitions/myinventory/requisition.properties

@@ -0,0 +1,10 @@
+### File: myRouter/requisition.properties
+# This example imports devices from a spreadsheet
+# named "myRouter" from the myInventory.xls file
+# Path to the XLS fils is relative to
+# requisitions.properties
+source = xls
+source.file = ./myinventory.csv
+
+### default no-operation mapper
+mapper = echo

docs/modules/sources/nav.adoc

@@ -7,3 +7,4 @@
 * xref:ocs.adoc[]
 * xref:script.adoc[]
 * xref:xls.adoc[]
+* xref:csv.adoc[]

docs/modules/sources/pages/csv.adoc

@@ -0,0 +1,41 @@
+= CSV Source
+
+The `xls` source can also create a requisition from a UTF-8 encoded, comma-separated variable (CSV) file if the given file name has the `.csv` suffix.
+
+In this case the first line of the CSV file should contain a comma-separated list of headers in the same way the spreadsheet should be configured in a normal XLS source. 
+Alternatively, you can set a property containing a comma-separated set of headers to use as the first line of the CSV file.
+This lets {page-component-title} read CSV files that do not have a header.
+
+[options="header",autowidth"]
+|===
+| Parameter         | Required | Description
+| `source`          | *        | Set `xls` to use the XLS source for this requisition.
+| `source.file`     | *        | Path of the CSV file to read relative to the `requisition.properties`.
+Note that the file name must end with `.csv`.
+| `source.org.opennms.pris.spreadsheet.fields` |          | If this property is not present, the first line of the CSV file is used as the column headers in the same way as in the XLS data source. 
+If this property is set, the value of this field should be a comma-separated set of headers to use instead of using the first line of the CSV file.
+|===
+
+The structure of the CSV file should follow the same rules and use the same headers as in the XLS data source.
+
+However, any columns that would contain comma-separated values in a spreadsheet must have the contents delineated using a semicolon ';' character rather than commas.
+In the following example, the svc_Forced services ICMP;SNMP are separated using a semicolon.
+
+```
+Node_Label,IP_Management,MgmtType_,svc_Forced,cat_Environment
+bbone-gw2,10.0.23.2,P,ICMP;SNMP,Backbone
+```
+
+Example configuration for the requisition `myinventory` from a CSV file `myinventory.csv`:
+[source,bash]
+----
+include::example$csv/requisitions/myinventory/requisition.properties[]
+----
+
+Example configuration for the requisition `myinventory-noheaders` from a CSV file `myinventory-noheaders.csv`:
+This example has a `source.org.opennms.pris.spreadsheet.fields` property set:
+
+[source,bash]
+----
+include::example$csv/requisitions/myinventory-noheaders/requisition.properties[]
+----

opennms-pris-plugins/opennms-pris-plugins-xls/pom.xml

@@ -1,51 +1,55 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0"
-         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+   <modelVersion>4.0.0</modelVersion>
 
-    <parent>
-        <groupId>org.opennms</groupId>
-        <artifactId>opennms-pris-plugins</artifactId>
-        <version>BLEEDING</version>
-    </parent>
+   <parent>
+      <groupId>org.opennms</groupId>
+      <artifactId>opennms-pris-plugins</artifactId>
+      <version>BLEEDING</version>
+   </parent>
 
-    <artifactId>opennms-pris-plugins-xls</artifactId>
-    <packaging>jar</packaging>
+   <artifactId>opennms-pris-plugins-xls</artifactId>
+   <packaging>jar</packaging>
 
-    <name>OpenNMS :: Provisioning Integration Server :: Plugins :: XLS</name>
+   <name>OpenNMS :: Provisioning Integration Server :: Plugins :: XLS</name>
 
-    <properties>
-        <apachePoiVersion>4.1.1</apachePoiVersion>
-    </properties>
+   <properties>
+      <apachePoiVersion>4.1.1</apachePoiVersion>
+   </properties>
 
-    <dependencies>
-        <!-- XLS -->
-    <dependency>
-        <groupId>org.apache.poi</groupId>
-        <artifactId>poi</artifactId>
-        <version>${apachePoiVersion}</version>
-    </dependency>
-	<dependency>
-        <groupId>org.apache.poi</groupId>
-        <artifactId>poi-ooxml</artifactId>
-        <version>${apachePoiVersion}</version>
-	</dependency>
-        <!-- Tests -->
-        <dependency>
-            <groupId>${project.groupId}</groupId>
-            <artifactId>opennms-pris-api</artifactId>
-            <classifier>tests</classifier>
-        </dependency>
-    </dependencies>
+   <dependencies>
+      <!-- XLS -->
+      <dependency>
+         <groupId>org.apache.poi</groupId>
+         <artifactId>poi</artifactId>
+         <version>${apachePoiVersion}</version>
+      </dependency>
+      <dependency>
+         <groupId>org.apache.poi</groupId>
+         <artifactId>poi-ooxml</artifactId>
+         <version>${apachePoiVersion}</version>
+      </dependency>
+      <dependency>
+         <groupId>org.apache.commons</groupId>
+         <artifactId>commons-lang3</artifactId>
+         <version>${commonsLang3Version}</version>
+      </dependency>
+      <!-- Tests -->
+      <dependency>
+         <groupId>${project.groupId}</groupId>
+         <artifactId>opennms-pris-api</artifactId>
+         <classifier>tests</classifier>
+      </dependency>
+   </dependencies>
 
-    <build>
-        <plugins>
-            <!-- Build fat JAR -->
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-shade-plugin</artifactId>
-            </plugin>
-        </plugins>
-    </build>
+   <build>
+      <plugins>
+         <!-- Build fat JAR -->
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-shade-plugin</artifactId>
+         </plugin>
+      </plugins>
+   </build>
 </project>