Merge "Add documentation for SDNC actor"

1 files changed, 154 insertions, 4 deletions

diff --git a/docs/development/actors/sdnc/sdnc.rst b/docs/development/actors/sdnc/sdnc.rst
index 67ecaaf0..95998daf 100644
--- a/docs/development/actors/sdnc/sdnc.rst
+++ b/docs/development/actors/sdnc/sdnc.rst
@@ -2,14 +2,164 @@
 .. Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
 
-#################
+.. _sdnc-label:
+
+##########
 SDNC Actor
-#################
+##########
 
 .. contents::
     :depth: 3
 
 Overview of SDNC Actor
-#############################
+######################
+ONAP Policy Framework enables SDNC as one of the supported actors.
+SDNC uses a REST-based interface, and supports the following operations:
+*BandwidthOnDemand*, *Reroute*.
+
+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 *SdncOperation* class, which is, itself, derived from
+*HttpOperation*.  Each operation class implements its own *makeRequest()* method to
+construct a request appropriate to the operation.
+
+
+Request
+#######
+
+A number of nested structures are populated within the request.  The following table
+lists the contents of some of the fields that appear within these structures.
+
++----------------------------------+---------+----------------------------------------------------------------------+
+| Field Name                       |  Type   |                         Description                                  |
++----------------------------------+---------+----------------------------------------------------------------------+
++----------------------------------+---------+----------------------------------------------------------------------+
+| top level:                       |         |                                                                      |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *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.   |
++----------------------------------+---------+----------------------------------------------------------------------+
++----------------------------------+---------+----------------------------------------------------------------------+
+| sdnc-request-header:             |         |                                                                      |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *svc-action*                     | string  |   Set by Policy, based on the operation.                             |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *svc-request-id*                 | string  |   Generated by Policy. Is a UUID.                                    |
++----------------------------------+---------+----------------------------------------------------------------------+
++----------------------------------+---------+----------------------------------------------------------------------+
+| request-information:             |         |                                                                      |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *request-action*                 | string  |   Set by Policy, based on the operation.                             |
++----------------------------------+---------+----------------------------------------------------------------------+
++----------------------------------+---------+----------------------------------------------------------------------+
+| network-information:             |         |   Applicable to *Reroute*.                                           |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *network-id*                     | string  |   Set by Policy, using the                                           |
+|                                  |         |   "network-information.network-id" property                          |
+|                                  |         |   found within the enrichment data provided by DCAE                  |
+|                                  |         |   with the ONSET event.                                              |
++----------------------------------+---------+----------------------------------------------------------------------+
++----------------------------------+---------+----------------------------------------------------------------------+
+| vnf-information:                 |         |   Applicable to *BandwidthOnDemand*.                                 |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *vnf-id*                         | string  |   Set by Policy, using the                                           |
+|                                  |         |   "vnfId" property                                                   |
+|                                  |         |   found within the enrichment data provided by DCAE                  |
+|                                  |         |   with the ONSET event.                                              |
++----------------------------------+---------+----------------------------------------------------------------------+
++----------------------------------+---------+----------------------------------------------------------------------+
+| vf-module-input-parameters:      |         |   Applicable to *BandwidthOnDemand*.                                 |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *param[0]*                       | string  |   Set by Policy, using the                                           |
+|                                  |         |   "bandwidth" property                                               |
+|                                  |         |   found within the enrichment data provided by DCAE                  |
+|                                  |         |   with the ONSET event.                                              |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *param[1]*                       | string  |   Set by Policy, using the                                           |
+|                                  |         |   "bandwidth-change-time" property                                   |
+|                                  |         |   found within the enrichment data provided by DCAE                  |
+|                                  |         |   with the ONSET event.                                              |
++----------------------------------+---------+----------------------------------------------------------------------+
++----------------------------------+---------+----------------------------------------------------------------------+
+| vf-module-information:           |         |   Applicable to *BandwidthOnDemand*.                                 |
++----------------------------------+---------+----------------------------------------------------------------------+
+| *vf-module-id*                   | string  |   Set by Policy to "".                                               |
++----------------------------------+---------+----------------------------------------------------------------------+
+
+
+Examples
+########
+
+Suppose the *ControlLoopOperationParams* were populated as follows:
+
+.. code-block:: bash
+
+        {
+            "actor": "SDNC",
+            "operation": "Reroute",
+            "context": {
+                "enrichment": {
+                    "service-instance.service-instance-id": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65",
+                    "network-information.network-id": "2246ebc9-9b9f-42d0-a5e4-0248324fb884"
+                }
+            }
+        }
+
+An example of a request constructed by the actor using the above parameters, sent to the
+SDNC REST server:
+
+.. code-block:: bash
+
+        {
+            "input": {
+                "sdnc-request-header": {
+                    "svc-request-id": "2612653e-d946-423b-96d9-a8d5e8e39618",
+                    "svc-action": "reoptimize"
+                },
+                "request-information": {
+                    "request-action": "ReoptimizeSOTNInstance"
+                },
+                "service-information": {
+                    "service-instance-id": "c7c6a4aa-bb61-4a15-b831-ba1472dd4a65"
+                },
+                "network-information": {
+                    "network-id": "2246ebc9-9b9f-42d0-a5e4-0248324fb884"
+                }
+            }
+        }
+
+
+An example response received from the SDNC REST service:
+
+.. code-block:: bash
+
+        {
+          "output": {
+            "svc-request-id": "2612653e-d946-423b-96d9-a8d5e8e39618",
+            "response-code": "200",
+            "ack-final-indicator": "Y"
+          }
+        }
+
+
+Configuration of the SDNC Actor
+###############################
+
+The following table specifies the fields that should be provided to configure the SDNC
+actor.
+
+=============================== ====================    ==================================================================
+Field name                         type                             Description
+=============================== ====================    ==================================================================
+clientName                        string                  Name of the HTTP client to use to send the request to the
+                                                          SDNC REST server.
+timeoutSec                        integer (optional)      Maximum time, in seconds, to wait for a response to be received
+                                                          from the REST server.  Defaults to 90s.
+path                              string                  URI appended to the URL.  This field only applies to individual
+                                                          operations; it does not apply at the actor level.  Note: the
+                                                          *path* should not include a leading or trailing slash.
+=============================== ====================    ==================================================================
 
-This is a place-holder for the actor documentation.
+The individual operations are configured using these same field names.  However, all
+of them, except the *path*, are optional, as they inherit their values from the
+corresponding actor-level fields.