USSD Notify Lua Service

Introduction

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

The UssdNotifyLuaService receives a UnstructuredSSNotify operation contained in a TCAP-RECV message from an instance of the SigtranApp which is configured to receive TCAP messages from an external client.

During the transaction, the UssdNotifyLuaService communicates with the SigtranApp using the TCAP-SEND message. See the definition of the TCAP-… messages.

Configuring UssdNotifyLuaService

The UssdNotifyLuaService 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::UssdNotifyLuaService" libs="/usr/share/n2ttg/apps/sigtran/lib/" script_dir="/var/lib/n2svcd/logic/ussd_gw">
                <triggers>
                  <trigger dest_ssn="120" ussd_string_prefix="*123#" script_key="123"/>
                  <trigger dest_ssn="120" destination="333" script_key="333"/>
                  <trigger dest_ssn="120" ussd_string_prefix="*444#" script_key="444"/>
                  <trigger dest_ssn="120" ussd_string_prefix="*666#" script_key="666"/>
                  <trigger dest_ssn="120" destination="777" script_key="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:

Parameter Name Type XML Type Description
module String Attribute [Required] The module name containing the Lua Service code: SigtranApp::UssdNotifyLuaService
libs String Element Location of the module for UssdNotifyLuaService.
(Default: ../apps/sigtran/lib)
script_dir String Attribute [Required] The directory containing scripts used by this service.
.triggers Array Element Array of trigger elements specifying Lua scripts to run for USSD Inbound Transactions.
.trigger Object Element Provisions a Lua script to run for a USSD Inbound Transaction for received ProcessUssdRequest operations.

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 origination addresses may contain hex digits A-F, and the matching is for destination_prefix and origination_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.

Parameter Name Type XML Type Description
ssn 1-255 Attribute 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 Attribute This trigger applies for only USSD UnstructuredSSNotify with content beginning with this sub-string.
(Default = Trigger applies to all UnstructuredSSNotify).
destination Hex Digits Attribute This trigger applies for only USSD UnstructuredSSNotify to this exact destination reference digits (in MAP Open).
(Default = Trigger applies to all UnstructuredSSNotify).
destination_prefix Hex Digits Attribute This trigger applies for only USSD UnstructuredSSNotify to destination reference digits (in MAP Open) with this prefix.
(Default = Trigger applies to all UnstructuredSSNotify).
origination Hex Digits Attribute This trigger applies for only USSD UnstructuredSSNotify from this exact origination reference digits (in MAP Open).
(Default = Trigger applies to all UnstructuredSSNotify).
origination_prefix Integer Attribute This trigger applies for only USSD UnstructuredSSNotify from origination reference digits (in MAP Open) with this prefix.
(Default = Trigger applies to all UnstructuredSSNotify).
script_key String Attribute The key for the Lua script to load. This is the file name 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 UnstructuredSSNotify 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 origination address for matching is:

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 ussdns_api = require "n2.n2svcd.ussdns_api"

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

        -- This sends UnstructuredSSNotify Result.
        -- In this case it uses a TCAP END to request that the transaction be closed.
        --
        ussdns_api.accept (true)
    end

    return n2svcd.handler (handler)

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

Attribute Type Description
.remote_sccp SCCP Address Object The far-end SCCP address, as per the TCAP-RECV Message.
.local_sccp SCCP Address Object The near-end SCCP address, as per the TCAP-RECV Message.
.text String The ussdString_text decoded message text copied from .ussd_notify.ussdString_text.
.ussd_notify Object The decoded attributes of the UnstructuredSSNotify 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) encoded 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) encoded 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 Table 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) encoded 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) encoded 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 if it will send back either:

In either of these cases it may choose to:

The script may either use explicit method calls to accept, decline, and close to perform this control.

If the script returns after having invoked accept or decline but without specifying the close parameter as true, then the still-open transaction will be closed by sending an empty TCAP END as if the close method had been called.

If the script returns without having involved accept, decline, or close, then the still-open transaction will be responsed-to by sending a ReturnResult in TCAP END as if the accept method had been called with close set to true.

The return value of the handler method should always be nil in any case. Returning a non-nil handler result for this service will always generate a warning message.

The UssdNotifyLuaService API

The Process USSD Service API can be loaded as follows.

    local ussdns_api = require "n2.n2svcd.ussdns_api"

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

.accept [Synchronous]

When a Lua script needs to perform extended processing, it may wish to confirm receipt of the notify before the script completes. This can be done with the accept method on the USSD Service API.

This method will send a ReturnResult for the UnstructuredSSNotify operation, within either a TCAP_END or a TCAP_CONTINUE, as specified using the close parameter.

Note: In future, this service may be extended to support follow-on interaction following a non-END accept.

The accept method takes a single close parameter.

Parameter Type Description
close Boolean Specify true to send the ReturnResult in TCAP END and close the transaction.
Specify false to send the ReturnResult in TCAP CONTINUE.
(Default = false, the transaction remains open)

The accept method returns the following object structure:

Parameter Type Description
controlled Boolean This field is currently always false to indicate that the session is no longer under control.
This may change in future, if follow-on processing is added.
reason Accept / Abandon Accept - The ReturnResult was successfully sent.
Abandon - The user abandoned with TCAP ABORT or TCAP Empty END prior to the accept attempt.

[Fragment] Example Early Accept with inbuilt transaction close:

    ...
    ussdns_api.accept (true)

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

[Fragment] Example Early Accept with separate transaction close:

    ...
    ussdns_api.accept ()
    ussdns_api.close ()

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

.decline [Synchronous]

The Lua service logic script may indicate to the handset that it did not accept the request. This can be done by using the decline method.

This method will send a ReturnError for the UnstructuredSSNotify operation, within either a TCAP_END or a TCAP_CONTINUE, as specified using the close parameter.

Note: In future, this service may be extended to support follow-on interaction following a non-END decline.

The decline method takes two parameters.

Parameter Type Description
error_code Integer An optional custom error code.
(Default = Call Barred - Error Code 25, or other configured default)
close Boolean Specify true to send the ReturnResult in TCAP END and close the transaction.
Specify false to send the ReturnResult in TCAP CONTINUE.
(Default = false, the transaction remains open)

The decline method returns the following object structure:

Parameter Type Description
controlled Boolean This field is currently always false to indicate that the session is no longer under control.
This may change in future, if follow-on processing is added.
reason Response / Abandon Response - The ReturnError was successfully sent.
Abandon - The user abandoned with TCAP ABORT or TCAP Empty END prior to the decline attempt.

[Fragment] Example Early Decline with inbuilt transaction close:

    ...
    ussdns_api.decline (ussdns_api.ERROR_ABSENT_SUBSCRIBER, true)

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

[Fragment] Example Early Decline with separate transaction close:

    ...
    ussdns_api.decline (17)
    ussdns_api.close ()

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

.close [Synchronous]

The service logic may use this method to conclude the subscriber interaction without sending back a final response message.

Calling close causes the USSD session (and associated TCAP transaction) to be closed immediately. If the script has not yet called accept or decline, then alling close will end the USSD session with an empty TCAP END and will not have returned neither ReturnResult nor ReturnError.

The close method takes no parameters.

The close method returns nil.

[Fragment] Example close session without acknowledging the Notify:

    ...
    -- Session is no longer required and we do not wish to acknowledge the Notify.
    ussdns_api.close ()
    ...

Constants

The following USSD constants are defined on the returned ussdns_api object.

USSD Reason Constants

The following constants are used to indicate the reason that a USSD interaction succeed or failed.

-- USSD Reason Constants.
ussdns_api.REASON_ACCEPT = 'Accept',
ussdns_api.REASON_DECLINE = 'Decline',
ussdns_api.REASON_ABANDON = 'Abandon',
ussdns_api.REASON_TIMEOUT = 'Timeout',

USSD Error Constants

The following constants are error code values for ReturnError, for example as passed into the decline method.

-- USSD Error Constants.
ussdns_api.ERROR_SYSTEM_FAILURE = 34,
ussdns_api.ERROR_DATA_MISSING = 35,
ussdns_api.ERROR_UNEXPECTED_DATA_VALUE = 36,
ussdns_api.ERROR_ABSENT_SUBSCRIBER = 27,
ussdns_api.ERROR_ILLEGAL_SUBSCRIBER = 9,
ussdns_api.ERROR_ILLEGAL_EQUIPMENT = 12,   
ussdns_api.ERROR_UNKNOWN_ALPHABET = 71,
ussdns_api.ERROR_USSD_BUSY = 72