Merge "Add documentation for APPC Legacy actor"

1 files changed, 190 insertions, 0 deletions

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.