USSD - Training Document R1-4.docx

USSD Training Document *This page intentionally left blank* Publisher Pharos Avantgard (Pty) Ltd\ Registered No.: 2000/004482/07\ Physical Address: 1^st^ Floor, Willowbrook House\ Constantia Office Park, Weltevreden Park, Johannesburg, South Africa, 1709\ Postal Address: PO Box 149, Melrose Arch...

USSD Training Document *This page intentionally left blank* Publisher Pharos Avantgard (Pty) Ltd\ Registered No.: 2000/004482/07\ Physical Address: 1^st^ Floor, Willowbrook House\ Constantia Office Park, Weltevreden Park, Johannesburg, South Africa, 1709\ Postal Address: PO Box 149, Melrose Arch, Johannesburg, South Africa, 2076\ Email: info\@pharos-avantgard.com\ Internet: www.pharos-avantgard.com Copyright Copyright © 2024 Pharos Avantgard (Pty) Ltd. All rights reserved.\ No copying, distribution, publication, modification, or incorporation of this document, in whole or part, is permitted without the express written permission of Pharos Avantgard (Pty) Ltd. In the event of any permitted copying, distribution, publication, modification, or incorporation of this document, no changes in or deletion of author attribution, trademark legend, or copyright notice shall be made.\ No part of this document may be reproduced, stored in a retrieval system, published, used for commercial exploitation, or transmitted, in any form by any means, electronic, mechanical, photocopying, recording, or otherwise, without the express written permission of Pharos Avantgard (Pty) Ltd. Confidentiality This document contains information that is confidential and proprietary to Pharos Avantgard (Pty) Ltd. Trademarks The Pharos Avantgard wordmark, Pharos Avantgard logo, and the names of the Pharos Avantgard products and services referred to in this document are trademarks of Pharos Avantgard (Pty) Ltd.\ ERLANG is a trademark of Telefonaktiebolaget L M Ericsson.\ Other brand or product names referred to in this document are the trademarks or registered trademarks of their respective owners. Limitation of Liability Pharos Avantgard (Pty) Ltd has made every effort to assure that the contents of this document are accurate; however, due to the inherent complexity in the design and implementation of its systems, no liability is accepted for any errors or omissions; or the consequences of any use made of this document. Pharos Avantgard (Pty) Ltd may, at any time and without notice, make changes to this document.\ Pharos Avantgard (Pty) Ltd or its partners assumes no liability for technical or editorial errors or omissions made herein, and shall not be liable for incidental, consequential, indirect, or special damages, including, without limitation, loss of use, loss, or alteration of data, delays, or lost profits or savings arising from the use of this document. Contents {#contents.TOCHeading} ======== [Preface 11](#preface) [Purpose 11](#purpose) [Audience 11](#audience) [How this Document is Organised 11](#how-this-document-is-organised) [Related Documents 11](#related-documents) [About Pharos 12](#about-pharos) [**1** About USSD GW 13](#about-ussd-gw) [1.1 What is USSD GW? 13](#what-is-ussd-gw) [1.2 USSD GW in Context 13](#ussd-gw-in-context) [1.3 USSD Traffic Types 14](#ussd-traffic-types) [1.3.1 USSD Subscriber Initiated -- Pull 15](#ussd-subscriber-initiated-pull) [1.3.2 USSD Network Initiated -- Push 15](#ussd-network-initiated-push) [1.3.3 USSD -- Roaming Subscribers 15](#ussd-roaming-subscribers) [1.3.4 MARS Redirect 15](#mars-redirect) [1.3.5 USSD -- Inter Gateway Redirect 15](#ussd-inter-gateway-redirect) [1.4 GSM MAP Specification for USSD 15](#gsm-map-specification-for-ussd) [1.5 USSD PDU Types 16](#ussd-pdu-types) [1.5.1 USSD Traffic Flows 16](#ussd-traffic-flows) [1.6 3G FallBack 21](#g-fallback) [1.7 USSi 21](#ussi) [1.7.1 USSi GW 21](#ussi-gw) [**2** USSD Gateway 25](#ussd-gateway) [2.1 USSD VI Overview 25](#ussd-vi-overview) [2.2 USSD GW Subsystems 26](#ussd-gw-subsystems) [2.2.1 USSD VI Core 26](#ussd-vi-core) [2.2.2 UXML 33](#uxml) [2.2.3 USRT (USSD Scripting Runtime) 34](#usrt-ussd-scripting-runtime) [2.2.4 MARS Redirect 34](#mars-redirect-1) [2.2.5 USRT (Inter Gateway Redirect) 35](#usrt-inter-gateway-redirect) [2.2.6 USSD Push 36](#ussd-push) [2.2.7 UREC and CDRs 36](#urec-and-cdrs) [2.2.8 SNAP Stack 40](#snap-stack) [2.3 UXML-X Interface 41](#uxml-x-interface) [2.3.1 Login 42](#login) [2.3.2 UXML PDUs 42](#uxml-pdus) [2.4 USSD NISE 43](#ussd-nise) [2.4.1 USSD NISE Implementation 44](#ussd-nise-implementation) [2.5 Financial Reporting 46](#financial-reporting) [2.6 General Functionality 47](#general-functionality) [2.6.1 USSD String Text Lengths 47](#ussd-string-text-lengths) [2.6.2 Error Friendly Messages 48](#error-friendly-messages) [2.7 Deployment Overview 48](#deployment-overview) [2.7.1 WASP Network Diagram 49](#wasp-network-diagram) [2.7.2 Self Service Gateway Network Diagram 50](#self-service-gateway-network-diagram) [2.7.3 121Gateway Network Diagram 50](#gateway-network-diagram) [2.7.4 MFS Gateway Network Diagram 51](#mfs-gateway-network-diagram) [2.7.5 ICASA Gateway Network Diagram 52](#icasa-gateway-network-diagram) [2.7.6 PEP Server Deployment 53](#pep-server-deployment) [2.8 USSD Point Codes and Global Title 54](#ussd-point-codes-and-global-title) [2.8.1 WASP GW Pool 54](#wasp-gw-pool) [2.8.2 Self Service GW Pool 54](#self-service-gw-pool) [2.8.3 121 GW Pool 55](#gw-pool) [2.8.4 ICASA GW Pool 55](#icasa-gw-pool) [2.8.5 MFS GW Pool 56](#mfs-gw-pool) [2.8.6 HLR Configs (ENAP) 56](#hlr-configs-enap) [**3** Signaling Routing 58](#signaling-routing) [3.1 Route on GT 58](#route-on-gt) [**4** Error Codes 59](#error-codes) [4.1 USSD Error Codes 59](#ussd-error-codes) [4.2 MAP Error Codes 62](#map-error-codes) [Glossary 63](#glossary) [Contact Details 67](#contact-details) List of Figures {#list-of-figures.TOCHeading} =============== [**Figure 1**: High Level Overview 14](#_Toc163121433) [**Figure 2**: USSD Flow 14](#_Toc163121434) [**Figure 3**: Single Request Single Reply 17](#_Toc163121435) [**Figure 4**: Menu Based USSD Session 17](#_Toc163121436) [**Figure 5**: MS Timeout 18](#_Toc163121437) [**Figure 6**: Application Timeout 18](#_Toc163121438) [**Figure 7**: MS Abort 19](#_Toc163121439) [**Figure 8**: NI USSD -- Single Notification 19](#_Toc163121440) [**Figure 9**: NI USSD -- Prompt with multiple exchanges 20](#_Toc163121441) [**Figure 10**: USSi Pull -- Single Request Single Reply 22](#_Toc163121442) [**Figure 11**: USSi Pull -- Multiple Exchanges 22](#_Toc163121443) [**Figure 12**: USSi NI -- Prompt with Final Notification 23](#_Toc163121444) [**Figure 13**: USSi NI -- Single Notification 24](#_Toc163121445) [**Figure 14**: USSD GW Subsystem Overview 25](#_Toc163121446) [**Figure 15**: Get RICA and MVNO Query Results 27](#_Toc163121447) [**Figure 16**: RICA Whitelist 27](#_Toc163121448) [**Figure 17**: RICA Exclusion 27](#_Toc163121449) [**Figure 18**: Adding USSD Rating on CGW 30](#_Toc163121450) [**Figure 19**: UXML Options for ICASA Emergency Profile 33](#_Toc163121451) [**Figure 20**: MARS Redirect 35](#_Toc163121452) [**Figure 21**: SS7 Inter Gateway Redirect 35](#_Toc163121453) [**Figure 22**: USSD Push Ranges 36](#_Toc163121454) [**Figure 23**: SNAP Layers 41](#_Toc163121455) [**Figure 24**: UXML-X 42](#_Toc163121456) [**Figure 25**: UXML Asynchronous Communications 43](#_Toc163121457) [**Figure 26**: USSD NISE Implementation 45](#_Toc163121458) [**Figure 27**: USSD NISE Implementation - Detailed 46](#_Toc163121459) [**Figure 28**: WASP USSD GW Pool Diagram 49](#_Toc163121460) [**Figure 29**: Self Service USSD GW Pool Diagram 50](#_Toc163121461) [**Figure 30**: 121 USSD GW Pool Diagram 51](#_Toc163121462) [**Figure 31**: MFS USSD GW Pool Diagram 52](#_Toc163121463) [**Figure 32**: ICASA USSD System Network Diagram 53](#_Toc163121464) List of Tables {#list-of-tables.TOCHeading} ============== [**Table 1**: Document Revision History 10](#_Toc163121421) [**Table 2**: Diameter Service Parameter Info Definition for USSD Billing 32](#_Toc163121422) [**Table 3**: WASP GW Point Code and GTs 54](#_Toc163121423) [**Table 4**: Self Service GW Point Code and GTs 55](#_Toc163121424) [**Table 5**: 121 GW Point Code and GTs 55](#_Toc163121425) [**Table 6**: ICASA GW Point Code and GTs 56](#_Toc163121426) [**Table 7**: MFS GW Point Code and GTs 56](#_Toc163121427) [**Table 8**: HLR ENAP GT Route Config 57](#_Toc163121428) [**Table 9**: HLR ENAP NS Route Config 57](#_Toc163121429) [**Table 10**: USSD Error Codes 60](#_Toc163121430) [**Table 11**: UXML Error Codes 62](#_Toc163121431) [**Table 12**: MAP Error Codes 62](#_Toc163121432) Document Revision History {#document-revision-history.TOCHeading} ========================= []{#_Toc163121421.anchor}**Table** **1**: Document Revision History **Rev.** **Date** **Author** **Description** ---------- ------------ ------------- --------------------------------------------------------------------------- R1-3 2024-03-18 Chih-Wei Yu Updated training material for 05-04-2024. Use new document look and field R1-4 2024-04-04 Chih-Wei Yu Added info about CallBack and ICASA customizations Preface ======= Purpose ------- This document describes the solution overview, USSD VI Core, various topics and deployments of the USSD Gateway. Audience -------- This document is intended for personnel that performs planning or operations on the USSD Gateway. How this Document is Organised ------------------------------ This document is divided into x sections. It also includes a glossary, a document feedback section, and provides our contact details. [Section 1: About USSD](#about-ussd-gw) GW Describes *USSD GW* purpose and capabilities as well as its objectives. [Section 2:](#about-ussd-gw) USSD Gateway USSD Gateway Subsystem, functions and deployment setup [Section 3:](#about-ussd-gw) Signalling Routing Signalling Routing for USSD. [Section 4: Error Codes](#about-ussd-gw) USSD GW related error codes [Glossary](#Glossary) Defines each term and acronym used in this document. [Contact Details](#contact-details) Provides you with every way in which to contact *us* for support and further information. Related Documents ----------------- This document forms part of the *USSD Gateway* product documentation set, which comprises the following other documents: - Deployment Architecture Document - UXML-X Technical Specification Document - Support Documentation Series About Pharos ------------ Since 2000, South African-based *Pharos* has been creating innovative products for mobile operators in emerging markets and other commercial industries throughout the world. *Pharos* consistently: - Furnishes clients with technological products that are cost-effective and well-engineered. - Enriches the lives of the people and businesses with products that provide high levels of: - Reliability - Performance - Efficiency - Uses an innovative approach to solve technological challenges. About USSD GW ============= What is USSD GW? ---------------- *USSD (Unstructured Supplementary Service Data) is a technology used by network operators to send information (usually text menus) between a mobile phone and an application on the network. The USSD Gateway (GW) allows subscribers to access WASP (Wireless Application Service Provider) services through an Access Point which allows access to the USSD GW with the permission of the mobile network operator and provide a service to the network subscribers. The USSD GW also allows for the charging of the USSD session by performing billing against the OCS via DBRA.* *Internal USSD gateways are connected to internal applications and provide self-services such as balance checks and voucher recharges.* *The USSD GW supports MAP v1 and MAP v2. Note that MAP v1 is for old handsets and supports only PSSRR and PSSRC. MAP v2 allows support for multiple USSD exchanges.* USSD GW in Context ------------------ - **CSID Query and RICA status is retrieved from VASHLR** - **USSD Rating on CGW** - **USSD Billing is performed via DBRA** - **Application traffic is sent via UXML to external applications or via native Erlang to USRT Applications** []{#_Toc163121433.anchor}**Figure** **1**: High Level Overview []{#_Toc163121434.anchor}**Figure** **2**: USSD Flow USSD Traffic Types ------------------ ### USSD Subscriber Initiated -- Pull ### USSD Network Initiated -- Push ### USSD -- Roaming Subscribers ### MARS Redirect ### USSD -- Inter Gateway Redirect Since different base USSD codes could be serviced on different USSD Gateways, there has been a need to redirect from one service to another while keep the USSD session active. With the introduction of Gateway 6, the inter gateway redirect is done via signalling. GSM MAP Specification for USSD ------------------------------ - processUnstructuredSS-Request - unstructuredSS-Request - unstructuredSS-Notify USSD PDU Types -------------- ### USSD Traffic Flows []{#_Toc163121435.anchor}**Figure** **3**: Single Request Single Reply []{#_Toc163121436.anchor}**Figure** **4**: Menu Based USSD Session []{#_Toc163121437.anchor}**Figure** **5**: MS Timeout []{#_Toc163121438.anchor}**Figure** **6**: Application Timeout []{#_Toc163121439.anchor}**Figure** **7**: MS Abort []{#_Toc163121440.anchor}**Figure** **8**: NI USSD -- Single Notification []{#_Toc163121441.anchor}**Figure** **9**: NI USSD -- Prompt with multiple exchanges *\ * 3G FallBack ----------- When a device is on LTE/4G and dials a USSD string, the network initiates 3G fallback to service the USSD request. Once the USSD session has been terminated, the device then goes back to LTE/4G. When a USSD Push is initiated against the device, the device will fallback to 3G and receive the USSD push. Once the USSD Push session has been terminated, the device then goes back to LTE/4G. USSi ---- USSi(USSD over IMS) allows the device to use USSD whilst on LTE/4G. This however requires an USSI capable device and registered on IMS for the USSD service. ### USSi GW The USSi GW will allow subscribers to use USSD when on LTE/4G. The USSi GW will act as an intermediary between the USSD GW and IMS Core. It will convert SS7 MAP to SIP and vice-versa. Below are sequence diagrams for USSi GW pull and push converting between MAP and SIP.  []{#_Toc163121442.anchor}**Figure** **10**: USSi Pull -- Single Request Single Reply A black background with a black square Description automatically generated with medium confidence []{#_Toc163121443.anchor}**Figure** **11**: USSi Pull -- Multiple Exchanges  []{#_Toc163121444.anchor}**Figure** **12**: USSi NI -- Prompt with Final Notification A black background with a black square Description automatically generated with medium confidence []{#_Toc163121445.anchor}**Figure** **13**: USSi NI -- Single Notification USSD Gateway ============ USSD VI Overview ---------------- []{#_Toc163121446.anchor}**Figure** **14**: USSD GW Subsystem Overview - USSD VI Core - UXML - USRT (Self Service Applications) - USRT Inter GW Redirect - BIP Diameter - SNAP Stack - Admin - UREC - Statistics USSD GW Subsystems ------------------ ### USSD VI Core **The USSD VI Core instance is the servicing layer that bridges between the SNAP stack and the servicing applications. It provides mediation from Dialogic MAP messages to internal Erlang format and maintains the state machines of each USSD session. If the subscriber is not RICA'ed then a friendly message is returned to the subscriber.** **MARS is used to route based on configured USSD string or USSD substrings (and CPID) to perform routing to the application. The USSD string is tokenized using \*\# and finds the best match route. It will find up to the base USSD code and if no route is found, it will return a friendly message.** **The USSD rating is maintained on CGW and a local is kept on the USSD GW. The Diameter billing is performed against DBRA and DBRA routes it further to the downstream system.** **The USSD rating is time based and billed \ amount of cents per interval. Note that billing is done up front if the subscriber does not have enough funds, a friendly message is returned. If the subscriber runs out of funds during a session, then the USSD session is aborted.** #### RICA Check and Exclusions **The RICA check is done against VASHLR using the query *getRICAandMVNO.* If the subscriber is RICA barred then the USSD service is not allowed. There are however exclusions defined in NPLS if the subscriber is subjected to RICA check. There is a RICA whitelist and RICA exclusion.** **RICA whitelist is when the subscriber is found on VASHLR but not RICA'ed.** **RICA exclusion is when the subscriber is not found on VASHLR.** **Example of the results for the *getRICAandMVNO* query.**  []{#_Toc163121447.anchor}**Figure** **15**: Get RICA and MVNO Query Results **The CS\_ID or CPID is used in the rating lookup.** **RICA Whitelist** []{#_Toc163121448.anchor}**Figure** **16**: RICA Whitelist **RICA Exclusion where the USSD runtime applies as well as the dial string**  []{#_Toc163121449.anchor}**Figure** **17**: RICA Exclusion #### MARS MARS stands for Mobile Application Routing Service and it's used to find the application service for a given dial string and service class. Note that in this implementation, the service class is based on CPID. Thus, the combination of Dial String (Service Code) and the Subscribers CPID will determine the route to the application service. For example, a MARS entry needs to exist for the Service Code and Service Class which will route it to the Routing Code ABSA\_R01. If the subscribers CPID is not added on MARS, then the sub will receive "Service code not supported". A white background with black text Description automatically generated #### CGW Rating and Advice of Charge (AoC) USSD Rating is managed and maintained on CGW. - CGW keeps all the USSD rating for MTN SA and MVNOs. A local copy is also kept on the USSD GW. - Rating can be free (0T20), standard (20T20) and premium forward billed (e.g. 50T20). - Rating can be reversed billed which then bills against the WASP MSISDN. - Custom rating is done specifically for MVNO. It needs to be configured for CPID for the MVNO. If it is not configured, then the subscriber will receive USSD error. Example:  - MVNO's has a set of custom ratings for USSD and Premium rating is supported. - Advise of charge (AoC) is presented upon Premium rating for the Routing Code returned. - External application must be connected before charging can take place. For the premium service code, it will prompt AoC - If premium rated service, Advice of Charge (AoC) is prompted against user AoC message e.g. - If AoC is accepted, USSD starts initial billing and timer tick and sends PSSRR request to UXML/USRT application. **The following are required to configure a rating:** - **Routing Code -- Routing code defined in the UXML/USRT Profile** - **CPID -- Charge Party ID** - **Rate (1 unit = 1 cent)** - **Interval in seconds per billing tick** - **Tariff Code -- This is automatically constructed from rate and interval** - **Billing Type -- Free, standard, premium or custom** - **Billed Party -- Forward or reverse billing** - **WASP MSISDN** - **Billing Entity -- MTN or MVNO** - **AoC -- Advice of Charge for Premium rated services** - **Work Order number** **The following is an example of the page for adding a new rating on CGW.**  []{#_Toc163121450.anchor}**Figure** **18**: Adding USSD Rating on CGW **Once the rating is published to the USSD GW, the USSD GW will use the local version of the rating configuration. It does not consult CGW for each USSD session.** **Billing is done upfront and performed at the Interval (seconds) thereafter. USSD GW will use the rating information and construct the Diameter billing request. If the initial billing is unsuccessful due to funds, then the subscriber will receive a message indicating insufficient funds. For other billing errors, subscriber will receive error message "Service temporarily unavailable (503)".** **However, if the billing fails within a session, then the GW will abort the USSD session. If the subscriber attempts to reply to an aborted session, the subscriber will receive "MMI error".** #### DBRA Diameter Billing Once the rating is determined, USSD GW will send a Diameter Credit Control Request to DBRA to perform billing. When billing is successful, the timer will start, and GW sends the USSD request to the servicing application. **The diameter billing performed by GW uses Credit Control Requests with SCAPv2 which is an Ericsson specific implementation.** - **Service context ID is ** - **The service identifier for USSD is 120.** - **Requested-Action is DIRECT\_DEBITING (0)** - **Subscription ID is the subscriber's MSISDN.** - **CC-Request-Type is Event Request (4)** **The field and values are carried using the Diameter Service Parameter Info AVP.** -- -- -- -- -- -- []{#_Toc163121422.anchor}**Table** **2**: Diameter Service Parameter Info Definition for USSD Billing #### Customizations -- CallBack, ICASA GWs There are customizations made specifically for the CallBack and ICASA GWs. These customizations are localised in the USSM SDACC modules and deployed and configured for the CallBack and ICASA GWs. For the CallBack GW: - The SDACC module is *ussm\_mtnsa\_cb\_sdacc.erl* - For CPID 0,1,2,3, the service class is CB00, CB01, CB02 and CB03. The service class works in pairs thus CB00 and CB02 is pair \#1, CB01 and CB03 is pair \#2. - For CPID 11 and above, the CPID will be pre-appended to CB00, CB01, CB02 and CB03. Thus, the service class will be 11CB00, 11CB01, 11CB02 and 11CB03. - The MSISDN is hashed to return one of the pairs and traffic is sent to the first one in the pair. If the first one is not available, it will then send to the second one. This allows for active failover configuration. - The CPID is also included in the request towards CallBack USRT. This allows CallBack MVNO to determine which MVNO the CallBack Request belongs to. - The same rating and billing rules applies for CallBack For the ICASA GW: - The SDACC module is *ussm\_mtnsa\_icasa\_sdacc.erl* - **Performs VASHLR query *get\_112\_location\_v1* for \*112 dial string to get location information from VASHLR-CellFinder. The query returns LATSTR, LONSTR, LATOPT and LONOPT and these are included in the request to UXML subsystem. The UXML Profile needs to have options to pass it as attributes in the PSSRR request.** []{#_Toc163121451.anchor}**Figure** **19**: UXML Options for ICASA Emergency Profile - The same rating and billing rules applies for ICASA GWs Example: Received: \\\\\ ### UXML The UXML interface allows for WASP applications to provide USSD services through the USSD Gateway. It uses Access Control List (ACLs) to limit the number of connections a WASP can have. UXML PDUs: LOGIN -- Login PDU External F5 Public IPs for WASPs \- 196.11.240.101 Port 8000 (GEAUSGRVA02) \- 196.11.242.101 Port 8000 (NLAUSGRVA02) \- 196.11.240.101 Port 8001 (GEPEP01) \- 196.11.242.101 Port 8001 (NLPEP01) External F5 Public IPs for Self Service \- 196.11.240.101 Port 9002, 9003, 9005 \- 196.11.242.101 Port 9001, 9006, 9004 ### USRT (USSD Scripting Runtime) **The USRT is an environment that allows USSD apps to be developed. The USSD Self service applications are built using the USRT environment.** - USRT is an environment provides USSD services - USSD services with USRT is developed using ASCE scripting - In addition, different types of widgets are used to retrieve data - USRT needs to be connected to the USSD VI Core runtime. - USRT account must be created linking to the initial ASCE Script - USRT account is similar to UXML account and takes on values such as routing code, MS timeout, application timeout, session timeout, MSISDN - USRT Routing code is registered against MARS ### MARS Redirect **MARS redirect allows an existing USSD session to be redirected to another USSD application using the USSD dial string. It uses the MARS PDR to initiate a redirect and GW will return an ARES PDU reply. If the redirected service is not running, then the subscriber will receive the "Service not running" error message. If the redirect dial string is not routed on MARS, then subscriber receive the "Service Code not supported"error.** []{#_Toc163121452.anchor}**Figure** **20**: MARS Redirect ### USRT (Inter Gateway Redirect) **The Inter gateway on USSD VI is implemented by creating another outgoing dialog against network. The ASCE script is used to maintain the session and a widget is used to relay requests between USRT and MAP DSM. This USRT runtime communicates to the local USSD VI core and go out via the MAP DSM, SNAP stack.** []{#_Toc163121453.anchor}**Figure** **21**: SS7 Inter Gateway Redirect ### USSD Push **CGW rating is required for USSD Push. This is based on the Routing Code and CPID. If the rating is not configured, the UXML error 12562 indicating push rating failed is returned.** **It does local billing and does not engage the OCS and produces ASN.1 records.** **The MSISDN ranges needs to be configured for USSD push as this also determines the way routing is done on the network.**  []{#_Toc163121454.anchor}**Figure** **22**: USSD Push Ranges ### UREC and CDRs **USSD transcripts are written to journal files on the USSD6 instance. The UREC runtime has a journal reader that reads from the journal and creates the ASN.1 format CDRs. The CDRs are shipped to EMM with a prefix filenames.** **USSD VI** - **GEUSSD6 (shipped from GEAURCRVA01)** - **NLUSSD6 (shipped from NLAURCRVA01)** **An extract of the ASN.1 PUsageRecords definition is shown below:** PUsageRecords DEFINITIONS IMPLICIT TAGS ::= BEGIN \--EXPORTS everything \-- \--IMPORTS enterprises FROM RFC1155-SMI \-- \--Pharos OBJECT IDENTIFIER ::= { enterprises 20753 } \-- PUsageRecord ::= \[0\] SEQUENCE { dateTimeStamp \[0\] DateTimeStamp, usageType \[1\] UsageType, customerInfo \[2\] CustomerInfo, originatingParty \[3\] OriginatingParty, transactionNumber \[4\] PrintableString( SIZE( 1..13 ) ), usage \[5\] PUsageDetails, ussdDialedString \[6\] IA5String OPTIONAL gateWayHost \[7\] PrintableString( SIZE( 1..13 ) ), billableTransaction \[8\] PrintableString( SIZE( 1..13 ) ) } PUsageDetails ::= CHOICE { usageUssd \[0\] UsageUssd, \... } UsageUssd ::= SEQUENCE { ussdChargeStart \[0\] UssdChargeStart, ussdChargeSegmentList \[1\] SET OF UssdChargeSegment, ussdChargeEnd \[2\] UssdChargeEnd } UssdChargeStart ::= SEQUENCE { dateTimeStamp \[0\] DateTimeStamp, source \[1\] PrintableString( SIZE( 1..20 ) ) } UssdChargeSegment ::= SEQUENCE { dateTimeStamp \[0\] DateTimeStamp, waspMSISDN \[1\] MsisdnString, waspRouteCode \[2\] PrintableString( SIZE( 1..20 ) ), ussdChargeElementList \[3\] SET OF UssdChargeElement } UssdChargeEnd ::= SEQUENCE { dateTimeStamp \[0\] DateTimeStamp, reason \[1\] UssdTerminationReason } UssdChargeElement ::= SEQUENCE { dateTimeStamp \[0\] DateTimeStamp, transactionNumber \[1\] PrintableString( SIZE( 1..13 ) ), pduType \[2\] UssdPduType, chargedParty \[3\] ChargedPartyIndicator, tarrif \[4\] PrintableString( SIZE( 1..20 ) ), billingClassification \[5\] PrintableString( SIZE( 1..50 ) ), chargeDuration \[6\] PrintableString( SIZE( 1..10 ) ), charge \[7\] PrintableString( SIZE( 1..10 ) ), payload \[8\] OCTET STRING( SIZE( 0..160 ) } CustomerInfo ::= SEQUENCE { msisdn \[0\] MsisdnString, imsi \[1\] IMSINumber OPTIONAL, customerType \[2\] CustomerType, cpid \[3\] CPID } MsisdnString ::= SEQUENCE { ton \[0\] TypeOfNumber, npi \[1\] NumberPlanIdentification, msisdn \[2\] PrintableString( SIZE( 1..20 ) ) } DateTimeStamp ::= SEQUENCE { date \[0\] DateStamp, time \[1\] TimeStamp } ***Examples of USSD Transcript:*** ***Example of ASN.1 decoded entry:*** **\"\*151\*63787355\#\",\"RBAUSGRVA01\",\"1\"}}\]** ### SNAP Stack The SNAP stack is implemented in Erlang and has: - - []{#_Toc163121455.anchor}**Figure** **23**: SNAP Layers UXML-X Interface ---------------- **The UXML (USSD over XML) interface is an API interface that allows external applications to provide USSD services. It is a connection-oriented interface and USSD GW acts as the server whilst the external application acts as the client. UXML-X allows for additional attributes to be included as part of the initial PDU sent to the external application. These attributes are defined in the UXML profile as part of options however they will also need to be available from USSD GW to UXML.** **The connection allows for asynchronous transactions and identified by the MSISDN and Transaction ID. The Request ID can be used by the external application to identify the transactions on their end. Each PDU needs to be separated by the 0xFF byte value.** **The connection is over TCP however TLS is also supported.** []{#_Toc163121456.anchor}**Figure** **24**: UXML-X ### Login **Upon a successful TCP/TLS connection establishment, the external application must issue a login PDU with User, Password, Remote Sys, Node ID and Cookie. User and Password are configured as in the UXML profile. Remote Sys is not used anymore and can be any arbitrary value. Node ID is equivalent to the ACL that is configured on the GW. Each ACL represents a TCP connection. Cookie can be any value and echoed back on the successful login response.** **If the credentials are incorrect or the Node ID is incorrect or in use, then a Status with error code will be returned.** **Example of login PDU and response** **Login PDU** **\\** **Login Response** **\\** ### UXML PDUs **Once the UXML connection is established and authenticated, the connection must be kept alive to receive transactions from the GW.** **CTRL PDUs must be issued periodically and/or replied to in order to keep the connection established. If after 10 minutes that there is no traffic or no CTRL PDU replies, then the GW will terminate the connection.** **Below is a sequence of PDUs that can flow over the established connection.** []{#_Toc163121457.anchor}**Figure** **25**: UXML Asynchronous Communications **New USSD sessions are defined by the PSSRR request and subsequent exchanges are defined by USSRR and USSRC. The final message is the PSSRC. However, the session can be aborted either from the MS/network or GW or by the external application. Once the transaction is closed or aborted, then any transactions thereafter will be indicated by the status code Bad Transaction ID. Timers exist based on which state the transaction is in, e.g.** **MS Timeout -- Time in seconds waiting for response from MS/network** **App Timeout -- Time in seconds waiting for response from external application** **Session timeout -- Max time in seconds that the session can survive on the USSD GW.** USSD NISE --------- **NISE (Network Initiated Service Engagement) allows a USSD pull service to be initiated against the subscriber as a USSD push service. An anchor script is recommended to host the initial service and from there, redirect to another service. This allows Advice of Charge for premium rated services to be engaged against the subscriber if and when necessary.** ### USSD NISE Implementation **The request is initiated by enqueuing a request to a DQS queue serviced by the NISE P-Flow™. The request would have the subscriber's MSISDN, the Account name initiating the request, the USSD dial string as well as an auth token.** **Once the request is received by the USSD NISE P-Flow™, it engages the PMAP USSD driver and emulates a PSSRR request towards MAP DSM. This is a common infrastructure that services normal USSD pull requests coming from the SNAP stack (Network). From there on, it will start a state machine, get RICA status, find MARS route, perform billing if any, and route it to the anchor application.** **The application will reply with a USSRR (USSD menu/option) which will result in USSD NISE performing a USSD Push (USSRR) against USSD Push TP for the subscriber's MSISDN.** **If the subscriber replies to the USSD push, USSRC will be received by USSD NISE and relay it back to the application. The GW will handle redirect if the anchor application decides to redirect to another application.** **The USSD interaction will then continue with USSRR-USSRC.** **If the application sends a PSSRC, USSD NISE will change it and perform a USSNR on the same transaction and the subscriber will see it as a last message.** **Below is a diagram depicting the flow of USSD NISE as explained in the above steps.** []{#_Toc163121458.anchor}**Figure** **26**: USSD NISE Implementation []{#_Toc163121459.anchor}**Figure** **27**: USSD NISE Implementation - Detailed Financial Reporting ------------------- **The USSD GW produces a daily recon file which contains a summary of the charging transaction records produced by all the USSD GWs.** **Each GW has a local process that collects the information by reading the journal file and storing the information in an SDACC.** **At 02h00 in the morning, the summary will run and fetches the information for the previous day from each GW and produces a summary per CPID as well as the billing type and billing party.** **Once the financial reporting file is completed, it is then SFTP to EMM.** **A sample of the file is shown below.** USSD GW Financial Recon Report - 20240324 CPID;TOTAL-SUCCESS;FORWARD-FREE;FORWARD-STANDARD;FORWARD-PREMIUM;FORWARD-CUSTOM;REVERSE-FREE;REVERSE-STANDARD;REVERSE-CUSTOM;NI-FREE;NI-STANDARD 23;2;0;0;0;2;0;0;0;0;0 21;67;0;0;0;23;0;0;8;0;0 20;11360;0;0;0;10835;0;0;134;0;0 18;161;0;0;0;156;0;0;0;0;0 17;568;0;0;0;568;0;0;0;0;0 15;34833;0;0;0;34641;0;0;4;0;0 13;1670;0;0;0;1598;0;0;9;0;0 12;1298;0;0;0;1273;0;0;0;0;0 11;601;0;0;0;568;0;0;1;0;0 0;69950098;64493897;1174070;3205;0;0;309996;0;1443632;77567 **The EMM server is** **IP: 10.200.11.143 (SFTP)** **Destination path:** /var/opt/mediation/MMStorage7/Server7/TT-Files/IN/VAS-COL/USSD/ **User: sms** General Functionality --------------------- ### USSD String Text Lengths **The** USSD string length per specification is defined as 182 characters using 7bit encoding. However on the initial transaction setup, the max characters is limited to 160 characters. This is due to the dialogue portion overhead. Subsequent menu exchanges that follow and then go up to 182 characters. Note that for UCS characters, this drops down to 70 unicode characters as the max is 70 octets. ### Error Friendly Messages **The following messages are friendly error messages when issues occur:** - **"Service code not supported"** - **No routing on MARS configured** - **"Service not running! Please try again later"** - **MARS is configured however application not connected** - **"Internal Service Error \"** - **Something broke but this usually comes with an error code** - **"Service execution error: timeout"** - **External application did not reply within time. Usually 10 seconds** - **"You have been barred from using this service."** - **Barred through barring manager** - **"Please note that this service cannot be used until you RICA this SIM. To RICA this SIM please go to where you bought it along with your ID and proof of address."** - **RICA Barred on VASHLR** - **"MSISDN not found. Please contact the call center."** - **MSISDN not found on VASHLR** - **"You have no funds available to support this request."** - **Insufficient funds** - **"Service temporarily unavailable. Please try later again later."** - **RICA Check Failed** - **Or other error** Deployment Overview ------------------- - WASP GW Pool services traffic that are handled by External WASP accounts - Self Service GW Pool services internal self-service traffic that are handled by EPI USE - 121 GW Pool services CallBack traffic - MFS GW Pool services mobile financial services traffic such as Xtratime and MoMo - ICASA GW Pool services push traffic for Upsell upon bundle depletion. This GW pool also handles \*112\# Traffic ### WASP Network Diagram The WASP related service codes such as \*111, \*123, \*120, \*130, \*135 and routed to the WASP GWs. The network diagram for the WASP USSD VI is given below: []{#_Toc163121460.anchor}**Figure** **28**: WASP USSD GW Pool Diagram Pantheon allows dynamic configuration of billing parameters such as rating per CPID, WASP MSISDN, time interval and amount (cents) per interval. ### Self Service Gateway Network Diagram The USSD Service code \*141, \*136, \*142, \*143, \*411 are routed to the Self Service GWs. Note that the GWs are connected to VASHLR to retrieve RICA Status. The network diagram for the Self Service USSD GW deployment is given below: []{#_Toc163121461.anchor}**Figure** **29**: Self Service USSD GW Pool Diagram ### 121Gateway Network Diagram The USSD Service code \*121, \*175 (Zone decommed) are routed to the 121 GWs. The network diagram for the 121 USSD GW deployment is given below: []{#_Toc163121462.anchor}**Figure** **30**: 121 USSD GW Pool Diagram ### MFS Gateway Network Diagram The service codes \*151 and \*155 is routed to this GW pool. []{#_Toc163121463.anchor}**Figure** **31**: MFS USSD GW Pool Diagram ### ICASA Gateway Network Diagram The ICASA Gateway servers have deployed with GW VI. The main USSD traffic is USSD NI traffic for upselling bundles and Xtratime Registration It is also deployed with the SNAP Stack. The network diagram for the ICASA USSD GW deployment, together with each of its interfacing nodes, is given below: []{#_Toc163121464.anchor}**Figure** **32**: ICASA USSD System Network Diagram ### PEP Server Deployment There are two servers dedicated for hosting the PEP UXML runtime. The servers are: - - The UXML on these two servers service the \*130\*7371\*, \*130\*737\#, \*130\*269\#, \*130\*7172582\# which are routed to the ISOL\_F01 account. The UXML runtimes are connected natively to the USSD GW. As part of the PEP feature, the PEP price plans are mapped from the service options obtained for VASHLR (IBF). These are then passed as **XML attributes** in the PSSRR request towards the application. Example: \\**\**\\ USSD Point Codes and Global Title --------------------------------- ### WASP GW Pool -- -- -- -- -- -- -- -- -- -- []{#_Toc163121423.anchor}**Table** **3**: WASP GW Point Code and GTs ### Self Service GW Pool -- -- -- -- -- -- -- -- -- -- []{#_Toc163121424.anchor}**Table** **4**: Self Service GW Point Code and GTs ### 121 GW Pool -- -- -- -- -- -- -- -- -- -- []{#_Toc163121425.anchor}**Table** **5**: 121 GW Point Code and GTs ### ICASA GW Pool -- -- -- -- -- -- -- -- -- -- []{#_Toc163121426.anchor}**Table** **6**: ICASA GW Point Code and GTs ### MFS GW Pool -- -- -- -- -- -- -- -- -- -- []{#_Toc163121427.anchor}**Table** **7**: MFS GW Point Code and GTs ### HLR Configs (ENAP) On HLR, there exists two configuration that is important for routing traffic to the GW. Firstly, a route needs to be defined and numbered. The IMSIND indicates if IMSI is included in the MAP Open. e.g. ENAP ID ENAP     EADD IMSIND   FCODE GW/VGT ------------ ---------- --------------- ---------- ------- ----------- ENAP3SC-0 0 4-27830001351 YES VGT \*175 ENAP3SC-1 1 4-27830111810 YES ENAP3SC-2 2 4-27830001413 YES VGT \*141 ENAP3SC-15 15 4-27830001361 NO VGT \*136 ENAP3SC-16 16 4-27830001414 NO VGT \*141 ENAP3SC-17 17 4-27830001415 NO VGT \*141 ENAP3SC-29 29 4-27830001202 YES VGT \*120 []{#_Toc163121428.anchor}**Table** **8**: HLR ENAP GT Route Config Secondly, the MSISDN range and Dial String combination is routed to a ENAP Number. One can see that the NS is the based dial string however if the MSISDN range is appended, it will indicate that only this range is routed. CHAR NS EADD               Description ------------ ------------ -------------------- ------------- ENAP3SC-0 151 4-27830001351 VGT \*175 ENAP3SC-0 155 4-27830001351 VGT \*175 ENAP3SC-15 136 4-27830001361 VGT \*136 ENAP3SC-15 137 4-27830001361 VGT \*136 ENAP3SC-16 141 4-27830001414 VGT \*141 ENAP3SC-16 142 4-27830001414 VGT \*141 ENAP3SC-16 143 4-27830001414 VGT \*141 ENAP3SC-29 180 4-27830001202 VGT \*120 ENAP3SC-29 1802783200 4-27830001202 VGT \*120 ENAP3SC-29 1802783209 4-27830001202 VGT \*120 ENAP3SC-29 1802783212 4-27830001202 VGT \*120 ENAP3SC-29 1802783213 4-27830001202 VGT \*120 []{#_Toc163121429.anchor}**Table** **9**: HLR ENAP NS Route Config A detailed printout can be requested from DCG team. Test Environment ---------------- There are currently two VMs for USSD GW testing. - FLAUSGRVS01 - GEAUSGRVS01 FLAUSGRVS01 - The flausgrvs01 does not have SIGTRAN IPs nor stack. It uses the stack on JHWASP03 (PC 2-32) - The base USSD code routed to this GW is \*930 - The GW has the standard MTN SA SDACC as well as the CallBack SDACC however only one type can be configured for testing. There is a separate USSD core runtime for ICASA testing. - USSD Rating is published from CGW from gemcgwrve101 or from jhmcgwrvs01. - The GW uses test VASHLR at geavhrrvu01 - Diameter billing is sent to DBRA at ecadrarvu01 - The MVNO's use this test GW for testing their self service applications. - Dev and Staging MoMo application is connected to this GW. - The public IP and port for UXML for 196.11.240.101 port 9000 GEAUSGRVU01 - This GW has a local stack. (SIGTRAN IPs 10.106.172.17/ 10.106.173.17). Point code 2-636, GT 27830006360 - The base USSD code routed to this GW is \*931 - The GW has the standard MTN SA SDACC - USSD Rating is published from CGW from gemcgwrve101 or from jhmcgwrvs01. - The GW uses test VASHLR at geavhrrvu01 - Diameter billing is sent to DBRA at ecadrarvu01 - EPIUSE connects to this GW and is used for self service testing Signaling Routing ================= Route on GT ----------- USSD traffic is routed on GT on the network. This applies for USSD Pull and for USSD Push The subsystem number 5 is defined on the USSD GWs. The subsystem number 147 gsmSCF can also be used for the USSD GW. - Routing on Global title routes based on the GT in the SCCP called address - Routing indicator of the Called Q713 must be set to 0 - USSD Requests are route on GT. Error Codes =========== USSD Error Codes ---------------- **Error Code** **Description** ---------------- ------------------------------------------------------------------------------ *12300* A general error has occurred *12307* Invalid Tariff Code *12308* No Funds *12309* Bad Tariff *12310* Bad Tariff Value *12311* MARS Disabled *12312* Billing Error *12313* MAP transaction abort by USSD (user) *12314* MAP transaction aborted by remote peer (provider) *12316* Session expired *12331* MARS routing already exists *12332* MARS routing not found *12333* Routing code not found *12334* Routing PID not found *12337* MARS redirection failed *12338* Source Routing Code not allowed to destination Routing code. 12352 Barring loading failed 12353 Barring invalid routing 12354 Barring configuration unavailable 12355 Barring range failed 12356 Unbarring range failed 12357 Barring address failed 12358 Unbarring address failed 12359 Unable to retrieve barring configuration 12361 Barring select failed 12362 Barring invalid regular expression 12367 RICA Barred 12368 RICA MSISDN not found 12369 RICA Error *12373* No response received from the SS7 network within the specified timeout value *12386* Unexpected MAP response received from remote peer *12390* Service initialization error *12391* Maximum processes reached *12392* Application timeout *12393* MS timeout *12394* Bad arguments *12395* Bad service module *12398* ACL name rejected *12390* Service initialization error 12391 Maximum process limit reached 12392 Application timeout 12393 MS timeout 12397 Maximum concurrent sessions exceeded 12399 Maximum rate exceeded []{#_Toc163121430.anchor}**Table** **10**: USSD Error Codes **Error Code** **Description** ---------------- -------------------------------------------------- *12501* Incomplete input data *12502* Bad arguments *12503* Bad match *12504* Unexpected data *12505* Timeout *12507* Bad or busy named link *12508* Process already registered using named link name *12509* Login failed *12510* Bad callback implementation *12511* Bad TID *12512* Encoding failed *12513* Network TCP failed *12514* No push agent *12515* Push mode not supported *12516* Push initialization failed *12517* Script ID not supported *12519* USSD phase not supported *12520* Redirection failed *12521* MAP aborted transaction *12522* MAP USSNC nack *12523* USSD phase 1 abort *12524* USSD phase 2 abort *12525* Unable to load script *12526* Script not found *12527* No running process *12528* Application timeout *12529* NIM timeout *12530* Session resumption application timeout *12531* Session resumption NIM timeout *12532* MSISDN push barred *12533* No Push Route (Number range not defined) *12534* Redirect not allowed *12550* Unknown Subscriber (Push) *12551* Call Barred (Push) *12552* Absent Subscriber (Push) *12553* System Failure (Push) *12554* Data Missing (Push) *12555* Unknown Alphabet (Push) *12556* USSD Busy (Push) *12557* MAP P-Abort (Push) *12558* MAP U-Abort (Push) *12559* Illegal Equipment (Push) *12560* Illegal Subscriber (Push) *12561* Push generic error *12562* Push Rating Failed []{#_Toc163121431.anchor}**Table** **11**: UXML Error Codes MAP Error Codes --------------- **Error Code** **Description** ---------------- -------------------------------------------------------------- *1* Unknown subscriber *6* Subscriber not service centre subscriber (Absent subscriber) *9* Illegal subscriber *27* Absent subscriber SM *34* System failure *35* Data missing *36* Unexpected data value *71* unknownAlphabet *72* USSD-busy []{#_Toc163121432.anchor}**Table** **12**: MAP Error Codes Glossary ======== --------------------- ---------------------------------------------------------------- **Term or Acronym** **Definition** ACL Access Control List AoC Advice of Charge BIP Backend Integration Part CDR Charge Data Record CGW Charging Gateway CPID Charging Party ID CSV Comma Separated Values CTRL Control DBRA Diameter Billing Routing Agent DQS Disk Queue Service DSM Dialogue State Machine EMM Ericsson Multi Mediation gsmSCF *GSM Service Control Function* HLR *Home Location Register* HLR-FE *HLR-Front End* ICASA *Independent Communications Authority South Africa* IMS *IP Multi-Media Subsystem* IP Internet Protocol M3UA MTP3 User Adaptation MAP Mobile Application Part MARS Mobile Application Routing Service MFS Mobile Financial Service MSISDN Mobile Station International Subscriber Digital Number MTN Mobile Telephone Network MVNO Mobile Virtual Network Operator NI Network Initiated NISE Network Initiated Service Engagement NFS Network File Sharing PDU Protocol Data Unit PMAP Pharos MAP PSSRC Process Structured Supplementary Services Request Confirmation PSSRR Process Structured Supplementary Services Request Request RICA Regulation of Interception of Communications Act SCCP Signalling Connection Control Part SDACC Service Data ACcess Controller SIP Session Initiation Protocol SNAP Signalling Network Access Point SFTP Secure File Transport Protocol STP Signalling Transfer Point TCAP Transaction Capabilities Application Part TCP Transmission Control Protocol TLS Transport Layer Security TP Transaction Processor UREC Usage Records USRT USSD Scripting Runtime USSD Unstructured Supplementary Services Data USSI USSD over IMS USSM USSD Service State Machine USSNC Unstructured Supplementary Services Notify Confirmation USSNR Unstructured Supplementary Services Notify Request USSRC Unstructured Supplementary Services Request Confirmation USSRR Unstructured Supplementary Services Request Request UXML USSD over XML VAS Value Added Services VASHLR VAS Home Location Register VPN Virtual Private Network WASP Wireless Application Service Provider --------------------- ---------------------------------------------------------------- Contact Details =============== Please get in touch with us for sales, support, and further information about this *Pharos* product. **Office Telephone**: +27 (0)11 475 1022 {8:00--17:00, GMT+2}\ **Support Mobile**: +27 (078) 886 6535 {24/7 service}\ **Fax**: +27 (0)11 475 1038\ **Email**:** ** [info\@pharos-avantgard.com](https://mail.google.com/mail/?view=cm&fs=1&tf=1&[email protected])\ **Website**: [www.pharos-avantgard.com](http://www.pharos-avantgard.com) **Head Office**\ First Floor, Willowbrook House\ Constantia Office Park\ Weltevreden Park\ Johannesburg, South Africa\ **GPS:** [-26.147341, 27.925641](https://www.google.co.za/maps/place/Pharos+Avantgard/@-26.1473367,27.9234526,17z/data=!3m1!4b1!4m8!1m2!10m1!1e1!3m4!1s0x1e95a07000000007:0xcc9a2348d03f3601!8m2!3d-26.1473415!4d27.9256413) **Postal Address**\ PO Box 149 \ Melrose Arch\ Johannesburg, 2076,\ South Africa