USSD Lua Service

Introduction

The ProcessUssdLuaService is a service for initiating Lua scripts running within the LogicApp.

The ProcessUssdLuaService receives a ProcessUnstructuredSSRequest message from one or more instances of the SigtranApp which is configured to receive TCAP messages from an external client.

The ProcessUssdLuaService communicates with the SigtranApp using the TCAP-… messages.

Configuring ProcessUssdLuaService

The ProcessUssdLuaService is configured within a LogicApp.

    <?xml version="1.0" encoding="utf-8"?>
    <n2svcd>
      ...
      <applications>
        ...
        <application name="Logic" module="LogicApp">
          <include>
            <lib>../apps/logic/lib</lib>
          </include>
          <parameters>
            ...
          </parameters>
          <config>
            <services>
              <service module="SigtranApp::ProcessUssdLuaService" libs="../apps/sigtran/lib" script_dir="/var/lib/n2svcd/logic/ussd_gw">
                <menu_timeout>10</menu_timeout>
                <timeout_message>Custom Timeout</timeout_message>
                <success_message>Custom Success</success_message>
                <triggers>
                  <trigger dest_ssn="120" ussd_string_prefix="*123#" script_name="123"/>
                  <trigger dest_ssn="120" destination="333" script_name="333"/>
                  <trigger dest_ssn="120" ussd_string_prefix="*444#" script_name="444"/>
                  <trigger dest_ssn="120" ussd_string_prefix="*666#" script_name="666"/>
                  <trigger dest_ssn="120" destination="777" script_name="777"/>
                </triggers>
              </service>
            </services>
            <agents>
              ...
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

In addition to the Common LogicApp Service Configuration, note the following specific attribute notes, and service-specific attributes.

Under normal installation, the following service attributes apply:

Script Trigger Rules

Each USSD Incall trigger rule defines the name of a script which is ready to handle an inbound USSD Transaction.

Note that destination and source addresses may contain hex digits A-F, and the matching is for destination_prefix and source_prefix is case-insensitive. However, the string matching for ussd_string_prefix is case-sensitive.

Each trigger Object in the config.triggers Array is configured as follows.

Script Selection (USSD Transaction Request)

The Lua Script selection to execute for a USSD ProcessUnstructuredSSRequest takes into consideration the received content of the inbound TCAP_BEGIN transaction and/or the MAP content and/or the SCCP addressing information.

The destination address for matching is:

• The MAP_OPEN Destination Reference Digits.

The source address for matching is the first value found in:

• The ProcessUnstructuredSSRequest MSISDN, or
• The MAP_OPEN Origination Reference Digits.

The Process USSD Lua Service will iterate the configured trigger entries in the sequence in which they are configured and find the first trigger which matches the parameters of the received message.

Refer to the LogicApp configuration for more information on directories, library paths, and script caching parameters.

Script Global Variables

Scripts run with this service have access to the Common LUA Service Global Variables.

There are no service-specific global variables.

Script Entry Parameters (USSD Request)

The Lua script must be a Lua chunk which returns an n2svcd.handler, such as the following:

    local n2svcd = require "n2.n2svcd"
    local ussd = require "n2.n2svcd.ussd"

    -- The args contain the content of the ProcessUnstructuredSSRequest sent by the HLR.
    local handler = function (args)

        -- This sends UnstructuredSSRequest and expects a UnstructuredSSRequestResult.
        local input = ussd.menu ("1. Add-ons\n2. Packages\n3. Account Services\n4. Other Services", 2)
        if (type (input) == "nil") then
            return "No input provided.  Session over."
        end

        -- This sends UnstructuredSSNotify within the session.  No response is required.
        ussd.notify ("You chose option " .. input .. " thanks.")

        -- This closes the session by sending ProcessUnstructuredSSRequestResult.
        return "We'll send an SMS with your usage details."
    end

    return n2svcd.handler (handler)

The handler will be executed with a single ussd entry parameter which is an object with the following attributes:

Script Return Parameters (USSD Response)

The Lua script is responsible for determing the contents of the ProcessUnstructuredSSRequestResult which will be sent back to the subscriber at the conclusion of the session.

The simplest way to do this is by the return value given back to the service at the end of script execution.

For full control over the USSD response, the script return value may be a response object with the following attributes:

Alternatively, the script may return a string. This is the same as specifying .ussdString_text = (the given simple string) with all other attributes not specified.

Alternatively, the script may return nil in which case the configured default success_message string will be used with all other attributes not specified.

Example (returning a Table USSD Response):

    local n2svcd = require "n2.n2svcd"

    local handler = function (ussd)
        return ({ ussdString_text = "Bienvenue a la service", ussdDataCodingScheme_language = 3 })
    end

    return n2svcd.handler (handler)

Alternatively, a script may return a simple string instead of a Table.

Example (returning a String USSD Response):

    local n2svcd = require "n2.n2svcd"

    local handler = function (ussd)
        return "Welcome to the service"
    end

    return n2svcd.handler (handler)

This is a shorthand for ussdString_text = (Text Message) with all other values set to defaults.

Alternatively, a script may return nil.

Example (returning the default success message):

    local n2svcd = require "n2.n2svcd"

    local handler = function (ussd)
        return nil
    end

    return n2svcd.handler (handler)

In this case, the default-configured success_message for the service will be returned.

The ProcessUssdLuaService API

The Process USSD Service API can be loaded as follows.

    local ussd_api = require "n2.n2svcd.ussd"

It is not necessary to load the Process USSD Service API if you are only using the simple response mechanism described above. It is only required if you wish to use any of the extended features described below.

.response

When a Lua Script needs to perform extended processing, it may wish to send an early USSD response before the script completes. This can be done with the response method on the USSD API.

This method will send a ProcessUnstructuredSSRequestResult within a TCAP_END. The USSD transaction is over. Subsequent calls to response, notify, or menu are not permitted, and will generate a runtime script error.

The response method takes a single response parameter.

The response method returns true.

[Fragment] Example Early Response specifying Language:

    ...
    ussd_api.response ({ ussdString_text = "Bienvenue a la service", ussdDataCodingScheme_language = 3 })

    [post-processing logic after USSD transaction is terminated]
    ...

[Fragment] Example Early Response with default Language:

    ...
    ussd_api.response ("Welcome to the service")

    [post-processing logic after USSD transaction is terminated]
    ...

[Fragment] Example Early Response with default Message:

    ...
    ussd_api.response ()

    [post-processing logic after USSD transaction is terminated]
    ...

.notify

As part of the interaction, the Lua script may wish to send intermediate UnstructuredSSNotify messages to the subscriber. There is no response or confirmation for these messages.

The notify method on the USSD API will perform this function.

After calling the notify message, the USSD transaction is still in progress. Calls may still be made to notify, menu, or response.

The notify method takes a single notify parameter.

The notify method returns true.

[Fragment] Example Notification specifying Language:

    ...
    ussd_api.notify ({ ussdString_text = "En cours.  Patientez SVP.", ussdDataCodingScheme_language = 3 })
    ...
    [additional logic including further USSD interactions]
    ...

[Fragment] Example Notification with default Language:

    ...
    ussd_api.notify ("Working... please wait.")
    ...
    [additional logic including further USSD interactions]
    ...

.menu

As part of the interaction, the Lua script may wish to send intermediate UnstructuredSSRequest messages to the subscriber. The subscriber will be prompted to enter additional input which is returned to the service in a UnstructuredSSRequestResult message.

The script will suspend until the subscriber input is received, or until the configurable time value expires.

The menu method on the USSD API will perform this function.

After calling the menu message, the USSD transaction is still in progress. Calls may still be made to notify, menu, or response.

The menu method takes the following parameters.

The menu method returns the text string which was supplied by the subscriber in response to the menu prompt.

[Fragment] Example Menu with custom Timeout:

    ...
    local input = ussd_api.menu ("1. Account Balance\n2. My Usage\n3. Recharge History\n4. Recharge\n0. Back", 20)
    if (type (input) == "nil") then
        return "No input received to menu.  Session terminated."
    end

    if (input == "1") then
        ...
    end
    ...