.. 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.
Code Review / policy / parent.git / commitdiff