docs/development/actors/appclcm/appclcm.rst

.. This work is licensed under a
.. 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.
=============================== ====================    ==================================================================

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.