Document new APPC LCM actor

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

1 files changed, 216 insertions, 4 deletions

diff --git a/docs/development/actors/appclcm/appclcm.rst b/docs/development/actors/appclcm/appclcm.rst
index 55d3937f..e9ea684f 100644
--- a/docs/development/actors/appclcm/appclcm.rst
+++ b/docs/development/actors/appclcm/appclcm.rst
@@ -2,14 +2,226 @@
 .. Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-#################
+.. _appclcm-label:
+
+##############
 APPC LCM Actor
-#################
+##############
 
 .. contents::
     :depth: 3
 
 Overview of APPC LCM Actor
-#############################
+##########################
+ONAP Policy Framework enables APPC as one of the supported actors.  The APPC LCM Actor
+contains operations supporting both the LCM interface and the legacy interface.
+As such, this actor supersedes the APPC Legacy actor.  Its sequence number is lower
+than the APPC Legacy actor's sequence number, which ensures that it is loaded
+first.
+
+APPC Legacy uses a single DMaaP topic for both requests and responses.  The class(es)
+supporting this interface are described in :ref:`appc-legacy-label`.  The APPC LCM
+Actor only supports the APPC Legacy operation, *ModifyConfig*.
+
+The APPC LCM interface, on the other hand, uses two DMaaP topics, one to which requests
+are published, and another from which responses are received.  Similar to the legacy
+interface, APPC LCM 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.  (APPC LCM also has a "correlation-id"
+field, which could potentially be used to match the response to the request, but
+apparently APPC LCM has not implemented that capability yet.)
+
+All APPC LCM operations are currently supported by a single java class,
+*AppcLcmOperation*, which is responsible for populating the request structure
+appropriately.  This class is derived from *BidirectionalTopicOperation*.
+
+
+**The remainder of this discussion describes the operations that are specific to APPC
+LCM.**
+
+
+Request
+#######
+
+CommonHeader
+************
+
+The "common-header" field in the request is built by policy.
+
+=============================== =========== ==================================================================
+   "common-header" field name       type                             Description
+=============================== =========== ==================================================================
+sub-request-id                    string      Generated by Policy. Is a UUID and used internally by policy
+                                              to match the response with the request.
+request-id                        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.
+originator-id                     string      Copy of the request-id.
+=============================== =========== ==================================================================
+
+
+Action
+******
+
+The "action" field uniquely identifies the operation to perform.  Currently, the
+following operations are supported:
+
+- Restart
+- Rebuild
+- Migrate
+- ConfigModify
+
+The valid operations are listed in *AppcLcmConstants*.  These are the values that must
+be specified in the policy.  However, before being stuffed into the "action" field,
+they are converted to camel case, stripping any hyphens, and translating the first
+character to upper case, if it isn't already.
+
+
+Action Identifiers
+******************
+
+Currently, the "action-identifiers" field contains only the VNF ID, which should be the
+*targetEntity* specified within the *ControlLoopOperationParams*.
+
+
+Payload
+*******
+
+The "payload" field is populated based on the *payload* specified within the
+*ControlLoopOperationParams*.  Unlike the APPC Legacy operations, which inject POJOs
+into the "payload" field, the APPC LCM operations simply encode the entire
+parameter *payload* into a JSON string, and then place the encoded string into the
+"payload" field of the request.
+
+
+Examples
+########
+
+Suppose the *ControlLoopOperationParams* were populated as follows:
+
+.. code-block:: bash
+
+        {
+            "actor": "APPC",
+            "operation": "Restart",
+            "targetEntity": "my-target",
+            "payload": {
+                "my-key-A": "hello",
+                "my-key-B": "world"
+            },
+            "context": {
+                "event": {
+                    "requestId": "664be3d2-6c12-4f4b-a3e7-c349acced200"
+                }
+            }
+        }
+
+An example of a request constructed by the actor using the above parameters, published
+to the APPC LCM request topic:
+
+.. code-block:: bash
+
+        {
+          "version": "2.0",
+          "rpc-name": "restart",
+          "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-8c4c1914-00ed-4be0-ae3b-49dd22e8f461",
+          "type": "request",
+          "body": {
+            "input": {
+              "common-header": {
+                "timestamp": "2020-05-14T19:19:32.619890900Z",
+                "api-ver": "2.00",
+                "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461",
+                "flags": {}
+              },
+              "action": "Restart",
+              "action-identifiers": {
+                "vnf-id": "my-target"
+              },
+              "payload": "{\"my-key-A\":\"hello\", \"my-key-B\":\"world\"}"
+            }
+          }
+        }
+
+
+An example initial response received from the APPC LCM response topic:
+
+.. code-block:: bash
+
+        {
+          "body": {
+            "output": {
+              "common-header": {
+                "timestamp": "2020-05-14T19:19:32.619897000Z",
+                "api-ver": "5.00",
+                "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461",
+                "flags": {}
+              },
+              "status": {
+                "code": 100,
+                "message": "Restart accepted"
+              }
+            }
+          },
+          "version": "2.0",
+          "rpc-name": "restart",
+          "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-1",
+          "type": "response"
+        }
+
+
+An example final response received from the APPC LCM on the same response topic:
+
+.. code-block:: bash
+
+        {
+          "body": {
+            "output": {
+              "common-header": {
+                "timestamp": "2020-05-14T19:19:32.619898000Z",
+                "api-ver": "5.00",
+                "originator-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                "request-id": "664be3d2-6c12-4f4b-a3e7-c349acced200",
+                "sub-request-id": "8c4c1914-00ed-4be0-ae3b-49dd22e8f461",
+                "flags": {}
+              },
+              "status": {
+                "code": 400,
+                "message": "Restart Successful"
+              }
+            }
+          },
+          "version": "2.0",
+          "rpc-name": "restart",
+          "correlation-id": "664be3d2-6c12-4f4b-a3e7-c349acced200-1",
+          "type": "response"
+        }
+
+
+Configuration of the APPC LCM Actor
+###################################
+
+The following table specifies the fields that should be provided to configure the APPC
+LCM 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.  That being said, the APPC Legacy operation(s) use a different topic than the
+APPC LCM operations.  As a result, the sink and source topics should be specified for
+each APPC Legacy operation supported by this actor.