Docs updates for Guilin Maintenance

Change-Id: If0000cc4be08d5f5a96ba0485dcd088a45dbd6bd
Issue-ID: CCSDK-3085
Issue-ID: CCSDK-3109
Signed-off-by: elinuxhenrik <henrik.b.andersson@est.tech>
Signed-off-by: JohnKeeney <john.keeney@est.tech>

9 files changed, 145 insertions, 100 deletions

diff --git a/docs/architecture/architecture.rst b/docs/architecture/architecture.rst
index bfe827bd..6447facc 100644
--- a/docs/architecture/architecture.rst
+++ b/docs/architecture/architecture.rst
@@ -1,5 +1,5 @@
 .. SPDX-License-Identifier: CC-BY-4.0
-.. Copyright 2020 Nordix Foundation
+.. Copyright 2021 Nordix Foundation
 .. _architecture:
 
 
@@ -11,14 +11,16 @@ Introduction
 ************
 
 
-The CCSDK ORAN components provides handling of the O-RAN A1 interface.
+The CCSDK ORAN components add support for handling "A1 Policies" as defined for the O-RAN A1 interface.
+
+The O-RAN A1 interface is defined by the `O-RAN Alliance <https://www.o-ran.org>`_
 
 
 *********************************************
-Global NBI architecture for Frankfurt release
+Architecture for ONAP Guilin release
 *********************************************
 
-Following illustration provides a global view about Non-Real-Time-RIC architecture,
+This picture provides a overview of ONAP's A1 Controller architecture,
 integration with other ONAP components and API resource/operation provided.
 
 .. image:: ../media/ONAP-A1ControllerArchitecture.png
@@ -29,5 +31,5 @@ integration with other ONAP components and API resource/operation provided.
 Developer Guide
 ***************
 
-Technical information about the ORAN components (dependencies, configuration, running & testing) could be found in :ref:`developer_guide`.
+Technical information about the O-RAN components (dependencies, configuration, running & testing) can be found in :ref:`developer_guide`.
 
diff --git a/docs/consumedapis/consumedapis.rst b/docs/consumedapis/consumedapis.rst
index 8357e43d..48d3af2b 100644
--- a/docs/consumedapis/consumedapis.rst
+++ b/docs/consumedapis/consumedapis.rst
@@ -1,5 +1,5 @@
 .. SPDX-License-Identifier: CC-BY-4.0
-.. Copyright 2020 Nordix Foundation
+.. Copyright 2021 Nordix Foundation
 
 Consumed APIs
 =============
@@ -11,26 +11,22 @@ Policy Management Service application is interacting with two ONAP APIs and the
 CBS API
 *******
 
-The CBS API is used to get the dynamic configuration of the service, such as available Near-RT RICs.
-
-::
-
-    CBS_GET_ALL
+If *Consul* is used for configuring the A1 Policy Management Service the `ONAP DCAE Config Binding Service <https://docs.onap.org/projects/onap-dcaegen2/en/guilin/sections/apis/configbinding.html>`_ is used. 
 
 *********
 DMAAP API
 *********
 
-The DMaaP API is used to provide the possibility to interact with the Policy Management Service through DMaaP Message
-Router.
+The A1 Policy Management Service API can also be accessed using *ONAP DMaaP*. To support this the `DMaaP Message Router API <https://docs.onap.org/projects/onap-dmaap-messagerouter-messageservice/en/guilin/offeredapis/api.html>`_ is used.  
 
-::
+*****************************************
+O-RAN A1 interface for A1 Policies (A1-P)
+*****************************************
 
-    DMAAP_GET_EVENTS
+Southbound, the ONAP A1 Policy functions communicate with *near-RT-RIC* RAN functions using the **A1** interface, as defined by the `O-RAN Alliance <https://www.o-ran.org>`_   
+The *A1 Interface - Application Protocol Specification (A1-AP)* describe this interface. The specification can be viewed from the `O-RAN Alliance <https://www.o-ran.org>`_ website. 
 
-********
-A1-P API
-********
+The **Guilin** ONAP A1 Policy functions implement the *A1 Policy* parts (*A1-P*) of A1-AP versions *v1.1* and *v2.0*
+    
+An opensource implementation of a `near-RT-RIC <https://wiki.o-ran-sc.org/pages/viewpage.action?pageId=1179659>`_ is available from `O-RAN Software Community <https://o-ran-sc.org>`_. It supports a pre-spec version of the A1-AP. The ONAP A1 Policy functions described here also supports this A1 version (A1-OSC). 
 
-The A1-P API is used to communicate with the Near-RT RICs (north bound). All endpoints of the OSC A1 REST API and the
-standard A1 REST API version 1.1 are used.
diff --git a/docs/guide/developer-guide.rst b/docs/guide/developer-guide.rst
index f067a3fa..f2c8b25e 100644
--- a/docs/guide/developer-guide.rst
+++ b/docs/guide/developer-guide.rst
@@ -1,27 +1,27 @@
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2020 Nordix Foundation.
+.. Copyright (C) 2021 Nordix Foundation.
 
 .. _developer_guide:
 
 Developer Guide
 ===============
 
-This document provides a quickstart for developers of the CCSDK ORAN parts.
+This document provides a quickstart for developers of the CCSDK functions for O-RAN A1 Policies.
 
 Source tree
 +++++++++++
 
-This application provides CCSDK Policy Management Service and A1 Adapter as main functional resources.
+This provides CCSDK with "A1 Policy Management Service" and "A1 Adapter" functions.
 Each resource is implemented independently in a package corresponding to its name.
 
 A1 Policy Management Service
 ++++++++++++++++++++++++++++
 
-The CCSDK Policy Management Service (PMS) is a Java 11 web application built over Spring Framework.
+The ONAP CCSDK A1 Policy Management Service is a Java 11 web application built using the Spring Framework.
 Using Spring Boot dependencies, it runs as a standalone application.
 
-PMS provides a REST API for management of policices. It provides support for:
+A1 Policy Management Service provides a REST API for management of policies. It provides support for:
 
  * Supervision of clients (R-APPs) to eliminate stray policies in case of failure
  * Consistency monitoring of the SMO view of policies and the actual situation in the RICs
@@ -32,7 +32,7 @@ PMS provides a REST API for management of policices. It provides support for:
    * Query functions that can find all policies in a RIC, all policies owned by a service (R-APP), all policies of a type etc.
    * Maps O1 resources (ManagedElement) as defined in O1 to the controlling RIC.
 
-The Policy Management Service can be accessed over the REST API. See :ref:`pms_api` for how to use the API.
+The Policy Management Service can be accessed over the REST API, and with an equivalent interface using DMaaP. See :ref:`pms_api` for more information about the API.
 
 Dependencies
 ------------
@@ -53,10 +53,63 @@ dependency management tool (see *pom.xml* file at root level) :
 Configuration
 -------------
 
-There are two configuration files for PMS, *config/application_configuration.json* and *config/application.yaml*.
+There are two configuration files for A1 Policy Management Service, *config/application_configuration.json* and *config/application.yaml*
 The first one contains configuration of data needed by the application, such as which Near-RT RICs
 that are available. The second contains logging and security configurations.
 
+For more information about these configuration files can be found as comments in the sample files provided with the source code, or on the `ONAP wiki <https://wiki.onap.org/display/DW/O-RAN+A1+Policies+in+ONAP+Guilin>`_
+
+Static configuration (application.yaml)
+---------------------------------------
+
+The file *./config/application.yaml* is read by the application at startup. It provides the following configurable features:
+
+ * server; configuration for the WEB server
+
+   * used port for HTTP/HTTPS, this is however not the port numbers visible outside the container
+   * SSL parameters for setting up using of key store and trust store databases.
+ * webclient; configuration parameters for a web client used by the component
+
+   * SSL parameters for setting up using of key store and trust store databases.
+   * Usage of HTTP Proxy; if configured, the proxy will be used for accessing the NearRT-RICs
+
+ * logging; setting of of which information that is logged.
+ * filepath; the local path to a file used for dynamic configuration (if used). See next chapter.
+
+For details about the parameters in this file, see documentation in the file.
+
+Dynamic configuration
+---------------------
+
+The component has configuration that can be updated in runtime. This configuration can either be loaded from a file (accessible from the container) or from a CBS/Consul database (Cloudify). The configuration is re-read and refreshed at regular intervals.
+
+The configuration includes:
+
+ * Controller configuration, which includes information on how to access the a1-adapter
+ * One entry for each NearRT-RIC, which includes:
+
+   * The base URL of the NearRT RIC
+   * A list of O1 identifiers that the NearRT RIC is controlling. An application can query this service which NearRT RIC should be addressed for controlling (for instance) a given Cell.
+   * An optional reference to the controller to use, or excluded if the NearRT-RIC can be accessed directly from this component.
+
+ * Optional configuration for using of DMAAP. There can be one stream for requests to the component and an other stream for responses.
+
+For details about the syntax of the file, there is an example in source code repository */config/application_configuration.json*. This file is also included in the docker container */opt/app/policy-agent/data/application_configuration.json_example*.
+
+Using CBS/Consul database for dynamic configuration
+---------------------------------------------------
+
+The access of CBS is setup by means of environment variables. There is currently no support for setting these at on boarding.
+
+The following variables are required by the CBS:
+
+ * CONSUL_HOST
+ * CONSUL_PORT
+ * CONFIG_BINDING_SERVICE
+ * SERVICE_NAME
+
+
+
 Configuration of certs
 ----------------------
 
@@ -90,6 +143,6 @@ Example docker run command for mounting new files (assuming they are located in
 A1 Adapter (Internal)
 +++++++++++++++++++++
 
-The O-RAN A1 Adapter provides an internal REST CONF API for management of A1 policices, useful for test and verification.
+The O-RAN A1 Adapter provides an **internal** RESTCONF API that is used by the A1 Policy Management System when accessing the A1 Interface. This API is useful for test and verification but should not used otherwise.
 
-The A1 Adapter can be accessed over the REST CONF API. See :ref:`a1_adapter_api` for how to use the API.
+See :ref:`a1_adapter_api` for details of this internal API.
diff --git a/docs/humaninterfaces/humaninterfaces.rst b/docs/humaninterfaces/humaninterfaces.rst
index ab7d421f..f050f44f 100644
--- a/docs/humaninterfaces/humaninterfaces.rst
+++ b/docs/humaninterfaces/humaninterfaces.rst
@@ -6,6 +6,6 @@ Human Interfaces
 ================
 
 The NON-RT RIC Control Panel in O-RAN-SC can be used to interact with the Policy Management Service.
-See `NON-RT RIC Control Panel repo <https://gerrit.o-ran-sc.org/r/admin/repos/portal/nonrtric-controlpanel>`_.
+See `NON-RT RIC Control Panel repo <https://gerrit.o-ran-sc.org/r/admin/repos/portal/nonrtric-controlpanel>`_ from the `O-RAN-SC NONRTRIC Project <https://wiki.o-ran-sc.org/display/RICNR>`_. 
 
-Any "Rest Client" application may be used (Postman, ...) to interact with the Policy Management Service application.
+Any "Rest Client" application may be used (Postman, ...) to interact with the Policy Management Service application via the :ref:`A1 Policy Management Service API<offered_apis>`_
diff --git a/docs/media/ONAP-A1ControllerArchitecture.png b/docs/media/ONAP-A1ControllerArchitecture.png
index 59516628..1285e2d8 100644
--- a/docs/media/ONAP-A1ControllerArchitecture.png
+++ b/docs/media/ONAP-A1ControllerArchitecture.png
diff --git a/docs/offeredapis/offeredapis.rst b/docs/offeredapis/offeredapis.rst
index b6b2cd66..99f59e9b 100644
--- a/docs/offeredapis/offeredapis.rst
+++ b/docs/offeredapis/offeredapis.rst
@@ -1,7 +1,7 @@
 .. This work is licensed under a Creative Commons Attribution 4.0
    International License.
 .. http://creativecommons.org/licenses/by/4.0
-.. Copyright 2020 Nordix Foundation
+.. Copyright 2021 Nordix Foundation
 
 .. _offered_apis:
 
@@ -10,54 +10,22 @@ Offered APIs
 ============
 
 Introduction
-************
+------------
 
-The north bound REST API of the Policy Management Service provides convenient methods to handle policies.
+The north bound REST API of the A1 Policy Management Service provides convenient methods to handle policies.
 
 
-Global ORAN architecture
-************************
+Overall architecture for O-RAN A1 Policy functions
+--------------------------------------------------
 
-Following illustration provides a global view about **ORAN** architecture,
+This picture provides a overview of ONAP's A1 Controller architecture,
 integration with other ONAP components and API resource/operation provided.
 
 .. image:: ../media/ONAP-A1ControllerArchitecture.png
    :width: 500pt
 
-
-API Version
-***********
-
-APIs are described with a  state version with "v" following the API Name,
-e.g.:  ``v2/policy``.
-The schema associated with a REST API must have its version number aligned
-with that of the REST API.
-
-The version number has major, minor and revision numbers. E.g. v1.0.0
-The version number (without the revision number) is held in the URI.
-
-The major version number is incremented for an incompatible change.
-The minor version number is incremented for a compatible change.
-For minor modifications of the API, version numbering must not be updated,
-provided the following  backward compatibility rules are respected:
-
-- New elements in a data type must be optional (``minOccurs=0``)
-- Changes in the cardinality of an attribute in a data type must be from
-  mandatory to optional or from lower to greater
-- New attributes defined in an element must be optional (absence of
-  ``use="required"``).
-- If new enumerated values are included, the former ones and its meaning must
-  be kept.
-- If new operations are added, the existing operations must be kept
-- New parameters added to existing operations must be optional and existing
-  parameters must be kept
-
-For major modifications of the API, not backward compatible and forcing client
-implementations to be changed, the version number must be updated.
-
-
 API Table
-*********
+---------
 
 .. |swagger-icon| image:: ../media/swagger.png
                   :width: 40px
@@ -70,19 +38,23 @@ API Table
    :header: "API name", "|swagger-icon|", "|yaml-icon|"
    :widths: 10,5, 5
 
-   "PMS API", ":download:`link <./swagger/pms-api.json>`", ":download:`link <./swagger/pms-api.yaml>`"
+   "A1 Policy Management Service API (NBI)", ":download:`link <./swagger/pms-api.json>`", ":download:`link <./swagger/pms-api.yaml>`"
    "A1 ADAPTER API (Internal)", ":download:`link <./swagger/a1-adapter-api.json>`", ":download:`link <./swagger/a1-adapter-api.yaml>`"
 
-
 .. _pms_api:
 
-PMS API
-.......
-`PMS API <./pms-api.html>`_
+A1 Policy Management Service API
+................................
+
+The A1 Policy Management Service API is described in more detail in `A1 Policy Management Service API (html) <./pms-api.html>`_
+
 
 .. _a1_adapter_api:
 
 A1 ADAPTER API
 ..............
-`A1 ADAPTER API (Internal) <./a1-adapter-api.html>`_
+
+The O-RAN A1 Adapter provides an **internal** RESTCONF API that is used by the A1 Policy Management System when accessing the A1 Interface. This API is useful for test and verification but should not be used otherwise.
+
+The A1 Adapter API is described in more detail in `A1 ADAPTER API (html) <./a1-adapter-api.html>`_
 
diff --git a/docs/offeredapis/swagger/pms-api.json b/docs/offeredapis/swagger/pms-api.json
index 1837e098..72eaa977 100644
--- a/docs/offeredapis/swagger/pms-api.json
+++ b/docs/offeredapis/swagger/pms-api.json
@@ -1,7 +1,7 @@
 {
   "openapi": "3.0.1",
   "info": {
-    "title": "A1 Policy management service",
+    "title": "A1 Policy Management Service",
     "description": "The O-RAN Non-RT RIC PolicyAgent provides a REST API for management of policices. It provides support for: -Supervision of clients (R-APPs) to eliminate stray policies in case of failure -Consistency monitoring of the SMO view of policies and the actual situation in the RICs -Consistency monitoring of RIC capabilities (policy types) -Policy configuration. This includes: -One REST API towards all RICs in the network -Query functions that can find all policies in a RIC, all policies owned by a service (R-APP), all policies of a type etc. -Maps O1 resources (ManagedElement) as defined in O1 to the controlling RIC of A1 policices.",
     "version": "1.0"
   },
@@ -16,19 +16,19 @@
   "tags": [
     {
       "name": "A1 Policy Management",
-      "description": "Policy Controller"
+      "description": "This is the north bound API of the A1 Policy Management Service (\"Policy Agent\"). This API allows *services* to interact with the Policy Agent using REST. By registering with the Policy Agent, the Policy Agent takes responsibility for synchronizing the policies created by the service in the Near RT RICs. This means that if a Near RT RIC restarts, the Policy Agent will try to recreate all the policies residing in the Near RT RIC once it is started again. If this is not possible, it will remove all policies belonging to the Near RT RIC. The Policy Agent also keeps an updated view of the policy types available, and which Near RT RICs that support which types. Also, the Policy Agent can tell if a Managed Element is managed by a certain Near RT RIC."
     },
     {
       "name": "Health check",
-      "description": "Status Controller"
+      "description": "The status of the A1 Policy Management Service"
     },
     {
       "name": "RIC Repository",
-      "description": "Ric Repository Controller"
+      "description": "The A1 Policy Management Service keeps an updated view of the Near RT RICs that are available in the system. A service can find out which Near RT RIC that manages a specific element in the network or which Near RT RICs that support a specific policy type."
     },
     {
       "name": "Service registry and supervision",
-      "description": "Service Controller"
+      "description": "A service can register itself in the A1 Policy Management Service. By providing a callback URL the service can get notifications from the A1 Policy Management Service. A service can also register a \"*Keep Alive Interval*\", in seconds. By doing this the service promises to call the A1 Policy Management Service's \"*Keep Alive*\" method, or else create or delete policies, more often than the \"*Keep Alive Interval*\" measured in seconds. If the service, for some reason, is not able to do this, the A1 Policy Management Service will consider that the service has died or vanished and will then delete all its policies, both in the internal repository and in the Near RT RICs where they were earlier created. **Note!** If the service does not provide a value for \"*Keep Alive Interval*\", then the service maintains full responsibility to delete all of its policies when they are no longer needed."
     }
   ],
   "paths": {
@@ -1130,7 +1130,7 @@
           },
           "keepAliveIntervalSeconds": {
             "type": "integer",
-            "description": "keep alive interval for the service. This is a heartbeat supervision of the service, which in regular intevals must invoke a 'keepAlive' REST call. When a service does not invoke this call within the given time, it is considered unavailble. An unavailable service will be automatically deregistered and its policies will be deleted. Value 0 means no timeout supervision.",
+            "description": "Keep alive interval for the service. This is a heartbeat supervision of the service, which in regular intevals must invoke a 'keepAlive' REST call. When a service does not invoke this call within the given time, it is considered unavailble. An unavailable service will be automatically deregistered and its policies will be deleted. Value 0 means no timeout supervision.",
             "format": "int64"
           },
           "serviceName": {
diff --git a/docs/offeredapis/swagger/pms-api.yaml b/docs/offeredapis/swagger/pms-api.yaml
index 3bf13a21..865eb770 100644
--- a/docs/offeredapis/swagger/pms-api.yaml
+++ b/docs/offeredapis/swagger/pms-api.yaml
@@ -1,7 +1,7 @@
 ---
 openapi: 3.0.1
 info:
-  title: A1 Policy management service
+  title: A1 Policy Management Service
   description: 'The O-RAN Non-RT RIC PolicyAgent provides a REST API for management
     of policices. It provides support for: -Supervision of clients (R-APPs) to eliminate
     stray policies in case of failure -Consistency monitoring of the SMO view of policies
@@ -16,13 +16,36 @@ servers:
 - url: http://localhost:8081/
 tags:
 - name: A1 Policy Management
-  description: Policy Controller
+  description: This is the north bound API of the A1 Policy Management Service ("Policy
+    Agent"). This API allows *services* to interact with the Policy Agent using REST.
+    By registering with the Policy Agent, the Policy Agent takes responsibility for
+    synchronizing the policies created by the service in the Near RT RICs. This means
+    that if a Near RT RIC restarts, the Policy Agent will try to recreate all the
+    policies residing in the Near RT RIC once it is started again. If this is not
+    possible, it will remove all policies belonging to the Near RT RIC. The Policy
+    Agent also keeps an updated view of the policy types available, and which Near
+    RT RICs that support which types. Also, the Policy Agent can tell if a Managed
+    Element is managed by a certain Near RT RIC.
 - name: Health check
-  description: Status Controller
+  description: The status of the A1 Policy Management Service
 - name: RIC Repository
-  description: Ric Repository Controller
+  description: The A1 Policy Management Service keeps an updated view of the Near
+    RT RICs that are available in the system. A service can find out which Near RT
+    RIC that manages a specific element in the network or which Near RT RICs that
+    support a specific policy type.
 - name: Service registry and supervision
-  description: Service Controller
+  description: A service can register itself in the A1 Policy Management Service.
+    By providing a callback URL the service can get notifications from the A1 Policy
+    Management Service. A service can also register a "*Keep Alive Interval*", in
+    seconds. By doing this the service promises to call the A1 Policy Management Service's
+    "*Keep Alive*" method, or else create or delete policies, more often than the
+    "*Keep Alive Interval*" measured in seconds. If the service, for some reason,
+    is not able to do this, the A1 Policy Management Service will consider that the
+    service has died or vanished and will then delete all its policies, both in the
+    internal repository and in the Near RT RICs where they were earlier created. **Note!**
+    If the service does not provide a value for "*Keep Alive Interval*", then the
+    service maintains full responsibility to delete all of its policies when they
+    are no longer needed.
 paths:
   "/policies":
     get:
@@ -759,7 +782,7 @@ components:
           description: callback for notifying of RIC synchronization
         keepAliveIntervalSeconds:
           type: integer
-          description: keep alive interval for the service. This is a heartbeat supervision
+          description: Keep alive interval for the service. This is a heartbeat supervision
             of the service, which in regular intevals must invoke a 'keepAlive' REST
             call. When a service does not invoke this call within the given time,
             it is considered unavailble. An unavailable service will be automatically
@@ -849,4 +872,3 @@ components:
           ueId: '1'
         statement:
           priorityLevel: 1
-
diff --git a/docs/releasenotes/release-notes.rst b/docs/releasenotes/release-notes.rst
index 1bee897e..d57a2331 100644
--- a/docs/releasenotes/release-notes.rst
+++ b/docs/releasenotes/release-notes.rst
@@ -1,7 +1,7 @@
 .. This work is licensed under a Creative Commons Attribution
 .. 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0
-.. Copyright (C) 2020 Nordix Foundation.
+.. Copyright (C) 2021 Nordix Foundation.
 .. _release_notes:
 
 =============
@@ -18,14 +18,15 @@ of the ORAN project.
 Version history Policy Management Service
 =========================================
 
-+------------+----------+-------------+----------------+
-| **Date**   | **Ver.** | **Author**  | **Comment**    |
-|            |          |             |                |
-+------------+----------+-------------+----------------+
-| 2020-09-10 | 1.0.0    | Dan Timoney | First version  |
-|            |          |             | Guilin Release |
-+------------+----------+-------------+----------------+
-
++------------+----------+-------------+----------------------------+
+| **Date**   | **Ver.** | **Author**  | **Comment**                |
++------------+----------+-------------+----------------------------+
+| 2020-09-10 | 1.0.0    | Dan Timoney | First version              |
+|            |          |             | Guilin Release             |
++------------+----------+-------------+----------------------------+
+| 2021-01-29 | 1.0.0    | Dan Timoney | Guilin Maintenance Release |
+|            |          |             | Only documentation updates |
++------------+----------+-------------+----------------------------+
 
 Summary
 -------
@@ -36,9 +37,8 @@ Version history A1 Adapter
 
 +------------+----------+-------------+----------------+
 | **Date**   | **Ver.** | **Author**  | **Comment**    |
-|            |          |             |                |
 +------------+----------+-------------+----------------+
-| 2019-09-10 | 1.0.0    | Dan Timoney | First version  |
+| 2020-09-10 | 1.0.0    | Dan Timoney | First version  |
 |            |          |             | Guilin Release |
 +------------+----------+-------------+----------------+