System Level Dialogues for CL docs.

- added a new page for system level dialogues
- fixed few missed hyperlinks on controlloops main page

Issue-ID: POLICY-3363
Change-Id: Iccc1a1493f594ed8f7d55da247d637567abff4ec
Signed-off-by: adheli.tavares <adheli.tavares@est.tech>

25 files changed, 249 insertions, 39 deletions

diff --git a/.gitignore b/.gitignore
index e7d23e9d..6bb994f1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,3 +14,4 @@ docs/conf.pyc
 docs/html/
 docs/_static/
 docs/__pycache__/
+.vscode/
diff --git a/docs/clamp/clamp.rst b/docs/clamp/clamp.rst
index 0b270d3e..7d9452e6 100644
--- a/docs/clamp/clamp.rst
+++ b/docs/clamp/clamp.rst
@@ -12,4 +12,5 @@ CLAMP handles control loops in two ways, either using built in ONAP Control Loop
 
    clamp/clamp
    controlloop/controlloop
+   controlloop/system-level-dialogues
 
diff --git a/docs/clamp/controlloop/controlloop.rst b/docs/clamp/controlloop/controlloop.rst
index db438e02..aa6bbedc 100644
--- a/docs/clamp/controlloop/controlloop.rst
+++ b/docs/clamp/controlloop/controlloop.rst
@@ -10,21 +10,23 @@ CLAMP Metadata Control Loop Automation Management using TOSCA
     :depth: 4
 
 The idea of using control loops to automatically (or autonomously) perform network management
-has been the subject of much research in the Network Management research community, see this
-paper for some background. However, it is only with the advent of ONAP that we have a platform
-that supports control loops for network management. Before ONAP, Control Loops have been
-implemented by hard-coding components together and hard coding logic into components. ONAP
-has taken a step forward towards automatic implementation of Control Loops by allowing
-parameterization of Control Loops that work on the premise that the Control Loops use a set
-of analytic, policy, and control components connected together in set ways.
+has been the subject of much research in the Network Management research community, see
+:download:`this paper <files/ControlLoops.pdf>` for some background. However, it is only with
+the advent of ONAP that we have a platform that supports control loops for network management.
+Before ONAP, Control Loops have been implemented by hard-coding components together and hard
+coding logic into components. ONAP has taken a step forward towards automatic implementation
+of Control Loops by allowing parameterization of Control Loops that work on the premise that
+the Control Loops use a set of analytic, policy, and control components connected together in
+set ways.
 
 The goal of the work is to extend and enhance the current ONAP Control Loop support to provide
 a complete open-source framework for Control Loops. This will enhance the current support to
 provide TOSCA based Control Loop definition and development, commissioning and run-time management.
 The participants that comprise a Control Loop and the metadata needed to link the participants
-together to create a Control Loop are specified in a standardized way using the OASIS TOSCA
-modelling language. The TOSCA description is then used to commission, instantiate, and manage
-the Control Loops in the run time system.
+together to create a Control Loop are specified in a standardized way using the `OASIS TOSCA
+modelling language <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/>`_. The TOSCA
+description is then used to commission, instantiate, and manage the Control Loops in the run
+time system.
 
 .. image:: images/01-controlloop-overview.png
 
@@ -92,6 +94,7 @@ concepts are defined at design time and are passed to the runtime in a TOSCA doc
 concepts in the Control Loop Runtime are created by the runtime part of the system using the
 definitions created at design time.
 
+.. _controlloop-capabilities:
 
 2 Capabilities
 ==============
@@ -217,7 +220,7 @@ At Run Time, the following Control Loop Life Cycle management capabilities are s
 
 .. note::
     The system dialogues for run time capabilities are described in detail on the
-    System Level Dialogues page.
+    :ref:`System Level Dialogues <system-level-label>` page.
 
 
 2.1 Control Loop Instance States
@@ -293,7 +296,8 @@ A Participant runs Control Loop Elements and manages and reports on their life c
 following the instructions it gets from the CLAMP runtime in messages delivered over DMaaP.
 
 In the figure above, five participants are shown. A Configuration Persistence Participant
-manages Control Loop Elements that interact with the ONAP Configuration Persistence Service
+manages Control Loop Elements that interact with the `ONAP Configuration Persistence Service
+<https://docs.onap.org/projects/onap-cps/en/latest/overview.html>`_
 to store common data. The DCAE Participant runs Control Loop Elements that manage DCAE
 microservices. The Kubernetes Participant hosts the Control Loop Elements that are managing
 the life cycle of microservices in control loops that are in a Kubernetes ecosystem. The
@@ -315,33 +319,34 @@ In order to keep management of versions of the configuration of control loop ins
 straightforward and easy to implement, the following version management scheme using
 semantic versioning is implemented. Each configuration of a Control Loop Instance and
 configuration of a Control Loop Element has a semantic version with 3 digits indicating
-the major.minor.patch number of the version.
+the **major.minor.patch** number of the version.
 
-Note that a configuration means a full set of parameter values for a Control Loop Instance.
+.. note::
+    A **configuration** means a full set of parameter values for a Control Loop Instance.
 
 .. image:: images/05-upgrade-states.png
 
 Change constraints:
 
-A Control Loop or Control Loop Element in state **RUNNING** can be changed to a higher patch
-level or rolled back to a lower patch level. This means that hot changes that do not
-impact the structure of a Control Loop or its elements can be executed.
+#. A Control Loop or Control Loop Element in state **RUNNING** can be changed to a higher patch
+   level or rolled back to a lower patch level. This means that hot changes that do not
+   impact the structure of a Control Loop or its elements can be executed.
 
-A Control Loop or Control Loop Element in state **PASSIVE** can be changed to a higher
-minor/patch level or rolled back to a lower minor/patch level. This means that structural
-changes to Control Loop Elements that do not impact the Control Loop as a whole can be
-executed by taking the control loop to state **PASSIVE**.
+#. A Control Loop or Control Loop Element in state **PASSIVE** can be changed to a higher
+   minor/patch level or rolled back to a lower minor/patch level. This means that structural
+   changes to Control Loop Elements that do not impact the Control Loop as a whole can be
+   executed by taking the control loop to state **PASSIVE**.
 
-A Control Loop or Control Loop Element in state **UNINITIALIZED** can be changed to a higher
-major/minor/patch level or rolled back to a lower major/minor/patch level. This means
-that where the structure of the entire control loop is changed, the control loop must
-be uninitialized and reinitialized.
+#. A Control Loop or Control Loop Element in state **UNINITIALIZED** can be changed to a higher
+   major/minor/patch level or rolled back to a lower major/minor/patch level. This means
+   that where the structure of the entire control loop is changed, the control loop must
+   be uninitialized and reinitialized.
 
-If a Control Loop Element has a minor version change, then its Control Loop Instance must
-have at least a minor version change.
+#. If a Control Loop Element has a **minor** version change, then its Control Loop Instance
+   must have at least a **minor** version change.
 
-If a Control Loop Element has a major version change, then its Control Loop Instance must
-have a major version change.
+#. If a Control Loop Element has a **major** version change, then its Control Loop Instance
+   must have a **major** version change.
 
 4.2 Scalability
 ---------------
@@ -389,15 +394,18 @@ of many types across themselves using a mechanism such as a Kubernetes cluster.
 
 At runtime, interaction between ONAP platform services and application microservices are
 relatively unconstrained, so interactions between Control Loop Elements for a given Control
-Loop Instance remain relatively unconstrained. A proposal to support access-controlled access
-to and between ONAP services will improve this. This can be complemented by intercepting and
-controlling services accesses between Control Loop Elements for Control Loop Instances for
-some/all Control Loop types.
-
-API gateways such as Kong have emerged as a useful technology for exposing and controlling
-service endpoint access for applications and services. When a Control Loop Type is onboarded,
-or when Control Loop Instances are created in the Participants, CLAMP can configure service
-endpoints between Control Loop Elements to redirect through an API Gateway.
+Loop Instance remain relatively unconstrained. A
+`proposal to support access-controlled accessto and between ONAP services
+<https://wiki.onap.org/pages/viewpage.action?pageId=103417456>`_
+will improve this. This can be complemented by intercepting and controlling services
+accesses between Control Loop Elements for Control Loop Instances for some/all Control
+Loop types.
+
+API gateways such as `Kong <https://konghq.com/kong/>`_ have emerged as a useful technology
+for exposing and controlling service endpoint access for applications and services. When a
+Control Loop Type is onboarded, or when Control Loop Instances are created in the Participants,
+CLAMP can configure service endpoints between Control Loop Elements to redirect through an
+API Gateway.
 
 Authentication and access-control rules can then be dynamically configured at the API gateway
 to support constrained access between Control Loop Elements and Control Loop Instances.
@@ -440,7 +448,7 @@ in isolated namespaces or in dedicated workers/clusters; etc..
 
 The APIs and Protocols used by CLAMP for Control Loops are described on the pages below:
 
-#. System Level Dialogues
+#. :ref:`System Level Dialogues <system-level-label>`
 #. Defining Control Loops in TOSCA for CLAMP
 #. REST APIs for CLAMP Control Loops
 #. The CLAMP Control Loop Participant Protocol
@@ -456,3 +464,5 @@ The design and implementation of TOSCA Control Loops in CLAMP is described for e
 #. The CLAMP GUI
 #. Building and running CLAMP
 #. Testing CLAMP
+
+End of Document
diff --git a/docs/clamp/controlloop/files/ControlLoops.pdf b/docs/clamp/controlloop/files/ControlLoops.pdf
new file mode 100644
index 00000000..c5b978db
--- /dev/null
+++ b/docs/clamp/controlloop/files/ControlLoops.pdf
diff --git a/docs/clamp/controlloop/images/system-dialogues/change-cl-instance-state-participants.png b/docs/clamp/controlloop/images/system-dialogues/change-cl-instance-state-participants.png
new file mode 100644
index 00000000..8892f07d
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/change-cl-instance-state-participants.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/comissioning-clamp-gui.png b/docs/clamp/controlloop/images/system-dialogues/comissioning-clamp-gui.png
new file mode 100644
index 00000000..473cf05b
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/comissioning-clamp-gui.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/comissioning-sdc.png b/docs/clamp/controlloop/images/system-dialogues/comissioning-sdc.png
new file mode 100644
index 00000000..19f3f84d
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/comissioning-sdc.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/common-properties-type-definition.png b/docs/clamp/controlloop/images/system-dialogues/common-properties-type-definition.png
new file mode 100644
index 00000000..06fa8967
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/common-properties-type-definition.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/create-cl-instance.png b/docs/clamp/controlloop/images/system-dialogues/create-cl-instance.png
new file mode 100644
index 00000000..88a67648
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/create-cl-instance.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/decommission-cl-type-definition.png b/docs/clamp/controlloop/images/system-dialogues/decommission-cl-type-definition.png
new file mode 100644
index 00000000..c4051eee
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/decommission-cl-type-definition.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/deinstantiate-cl-from-participants.png b/docs/clamp/controlloop/images/system-dialogues/deinstantiate-cl-from-participants.png
new file mode 100644
index 00000000..174250c0
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/deinstantiate-cl-from-participants.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/delete-cl-instance.png b/docs/clamp/controlloop/images/system-dialogues/delete-cl-instance.png
new file mode 100644
index 00000000..8417017f
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/delete-cl-instance.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/depriming-cl-type-definition.png b/docs/clamp/controlloop/images/system-dialogues/depriming-cl-type-definition.png
new file mode 100644
index 00000000..60d97805
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/depriming-cl-type-definition.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/monitoring-by-participants.png b/docs/clamp/controlloop/images/system-dialogues/monitoring-by-participants.png
new file mode 100644
index 00000000..69ceabf8
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/monitoring-by-participants.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/priming-cl-type-definition.png b/docs/clamp/controlloop/images/system-dialogues/priming-cl-type-definition.png
new file mode 100644
index 00000000..46f93480
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/priming-cl-type-definition.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/read-cl-instance.png b/docs/clamp/controlloop/images/system-dialogues/read-cl-instance.png
new file mode 100644
index 00000000..611039b9
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/read-cl-instance.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/read-commision-cl-type-definition.png b/docs/clamp/controlloop/images/system-dialogues/read-commision-cl-type-definition.png
new file mode 100644
index 00000000..3a308787
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/read-commision-cl-type-definition.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/statistics-housekeeping.png b/docs/clamp/controlloop/images/system-dialogues/statistics-housekeeping.png
new file mode 100644
index 00000000..6cbfda52
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/statistics-housekeeping.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/supervise-controlloops.png b/docs/clamp/controlloop/images/system-dialogues/supervise-controlloops.png
new file mode 100644
index 00000000..c24d3a09
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/supervise-controlloops.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/supervise-participants.png b/docs/clamp/controlloop/images/system-dialogues/supervise-participants.png
new file mode 100644
index 00000000..2439d926
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/supervise-participants.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/update-cl-instance-config-participants.png b/docs/clamp/controlloop/images/system-dialogues/update-cl-instance-config-participants.png
new file mode 100644
index 00000000..f16ebc2b
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/update-cl-instance-config-participants.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/update-instance-params-cl.png b/docs/clamp/controlloop/images/system-dialogues/update-instance-params-cl.png
new file mode 100644
index 00000000..ec84ed35
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/update-instance-params-cl.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/view-monitoring-info.png b/docs/clamp/controlloop/images/system-dialogues/view-monitoring-info.png
new file mode 100644
index 00000000..5937d2f1
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/view-monitoring-info.png
diff --git a/docs/clamp/controlloop/images/system-dialogues/view-statistics.png b/docs/clamp/controlloop/images/system-dialogues/view-statistics.png
new file mode 100644
index 00000000..451a5d92
--- /dev/null
+++ b/docs/clamp/controlloop/images/system-dialogues/view-statistics.png
diff --git a/docs/clamp/controlloop/system-level-dialogues.rst b/docs/clamp/controlloop/system-level-dialogues.rst
new file mode 100644
index 00000000..4392e1e8
--- /dev/null
+++ b/docs/clamp/controlloop/system-level-dialogues.rst
@@ -0,0 +1,198 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+.. _system-level-label:
+
+System Level Dialogues
+######################
+
+
+.. contents::
+    :depth: 4
+
+
+The CLAMP Control Loop Runtime Lifecycle Management uses the following system level dialogues.
+These dialogues enable the CLAMP runtime capabilities described in :ref:`Section 2 of
+TOSCA Defined Control Loops: Architecture and Design <controlloop-capabilities>`.
+Design Time dialogues will be described in future releases of the system.
+
+
+1 Commissioning Dialogues
+=========================
+
+Commissioning dialogues are used to commission and decommission Control Loop Type definitions
+and to set the values of Common Parameters.
+
+Commissioning a Control Loop Type is a three-step process:
+
+#. The Control Loop Type must be created, that is the Control Loop Type definition must be
+   loaded and stored in the database. This step may be carried out over the REST interface or
+   using SDC distribution.
+
+#. The Common Properties of the Control Loop type must be assigned values and those values
+   must be stored in the database. This step is optional only if all mandatory common properties
+   have default values. The Common Property values may be set and amended over and over again
+   in multiple sessions until the Control Loop Type is primed.
+
+#. The Control Loop Type Definition and the Common Property values must be primed, that is
+   sent to the concerned participants. Once a Control Loop Type is primed, its Common Property
+   values can no longer be changed. To change Common Properties on a primed Control Loop Type,
+   all instances of the Control Loop Type must be removed and the Control Loop Type must be
+   de-primed.
+
+1.1 Commissioning a Control Loop Type Definition using the CLAMP GUI
+--------------------------------------------------------------------
+
+This dialogue corresponds to a "File → Import" menu on the CLAMP GUI. The documentation of
+future releases of the system will describe how the Design Time functionality interacts
+with the Runtime commissioning API.
+
+.. image:: images/system-dialogues/comissioning-clamp-gui.png
+
+1.2 Commissioning a Control Loop Type Definition using SDC
+----------------------------------------------------------
+
+.. image:: images/system-dialogues/comissioning-sdc.png
+
+1.3 Setting Common Properties for a Control Loop Type Definition
+----------------------------------------------------------------
+
+This dialogue sets the values of common properties. The values of the common properties
+may be set, updated, or deleted at will, as this dialogue saves the properties to the
+database but does not send the definitions or properties to the participants. However,
+once a Control Loop Type Definition and its properties are primed (See :ref:`Section 1.4
+<_priming-cl-label>`), the properties cannot be changed until the control loop type
+definition is de-primed (See :ref:`Section 1.5 <depriming-cl-label>`).
+
+.. image:: images/system-dialogues/common-properties-type-definition.png
+
+.. _priming-cl-label:
+
+1.4 Priming a Control Loop Type Definition on Participants
+----------------------------------------------------------
+The Priming operation sends Control Loop Type definitions and common property values
+to participants. Once a Control Loop Type definition is primed, its property values
+can on longer be changed until it is de-primed.
+
+.. image:: images/system-dialogues/priming-cl-type-definition.png
+
+.. _depriming-cl-label:
+
+1.5 De-Prime a Control Loop Type Definition on Participants
+-----------------------------------------------------------
+
+This dialogue allows a Control Loop Type Definition to be de-primed so that it can be
+deleted or its common parameter values can be altered.
+
+.. image:: images/system-dialogues/depriming-cl-type-definition.png
+
+1.6 Decommissioning a Control Loop Type Definition in CLAMP
+-----------------------------------------------------------
+
+.. image:: images/system-dialogues/decommission-cl-type-definition.png
+
+1.7 Reading Commissioned Control Loop Type Definitions
+------------------------------------------------------
+
+.. image:: images/system-dialogues/read-commision-cl-type-definition.png
+
+
+2. Instantiation Dialogues
+==========================
+
+Instantiation dialogues are used to create, set parameters on, instantiate, update,
+and remove Control Loop instances.
+
+Assume a suitable Control Loop Definition exists in the Commissioned Control Loop Inventory.
+To get a Control Loop instance running one would, for example, execute dialogues
+:ref:`2.1 <creating-cl-instance>`, :ref:`2.3 <updating-cl-instance-config>`, and
+:ref:`2.4 <changing-cl-instance-state>`.
+
+.. _creating-cl-instance:
+
+2.1 Creating a Control Loop Instance
+------------------------------------
+
+.. image:: images/system-dialogues/create-cl-instance.png
+
+.. note::
+    This dialogue creates the Control Loop Instance in the Instantiated Control Loop Inventory.
+    The instance is sent to the participants using the process described in the dialogue in
+    :ref:`Section 2.3 <updating-cl-instance-config>`.
+
+2.2 Updating Instance Specific Parameters on a Control Loop Instance
+--------------------------------------------------------------------
+
+.. image:: images/system-dialogues/update-instance-params-cl.png
+
+.. _updating-cl-instance-config:
+
+2.3 Updating a Control Loop Instance with a Configuration on Participants
+-------------------------------------------------------------------------
+
+.. image:: images/system-dialogues/update-cl-instance-config-participants.png
+
+.. _changing-cl-instance-state:
+
+2.4 Changing the state of a Control Loop Instance on Participants
+-----------------------------------------------------------------
+
+.. image:: images/system-dialogues/change-cl-instance-state-participants.png
+
+2.5 De-instantiating a Control Loop Instance from Participants
+--------------------------------------------------------------
+
+.. image:: images/system-dialogues/deinstantiate-cl-from-participants.png
+
+2.6 Deleting a Control Loop Instance
+------------------------------------
+
+.. image:: images/system-dialogues/delete-cl-instance.png
+
+2.7 Reading Control Loop Instances
+----------------------------------
+
+.. image:: images/system-dialogues/read-cl-instance.png
+
+
+1. Monitoring Dialogues
+=======================
+
+Monitoring dialogues are used to monitor and to read statistics on Control Loop Instances.
+
+3.1 Reporting of Monitoring Information and Statistics by Participants
+----------------------------------------------------------------------
+
+.. image:: images/system-dialogues/monitoring-by-participants.png
+
+3.2 Viewing of Monitoring Information
+-------------------------------------
+
+.. image:: images/system-dialogues/view-monitoring-info.png
+
+3.2 Viewing of Statistics
+-------------------------
+
+.. image:: images/system-dialogues/view-statistics.png
+
+3.3 Statistics Housekeeping
+---------------------------
+
+.. image:: images/system-dialogues/statistics-housekeeping.png
+
+
+4. Supervision Dialogues
+========================
+
+Supervision dialogues are used to check the state of Control Loop Instances and Participants.
+
+4.1 Supervise Participants
+--------------------------
+
+.. image:: images/system-dialogues/supervise-participants.png
+
+4.2 Supervise Control Loops
+---------------------------
+
+.. image:: images/system-dialogues/supervise-controlloops.png
+
+End of Document