Add user-guide in SubManager's document

Change-Id: I7a8373902241cbd111a21418ba3ea169bf054b08
Signed-off-by: Anssi Mannila <anssi.mannila@nokia.com>

diff --git a/docs/images/PlaceInRICSoftwareArchitecture.png b/docs/images/PlaceInRICSoftwareArchitecture.png
new file mode 100755 (executable)
index 0000000..b6b693d
Binary files /dev/null and b/docs/images/PlaceInRICSoftwareArchitecture.png differ

diff --git a/docs/images/Subscription_Delete_Failure.png b/docs/images/Subscription_Delete_Failure.png
new file mode 100755 (executable)
index 0000000..e6c52e6
Binary files /dev/null and b/docs/images/Subscription_Delete_Failure.png differ

diff --git a/docs/images/Subscription_Delete_Timeout.png b/docs/images/Subscription_Delete_Timeout.png
new file mode 100755 (executable)
index 0000000..6c5be50
Binary files /dev/null and b/docs/images/Subscription_Delete_Timeout.png differ

diff --git a/docs/images/Subscription_Failure.png b/docs/images/Subscription_Failure.png
new file mode 100755 (executable)
index 0000000..1abc1d1
Binary files /dev/null and b/docs/images/Subscription_Failure.png differ

diff --git a/docs/images/Subscription_Timeout.png b/docs/images/Subscription_Timeout.png
new file mode 100755 (executable)
index 0000000..3fcd8d4
Binary files /dev/null and b/docs/images/Subscription_Timeout.png differ

diff --git a/docs/images/Successful_Subscription.png b/docs/images/Successful_Subscription.png
new file mode 100755 (executable)
index 0000000..7f9bc7a
Binary files /dev/null and b/docs/images/Successful_Subscription.png differ

diff --git a/docs/images/Successful_Subscription_Delete.png b/docs/images/Successful_Subscription_Delete.png
new file mode 100755 (executable)
index 0000000..9fd1888
Binary files /dev/null and b/docs/images/Successful_Subscription_Delete.png differ

diff --git a/docs/images/Successful_Subscription_Delete_Merge.png b/docs/images/Successful_Subscription_Delete_Merge.png
new file mode 100755 (executable)
index 0000000..be2d76c
Binary files /dev/null and b/docs/images/Successful_Subscription_Delete_Merge.png differ

diff --git a/docs/images/Successful_Subscription_Merge.png b/docs/images/Successful_Subscription_Merge.png
new file mode 100755 (executable)
index 0000000..37b2fe7
Binary files /dev/null and b/docs/images/Successful_Subscription_Merge.png differ

diff --git a/docs/images/source/SubManager pictures.odp b/docs/images/source/SubManager pictures.odp
new file mode 100644 (file)
index 0000000..96322ee
Binary files /dev/null and b/docs/images/source/SubManager pictures.odp differ

diff --git a/docs/index.rst b/docs/index.rst
index c451042..3983787 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,6 +24,7 @@ Welcome to O-RAN Subscription Manager Documentation
    :caption: Contents:
 
    release-notes.rst
+   user-guide.rst
 
 * :ref:`genindex`
 * :ref:`modindex`

diff --git a/docs/user-guide.rst b/docs/user-guide.rst
new file mode 100755 (executable)
index 0000000..10a18e8
--- /dev/null
+++ b/docs/user-guide.rst
@@ -0,0 +1,245 @@
+..
+..  Copyright (c) 2019 AT&T Intellectual Property.
+..  Copyright (c) 2019 Nokia.
+..
+..  Licensed under the Creative Commons Attribution 4.0 International
+..  Public License (the "License"); you may not use this file except
+..  in compliance with the License. You may obtain a copy of the License at
+..
+..    https://creativecommons.org/licenses/by/4.0/
+..
+..  Unless required by applicable law or agreed to in writing, documentation
+..  distributed under the License is distributed on an "AS IS" BASIS,
+..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+..
+..  See the License for the specific language governing permissions and
+..  limitations under the License.
+..
+
+User-Guide
+==========
+
+.. contents::
+   :depth: 3
+   :local:
+
+Overview
+--------
+Subscription Manager is a basic platform service in RIC. It is responsible for managing E2 subscriptions from xApps to the
+Radio Access Network (RAN).
+
+xApp can subscribe and unsubscribe messages from gNodeB through Subscription Manager. Subscription Manager manages the subscriptions
+and message routing of the subscribed messages between E2 Termination and xApps. If one xApp has already made a subscription and then
+another xApp initiates identical subscription, Subscription Manager does not forward the subscription to gNodeB but merges the
+subscriptions internally. In merge case Subscription Manager just updates the message routing information to Routing Manager and
+sends response to xApp.
+
+There can be only one ongoing RIC Subscription or RIC Subscription Delete procedure towards RAN at any time. That is because Subscription
+Manager is able to merge new subscriptions only which those it has already received successful response from RAN. Subscriptions
+and delete subscriptions are therefore queued in Subscription Manager. Subscription Manager may need to do reties during subscribe or
+unsubscribe procedure. As it can increase completion time of the procedure, this needs to be considered when retries are implemented
+in xApp side. xApp's retry delay should not be too short.
+
+    .. image:: images/PlaceInRICSoftwareArchitecture.png
+      :width: 600
+      :alt: Place in RIC's software architecture picture
+
+Architecture
+------------
+
+  * Message routing
+
+      Subscribed messages from RAN are transported to RIC inside RIC Indication message. RIC Indication message is transported to xApp
+      inside RMR message, in Payload field of the RMR message. RMR message is routed to xApp based on SubId field (subscription id) in
+      the RMR header. Same routing mechanism is used also for response messages from Subscription Manager to xApp. Subscription Manager is
+      not able to respond to xApp if route for subscription has not been created.
+
+      When xApp sends message to Subscription Manager it sets -1 in SubId field in the RMR header. It means that messages are routed based
+      on message type (Mtype filed in RMR header). RIC Subscription Request and RIC Subscription delete Request messages are pre configured
+      to be routed to Subscription Manager.
+
+      Subscription Manager allocates unique RIC Request Sequence Number for every subscription during Subscription procedure. Subscription
+      Manager replaces existing ASN.1 decoded RIC Request Sequence Number in the RIC Subscription Request message allocated by the xApp.
+      That sequence number (subscription id) is then used for the subscription in RIC and RAN as long the subscription lives. xApp gets
+      the sequence number in RIC Subscription Response message from Subscription manager based on the message types.
+      
+      Subscribed messages are routed to xApps based on sequence number. Sequence number is placed in the SubId field of the RMR message
+      header when E2 Termination sends the subscribed message to xApp. When xApp wants to delete the subscription, the same sequence number
+      must be included in the ASN.1 encoded RIC Subscription Delete Request message sent to Subscription Manager.
+
+      Subscription Manager responds to xApp with xApp allocated RIC Requestor ID. In merge case subscription is created only for the first
+      requestor. RAN gets the Requestor ID of the xApp who makes the first subscription. RAN uses that Requestor ID in all RIC Indication
+      messages it sends to RIC for the subscription. Therefore xApp may get Requestor ID in RIC Indication message that belongs to another xApp.
+      The xApp whose subscription is merged into the first subscription will also get Requestor ID of the first subscribed xApp in the RIC
+      Subscription Response and RIC Subscription Delete Response messages.
+
+      TransactionId (Xid) in RMR message header is used to track messages between xApp and Subscription Manager. xApp allocates it. Subscription
+      Manager returns TransactionId received from xApp in response message to xApp. xApp uses it to map response messages to request messages
+      it sends.
+
+  * Subscription procedure
+      
+    * Successful case
+
+      xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager validates request types in the message and sends
+      route create to Routing Manager over REST interface. When route is created successfully Subscription Manager forwards request to E2
+      Termination. When RIC Subscription Response arrives from E2 Termination Subscription Manager forwards it to xApp.
+      
+      Subscription Manager supervises route create and RIC Subscription Request with a timer.
+
+      RIC Indication messages which are used to transport subscribed messages from RAN are routed from E2 Termination to xApps
+      directly using the routes created during Subscription procedure.
+
+      ``Routing manager has 1 second delay in routing create in R3 release before it responds to Subscription Manager. That is because of delay in route create to RMR.``
+
+      Subscription Manager supports REPORT and POLICY type subscriptions (RICActionTypes). CONTROL and INSERT are not supported. POLICY type
+      subscription can be updated. In update case signaling sequence is the same as above, except route is not created to Routing manager.
+      xApp uses initially allocated TransactionId and RIC Request Sequence Number in update case. Route in POLICY type subscription case is needed
+      only that Subscription Manager can send response messages to xApp. RIC Subscription Request message contains list of RICaction-ToBeSetup-ItemIEs.
+      The list cannot have both REPORT and POLICY action types at the same time. Subscription Manager checks actions types in the message.
+      If both action types is found the message is dropped.
+
+
+    .. image:: images/Successful_Subscription.png
+      :width: 600
+      :alt: Successful subscription picture
+
+
+    * Failure case
+
+      In failure case Subscription Manager checks the failure cause and acts based on that. If failure cause is "duplicate" Subscription
+      Manager sends delete to RAN and then resends the same subscription. If failure cause is such that Subscription manager cannot do
+      anything to fix the problem, it sends delete to RAN and sends RIC Subscription Failure to xApp. Subscription Manager may retry RIC
+      Subscription Request and RIC Subscription Delete messages also in this case before it responds to xApp.
+
+    .. image:: images/Subscription_Failure.png
+      :width: 600
+      :alt: Subscription failure picture
+
+    * Timeout case
+
+     In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Request to RAN. If there is no response
+      after retry, Subscription Manager shall NOT send any response to xApp. xApp may retry RIC Subscription Request, if it wishes to do so.
+      Subscription Manager does no handle the retry if Subscription Manager has ongoing subscription procedure for the same subscription.
+      Subscription just drops the request.
+
+    .. image:: images/Subscription_Timeout.png
+      :width: 600
+      :alt: Subscription timeout picture
+
+  * Subscription delete procedure
+
+    * Successful case
+
+      xApp sends RIC Subscription Delete Request message to Subscription Manager. xApp must use the same RIC Request Sequence Number which
+      it received in RIC Subscription Response message when subscription is deleted. When Subscription Manager receives RIC Subscription
+      Delete Request message, Subscription Manager first forwards the request to E2 Termination. When RIC Subscription Delete Response arrives
+      from E2 Termination to Subscription Manager, Subscription Manager forwards it to xApp and then request route deletion from Routing Manager.
+      
+      Subscription Manager supervises RIC Subscription Deletion Request and route delete with a timer.
+
+    .. image:: images/Successful_Subscription_Delete.png
+      :width: 600
+      :alt: Successful subscription delete picture
+
+    * Failure case
+
+      Delete procedure cannot fail from xApp point of view. Subscription Manager always responds with RIC Subscription Delete Response to xApp.
+
+    .. image:: images/Subscription_Delete_Failure.png
+      :width: 600
+      :alt: Subscription delete failure picture
+
+    * Timeout case
+
+      In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Delete Request to RAN. If there is no
+      response after retry, Subscription Manager responds to xApp with RIC Subscription Delete Response.
+
+    .. image:: images/Subscription_Delete_Timeout.png
+      :width: 600
+      :alt: Subscription delete timeout picture
+
+    * Unknown subscription
+
+      If Subscription Manager receives RIC Subscription Delete Request for a subscription which does not exist, Subscription Manager cannot respond
+      to xApp as there is no route for the subscription.
+
+  * Subscription merge procedure
+
+    * Successful case
+
+      xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager checks is the Subscription mergeable. If not,
+      Subscription Manager continues with normal Subscription procedure. If Subscription is mergeable, Subscription Manager sends route create
+      to Routing Manager and then responds with RIC Subscription Response to xApp.
+      
+      Route create is supervised with a timer.
+
+      Merge for REPORT type subscription is possible if Action Type and Event Trigger Definition of subscriptions are equal.
+
+      ``Only REPORT type subscriptions can be be merged.``
+
+    .. image:: images/Successful_Subscription_Merge.png
+      :width: 600
+      :alt: Successful subscription merge picture
+
+    * Failure case
+
+      Failure case is basically the same as in normal subscription procedure. Failure can come only from RAN when merge is not yet done.
+      If error happens during route create Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
+
+    * Timeout case
+
+      Timeout case is basically the same as in normal subscription procedure but timeout can come only in route create during merge operation.
+      If error happens during route create, Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
+
+  * Subscription delete merge procedure
+
+    * Successful case
+
+      xApp sends RIC Subscription Delete Request message to Subscription Manager. If delete concerns merged subscription, Subscription Manager
+      responds with RIC Subscription Delete Response to xApp and then sends route delete request to Routing manager.
+      
+      Subscription Manager supervises route delete with a timer.
+
+    .. image:: images/Successful_Subscription_Delete_Merge.png
+      :width: 600
+      :alt: Successful subscription delete merge picture
+
+    * Failure case
+
+      Delete procedure cannot fail from xApp point of view. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
+
+    * Timeout case
+
+      Timeout can only happen in route delete to Routing manager. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
+
+  * Unknown message
+
+     If Subscription Manager receives unknown message, Subscription Manager drops the message.
+
+RAN services explained
+----------------------
+  RIC hosted xApps may use the following RAN services from a RAN node:
+
+  *  REPORT: RIC requests that RAN sends a REPORT message to RIC and continues further call processing in RAN after each occurrence of a defined SUBSCRIPTION
+  *  INSERT: RIC requests that RAN sends an INSERT message to RIC and suspends further call processing in RAN after each occurrence of a defined SUBSCRIPTION
+  *  CONTROL: RIC sends a Control message to RAN to initiate or resume call processing in RAN
+  *  POLICY: RIC requests that RAN executes a specific POLICY during call processing in RAN after each occurrence of a defined SUBSCRIPTION
+
+Supported E2 procedures and RAN services
+----------------------------------------
+    * RIC Subscription procedure with following RIC action types:
+
+      - REPORT
+      - POLICY
+
+    * RIC Subscription Delete procedure
+
+    * Merge and delete of equal REPORT type subscriptions.
+
+Recommendations for xApps
+-------------------------
+
+   * Recommended retry delay
+
+     Recommended retry delay for xApp is > 10 seconds