USSD (WIP)

Introduction

Helium and the Helium DSL provides built-in functionality for USSD integration. The DSL provides an interface for these integrations through a USSD function annotation, and MezUssdMenu and MezUssdMenuOption built-in objects.

Functions that are annotated with @USSD serve as integration endpoints that are available to be executed for inbound requests from USSD gateways. These functions then return an instance of MezUssdMenu that describes the next menu structure that is to be presented to the end user during his USSD session.

@USSD

One of the following signatures is expected for USSD annotated functions:

@USSD("description")
MezUssdMenu processUssd(int menu, int selection)

@USSD("description")
MezUssdMenu processUssd(int menu, int selection, json gatewayArgs)

The "description" values in the example above and below represents a unique string literal identifier for the specific USSD function. More than one USSD method can be included as long as the descriptions are unique. Further more the descriptions are used as path parameter values in Helium's internal API and can thus be used to route inbound calls to the correct DSL USSD functions.

The method parameters above represents the following:

An integer that indicates the menu from which the USSD request originated. For an initial call a value of 0 is sent.

selection:

An integer that indicates the menu option that was selected for the current request. For an initial call a value of 0 is sent.

gatewayArgs:

A json parameter that is populated with all additional query parameters sent by the gateway to Helium. At present the only gateway that is supported is Vodacom USSD gateway. Note that this parameter is optional. The following shows an example of a value sent for this parameter using the Vodacom USSD gateway:

{
    "msisdn":"27763303624",
    "request":"*120*247253#",
    "provider":"Vodacom",
    "ussdSessionId":"2496158596"
}

The json attributes listed in the above example represent the following and can be used in the DSL logic for more context or can be ignored.

Attribute	Description
msisdn	The msisdn / mobile number that initiated the USSD session and request.
request	A field that describes the request made by the mobile end user. For requests where free text answers are provided, this field will contain the provided free text value.
provider	Name of the USSD provider. For the Vodacom gateway it will always be "Vodacom".
ussdSessionId	An integer value sent by the gateway that identifies the current USSD session. Note that at present Helium does not do any internal tracking of USSD sessions.

MezUssdMenu and MezUssdMenuOption

The DSL provides the MezUssdMenu and MezUssdMenuOption built-in objects that are used to structure return values for any USSD annotated functions. The details of these objects are as follows:

object MezUssdMenu {

    // Integer representing the id of this menu
    // This id is sent back to the DSL as the 'menu' argument for calls originating from this menu
    // Helium does not do any validation or uniqueness of this value
    int menuId;

    // The header text / question for this menu
    string headerText;

    // Flag indicating whether this menu is to be used for a free text question
    // By default (for both null and 'false' values) it is assumed that the menu is not a free text menu
    bool isFreeText;
}

object MezUssdMenuOption {

    // The text for this menu option
    string text;

    // The order for this menu option
    // This value is sent back to the DSL as the 'selection' argument for calls that 
    // originated from user requests that selected this option
    int order;

    // The menu options that are available for this menu
    // Menus that require free text input will not have any menu options
    @ManyToOne
    MezUssdMenu menu via menuOptions;
}

Multiple Option Example

For this example a workflow that used multiple choice USSD menus is demonstrated. The following screenshots demonstrate the USSD menu structure that is implemented in this example.

The following source code shows the implementation in the DSL:

Mode additions

@NotTracked
persistent object UssdRequest {
    datetime createdOn;
    int menu;
    int selection;
    string workflow;
    json params;
}

Presenter / Service additions

@USSD("options")
MezUssdMenu processUssd(int menu, int selection, json params) {

    // Keep a record of this request
    recordUssdRequest(menu, selection, params, "options");

    // Request originates from menu 0, this is the initiating request
    if(menu == 0) {
        return constructMenuOne();
    }
    
    // Request originates from menu 1
    if(menu == 1 && selection == 1) {
    	return constructMenuTwo();
    }
    
    // Requests originate from menu 2
    if(menu == 2 && selection == 1) {
    	return constructMenuThree();
    }

    if(menu == 2 && selection == 2) {
    	return constructMenuOne();
    }

    // We don't expect to ever encounter this but if we do it will show as an error on the device
    return null;
}

// Keep track of request simply for introspection
void recordUssdRequest(int menu, int selection, json params, string workflow) {
    UssdRequest request = UssdRequest:new();
    request.createdOn = Mez:now();
    request.menu = menu;
    request.selection = selection;
    request.params = params;
    request.workflow = workflow;
    request.save();
}

// Construct menu 1 for multiple option USSD workflow
MezUssdMenu constructMenuOne() {
    MezUssdMenu menu = MezUssdMenu:new();
    menu.headerText = "Can you answer the question?";
    menu.menuId = 1;

    MezUssdMenuOption option1 = MezUssdMenuOption:new();
    option1.text = "Yes I can";
    option1.order = 1;

    menu.menuOptions.append(option1);
    return menu;
}

// Construct menu 2 for multiple option USSD workflow
MezUssdMenu constructMenuTwo() {
    MezUssdMenu menu = MezUssdMenu:new();
    menu.headerText = "Can you answer the second question?";
    menu.menuId = 2;

    MezUssdMenuOption option1 = MezUssdMenuOption:new();
    option1.text = "Yes I can";
    option1.order = 1;

    MezUssdMenuOption option2 = MezUssdMenuOption:new();
    option2.text = "Take me back to the first one!";
    option2.order = 2;

    menu.menuOptions.append(option1);
    menu.menuOptions.append(option2);
    return menu;
}

// Construct menu 3 for multiple option USSD workflow
MezUssdMenu constructMenuThree() {
    MezUssdMenu menu = MezUssdMenu:new();
    menu.headerText = "Congratulations, you pass the test!";
    menu.menuId = 3;
    return menu;
}

Introduction

Overview

@USSD

menu:

selection:

gatewayArgs:

MezUssdMenu and MezUssdMenuOption

Multiple Option Example

Free Text Example

Additional Considerations

0 Comments