Adding Documentation of Mapper

Adding documentation of Mapper on readthedocs

Change-Id: I80ec21296ec42ef21552a9e93839ca5209a27a58
Issue-ID: DCAEGEN2-936
Signed-off-by: Pooja03 <pm00501616@techmahindra.com>

7 files changed, 346 insertions, 0 deletions

diff --git a/docs/sections/services/mapper/MappingFile.rst b/docs/sections/services/mapper/MappingFile.rst
new file mode 100644
index 00000000..e99ba5a9
--- /dev/null
+++ b/docs/sections/services/mapper/MappingFile.rst
@@ -0,0 +1,84 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2018 Tech Mahindra Ltd.
+
+Mapping File
+============
+
+Mapping file is needed by Universal VES Adapter to convert the telemetry data into the VES format.
+The Adapter uses Smooks Framework to do the data format conversion by using the mapping files.
+Currently it requires to write the mapping file manually and upload it using the SnmpMapper application. The file gets stored into the postgres database. The pgInventory instance is used for this.
+
+| To know more about smooks framework check the following link:
+| http://www.smooks.org/guide
+
+Following is the default snmp mapping file which is used when no mapping file is found while processing event from SNMP Trap Collector. 
+
+.. code-block:: xml
+
+ <?xml version="1.0"?>
+    <smooks-resource-list
+             xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
+            xmlns:json="http://www.milyn.org/xsd/smooks/json-1.1.xsd"
+            xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.4.xsd">
+        <json:reader rootName="vesevent"  keyWhitspaceReplacement="-">
+        <json:keyMap>
+                   <json:key from="date&amp;time" to="date-and-time" />
+                </json:keyMap>
+          </json:reader>
+     
+       <jb:bean class="org.onap.dcaegen2.ves.domain.VesEvent" beanId="vesEvent" createOnElement="vesevent">
+          <jb:wiring property="event" beanIdRef="event"/>
+     </jb:bean>
+  
+       <jb:bean class="org.onap.dcaegen2.ves.domain.Event" beanId="event" createOnElement="vesevent">
+           <jb:wiring property="commonEventHeader" beanIdRef="commonEventHeader"/>
+           <jb:wiring property="faultFields" beanIdRef="faultFields"/>     
+          <!--<jb:wiring property="measurementsForVfScalingFields" beanIdRef="measurementsForVfScalingFields"/> -->       
+      </jb:bean>   
+      <!--<jb:bean class="org.onap.dcaegen2.ves.domain.MeasurementsForVfScalingFields" beanId="measurementsForVfScalingFields" createOnElement="simple">
+          <jb:wiring property="additionalMeasurements" beanIdRef="additionalMeasurements"/>
+       </jb:bean>-->
+       
+       <jb:bean class="org.onap.dcaegen2.ves.domain.CommonEventHeader" beanId="commonEventHeader" createOnElement="vesevent">
+                  <jb:expression property="version">"3.0"</jb:expression>
+                   <jb:expression property="eventId">"XXXX"</jb:expression>
+                   <jb:expression property="reportingEntityName">"VesAdapter"</jb:expression>
+                  <jb:expression property="domain">"fault"</jb:expression>
+                  <jb:expression property="eventName" execOnElement="vesevent" >commonEventHeader.domain+"_"+"_"+ faultFields.alarmCondition;</jb:expression>
+          <jb:value property="sequence" data="0" default="0" decoder="Long"/>
+           <jb:value property="lastEpochMicrosec" data="#/time-received"  decoder="Double" />
+          <jb:value property="startEpochMicrosec" data="#/time-received"  decoder="Double"/>
+                  <jb:expression property="priority">"Medium"</jb:expression>
+          <jb:expression property="sourceName">"VesAdapter"</jb:expression>
+      </jb:bean>   
+      
+      <jb:bean class="org.onap.dcaegen2.ves.domain.FaultFields" beanId="faultFields" createOnElement="vesevent">
+           <jb:value property="alarmCondition" data="#/trap-category" />
+                 <jb:expression property="eventSeverity">"MINOR"</jb:expression>
+                   <jb:expression property="eventSourceType">"SNMP Agent"</jb:expression>
+           <jb:expression property="specificProblem">"SNMP Fault"</jb:expression>
+           <jb:value property="faultFieldsVersion" data="2.0" default="2.0" decoder="Double" />
+          <jb:wiring property="alarmAdditionalInformation" beanIdRef="alarmAdditionalInformationroot"/>   
+                  <jb:expression property="vfStatus">"Active"</jb:expression>
+         
+    </jb:bean>  
+        <jb:bean class="java.util.ArrayList" beanId="alarmAdditionalInformationroot" createOnElement="vesevent">
+         <jb:wiring beanIdRef="alarmAdditionalInformation"/>
+      </jb:bean>
+      
+        <jb:bean class="org.onap.dcaegen2.ves.domain.AlarmAdditionalInformation" beanId="alarmAdditionalInformation" createOnElement="varbinds/element">
+        <jb:value property="name" data="#/varbind_oid"/>
+         <jb:value property="value" data="#/varbind_value" />
+       </jb:bean>
+          <!--<jb:bean class="java.util.ArrayList" beanId="additionalMeasurements" createOnElement="simple">
+         <jb:wiring beanIdRef="additionalMeasurement"/>
+       </jb:bean>    
+      
+       <jb:bean class="org.onap.dcaegen2.ves.domain.AdditionalMeasurement" beanId="additionalMeasurement" createOnElement="varbinds/element">
+          <jb:value property="name" data="#/varbind_value" />
+      </jb:bean>  -->  
+      
+  </smooks-resource-list>
+
+
diff --git a/docs/sections/services/mapper/SampleSnmpTrapConversion.rst b/docs/sections/services/mapper/SampleSnmpTrapConversion.rst
new file mode 100644
index 00000000..71f5718b
--- /dev/null
+++ b/docs/sections/services/mapper/SampleSnmpTrapConversion.rst
@@ -0,0 +1,150 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2018 Tech Mahindra Ltd.
+
+Sample Snmp trap Conversion:
+===========================
+
+Following is the **Sample SNMP Trap** that will be received by the Universal VES Adapter from the Snmp Trap Collector :
+
+.. code-block:: json
+
+    {  
+   "cambria.partition":"10.53.172.132",
+   "trap category":"ONAP-COLLECTOR-SNMPTRAP",
+   "community len":0,
+   "protocol version":"v2c",
+   "varbinds":[  
+      {  
+         "varbind_value":"CLEARED and CRITICAL severities have the same name",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.2.0",
+         "varbind_type":"OctetString"
+      },
+      {  
+         "varbind_value":"1.3",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.3.0",
+         "varbind_type":"ObjectIdentifier"
+      },
+      {  
+         "varbind_value":"1.3",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.4.0",
+         "varbind_type":"ObjectIdentifier"
+      },
+      {  
+         "varbind_value":"CLEARED",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.5.0",
+         "varbind_type":"OctetString"
+      },
+      {  
+         "varbind_value":"Queue manager: Process failure cleared",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.6.0",
+         "varbind_type":"OctetString"
+      },
+      {  
+         "varbind_value":"The queue manager process has been restored to normal operation",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.7.0",
+         "varbind_type":"OctetString"
+      },
+      {  
+         "varbind_value":"The queue manager process has been restored to normal operation. The previously issued alarm has been cleared",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.8.0",
+         "varbind_type":"OctetString"
+      },
+      {  
+         "varbind_value":"Changes to shared config will be synchronized across the cluster",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.9.0",
+         "varbind_type":"OctetString"
+      },
+      {  
+         "varbind_value":"No action",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.10.0",
+         "varbind_type":"OctetString"
+      },
+      {  
+         "varbind_value":"sprout-1.example.com",
+         "varbind_oid":"1.3.6.1.4.1.19444.12.2.0.12.0",
+         "varbind_type":"OctetString"
+      }
+   ],
+   "notify OID":"1.3.6.1.6.3.1.1.5.3",
+   "community":"",
+   "uuid":"1fad4802-a6d0-11e8-a349-0242ac110002",
+   "epoch_serno":15350273450000,
+   "agent name":"10.53.172.132",
+   "sysUptime":"0",
+   "time received":1.535027345042007E9,
+   "agent address":"10.53.172.132",
+   "notify OID len":10
+ }
+
+
+Following is the converted VES Format of the above SNMP Sample Trap by using the default SNMP Trap Mapping File:
+
+.. code-block:: json
+
+ {  
+   "event":{  
+      "commonEventHeader":{  
+         "startEpochMicrosec":1.5350269902625413E9,
+         "eventId":"XXXX",
+         "sequence":0,
+         "domain":"fault",
+         "lastEpochMicrosec":1.5350269902625413E9,
+         "eventName":"fault__ONAP-COLLECTOR-SNMPTRAP",
+         "sourceName":"10.53.172.132",
+         "priority":"Medium",
+         "version":3,
+         "reportingEntityName":"VesAdapter"
+      },
+      "faultFields":{  
+         "eventSeverity":"MINOR",
+         "alarmCondition":"ONAP-COLLECTOR-SNMPTRAP",
+         "faultFieldsVersion":2,
+         "specificProblem":"SNMP Fault",
+         "alarmAdditionalInformation":[  
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.2.0",
+               "value":"CLEARED and CRITICAL severities have the same name"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.3.0",
+               "value":"1.3"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.4.0",
+               "value":"1.3"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.5.0",
+               "value":"CLEARED"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.6.0",
+               "value":"Queue manager: Process failure cleared"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.7.0",
+               "value":"The queue manager process has been restored to normal operation"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.8.0",
+               "value":"The queue manager process has been restored to normal operation. The previously issued alarm has been cleared"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.9.0",
+               "value":"Changes to shared config will be synchronized across the cluster"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.10.0",
+               "value":"No action"
+            },
+            {  
+               "name":"1.3.6.1.4.1.19444.12.2.0.12.0",
+               "value":"sprout-1.example.com"
+            }
+         ],
+         "eventSourceType":"SNMP Agent",
+         "vfStatus":"Active"
+      }
+   }
+ }
\ No newline at end of file
diff --git a/docs/sections/services/mapper/delivery.rst b/docs/sections/services/mapper/delivery.rst
new file mode 100644
index 00000000..10968b7e
--- /dev/null
+++ b/docs/sections/services/mapper/delivery.rst
@@ -0,0 +1,17 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2018 Tech Mahindra Ltd.
+
+Delivery
+========
+Mapper is delivered with **2 Docker container** having spring boot microservices, **UniversalVesAdapter** and **SnmMapper**. UniversalVesAdapter converts SNMP trap JSON to VES and snmpmapper is just helper application for uploading the mapping file to DB. 
+
+| In current release, the installation of mapper service is not integrated with DCAE's installation process and needs to be done manually.
+
+Docker Containers
+---------------
+Docker images can be pulled from ONAP Nexus repository with below commands: 
+
+| docker pull nexus3.onap.org:10003/snapshots/onap/org.onap.dcaegen2.services.mapper.vesadapter.universalvesadaptor:latest
+
+| docker pull nexus3.onap.org:10003/snapshots/onap/org.onap.dcaegen2.services.mapper.vesadapter.snmpmapper:latest
diff --git a/docs/sections/services/mapper/flow.PNG b/docs/sections/services/mapper/flow.PNG
new file mode 100644
index 00000000..614d5d5f
--- /dev/null
+++ b/docs/sections/services/mapper/flow.PNG
diff --git a/docs/sections/services/mapper/flow.rst b/docs/sections/services/mapper/flow.rst
new file mode 100644
index 00000000..cff2485e
--- /dev/null
+++ b/docs/sections/services/mapper/flow.rst
@@ -0,0 +1,17 @@
+============
+Flow
+============
+.. [#] VNF submits SNMP traps to the SNMP trap collecto.
+.. [#] Collector converts the trap into JSON format and publishes it on DMaaP topic **ONAP-COLLECTOR-SNMPTRAP**
+.. [#] The Universal VES Adapter(UVA) microservice has subscribed to this DMaaP topic.
+.. [#] On receiving an event from DMaaP, the adapter uses the corresponding mapping file from repository and converts received event into the VES event. It uses the enterprise ID from the received event to find the required mapping file. 
+.. [#] Those SNMP Traps for which no mapping file is identified, a default mapping file is used with generic mappings to create the VES object.
+.. [#] The VES formatted Event will be then published on DMaaP topic **unauthenticated.SEC_FAULT_OUTPUT**.
+
+
+.. image:: ./flow.png
+   :height: 100px
+   :width: 200 px
+   :scale: 50 %
+   :alt: alternate text
+   :align: left
\ No newline at end of file
diff --git a/docs/sections/services/mapper/index.rst b/docs/sections/services/mapper/index.rst
new file mode 100644
index 00000000..81122932
--- /dev/null
+++ b/docs/sections/services/mapper/index.rst
@@ -0,0 +1,30 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2018 Tech Mahindra Ltd.
+
+
+Mapper
+=====================
+
+| **Problem:** Different VNF vendors generate event and telemetry data in different formats. Out of the box, all VNF vendors may not support VES format. 
+| **Solution**: A generic adapter which can convert different formats of event and telemetry data to VES format can be of use here. 
+| *Note*: Currently support snmp trap telemetry data
+
+There are 2 micro services in the mapper functionality.
+
+**Universal VES Adapter** - It converts the telemetry data into the required ves format and publishes to the dmaap for further action to be taken. 
+ *Note*: Currently it supports conversion of snmp traps generated by SNMP TRAP Collector. With some work, it can support other collectors as well.
+
+
+**SnmpMapper** - It provides web UI to upload mapping files which are then stored into the postgres database. VES adapter refers to these mapping files at the time of converting the events into VES events.
+
+
+
+.. toctree::
+   :maxdepth: 1
+
+   ./flow.rst
+   ./delivery.rst
+   ./installation.rst
+   ./MappingFile.rst
+  ./SampleSnmpTrapConversion
diff --git a/docs/sections/services/mapper/installation.rst b/docs/sections/services/mapper/installation.rst
new file mode 100644
index 00000000..1d05ebb8
--- /dev/null
+++ b/docs/sections/services/mapper/installation.rst
@@ -0,0 +1,48 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2018 Tech Mahindra Ltd.
+
+
+Installation
+============
+Currently both Universal VES Adapter and SnmpMapper are not integrated with CONFIG_BINDING_SERVICE to get their configuration. All the required configuration needs to be passed as docker environment parameters.
+
+| **Universal Ves Adapter**
+
+ To run Universal Ves Adapter container on standalone mode, following docker environment parameters are required.
+
+
+- DMAAPHOST  -  Should contain an address to DMaaP, so that event publishing can work
+- MR_PORT - DMaaP Exposed Port
+- URL_JDBC - JDBC URL where postgres db is installed 
+- JDBC_USERNAME - Username for postgres DB user
+- JDBC_PASSWORD - Password for postgres  DB user
+- CONSUL_HOST - a host address where Consul service lies
+- CONFIG_BINDING_SERVICE - name of CBS as it is registered in Consul
+- HOSTNAME - name of Universal Ves Adapter application as it is registered in CBS catalog
+
+Sample docker run command could be -
+
+    ``docker run -d -p 8085:8085/tcp -e URL_JDBC=jdbc:postgresql://10.53.172.138:5432/postgres -e JDBC_USERNAME=postgres -e JDBC_PASSWORD=root -e DMAAPHOST=10.53.172.156 -e CONSUL_HOST=10.53.172.109 -e HOSTNAME=static-dcaegen2-services-mua -e MR_DEFAULT_PORT_NUMBER=3904 -e CONFIG_BINDING_SERVICE=config_binding_service nexus3.onap.org:10003/onap/org.onap.dcaegen2.services.mapper.vesadapter.universalvesadaptor:latest``
+
+Note: you should have a postgresql  and DMaap  instance running in your system and provide their credentials and hostname to run in standalone mode.
+
+
+
+
+| **SnmpMapper**
+
+- To run SnmpMapper container on standalone mode, following docker environment parameters are required.
+
+- DMAAPHOST-should contain an address to DMaaP, this will be used in future reference
+- MR_PORT - DMaaP Exposed Port
+- URL_JDBC- JDBC URL where postgres db is installed 
+- JDBC_USERNAME- Username for postgres DB user
+- JDBC_PASSWORD-Password for postgres  DB user
+- CONSUL_HOST - a host address where Consul service lies
+- CONFIG_BINDING_SERVICE - name of CBS as it is registered in Consul
+- HOSTNAME - name of Universal Ves Adapter application as it is registered in CBS catalog
+
+Sample docker run command could be -
+
+   ``docker run -d -p 8084:8080/tcp -e URL_JDBC=jdbc:postgresql://10.53.172.138:5432/postgres -e JDBC_USERNAME=postgres -e JDBC_PASSWORD=root -e DMAAPHOST=10.53.172.156 -e CONSUL_HOST=10.53.172.109 -e HOSTNAME=static-dcaegen2-services-msnmp -e MR_DEFAULT_PORT_NUMBER=3904 -e CONFIG_BINDING_SERVICE=config_binding_service nexus3.onap.org:10003/onap/org.onap.dcaegen2.services.mapper.snmpmapper:latest``