docs/user-guide.rst

   1 ..
   2 ..  Copyright (c) 2019 AT&T Intellectual Property.
   3 ..  Copyright (c) 2019 Nokia.
   4 ..
   5 ..  Licensed under the Creative Commons Attribution 4.0 International
   6 ..  Public License (the "License"); you may not use this file except
   7 ..  in compliance with the License. You may obtain a copy of the License at
   8 ..
   9 ..    https://creativecommons.org/licenses/by/4.0/
  10 ..
  11 ..  Unless required by applicable law or agreed to in writing, documentation
  12 ..  distributed under the License is distributed on an "AS IS" BASIS,
  13 ..  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 ..
  15 ..  See the License for the specific language governing permissions and
  16 ..  limitations under the License.
  17 ..
  18
  19 User-Guide
  20 ==========
  21
  22 .. contents::
  23    :depth: 3
  24    :local:
  25
  26 Overview
  27 --------
  28 Subscription Manager is a basic platform service in RIC. It is responsible for managing E2 subscriptions from xApps to the
  29 Radio Access Network (RAN).
  30
  31 xApp can subscribe and unsubscribe messages from gNodeB through Subscription Manager. Subscription Manager manages the subscriptions
  32 and message routing of the subscribed messages between E2 Termination and xApps. If one xApp has already made a subscription and then
  33 another xApp initiates identical subscription, Subscription Manager does not forward the subscription to gNodeB but merges the
  34 subscriptions internally. In merge case Subscription Manager just updates the message routing information to Routing Manager and
  35 sends response to xApp.
  36
  37 There can be only one ongoing RIC Subscription or RIC Subscription Delete procedure towards RAN at any time. That is because Subscription
  38 Manager is able to merge new subscriptions only which those it has already received successful response from RAN. Subscriptions
  39 and delete subscriptions are therefore queued in Subscription Manager. Subscription Manager may need to do reties during subscribe or
  40 unsubscribe procedure. As it can increase completion time of the procedure, this needs to be considered when retries are implemented
  41 in xApp side. xApp's retry delay should not be too short.
  42
  43     .. image:: images/PlaceInRICSoftwareArchitecture.png
  44       :width: 600
  45       :alt: Place in RIC's software architecture picture
  46
  47 Architecture
  48 ------------
  49
  50   * Message routing
  51
  52       Subscribed messages from RAN are transported to RIC inside RIC Indication message. RIC Indication message is transported to xApp
  53       inside RMR message, in Payload field of the RMR message. RMR message is routed to xApp based on SubId field (subscription id) in
  54       the RMR header. Same routing mechanism is used also for response messages from Subscription Manager to xApp. Subscription Manager is
  55       not able to respond to xApp if route for subscription has not been created.
  56
  57       When xApp sends message to Subscription Manager it sets -1 in SubId field in the RMR header. It means that messages are routed based
  58       on message type (Mtype filed in RMR header). RIC Subscription Request and RIC Subscription delete Request messages are pre configured
  59       to be routed to Subscription Manager.
  60
  61       Subscription Manager allocates unique RIC Request Sequence Number for every subscription during Subscription procedure. Subscription
  62       Manager replaces existing ASN.1 decoded RIC Request Sequence Number in the RIC Subscription Request message allocated by the xApp.
  63       That sequence number (subscription id) is then used for the subscription in RIC and RAN as long the subscription lives. xApp gets
  64       the sequence number in RIC Subscription Response message from Subscription manager based on the message types.
  65
  66       Subscribed messages are routed to xApps based on sequence number. Sequence number is placed in the SubId field of the RMR message
  67       header when E2 Termination sends the subscribed message to xApp. When xApp wants to delete the subscription, the same sequence number
  68       must be included in the ASN.1 encoded RIC Subscription Delete Request message sent to Subscription Manager.
  69
  70       Subscription Manager responds to xApp with xApp allocated RIC Requestor ID. In merge case subscription is created only for the first
  71       requestor. RAN gets the Requestor ID of the xApp who makes the first subscription. RAN uses that Requestor ID in all RIC Indication
  72       messages it sends to RIC for the subscription. Therefore xApp may get Requestor ID in RIC Indication message that belongs to another xApp.
  73       The xApp whose subscription is merged into the first subscription will also get Requestor ID of the first subscribed xApp in the RIC
  74       Subscription Response and RIC Subscription Delete Response messages.
  75
  76       TransactionId (Xid) in RMR message header is used to track messages between xApp and Subscription Manager. xApp allocates it. Subscription
  77       Manager returns TransactionId received from xApp in response message to xApp. xApp uses it to map response messages to request messages
  78       it sends.
  79
  80   * Subscription procedure
  81
  82     * Successful case
  83
  84       xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager validates request types in the message and sends
  85       route create to Routing Manager over REST interface. When route is created successfully Subscription Manager forwards request to E2
  86       Termination. When RIC Subscription Response arrives from E2 Termination Subscription Manager forwards it to xApp.
  87
  88       Subscription Manager supervises route create and RIC Subscription Request with a timer.
  89
  90       RIC Indication messages which are used to transport subscribed messages from RAN are routed from E2 Termination to xApps
  91       directly using the routes created during Subscription procedure.
  92
  93       ``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.``
  94
  95       Subscription Manager supports REPORT and POLICY type subscriptions (RICActionTypes). CONTROL and INSERT are not supported. POLICY type
  96       subscription can be updated. In update case signaling sequence is the same as above, except route is not created to Routing manager.
  97       xApp uses initially allocated TransactionId and RIC Request Sequence Number in update case. Route in POLICY type subscription case is needed
  98       only that Subscription Manager can send response messages to xApp. RIC Subscription Request message contains list of RICaction-ToBeSetup-ItemIEs.
  99       The list cannot have both REPORT and POLICY action types at the same time. Subscription Manager checks actions types in the message.
 100       If both action types is found the message is dropped.
 101
 102
 103     .. image:: images/Successful_Subscription.png
 104       :width: 600
 105       :alt: Successful subscription picture
 106
 107
 108     * Failure case
 109
 110       In failure case Subscription Manager checks the failure cause and acts based on that. If failure cause is "duplicate" Subscription
 111       Manager sends delete to RAN and then resends the same subscription. If failure cause is such that Subscription manager cannot do
 112       anything to fix the problem, it sends delete to RAN and sends RIC Subscription Failure to xApp. Subscription Manager may retry RIC
 113       Subscription Request and RIC Subscription Delete messages also in this case before it responds to xApp.
 114
 115     .. image:: images/Subscription_Failure.png
 116       :width: 600
 117       :alt: Subscription failure picture
 118
 119     * Timeout case
 120
 121      In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Request to RAN. If there is no response
 122       after retry, Subscription Manager shall NOT send any response to xApp. xApp may retry RIC Subscription Request, if it wishes to do so.
 123       Subscription Manager does no handle the retry if Subscription Manager has ongoing subscription procedure for the same subscription.
 124       Subscription just drops the request.
 125
 126     .. image:: images/Subscription_Timeout.png
 127       :width: 600
 128       :alt: Subscription timeout picture
 129
 130   * Subscription delete procedure
 131
 132     * Successful case
 133
 134       xApp sends RIC Subscription Delete Request message to Subscription Manager. xApp must use the same RIC Request Sequence Number which
 135       it received in RIC Subscription Response message when subscription is deleted. When Subscription Manager receives RIC Subscription
 136       Delete Request message, Subscription Manager first forwards the request to E2 Termination. When RIC Subscription Delete Response arrives
 137       from E2 Termination to Subscription Manager, Subscription Manager forwards it to xApp and then request route deletion from Routing Manager.
 138
 139       Subscription Manager supervises RIC Subscription Deletion Request and route delete with a timer.
 140
 141     .. image:: images/Successful_Subscription_Delete.png
 142       :width: 600
 143       :alt: Successful subscription delete picture
 144
 145     * Failure case
 146
 147       Delete procedure cannot fail from xApp point of view. Subscription Manager always responds with RIC Subscription Delete Response to xApp.
 148
 149     .. image:: images/Subscription_Delete_Failure.png
 150       :width: 600
 151       :alt: Subscription delete failure picture
 152
 153     * Timeout case
 154
 155       In case of timeout in Subscription Manager, Subscription Manager may resend the RIC Subscription Delete Request to RAN. If there is no
 156       response after retry, Subscription Manager responds to xApp with RIC Subscription Delete Response.
 157
 158     .. image:: images/Subscription_Delete_Timeout.png
 159       :width: 600
 160       :alt: Subscription delete timeout picture
 161
 162     * Unknown subscription
 163
 164       If Subscription Manager receives RIC Subscription Delete Request for a subscription which does not exist, Subscription Manager cannot respond
 165       to xApp as there is no route for the subscription.
 166
 167   * Subscription merge procedure
 168
 169     * Successful case
 170
 171       xApp sends RIC Subscription Request message to Subscription Manager. Subscription Manager checks is the Subscription mergeable. If not,
 172       Subscription Manager continues with normal Subscription procedure. If Subscription is mergeable, Subscription Manager sends route create
 173       to Routing Manager and then responds with RIC Subscription Response to xApp.
 174
 175       Route create is supervised with a timer.
 176
 177       Merge for REPORT type subscription is possible if Action Type and Event Trigger Definition of subscriptions are equal.
 178
 179       ``Only REPORT type subscriptions can be be merged.``
 180
 181     .. image:: images/Successful_Subscription_Merge.png
 182       :width: 600
 183       :alt: Successful subscription merge picture
 184
 185     * Failure case
 186
 187       Failure case is basically the same as in normal subscription procedure. Failure can come only from RAN when merge is not yet done.
 188       If error happens during route create Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
 189
 190     * Timeout case
 191
 192       Timeout case is basically the same as in normal subscription procedure but timeout can come only in route create during merge operation.
 193       If error happens during route create, Subscription Manager drops the RIC Subscription Request message and xApp does not get any response.
 194
 195   * Subscription delete merge procedure
 196
 197     * Successful case
 198
 199       xApp sends RIC Subscription Delete Request message to Subscription Manager. If delete concerns merged subscription, Subscription Manager
 200       responds with RIC Subscription Delete Response to xApp and then sends route delete request to Routing manager.
 201
 202       Subscription Manager supervises route delete with a timer.
 203
 204     .. image:: images/Successful_Subscription_Delete_Merge.png
 205       :width: 600
 206       :alt: Successful subscription delete merge picture
 207
 208     * Failure case
 209
 210       Delete procedure cannot fail from xApp point of view. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
 211
 212     * Timeout case
 213
 214       Timeout can only happen in route delete to Routing manager. Subscription Manager responds with RIC Subscription Delete Response message to xApp.
 215
 216   * Unknown message
 217
 218      If Subscription Manager receives unknown message, Subscription Manager drops the message.
 219
 220 RAN services explained
 221 ----------------------
 222   RIC hosted xApps may use the following RAN services from a RAN node:
 223
 224   *  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
 225   *  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
 226   *  CONTROL: RIC sends a Control message to RAN to initiate or resume call processing in RAN
 227   *  POLICY: RIC requests that RAN executes a specific POLICY during call processing in RAN after each occurrence of a defined SUBSCRIPTION
 228
 229 Supported E2 procedures and RAN services
 230 ----------------------------------------
 231     * RIC Subscription procedure with following RIC action types:
 232
 233       - REPORT
 234       - POLICY
 235
 236     * RIC Subscription Delete procedure
 237
 238     * Merge and delete of equal REPORT type subscriptions.
 239
 240 Recommendations for xApps
 241 -------------------------
 242
 243    * Recommended retry delay
 244
 245      Recommended retry delay for xApp is > 10 seconds