Merge "Add documentation for APPC Legacy actor"

10 files changed, 305 insertions, 2 deletions

diff --git a/docs/development/actors/aai/aai.rst b/docs/development/actors/aai/aai.rst
new file mode 100644
index 00000000..b8e0bdc6
--- /dev/null
+++ b/docs/development/actors/aai/aai.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+#################
+A&AI Actor
+#################
+
+.. contents::
+    :depth: 3
+
+Overview of A&AI Actor
+#############################
+
+This is a place-holder for the actor documentation.
diff --git a/docs/development/actors/actors.rst b/docs/development/actors/actors.rst
index 160f2ccf..77210883 100644
--- a/docs/development/actors/actors.rst
+++ b/docs/development/actors/actors.rst
@@ -9,4 +9,12 @@ Policy Platform Actor Development Guidelines
     :maxdepth: 1
 
     overview.rst
+    aai/aai.rst
+    appc-legacy/appc-legacy.rst
+    appclcm/appclcm.rst
     cds/cds.rst
+    guard/guard.rst
+    sdnc/sdnc.rst
+    sdnr/sdnr.rst
+    so/so.rst
+    vfc/vfc.rst
diff --git a/docs/development/actors/appc-legacy/appc-legacy.rst b/docs/development/actors/appc-legacy/appc-legacy.rst
new file mode 100644
index 00000000..1af71fe4
--- /dev/null
+++ b/docs/development/actors/appc-legacy/appc-legacy.rst
@@ -0,0 +1,190 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+#################
+APPC Legacy Actor
+#################
+
+.. contents::
+    :depth: 3
+
+Overview of APPC Legacy Actor
+#############################
+ONAP Policy Framework enables APPC Legacy as one of the supported actors.
+APPC Legacy uses a single DMaaP topic for both requests and responses.  As a result, the
+actor implementation must cope with the fact that requests may appear on the same
+stream from which it is reading responses, thus it must use the message content to
+distinguish responses from requests.  This particular implementation uses the *Status*
+field to identify responses.
+
+In addition, APPC 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.
+
+Each operation supported by the actor is associated with its own java class, which is
+responsible for populating the request structure appropriately.  The operation-specific
+classes are all derived from the *AppcOperation* class, which is, itself, 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.  Currently, only
+"ModifyConfig" is supported.
+
+Payload
+*******
+
+=============================== =========== ==================================================================
+   "Payload" field name            type                             Description
+=============================== =========== ==================================================================
+generic-vnf.vnf-id                string      The ID of the VNF selected from the A&AI Custom Query response
+                                              using the Target resource ID specified in the
+                                              *ControlLoopOperationParams*.
+=============================== =========== ==================================================================
+
+Additional fields are populated based on the *payload* specified within the
+*ControlLoopOperationParams*.  Each value found within the *payload* is treated as a
+JSON string and is decoded into a POJO, which is then inserted into the request payload
+using the same key.
+
+
+Examples
+########
+
+Suppose the *ControlLoopOperationParams* were populated as follows:
+
+.. code-block:: bash
+
+        {
+            "actor": "APPC",
+            "operation": "ModifyConfig",
+            "target": {
+                "resourceID": "2246ebc9-9b9f-42d0-a5e4-0248324fb884"
+            },
+            "payload": {
+                "my-key-A": "{\"input\":\"hello\"}",
+                "my-key-B": "{\"output\":\"world\"}"
+            },
+            "context": {
+                "cqdata": {
+                    "generic-vnf": [
+                        {
+                            "vnfId": "my-vnf",
+                            "vf-modules": [
+                                {
+                                    "model-invariant-id": "2246ebc9-9b9f-42d0-a5e4-0248324fb884"
+                                }
+                            ]
+                        }
+                    ]
+                }
+            }
+        }
+
+An example of a request constructed by the actor using the above parameters, published
+to the APPC topic:
+
+.. code-block:: bash
+
+        {
+          "CommonHeader": {
+            "TimeStamp": 1589400050910,
+            "APIver": "1.01",
+            "RequestID": "79e1d7d4-bac1-4399-8ee5-f84419c5723d",
+            "SubRequestID": "ee3f2dc0-a2e0-4ae8-98c3-478c784b8eb5",
+            "RequestTrack": [],
+            "Flags": []
+          },
+          "Action": "ModifyConfig",
+          "Payload": {
+            "my-key-B": {
+              "output": "world"
+            },
+            "my-key-A": {
+              "input": "hello"
+            },
+            "generic-vnf.vnf-id": "my-vnf"
+          }
+        }
+
+
+An example initial response received from APPC on the same topic:
+
+.. code-block:: bash
+
+        {
+          "CommonHeader": {
+            "TimeStamp": 1589400050923,
+            "APIver": "1.01",
+            "RequestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65",
+            "SubRequestID": "ee3f2dc0-a2e0-4ae8-98c3-478c784b8eb5",
+            "RequestTrack": [],
+            "Flags": []
+          },
+          "Status": {
+            "Code": 100,
+            "Value": "ACCEPTED"
+          }
+        }
+
+
+An example final response received from APPC on the same topic:
+
+.. code-block:: bash
+
+        {
+          "CommonHeader": {
+            "TimeStamp": 1589400050934,
+            "APIver": "1.01",
+            "RequestID": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65",
+            "SubRequestID": "ee3f2dc0-a2e0-4ae8-98c3-478c784b8eb5",
+            "RequestTrack": [],
+            "Flags": []
+          },
+          "Status": {
+            "Code": 400,
+            "Value": "SUCCESS"
+          }
+        }
+
+
+Configuration of the APPC Legacy Actor
+######################################
+
+The following table specifies the fields that should be provided to configure the APPC
+Legacy 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.
+timeoutSec                        integer (optional)      Maximum time, in seconds, to wait for a response to be received
+                                                          on the topic.
+=============================== ====================    ==================================================================
+
+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.
diff --git a/docs/development/actors/appclcm/appclcm.rst b/docs/development/actors/appclcm/appclcm.rst
new file mode 100644
index 00000000..55d3937f
--- /dev/null
+++ b/docs/development/actors/appclcm/appclcm.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+#################
+APPC LCM Actor
+#################
+
+.. contents::
+    :depth: 3
+
+Overview of APPC LCM Actor
+#############################
+
+This is a place-holder for the actor documentation.
diff --git a/docs/development/actors/guard/guard.rst b/docs/development/actors/guard/guard.rst
new file mode 100644
index 00000000..5a26c76d
--- /dev/null
+++ b/docs/development/actors/guard/guard.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+#################
+Guard Actor
+#################
+
+.. contents::
+    :depth: 3
+
+Overview of Guard Actor
+#############################
+
+This is a place-holder for the actor documentation.
diff --git a/docs/development/actors/overview.rst b/docs/development/actors/overview.rst
index 716f4f28..b9c24cec 100644
--- a/docs/development/actors/overview.rst
+++ b/docs/development/actors/overview.rst
@@ -122,7 +122,7 @@ XxxParams and XxxConfig
   XxxConfig objects are
   shared by all operations created by a single Operator.  As a result, it should not
   contain any data associated with an individual operation; such data should be stored
-  within the operation object, itself
+  within the Operation object, itself
 
 Junit tests
 ***********
@@ -177,7 +177,7 @@ Flow of operation
     "standard" payload
   - Subclasses may override *makeGuardPayload()* to add extra fields to the payload
     (e.g., some SO operations add the VF count)
-  - If any preprocessing step fails, then the "start" & "complete" callbacks will be
+  - If any preprocessing step fails, then the "start" and "complete" callbacks will be
     invoked to indicate a failure of the operation as a whole. Otherwise, the flow will
     continue on to *startOperationAsync()*, after the "start" callback is invoked
   - *StartOperationAsync()* will perform whatever needs to be done to start the operation
diff --git a/docs/development/actors/sdnc/sdnc.rst b/docs/development/actors/sdnc/sdnc.rst
new file mode 100644
index 00000000..67ecaaf0
--- /dev/null
+++ b/docs/development/actors/sdnc/sdnc.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+#################
+SDNC Actor
+#################
+
+.. contents::
+    :depth: 3
+
+Overview of SDNC Actor
+#############################
+
+This is a place-holder for the actor documentation.
diff --git a/docs/development/actors/sdnr/sdnr.rst b/docs/development/actors/sdnr/sdnr.rst
new file mode 100644
index 00000000..2b49d24a
--- /dev/null
+++ b/docs/development/actors/sdnr/sdnr.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+#################
+SDNR Actor
+#################
+
+.. contents::
+    :depth: 3
+
+Overview of SDNR Actor
+#############################
+
+This is a place-holder for the actor documentation.
diff --git a/docs/development/actors/so/so.rst b/docs/development/actors/so/so.rst
new file mode 100644
index 00000000..2062d585
--- /dev/null
+++ b/docs/development/actors/so/so.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+#################
+SO Actor
+#################
+
+.. contents::
+    :depth: 3
+
+Overview of SO Actor
+#############################
+
+This is a place-holder for the actor documentation.
diff --git a/docs/development/actors/vfc/vfc.rst b/docs/development/actors/vfc/vfc.rst
new file mode 100644
index 00000000..c99c9340
--- /dev/null
+++ b/docs/development/actors/vfc/vfc.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a
+.. Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+#################
+VFC Actor
+#################
+
+.. contents::
+    :depth: 3
+
+Overview of VFC Actor
+#############################
+
+This is a place-holder for the actor documentation.