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:

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.

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 MAP_OPEN Destination Reference Digits.

The origination address for matching is:

• 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 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:

Script Return Parameters (USSD Response)

The Lua script is responsible for determing if it will send back either:

• A ReturnResult to indicate successful processing, or
• A ReturnError to indicate a processing failure.

In either of these cases it may choose to:

• Send the ReturnResult or ReturnError in a TCAP END, or
• Send the ReturnResult or ReturnError in a TCAP CONTINUE, and send a separate subsequent empty TCAP END.

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.

• When accept is used with close = true, then the entire USSD transaction is over. Subsequent calls to accept, decline, or close are not permitted, and will generate a runtime script error.

• When accept is used with close = false, then the USSD transaction is still open, however the only subsequent permitted method call is to the close method.

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.

The accept method returns the following object structure:

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

• When decline is used with close = true, then the entire USSD transaction is over. Subsequent calls to accept, decline, or close are not permitted, and will generate a runtime script error.

• When decline is used with close = false, then the USSD transaction is still open, however the only subsequent permitted method call is to the close method.

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

The decline method takes two parameters.

The decline method returns the following object structure:

[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