Difference between revisions of "USSD GW"

From ss7api.null.ro
Jump to: navigation, search
(→‎ussd.finalize)
(→‎SMPP USSD description)
Line 55: Line 55:
 
== SMPP USSD description ==
 
== SMPP USSD description ==
  
 +
'''TO DO'''
  
 
== System description ==
 
== System description ==

Revision as of 18:01, 13 November 2013

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


Contents

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.

SMPP USSD description

TO DO

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.


Mobile originated USSD handling

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


User initiated ussd.png


  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:

Network initiated ussd.png

  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.


User initiated failover.png

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.

Network initiated failover.png

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.


Internal message API

This section documents the YATE messages used internally by the USSD GW.

call.route
ussd.execute

This message is used to begin a new USSD session:

  • on SMPP, if the message is directed to the ysmpp module
  • on MAP if the message is directed to the ussd_map module

This message is sent by either ussd_map module or ysmpp module after successful routing stage. In case of the ussd_map module, this is message is sent if the routing stage did not indicate failover necessity.


Parameters:

  • callto:
    • type : string
    • It specifies the target module to process the message. The string should start with 'ysmppserver/' for the ysmpp" module and with ussd_map/ for the ussd_map module.
  • id:
    • type: string
    • Identifier for the USSD session used by the dispatcher of the message.
  • called:
    • type: string
    • It specifies the value on which destination is determined. For a MO USSD session, this parameter will contain the decoded USSD string (USSD request code). For a MT USSD sessions, this parameter will contain the destination MSISDN.
  • callednumtype:
    • type: keyword
    • It specifies type (NAI) of the called parameter. It is used only when called is a MSISDN
  • callednumplan:
    • type: keyword
    • Numbering plan for the number specified by the called parameter. It is used only when called is a MSISDN.
  • caller:
    • type: string:
    • Identifies the caller in this USSD session. For MO USSD it can be the MSISDN (if present) . ussd_map will set the the calling party address GT in this parameter for MT case or if MSISDN is not specified for MO case.
  • callernumtype:
    • type: keyword
    • It specifies type (NAI) of the caller parameter.
  • callernumplan:
    • type: keyword
    • Numbering plan for the number specified by the caller parameter.
  • operation_type:
    • type: keyword
    • The type of USSD operation that fired this message.
  • text_encoding:
    • type: hexified string
    • The MAP USSD data coding scheme
  • text_encoded:
    • type: hexified string
    • The encoded USSD string
  • text:
    • type: string
    • The decoded USSD string conforming to the USSD data coding scheme.
  • imsi:
    • type: string
    • IMSI value if available.
  • hlr:
    • type: string
    • It specifies the HLR GTT if that information was available.
  • hlr.nature:
    • type: keyword
    • It specifies HLR GTT nature (NAI)
  • hlr.plan:
    • type: keyword
    • It specifies HLR GTT numbering plan
  • vlr:
    • type: string
    • It specifies the VLR GTT if that information was available.
  • vlr.nature:
    • type: keyword
    • It specifies VLR GTT nature (NAI)
  • vlr.plan:
    • type: keyword
    • It specifies VLR GTT numbering plan
  • gsmscf:
    • type: string
    • It specifies the gsmSCF GTT if that information was available.
  • gsmscf.nature:
    • type: keyword
    • It specifies gsmSCF GTT nature (NAI)
  • gsmscf.plan:
    • type: keyword
    • It specifies gsmSCF GTT numbering plan
  • destination_reference:
    • type: string
    • MSISDN or IMSI specified in the DestinationReference TCAP MAP parameter.
  • destination_reference.nature:
    • type: keyword
    • It specifies DestinationReference nature (NAI)
  • destination_reference.plan:
    • type: keyword
    • It specifies DestinationReference numbering plan
  • msisdn:
    • type: string
    • MSISDN
  • alert_pattern:
    • type: string
    • Alert Pattern parameter as received in the USSD MAP message.

Note:

  • The hlr/vlr address represents:
    • the address from which the message was received (if it can be determined) for MO USSD session.
    • the address where the message should be sent for MT USSD session.

Returned parameters:

  • peerid:
    • type: string
    • Identifier assigned for this USSD session by the entity that processed this message.
  • error:
    • type: keyword
    • Error returned if the message was not processed.

Processing of this message will return failure:

  • if the message will not be processed
  • if the 'id' parameter is missing.
  • in case of processing error
  • in case of congestion
ussd.update

This message is used for transmitting USSD messages during a USSD session. This type of message will be used after the initial stage of creating the session through ussd.execute has succeeded.

When receiving this message:

  • the ussd_map module will generate a TCAP CONTINUE message
  • the ysmpp module will generate a SMPP deliver_sm if it acts as a server (as in the case of the USSD GW) or submit_sm if it acts as a SMPP client.


Parameters:

  • id:
    • type: string
    • USSD session identifier of the sending side of the message
  • peerid:
    • type: string
    • USSD session identifier for the module that should process this message
  • operation_type:
    • type: keyword
    • The type of operation that fired this message.
  • text_encoding:
    • type: hexified string
    • The MAP USSD data coding scheme
  • text_encoded:
    • type: hexified string
    • The encoded USSD string
  • text:
    • type: string
    • The decoded USSD string conforming to the USSD data coding scheme.
  • error:
    • type: keyword
    • Error received from one the USSD session endpoints. It might be a MAP error when HLR/gsmSCF/ failed to process a request or SMPP error when the SMPP client failed to process a request.

Returned parameters:

  • error:
    • type: keyword
    • Error code if this message failed to be processed.

Points of failure:

  • The USSD session specified by peerid parameter cannot be found by the processing side.
  • Processing of this message will be refused if it is received after a ussd.finalize message.
  • Processing of this message will return an error if there are mandatory parameters missing of if the parameters specify a values not allowed in the context of the USSD session (e.g., sending a processUnstructuredSS-Request inside a ussd.update message)

ussd.finalize

This message is used to signal the termination of the USSD session. Successful processing of this message means that the USSD session was terminated and is no longer available.

When receiving this message:

  • the ussd_map module will generate a TCAP END/ABORT message depending upon the parameters received. A message containing an error that does not map to a MAP error will generate a TCAP ABORT.
  • the ysmpp module will generate a SMPP deliver_sm if it acts as a server (as in the case of the USSD GW) or submit_sm if it acts as a SMPP client, a message that will usually contain a last message indication.

Parameters:

  • id:
    • type: string
    • USSD session identifier of the sending side of the message
  • peerid:
    • type: string
    • USSD session identifier for the module that should process this message
  • operation_type:
    • type: keyword
    • The type of operation that fired this message.
  • text_encoding:
    • type: hexified string
    • The MAP USSD data coding scheme
  • text_encoded:
    • type: hexified string
    • The encoded USSD string
  • text:
    • type: string
    • The decoded USSD string conforming to the USSD data coding scheme.
  • error:
    • type: keyword
    • Error received from one the USSD session endpoints. It might be a MAP error when HLR/gsmSCF/ failed to process a request or SMPP error when the SMPP client failed to process a request.

Returned parameters:

  • error:
    • type: keyword
    • Error code if this message failed to be processed.

Points of failure:

  • The USSD session specified by 'peerid parameter cannot be found by the processing side.
  • Processing of this message will return an error if there are mandatory parameters missing of if the parameters specify a value not allowed in the context of the USSD session

Configuration

Monitoring

References

  • Mobile Application Part (MAP) specification: ETSI TE 129 002
Retrieved from "https://ss7api.null.ro/index.php?title=USSD_GW&oldid=466"
Personal tools
Namespaces

Variants
Actions
MAP & CAMEL XML Interface
Diameter XML Interface
MAP and CAMEL operations
Diameter interfaces
Examples
Resources
Navigation
Toolbox