Document new SDNR Actor

Issue-ID: POLICY-2515
Signed-off-by: Jim Hahn <jrh3@att.com>
Change-Id: I9b1cc6024d44469d10a8a732da0ab11aff2f546a

1 files changed, 182 insertions, 4 deletions

diff --git a/docs/development/actors/sdnr/sdnr.rst b/docs/development/actors/sdnr/sdnr.rst
index 2b49d24a..13d91940 100644
--- a/docs/development/actors/sdnr/sdnr.rst
+++ b/docs/development/actors/sdnr/sdnr.rst
@@ -2,14 +2,192 @@
 .. Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-#################
+.. _sdnr-label:
+
+##########
 SDNR Actor
-#################
+##########
 
 .. contents::
     :depth: 3
 
 Overview of SDNR Actor
-#############################
+######################
+ONAP Policy Framework enables SDNR as one of the supported actors.  SDNR uses two
+DMaaP topics, one to which requests are published, and another from which responses
+are received.  SDNR may generate more than one response for a particular request,
+the first response simply indicating that the request was accepted, while the second
+response indicates completion of the request.  For each request, a unique sub-request
+ID is generated.  This is used to match the received responses with the published
+requests.
+
+When an SDNR request completes, whether successfully or unsuccessfully, the actor
+populates the *controlLoopResponse* within the *OperationOutcome*.  The application
+will typically publish this to a notification topic so that downstream systems can
+take appropriate action.
+
+All SDNR operations are currently supported by a single java class,
+*SdnrOperation*, which is responsible for populating the request structure
+appropriately.  This class is derived from *BidirectionalTopicOperation*.
+
+
+Request
+#######
+
+CommonHeader
+************
+
+The "CommonHeader" field in the request is built by policy.
+
+=============================== =========== ==================================================================
+   "CommonHeader" field name       type                             Description
+=============================== =========== ==================================================================
+SubRequestID                      string      Generated by Policy. Is a UUID and used internally by policy
+                                              to match the response with the request.
+RequestID                         string      Inserted by Policy. Maps to the UUID sent by DCAE i.e. the ID
+                                              used throughout the closed loop lifecycle to identify a request.
+=============================== =========== ==================================================================
+
+
+Action
+******
+
+The "action" field uniquely identifies the operation to perform.  Operation names are
+not validated.  Instead, they are passed to SDNR, untouched.
+
+
+RPC Name
+********
+
+The "rpc-name" field is the same as the "action" field, with everything mapped to lower
+case.
+
+
+Payload
+*******
+
+The "payload" field is populated with the *payload* text that is provided within the
+ONSET event; no additional transformation is applied.
+
+
+Examples
+########
+
+Suppose the *ControlLoopOperationParams* were populated as follows:
+
+.. code-block:: bash
+
+        {
+            "actor": "SDNR",
+            "operation": "ModifyConfig",
+            "context": {
+                "event": {
+                    "requestId": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                    "payload": "some text"
+                }
+            }
+        }
+
+An example of a request constructed by the actor using the above parameters, published
+to the SDNR request topic:
+
+.. code-block:: bash
+
+        {
+          "body": {
+            "input": {
+              "CommonHeader": {
+                "TimeStamp": "2020-05-18T14:43:58.550499700Z",
+                "APIVer": "1.0",
+                "RequestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                "SubRequestID": "848bfd15-b189-43a1-bdea-80982b41fa24",
+                "RequestTrack": {},
+                "Flags": {}
+              },
+              "Action": "ModifyConfig",
+              "Payload": "some text"
+            }
+          },
+          "version": "1.0",
+          "rpc-name": "modifyconfig",
+          "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-848bfd15-b189-43a1-bdea-80982b41fa24",
+          "type": "request"
+        }
+
+
+An example initial response received from the SDNR response topic:
+
+.. code-block:: bash
+
+        {
+            "body": {
+                "output": {
+                    "CommonHeader": {
+                        "TimeStamp": "2020-05-18T14:44:10.000Z",
+                        "APIver": "1.0",
+                        "RequestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                        "SubRequestID": "848bfd15-b189-43a1-bdea-80982b41fa24",
+                        "RequestTrack": [],
+                        "Flags": []
+                    },
+                    "Status": {
+                        "Code": 100,
+                        "Value": "ACCEPTED"
+                    }
+                }
+            },
+            "version": "1.0",
+            "rpc-name": "modifyconfig",
+            "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-848bfd15-b189-43a1-bdea-80982b41fa24",
+            "type": "response"
+        }
+
+
+An example final response received from the SDNR on the same response topic:
+
+.. code-block:: bash
+
+        {
+            "body": {
+                "output": {
+                    "CommonHeader": {
+                        "TimeStamp": "2020-05-18T14:44:20.000Z",
+                        "APIver": "1.0",
+                        "RequestID": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                        "SubRequestID": "848bfd15-b189-43a1-bdea-80982b41fa24",
+                        "RequestTrack": [],
+                        "Flags": []
+                    },
+                    "Status": {
+                        "Code": 200,
+                        "Value": "SUCCESS"
+                    },
+                    "Payload": "{ \"Configurations\":[ { \"Status\": { \"Code\": 200, \"Value\": \"SUCCESS\" }, \"data\":{\"FAPService\":{\"alias\":\"Chn0330\",\"X0005b9Lte\":{\"phyCellIdInUse\":6,\"pnfName\":\"ncserver23\"},\"CellConfig\":{\"LTE\":{\"RAN\":{\"Common\":{\"CellIdentity\":\"Chn0330\"}}}}}} } ] }"
+                }
+            },
+            "version": "1.0",
+            "rpc-name": "modifyconfig",
+            "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-848bfd15-b189-43a1-bdea-80982b41fa24",
+            "type": "response"
+        }
+
+
+Configuration of the SDNR Actor
+###############################
+
+The following table specifies the fields that should be provided to configure the SNDR
+actor.
+
+=============================== ====================    ==================================================================
+Field name                         type                             Description
+=============================== ====================    ==================================================================
+sinkTopic                         string                  Name of the topic to which the request should be published.
+sourceTopic                       string                  Name of the topic from which the response should be read.
+                                                          This must not be the same as the *sinkTopic*.
+timeoutSec                        integer (optional)      Maximum time, in seconds, to wait for a response to be received
+                                                          on the topic.
+=============================== ====================    ==================================================================
 
-This is a place-holder for the actor documentation.
+The individual operations are configured using these same field names.  However, all
+of them are optional, as they inherit their values from the corresponding actor-level
+fields.