Add nbinotifications feature documentation

add descriptions of nbinotifications feature
into the developper-guide and user-guide.

JIRA: TRNSPRTPCE-406
Signed-off-by: Thierry Jiao <thierry.jiao@orange.com>
Change-Id: Ic27840223a3d3e13e93f4d572850f2fcd8097df3

diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst
index 923b9d7bcbab4f3d550de5786a2f2303d0a5fca8..7380ac54bd61411e01cf0b6d455aaebad9c3eea9 100644 (file)
--- a/docs/developer-guide.rst
+++ b/docs/developer-guide.rst
@@ -1448,6 +1448,72 @@ This feature listens on NBI notifications and sends the PublishNotificationServi
 Dmaap on the topic "unauthenticated.TPCE" through a POST request on /events/unauthenticated.TPCE
 It uses Jackson to serialize the notification to JSON and jersey client to send the POST request.
 
+odl-transportpce-nbinotifications
+---------------------------------
+
+This feature allows TransportPCE application to write and read notifications stored in topics of a Kafka server.
+When the feature is called to write notification to a Kafka server, it will serialize the notification
+into JSON format and then will publish it in a topic of the server.
+When the feature is called to read notifications from a Kafka server, it will retrieve it from
+the topic of the server and will deserialize it.
+
+For now, when the REST RPC service-create is called to create a bidirectional end-to-end service,
+depending on the success or the fail of the creation, the feature will notify the progression of
+the creation to a Kafka server. The topics that store these notifications are named after the connection type
+(service, infrastructure, roadm-line). For instance, if the RPC service-create is called to create an
+infrastructure connection, the service notifications related to this connection will be stored in
+the topic 'infrastructure'.
+
+The figure below shows an example of the application nbinotifications in order to notify the
+progress of a service creation.
+
+.. figure:: ./images/TransportPCE-nbinotifications-service-example.jpg
+   :alt: Example of service notifications using the feature nbinotifications in TransportPCE
+
+
+Depending of the success of the service creation, different notifications will be published
+to the topic 'service' of the Kafka server.
+
+
+-  **ServiceCreate request received** : Indicates that TransportPCE received an RPC request service-create
+   and started the process of creation. The notification contains all information concerning
+   the new service to create.
+
+
+If the service was correctly implemented, these notifications will be published :
+
+
+-  **PCE calculation done OK !** : Indicates that the PCE calculation requested by the service-create
+   was successful. It also contains all information concerning the new service to create.
+-  **Service implemented !** : Indicates that the service was successfully implemented.
+   It also contains all information concerning the new service.
+
+
+Otherwise, this notification will be published :
+
+
+-  **ServiceCreate failed ...** : Indicates that the process of service-create failed.
+   It contains the failure response.
+
+To retrieve these service notifications stored in the Kafka server :
+
+**REST API** : *POST /restconf/operations/nbi-notifications:get-notifications-service*
+
+**Sample JSON Data**
+
+.. code:: json
+
+    {
+      "input": {
+        "connection-type": "service",
+        "id-consumer": "consumer",
+        "group-id": "test"
+       }
+    }
+
+.. note::
+    The field 'connection-type' corresponds to the topic that store the notifications.
+
 Help
 ----
 

diff --git a/docs/images/TransportPCE-nbinotifications-service-example.jpg b/docs/images/TransportPCE-nbinotifications-service-example.jpg
new file mode 100755 (executable)
index 0000000..39ed1aa
Binary files /dev/null and b/docs/images/TransportPCE-nbinotifications-service-example.jpg differ

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 34b0b38cbd8c32b5454d3477e1ffa00115d9163e..f0d83ce15615e70d131658a219f99021bd8821cd 100644 (file)
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -60,6 +60,11 @@ TransportPCE User-Facing Features
    -  This feature is considered experimental. It provides a REST client in order to send TPCE notifications
       to ONAP Dmaap Message router.
 
+-  **feature odl-transportpce-nbinotifications**
+
+   -  This feature is considered experimental. It provides transportPCE with connectors in order to read/write
+      notifications stored in topics of a Kafka server.
+
 How To Start
 ------------
 
@@ -114,4 +119,20 @@ Then run in karaf::
 
    feature:install odl-transportpce-dmaap-client
 
+If you need the NBI-notifications support, before installing odl-transportpce-nbinotifications feature,
+make sure to run ZooKeeper and then the Kafka server.
+By default, it is considered that the Kafka server is installed in localhost and listens on the 9092 port,
+if it isn't the case then set the KAFKA_SERVER environment variable of your system or
+modify the file *'transportpce/features/odl-transportpce-nbinotifications
+/src/main/resources/org.opendaylight.transportpce.nbinotifications.cfg'*::
+
+   suscriber.server=${env:KAFKA_SERVER:-[IP_ADDRESS]:[PORT]}
+   publisher.server=${env:KAFKA_SERVER:-[IP_ADDRESS]:[PORT]}
+
+*where [IP_ADDRESS] and [PORT] are respectively the IP address and the port that host the Kafka server.*
+
+After that, run in karaf::
+
+   feature:install odl-transportpce-nbinotifications
+
 For a more detailed overview of the TransportPCE, see the :ref:`transportpce-dev-guide`.