.. .. 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. This needs to be considered when retries are implemented in xApp side, as it can increase completion time of the procedure. 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 allocates RIC Requestor ID. Currently the ID value is always 123. In merge case subscription is created only for the first requestor. RAN gets the Request of the xApp who makes the first subscription. RAN uses Subscription Manager allocated Requestor ID in all RIC Indication messages it sends to RIC for the subscription. 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. Subscription Manager supports REPORT, POLICY and INSERT type subscriptions (RICActionTypes). CONTROL is 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 REPORT, POLICY, INSERT 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. * xApp restart When xApp is restarted for any reason it may resend the subscriptions which have already been subscribed. In this case Subscription Manager sends successful response to such requests without updating Routing Manager and BTS. In restart IP address of the xApp may change but service address name does not. Message routing uses service address name. 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 - INSERT * RIC Subscription Delete procedure * Merge and delete of equal REPORT type subscriptions. Recommendations for xApps ------------------------- * Recommended retry delay Recommended retry delay for xApp is >= 5 seconds