USSD Support

Unstructured Supplementary Service Data (USSD) is a communication technology that is used by GSM cellular telephones to send text messages between a mobile phone and an application program in the network.

USSD establishes a real-time session between the mobile phone and the application that handles the service.

IBM MobileFirst™ Platform Foundation uses the HTTP/HTTPS protocol to communicate with the USSD gateway, which is a third-party entity. The USSD gateway routes USSD messages to the MobileFirst Server. Adapter procedures need to be defined to process these requests and send back a response. You need to define USSD event handler to route the requests to the adapter procedure that handles those requests.

Note: For more information, see the WL.Server.createUSSDEventHandler and WL.Server.createUSSDResponse APIs in WL.Server.

Here is a sample flow for USSD:

A mobile user enters a USSD short code, such as *123#.
The request is forwarded to a USSD gateway.
The gateway maps the short code to a known URL provided by IBM MobileFirst Platform Foundation, creates the USSD session, and forwards the request to the URL.
A MobileFirst adapter with the matching filter receives the request and responds to the gateway request with the configurable USSD menu/simple text.

Description of the USSD flow between the gateway and the mobile device.

Configuration required at USSD Gateway

http://<hostname>:<port>/<contextroot>/ussd

This URL can be followed by parameters specific to the gateway. Refer to your USSD Gateway documentation for more details.

Server-side APIs required at MobileFirst adapter side

To create a filter to process the USSD request:

WL.Server.setEventHandlers([ WL.Server.createUSSDEventHandler({
	'shortcode' : '*123#'
}, handleUSSDRequest) ]);

To send back a response:

WL.Server.createUSSDResponse("This is my response", "text/plain", true))

Security

To prevent entities with malicious intent from sending requests to the MobileFirst Server via a USSD URL, the USSD feature is protected by default. The authenticationConfig.xml file is configured to reject all requests to the USSD servlet with a rejecting login module. To allow restricted access to USSD, MobileFirst administrators must modify the authenticationConfig.xml file with appropriate authenticator and login modules, or comment the URL pattern /ussd* to allow unrestricted access. For example, the following configuration in the authenticationConfig.xml file ensures that only requests with a specific user name in the header of the HTTP request are allowed:

<staticResources>
    <resource id="subscribeServlet" securityTest="SubscribeServlet">
        <urlPatterns>/subscribeSMS*;/ussd*</urlPatterns>
    </resource>
    ...  
  </staticResources> 

  <securityTests>
    <customSecurityTest name="SubscribeServlet">
      <test realm="SubscribeServlet" isInternalUserID="true"/>
    </customSecurityTest>        
    ...
  </securityTests> 

  <realms>
    <realm name="SubscribeServlet" loginModule="headerLogin">
      <className>com.worklight.core.auth.ext.HeaderAuthenticator</className>  
    </realm>
    ...  
  </realms>

  <loginModules>
    <loginModule name="headerLogin">
      <className>com.worklight.core.auth.ext.HeaderLoginModule</className>
      <parameter name="user-name-header" value="username"/>  
    </loginModule>
    ...  
  </loginModules>