USSD Lua Service

ProcessUssdLuaService Module

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">
            <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>

Under normal installation, following service attributes apply:

Attribute Type Description
module SigtranApp::ProcessUssdLuaService [Required] The module name containing the Lua Service code.
libs ../apps/sigtran/lib Location of the module for ProcessUssdLuaService.
script_subdir String An optional subdirectory for scripts used by this service.
dcs_language Integer The default ussdDataCodingScheme_language.
If not present, a codec-specified default is applied.
menu_timeout Integer The default time (in seconds) after which the script will resume if no menu response is received.
error_message String The message which will be returned to the subscriber if an unhandled error occurs in then Lua script.
The internal script error will be written to the application log, but will not be sent to the subscriber.
success_message String The message which will be returned to the subscriber if the Lua script concludes successfully but returns a nil final result.
.triggers Array Array of trigger elements specifying Lua scripts to run for USSD Inbound Transactions.
.trigger Object Provisions a Lua script to run for a SIP Incall for a destination/source party.

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.

Attribute Type Description
ssn 1-255 This trigger applies for only USSD Transactions to this exact SCCP subsystem number.
(Default = Trigger applies to all SCCP subsystem numbers).
ussd_string_prefix String This trigger applies for only USSD ProcessUnstructuredSSRequest with content beginning with this sub-string.
(Default = Trigger applies to all ProcessUnstructuredSSRequest).
destination Hex Digits This trigger applies for only USSD ProcessUnstructuredSSRequest to this exact destination party.
(Default = Trigger applies to all ProcessUnstructuredSSRequest).
destination_prefix Hex Digits This trigger applies for only USSD ProcessUnstructuredSSRequest to destination parties starting with this prefix.
(Default = Trigger applies to all ProcessUnstructuredSSRequest).
source Hex Digits This trigger applies for only USSD ProcessUnstructuredSSRequest from this exact source party.
(Default = Trigger applies to all ProcessUnstructuredSSRequest).
source_prefix Integer This trigger applies for only USSD ProcessUnstructuredSSRequest from source parties starting with this prefix.
(Default = Trigger applies to all ProcessUnstructuredSSRequest).
script_name String The name of the Lua script to load (excluding the “.lua” suffix). The script should reside in the directory configured for the LogicApp’s lua_script_dir, or in the specified subdirectory if script_subdir is configured for this service library.

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 source address for matching is the first value found in:

The Process USSD Lua Service will iterate the configure 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 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:

Attribute Type Description
ussd Object Container for the parameters of the USSD request that we have received.
.ussd_string String The USSD string “sent” by the handset.
This is a copy of .process_ussd.ussdString_text.
.msisdn Integer The MSISDN source, being either the MSISDN digits from the ProcessUnstructuredSSRequest operation, or the Origination-Reference Digits from the MAP-Open.
This is the source address used for the trigger matching.
This is a copy of .process_ussd.msisdn_digits or .map_open.origination_reference_digits.
.process_ussd Object The decoded attributes of the ProcessUnstructuredSSRequest operation. Some of these attributes may be optional. Site-specific protocol variants may add additional parameters not documented here.
.ussdString Binary The raw encoded bytes of the USSD message content.
.ussdString_text String The decoded text of the ussdString in ASCII or Unicode.
.msisdn Binary The MSISDN (raw bytes) encded as MAP Address String.
.msisdn_digits HEX String The decoded digits of the MSISDN address.
.msisdn_noa Integer The decoded Nature Of Address of the MSISDN address.
.msisdn_npi Integer The decoded Numbering Plan Indicator of the MSISDN address.
.ussdDataCodingScheme Binary The USSD Data Coding Scheme (raw bytes) encded as USSD Call Broadcast Data Scheme.
.ussdDataCodingScheme_encoding Integer The decoded encoding of the ussdDataCodingScheme compound field.
.ussdDataCodingScheme_group Integer The decoded group of the ussdDataCodingScheme compound field.
.ussdDataCodingScheme_is_compressed 0/1 The decoded is_compressed of the ussdDataCodingScheme compound field.
.ussdDataCodingScheme_language Integer The decoded language of the ussdDataCodingScheme compound field.
.map_open Object The decoded attributes of the MAP-Open element within the TCAP’s MAP Dialogue PDU. Some of these attributes may be optional. Site-specific protocol variants may add additional parameters not documented here.
.destination_reference Binary The Destination Reference (raw bytes) encded as MAP Address String.
.destination_reference_digits HEX String The decoded digits of the Destination Reference address.
.destination_reference_noa Integer The decoded Nature Of Address of the Destination Reference address.
.destination_reference_npi Integer The decoded Numbering Plan Indicator of the Origination Reference address.
.origination_reference Binary The Origination Reference (raw bytes) encded as MAP Address String.
.origination_reference_digits HEX String The decoded digits of the Origination Reference address.
.origination_reference_noa Integer The decoded Nature Of Address of the Origination Reference address.
.origination_reference_npi Integer The decoded Numbering Plan Indicator of the Origination Reference address.

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:

Field Type Description
response Object Container for the USSD response parameters we are to send.
.ussdString Binary The encoded bytes for the USSD String content.
You will generally not specify this value, the service will encode it for you.
.ussdString_text String The user string in ASCII for Unicode that you wish to be encoded.
(Default = None)
.ussdDataCodingScheme_group Integer The encoding group associated with the string encoding.
(Default = 0)
.ussdDataCodingScheme_language Integer The encoding language associated with the string encoding.
(Default = service dcs_language or codec-determined default)
.ussdDataCodingScheme_is_compressed Integer The compression flag associated with the string encoding.
(Default = 0)
.ussdDataCodingScheme_message_class Integer The encoding message class associated with the string encoding.
(Default = 0)
.ussdDataCodingScheme_encoding Integer The encoding type associated with the string encoding.
(Default = 0)

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.

Parameter Type Description
response Object or String A simple “text/plain” string, or an Object with the same structure as the returned object described under “Script Return Parameters”.

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.

Parameter Type Description
notify Object or String A simple “text/plain” string, or an Object with the same structure as the returned object described under “Script Return Parameters”.

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]
...

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.

Parameter Type Description
menu Object or String A simple “text/plain” string, or an Object with the same structure as the returned object described under “Script Return Parameters”.
timeout Integer The timeout in seconds before the script resumes processing without input.
(Default = Service configured menu_timeout value).

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
...