USSD GW

This is an implementation an USSD gateway acting as a MAP Service Control Function (gsmSCF) and as a HLR at the same time. When communicating with a HLR or VLR, the YATE USSD GW acts as a gsmSCF. When communicating with a gsmSCF, the YATE USSDGW acts as a HLR. The purpose of this project is to:

• redirect USSD requests arriving either from user side or gsmSCF side to a SMPP client where they can be altered.
• act as a proxy for requests that need not be handled by SMPP clients or when the SMPP handling fails

MAP USSD description

In versions 2 and 3 of the GSM MAP protocol there are 3 operations used for USSD operations

• processUnstructedSS-Request
• unstructuredSS-Request
• unstrusturedSS-Notify

The are 2 scenarios for USSD operations:

• mobile initiated USSD requests
• network initiated USSD requests

A TCAP dialog used by USSD is always terminated by the network side.

Mobile initiated USSD requests

Mobile initiated USSD requests are USSD requests started by the mobile subscriber.

A USSD request is started when receiving a TCAP BEGIN message containing the processUnstructedSS-Request Invoke operation. The request can be handled by the VLR, HLR or a gsmSCF. If the VLR does not handle the request, it will transmit it to the HLR. The HLR can either handle it itself or it can transmit it to a gsmSCF for handling.

At this point, the network can either send a response to the request immediately or request additional information. In the first case, the handler of the request will send a TCAP End with processUnstructuredSS-Request ResultLast containing the result for the request. In the latter case, the network will send a TCAP CONTINUE with unstructuredSS-Request Invoke operation. The response of the mobile subscriber to this request will be passed to the network in a TCAP CONTINUE with unstructuredSS-Request ResultLast component. At this point, if the network decides that it has enough information for providing the response to the user, it will send a TCAP END with processUnstructuredSS-Request ResultLast.

Network initiated USSD requests

Network initiated USSD requests are USSD requests started by the network towards a certain subscriber.

Requests made by the network can be of one of two types:

• user interaction requests
• network notification requests.

User interaction requests are USSD requests that the network makes in which it requires some type of information back from the mobile subscriber. These are started by the network through a TCAP BEGIN containing an unstructuredSS-Request Invoke. The answer from the mobile subscriber will be received in a TCAP CONTINUE containing an unstructuredSS-Request ResultLast. If the network still wants to request further information, it will repeat the process. Otherwise, it will send a TCAP END to close the TCAP dialog.

Network notification requests are USSD requests in which the network only sends a notification to the user. This is achieved through by sending a TCAP BEGIN message containing a unstructuredSS-Notify invoke. The mobile subscriber side will only respond with a TCAP CONTINUE containing an empty unstructuredSS-Notify in order to signal that the notification was received. The network will close the TCAP dialog through TCAP END.

MAP USSD parameters

The following list describe common parameters used across all MAP USSD operations:

• destinationReference: this parameter will contain either an MSISDN or an IMSI. In the case of mobile originated USSD request, this will identify the user which made the request. In the case of network initiated requests, it will identify the mobile user to be contacted for this request.
• ussd-String: for processUnstructuredSS-Request Invoke it contains the dialed USSD code, for the result it would probably contain a message from the network detailing the result of the request. For unstructuredSS-Request Invoke it will contain a message asking for the user to choose some option and for the result it will contain the option chosen by the user. In the case of unstructuredSS-Notify, this parameter will only be present in the Invoke.
• ussd-DataCodingScheme: this is a parameter which specifies in which way the ussd-String parameter is encoded and it is present whenever ussd-String is present. E.g., this parameter would indicate if the ussd-String is encoded using GSM7bit encoding or UCS2.

System description

System design

In order to provide the required functionality, the system makes use of the following YATE components:

• the SS7 stack present in YATE
• the camel_map module which decodes/encodes MAP messages coming from the SS7 network to/from internal YATE messages containing MAP operations in XML form. Together with the SS7 layer this provides MAP connectivity with HLR/gsmSCF.
• the ussd_map module which takes internal MAP messsages decoded by the camel_map moduled and translates them to internal USSD messages. This module acts as gsmSCF towards a HLR and as a HLR towards a gsmSCF.
• the SMPP stack present in YATE (ysmpp module) which is able to catch internal USSD messages and transmit them over SMPP. It also translates SMPP messages into internal USSD messages.
• requests for new USSD sessions will go through routing to decide who should handle the request.

The following sections detail the behaviour of the system in the different USSD scenarios.

MO USSD handling

A user initiated USSD session is handled according to the following schema:

1. HLR sends a processUnstructuredSS-Request (Invoke) for code *100#. camel_map decodes the ussd-String into ussd-Text=*100#.
2. the ussd_map module (gsmSCF side) processes the request received from the HLR and emits a call.route message with called=*100#.
3. After ussd_map module successfully dispatched the call.route message, it generates a ussd.execute message with the callto parameter set to the value returned from routing. ussd_map dispatches the ussd.execute message.
4. The ysmpp module catches the ussd.execute message and if the callto param value starts with ysmppserver/ and with it it builds a deliver_sm message that it will send it to the target specified in callto parameter after the module prefix ysmppserver/.
5. The ysmpp module receives and process the received submit_sm message.
6. The ysmpp module will send a call.route message with the called=*100#.
7. The ysmpp module emits a ussd.execute message with callto=retvalue from call.route message.
8. The ussd_map module (HLR part) processes the ussd.execute message and if it is the target of the message, meaning that callto starts with ussd_map/. From that message it will build a map.message that it will send to the gsmSCF as a processUnstructuresSS-Request (Invoke) MAP message.
   NOTE: From here on, the gsmSCF could handle the request in one of two distinguished cases: one where the gsmSCF requires interaction with the mobile subscriber and one where the gsmSCF just needs to respond to the user request. The following steps detail the former case.
   
9. gsmSCF sends an unstructuredSS-Request (Invoke) to request further information.
10. The ussd_map module (HLR part) processes the unstructuredSS-Request (Invoke) message and emits an ussd.update message.
11. The ysmpp module receives the ussd.update message and confirms to the SMPP client that the message sent in step 5 was processed.
12. The SMPP client should confirm the processing of the SMPP message sent in step 4.
13. The ysmpp module sends a deliver_sm message to the SMPP client with the menu received in ussd.update message.
14. The SMPP client should send a submit_sm message with the received menu.
15. The ysmpp module receives the submit_sm message from SMPP client and emits a ussd.update message.
16. The ussd_map module (SCF part) process the ussd.update message and sends an unstructuredSS-Request (Invoke) towards the HLR.
    The time in which the mobile subscribers responds can be quite long.
    
17. The HLR sends unstructuredSS-Request (ResultLast) to USSD gateway when receiving the response from the mobile subscriber.
18. The ussd_map module (SCF part) processes the message and emits a ussd.update message.
19. ysmpp module processes the ussd.update message and sends submit_sm rsp to SMPP client to confirm the reception of the message sent on step 14.
20. The SMPP client should send a deliver_sm rsp to confirm the message received on step 13.
21. The ysmpp module will send a deliver_sm message to SMPP clients which will contain user's response.
22. The SMPP client should send a submit_sm message to SMPP server which will contain the message received on step 21.
23. The ysmpp module receives the submit_sm message and emits a ussd.update message.
24. The ussd_map module (HLR part) receives the ussd.update message and sends the unstructuredSS-Request (ResultLast) to gsmSCF.
    NOTE: Steps between 9 and 24 can be repeated.
    
25. The gsmSCF sends processUnstructuredSS-Request (ResultLast) for the initial user request.
26. The ussd_map module (HLR part) processes the processUnstructuredSS-Request (ResultLast) and sends a ussd.finalize message.
27. The ysmpp module receives the ussd.finalize message and sends a submit_sm rsp for the message received on point 22 or 5.
28. The SMPP client should send a deliver_sm rsp for the message received on point 21 or 4.
29. The ysmpp module sends a deliver sm + last message indication to SMPP client.
30. The SMPP client should send a submit sm + last message indication to SMPP server.
31. ysmpp module receives submit_sm message and sends a ussd.finalize message.
32. ysmpp module sends submit_sm rsp to confirm the message received on step 31.
33. SMPP client should send a deliver_sm rsp to confirm the message received on step 29.
34. The ussd_map module (SCF part) processes the ussd.finalize message and sends processUnstructuredSS-Request (ResultLast).

Network initiated USSD Request

A network initiated USSD session is handled as described in the following figure:

1. gsmSCF sendsunstructuredSS-Request (Invoke) to USSD Gateway (HLR part) to present a menu for MSISDN 0015559191.
2. The ussd_map module (HLR part) processes the unstructuredSS-Request (Invoke) message and emits a call.route message with called=0015559191.
3. After ussd_map module successfully dispatched the call.route message, it generates a ussd.execute message with callto set to the route returned in the return value of the call.route message and dispatches an ussd.execute message.
4. The ysmpp module catches the ussd.execute message and if the callto param value starts with ysmppserver/ and with it it builds a deliver_sm message that it will then send to the target specified in the callto'" parameter after the ysmppserver module prefix.
5. The SMPP client should send a submit_sm message towards SMPP server.
6. The SMPP server processes the received submit_sm message and dispatches a call.route message.
7. After successfully dispatching of call.route message the SMPP server will dispatch a call.execute message.
8. The ussd_map module (SCF part) process the ussd.execute message and sends an unstructuredSS-Request (Invoke) towards the HLR.
   The time to receiving a response from the user after gsmSCF has requested user interaction could be possibly quite long.
   
9. The HLR sends unstructuredSS-Request (ResultLast) to USSD gateway
10. The ussd_map module (SCF part) processes the message and emits a ussd.update message.
11. ysmpp module processes the ussd.update message and sends submit_sm rsp to SMPP client to confirm the reception of the message sent on step 5.
12. The SMPP client should send a deliver_sm rsp to confirm the message received on step 4.
13. The ysmpp module will send a deliver_sm message to SMPP clients which will contain user's response.
14. The SMPP client should send a submit_sm message to SMPP server which will contain the message received on step 13.
15. The ysmpp module receives the submit_sm message and emits a ussd.update message.
16. The ussd_map module (HLR part) receives the ussd.update message and sends the unstructuredSS-Request (ResultLast) to gsmSCF.
    NOTE: Steps between 1 and 16 can be repeated.
    
17. The gsmSCF sends TCAP END in order to finish the USSD session.
18. The ussd_map module (HLR part) processes the TCAP END and sends a ussd.finalize message.
19. The ysmpp module receives the ussd.finalize message and sends a submit_sm rsp for the message received on point 14.
20. The SMPP client should send a deliver_sm rsp for the message received on point 13.
21. The ysmpp module sends a deliver sm + last message indication to SMPP client.
22. The SMPP client should send a submit sm + last message indication to SMPP server.
23. ysmpp module sends submit_sm rsp to confirm the message received on step 22.
24. SMPP client should send a deliver_sm rsp to confirm the message received on step 21.
25. ysmpp module receives submit_sm message and sends a ussd.finalize message.
26. The ussd_map module (SCF part) processes the ussd.finalize message and sends END.

Fallback/Proxy mode

The following images detail scenarios where the USSD GW is instructed to do failover.

The picture above details a failover scenario for when an HLR sends processUnstructuredSS-Request (Invoke) (1).

NOTES:

• The read circles in the above picture represent points in handling where a fallback decision can be made.
• A fallback decision can be made only if in all previous fallback decision points the necessity for failover was determined to be false.
• U1 and U2 represent SMPP message responses.

Decision points where ussd_map will determine the need for failover:

• E1: Routing procedure does not return a valid route (call.route returns with false or an error) or routing decision indicates a failover route (routing return a route starting with prefix ussd_map/)
• E2: ussd.execute message fails to be processed (in this case by the ysmpp module)
• E3: SMPP server received an SMPP error for deliver_sm message.
• E4: SMPP client received an SMPP error for submit_sm message.
• E5: The call.route message emitted by ysmpp does not return a valid route (call.route returns with false or an error).
• E6: ussd.execute message fails to be processed (in this case by the ussd_map module).

Network initiated USSD session fallback.

The picture above details a failover scenario for when a gsmSCF sends a "unstructuredSS-Request/unstructuredSS-Notify (Invoke) (1).

NOTES:

• The read circles in the above picture represent points in handling where a fallback decision can be made.
• A fallback decision can be made only if in all previous fallback decision points the necessity for failover was determined to be false.
• U1 and U2 represent SMPP message responses.

Decision points where ussd_map will determine the need for failover:

• E1: Routing procedure does not return a valid route (call.route returns with false or an error) or routing decision indicates a failover route (routing return a route starting with prefix ussd_map/)
• E2: ussd.execute message fails to be processed (in this case by the ysmpp module)
• E3: SMPP server received an SMPP error for deliver_sm message.
• E4: SMPP client received an SMPP error for submit_sm message.
• E5: The call.route message emitted by ysmpp does not return a valid route (call.route returns with false or an error).
• E6: ussd.execute message fails to be processed (in this case by the ussd_map module).

The SMPP USSD gateway will also be bypassed when the ussd_map module is configured to do failover for all requests.

Any type of SMPP error received either in the result for the ussd.execute or in the first message back from SMPP that does not have a mapping on MAP will lead to the ussd_map module doing failover. Errors that would generate a failover are errors like timeout, session ended abnormally, unknown errors, congestion errors.

Once ussd_map decides that failover should be done, it will use the original received message from the HLR (MO case)/gsmSCF (MT case) and it will only alter the called address to be the one of the gsmSCF/HLR set for the failover.. The calling address will remain the one received from HLR/gsmSCF, the idea being that for the first message we want to pretend that we are the original gsmSCF/HLR. When the receiving end of this message will want to respond, it will use the calling address from the message. Seeing that the ussd_map module set it to the original calller's address, further messages exchanged in that dialog between HLR and gsmSCF will not pass through USSD GW again.

References

• Mobile Application Part (MAP) specification: ETSI TE 129 002