Update drools tutorials documentation

Issue-ID: POLICY-2399
Change-Id: I9756a660f80348eb69b217e6f1de6bad7a7b6f00
Signed-off-by: Peyton Puckett <peyton.puckett@att.com>

1 files changed, 286 insertions, 35 deletions

diff --git a/docs/drools/clsimulation.rst b/docs/drools/clsimulation.rst
index 8efff0a8..10276762 100644
--- a/docs/drools/clsimulation.rst
+++ b/docs/drools/clsimulation.rst
@@ -9,14 +9,42 @@ Control Loop Simulation and Injection of Messages Overview
 .. contents::
     :depth: 2
 
+This section will cover how to interact with the PDP-D using telemetry commands. This assumes that you have a PDP-D running to interact with. Take a look at the page "Methods to run PDP-D" if you do not have a PDP-D running for testing purposes.
+
 Telemetry
 ^^^^^^^^^
 The username and password for the Telemetry commands are in *${POLICY_HOME}/config/engine.properties*.
+If you are using Eclipse, the credentials can be found in the file **install-drools/src/files/base.conf** within the "drools-pdp" repository.
+The environment variables $TELEMETRY_USER and $TELEMETRY_PASSWORD will also have the credentials if they have already been set.
+
+Recall you can use the command "docker exec -it drools bash" to get the PDP-D running with Docker.
+
+    .. code-block:: bash
+
+      docker exec -it drools bash
+
+Your terminal should now look similar to "policy@drools:/<path>". This indicates you are in the drools docker container. If you run "policy status" the controller should be running.
+
+    .. image:: img/docker/policyStatus.png
+
+To enter the telemetry subshell, use the command "telemetry".
+
+    .. code-block:: bash
+
+      telemetry
+
+Use the "exit" command to exit the telemetry subshell. The terminal will now go back to the docker container.
+
+    .. code-block:: bash
+
+      exit
+
+    .. image:: img/docker/credentials.png
 
 Injecting messages:
 -------------------
 
-To inject messages use the following command.  The injected message will look as if it came in from the specified topic and will be processed accordingly.
+To inject messages, use the following command.  The injected message will look as if it came in from the specified topic and will be processed accordingly.
 
 Use the command:
 
@@ -24,33 +52,48 @@ Use the command:
 
         http --verify=no --default-scheme=https -a <userName>:<password> PUT :9696/policy/pdp/engine/topics/sources/<comm>/<topic>/events @<onsetFile> Content-Type:"text/plain"
 
-where <comm> is either "dmaap", "ueb", or "noop", depending on how the topic has been defined in the
-configuration.   "dmaap" is the default deployed messaging communication infrastructure in an ONAP installation.
-The following is the equivalent "curl" version:
+The equivalent "curl" version:
 
     .. code-block:: bash
 
         curl --insecure --silent --user <userName>:<password> -X PUT --header "Content-Type: text/plain" --data @<onsetFile> https://localhost:9696/policy/pdp/engine/topics/sources/<comm>/<topic>/events
 
-The topic being used is *unauthenticated.DCAE_CL_OUTPUT*, which is subject to change.  The onset file is a file that contains the data to inject as the onset.  The data contained depends on the use case. This is an example for VoLTE:
+Note: you may have to replace "https" with "http" depending on how you are running the drools-pdp.
+
+The <comm> is a messaging communication infrastructure in an ONAP installation. Depending on how a topic has been defined in the configuration, the <comm> is either "dmaap", "ueb", or "noop".
+The default messaging communication infrastructure is "dmaap".
+
+The <topic> is a specific topic name used to send and/or receive information. There are two types of topics:
+
+1. **source** topics (Example: dmaap.source.topics=APPC-LCM-WRITE or dmaap.source.topics=APPC-CL)
+
+2. **sink** topics (Example: dmaap.sink.topics=APPC-LCM-READ or dmaap.sink.topics=APPC-CL)
+
+You can extract <comm> and <topic> from the following example:
+Example: dmaap.sink.topics=APPC-LCM-READ
+
+1. <comm>=dmaap
+
+2. <topic>=APPC-LCM-READ
+
+The onset is a json file that contains the data to inject as the onset.  The data contained depends on the use case. This is an example for the vFirewall usecase:
 
     .. code-block:: json
-       :caption: VoLTE_Sample_Onset
+       :caption: vFirewall_Sample_Onset
 
         {
-            "closedLoopControlName": "ControlLoop-VOLTE-2179b738-fd36-4843-a71a-a8c24c70c55b",
-            "closedLoopAlarmStart": 1484677482204798,
-            "closedLoopEventClient": "DCAE.HolmesInstance",
+            "closedLoopControlName": "ControlLoop-vFirewall-d0a1dfc6-94f5-4fd4-a5b5-4630b438850a",
+            "closedLoopAlarmStart": 1463679805324,
+            "closedLoopEventClient": "microservice.stringmatcher",
             "closedLoopEventStatus": "ONSET",
-            "requestID": "97964e10-686e-4790-8c45-bdfa61df770f",
-            "target_type": "VM",
-            "target": "vserver.vserver-name",
+            "requestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65",
+            "target_type": "VNF",
+            "target": "generic-vnf.vnf-name",
             "AAI": {
                 "vserver.is-closed-loop-disabled": "false",
-                "vserver.vserver-name": "dfw1lb01lb01",
-                "service-instance.service-instance-id" : "vserver-name-16102016-aai3255-data-11-1",
-                "generic-vnf.vnf-id" : "vnf-id-16102016-aai3255-data-11-1",
-                "generic-vnf.vnf-name" : "vnf-name-16102016-aai3255-data-11-1"
+                "vserver.prov-status": "ACTIVE",
+                "generic-vnf.vnf-name": "fw0002vm002fw002",
+                "vserver.vserver-name": "OzVServer"
             },
             "from": "DCAE",
             "version": "1.0.2"
@@ -59,17 +102,44 @@ The topic being used is *unauthenticated.DCAE_CL_OUTPUT*, which is subject to ch
 Getting Information
 -------------------
 
-To get the name of the active controller(s), use:
+To get the name(s) of the active controller(s), use:
 
     .. code-block:: bash
 
         curl --insecure --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/controllers | python -m json.tool
 
-To check the facts currently in memory, use the following command.  There should be 1 each of org.onap.policy.controlloop.PapParams and org.onap.policy.controlloop.Params per policy pushed.
+        # Example output when running PDP-D with Docker:
+
+        policy@drools:/opt/app/policy/config$ echo $TELEMETRY_USER
+
+        demo@people.osaaf.org
+
+        policy@drools:/opt/app/policy/config$ echo $TELEMETRY_PASSWORD
+
+        demo123456!
+
+        policy@drools:/opt/app/policy/config$ curl --insecure --silent --user demo@people.osaaf.org:demo123456! -X GET https://localhost:9696/policy/pdp/engine/controllers | python -m json.tool
+        [
+            "frankfurt",
+            "usecases"
+        ]
+
+To check the facts currently in working memory, use the following command.
 
     .. code-block:: bash
 
-        curl --insecure --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/controllers/<controllerName>/drools/facts/<artifactId> | python -m json.tool
+        curl --insecure --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/controllers/<controllerName>/drools/facts | python -m json.tool
+
+        # Example output:
+
+        policy@drools:/opt/app/policy/config$ curl --insecure --silent --user demo@people.osaaf.org:demo123456! -X GET https://localhost:9696/policy/pdp/engine/controllers/frankfurt/drools/facts/ | python -m json.tool
+        {
+            "frankfurt": 0
+        }
+        policy@drools:/opt/app/policy/config$ curl --insecure --silent --user demo@people.osaaf.org:demo123456! -X GET https://localhost:9696/policy/pdp/engine/controllers/usecases/drools/facts/ | python -m json.tool
+        {
+            "usecases": 0
+        }
 
 To get additional information about the controller, use:
 
@@ -77,16 +147,193 @@ To get additional information about the controller, use:
 
         curl --insecure --silent --user <username>:<password> -X GET https://localhost:9696/policy/pdp/engine/controllers/<controllerName> | python -m json.tool
 
+        # Example output:
+
+        policy@drools:/opt/app/policy/config$ curl --insecure --silent --user demo@people.osaaf.org:demo123456! -X GET https://localhost:9696/policy/pdp/engine/controllers/frankfurt/ | python -m json.tool
+        {
+            "alive": true,
+            "name": "frankfurt",
+            "topicSinks": [
+                {
+                    "effectiveTopic": "APPC-CL",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": true,
+                    "topic": "APPC-CL",
+                    "recentEvents": [],
+                    "locked": false
+                },
+                {
+                    "effectiveTopic": "APPC-LCM-READ",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": true,
+                    "topic": "APPC-LCM-READ",
+                    "recentEvents": [],
+                    "locked": false
+                },
+                {
+                    "effectiveTopic": "POLICY-CL-MGT",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": true,
+                    "topic": "POLICY-CL-MGT",
+                    "recentEvents": [],
+                    "locked": false
+                },
+                {
+                    "effectiveTopic": "SDNR-CL",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": true,
+                    "topic": "SDNR-CL",
+                    "recentEvents": [],
+                    "locked": false
+                },
+                {
+                    "effectiveTopic": "DCAE_CL_RSP",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": true,
+                    "topic": "DCAE_CL_RSP",
+                    "recentEvents": [],
+                    "locked": false
+                }
+            ],
+            "drools": {
+                "sessions": [
+                    "frankfurt"
+                ],
+                "alive": true,
+                "brained": true,
+                "groupId": "org.onap.policy.drools-applications.controlloop.common",
+                "recentSourceEvents": [],
+                "version": "1.6.0",
+                "modelClassLoaderHash": -1185895883,
+                "baseDomainNames": [
+                    "onap.policies.controlloop.operational.common.Drools",
+                    "onap.policies.controlloop.Operational"
+                ],
+                "artifactId": "controller-frankfurt",
+                "recentSinkEvents": [],
+                "sessionCoordinates": [
+                    "org.onap.policy.drools-applications.controlloop.common:controller-frankfurt:1.6.0:frankfurt"
+                ],
+                "locked": false
+            },
+            "policyTypes": [
+                {
+                    "name": "onap.policies.controlloop.operational.common.Drools",
+                    "version": "1.0.0"
+                },
+                {
+                    "name": "onap.policies.controlloop.Operational",
+                    "version": "1.0.0"
+                }
+            ],
+            "locked": false,
+            "topicSources": [
+                {
+                    "effectiveTopic": "DCAE_TOPIC",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": false,
+                    "topic": "DCAE_TOPIC",
+                    "recentEvents": [],
+                    "locked": false
+                },
+                {
+                    "effectiveTopic": "APPC-CL",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": false,
+                    "topic": "APPC-CL",
+                    "recentEvents": [],
+                    "locked": false
+                },
+                {
+                    "effectiveTopic": "APPC-LCM-WRITE",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": false,
+                    "topic": "APPC-LCM-WRITE",
+                    "recentEvents": [],
+                    "locked": false
+                },
+                {
+                    "effectiveTopic": "SDNR-CL-RSP",
+                    "topicCommInfrastructure": "NOOP",
+                    "servers": [
+                        "NOOP"
+                    ],
+                    "alive": false,
+                    "topic": "SDNR-CL-RSP",
+                    "recentEvents": [],
+                    "locked": false
+                }
+            ]
+        }
+
+Within the telemetry subshell, it is easy to get information. Simply navigate to a specific directory using "cd". Use the "get" command to get information. This is a shorter alternatve to using the "curl" requests as shown above.
+
+To get information about the engine:
+
+    .. image:: img/docker/getEngine.png
+
+To list the names of the active controllers:
+
+    .. image:: img/docker/getControllers.png
+
+To get information about the specific "frankfurt" controller:
+
+    .. image:: img/docker/getFrankfurt.png
+
+To get information about the PDP-D environment:
+
+    .. image:: img/docker/getEnvironment.png
+
+To get a list of features that are currently enabled:
+
+    .. image:: img/docker/getFeatures.png
 
 Simulators
 ^^^^^^^^^^
 
-Currently, there are 4 supported simulators: A&AI, SO, vFC, and guard.  When they are up, they are accessed via localhost on the following ports: A&AI – 6666, SO – 6667, vFC – 6668, and guard – 6669.  They all respond with hard-coded values representing their various success messages except for with certain inputs.  For the A&AI simulator, if the value being queried with a “GET” query is “getFail” the simulator returns an exception message, if the value being queried in a “GET” query is “disableClosedLoop” the simulator returns a response with the value of “is-closed-loop-disabled” set to true, and if the value being queried in a named query is “error” the response from the simulator is A&AI’s failure message.  The other simulator that can return multiple response is the guard simulator, and that returns a deny response if the closed loop control name passed in is “denyGuard”
+Currently, there are 4 supported simulators: A&AI, SO, vFC, and guard.  When they are up, they are accessed via localhost on the following ports:
+
+1. A&AI - localhost:6666
+
+2. SO - localhost:6667
+
+3. vFC - localhost:6668
+
+4. guard - localhost:6669
+
+
+They all respond with hard-coded values representing their various success messages except for with certain inputs.  For the A&AI simulator, if the value being queried with a “GET” query is “getFail” the simulator returns an exception message, if the value being queried in a “GET” query is “disableClosedLoop” the simulator returns a response with the value of “is-closed-loop-disabled” set to true, and if the value being queried in a named query is “error” the response from the simulator is A&AI’s failure message.
+
+The other simulator that can return multiple responses is the guard simulator, and that returns a deny response if the closed loop control name passed in is “denyGuard”.
 
 Using the Simulators
 --------------------
 
-To check the status of the simulators, run the command: "*features status*".  If the feature controlloop-utils is enabled, the simulators are being used, otherwise, they are not.
+To check the status of the simulators, run the command: "*policy status*".  If the feature "controlloop-utils" is enabled, the simulators are being used, otherwise, they are not.
 
 **Turning on the simulators**
 
@@ -99,24 +346,25 @@ To check the status of the simulators, run the command: "*features status*".  If
 
     - First, make sure the controller is off by running the command “*policy stop*”.
     - Then turn the feature off with the command “*features disable controlloop-utils*”.
-    - Finally restart the controller by running “*policy start*”.  
+    - Finally restart the controller by running “*policy start*”.
     - Run “*features status*” again and the *feature controlloop-utils* will be **disabled**.
 
 **For Junits**
 
-    For Junits, the package *org.onap.policy.simulators* is neeeded.  In the Util class, there are four methods to start the four different simulators: *buildAaiSim()*, *buildSoSim()*, *buildVfcSim()*, and *buildGuardSim()*.  Once the method is called, the simulator should be up and waiting to respond to requests.  To bring down the simulators, call *HttpServletServer.factory.destroy()*.
+    For Junits, the package *org.onap.policy.simulators* is needed.  In the Util class, there are six methods to start the six different simulators: *buildAaiSim()*, *buildSoSim()*, *buildVfcSim()*, *buildGuardSim()*, *buildSdnc()*, and *buildDmaap()*.  Once the method is called, the simulator should be up and waiting to respond to requests.  To bring down the simulators, call *HttpServletServer.factory.destroy()*.
 
-Responses
----------
+Sample Responses
+^^^^^^^^^^^^^^^^
 
-**A&AI**
+A&AI
+--------
 
     .. code-block:: bash
        :caption: vnf-GET-response
 
         {
-         "vnf-id": vnfId, //vnfId will be the vnfId you query on.  If you query on a vnfName, the id will be "error" if the name is "error", "5e49ca06-2972-4532-9ed4-6d071588d792" otherwise
-         "vnf-name": vnfName, //vnfName will be the vnfName you query on.  If you query on a vnfId, the name will be "USUCP0PCOIL0110UJRT01"
+         "vnf-id": vnfId, // vnfId will be the vnfId you query on.  If you query on a vnfName, the id will be "error" if the name is "error", "5e49ca06-2972-4532-9ed4-6d071588d792" otherwise
+         "vnf-name": vnfName, // vnfName will be the vnfName you query on.  If you query on a vnfId, the name will be "USUCP0PCOIL0110UJRT01"
          "vnf-type": "RT",
          "service-id": "d7bb0a21-66f2-4e6d-87d9-9ef3ced63ae4",
          "equipment-role": "UCPE",
@@ -128,7 +376,7 @@ Responses
          "management-v6-address": "2001:1890:e00e:fffd::36",
          "in-maint": false,
          "prov-status":"ACTIVE",
-         "is-closed-loop-disabled": isDisabled, //isDisabled will be true if the vnf name/Id you query on is disableClosedLoop, false otherwise
+         "is-closed-loop-disabled": isDisabled, // isDisabled will be true if the vnf name/Id you query on is disableClosedLoop, false otherwise
          "resource-version": "1493389458092",
          "relationship-list": {
           "relationship": [{
@@ -174,7 +422,7 @@ Responses
     .. code-block:: bash
        :caption: vnf-GET-fail
 
-        //This is returned if you query on the value "getFail"
+        // This is returned if you query on the value "getFail"
         {
          "requestError": {
           "serviceException": {
@@ -230,7 +478,7 @@ Responses
     .. code-block:: bash
        :caption: vserver-GET-error
 
-        //This is returned if you query on the value "getFail"
+        // This is returned if you query on the value "getFail"
         {
          "requestError": {
           "serviceException": {
@@ -611,7 +859,8 @@ Responses
         }
 
 
-**SO**
+SO
+------
 
     .. code-block:: bash
        :caption: SO-response
@@ -633,7 +882,8 @@ Responses
 
 
 
-**vFC**
+vFC
+-------
 
     .. code-block:: bash
        :caption: vFC-POST-response
@@ -671,7 +921,8 @@ Responses
         }
 
 
-**GUARD**
+GUARD
+---------
 
     .. code-block:: bash
        :caption: permit-response
@@ -685,7 +936,7 @@ Responses
     .. code-block:: bash
        :caption: deny-response
 
-        //This is returned if the closed loop name is denyGuard
+        // This is returned if the closed loop name is denyGuard
         {
          "decision": "DENY",
          "details": "Decision Deny. You asked for it"