USSD Notify Lua Agent

Introduction

The UssdNotifyLuaAgent is a helper agent for Lua scripts running within the LogicApp.

• The USSD Notify Agent may be used by any Lua script, regardless of which Service initiated that script.

The UssdNotifyLuaAgent communicates with one or more instances of the SigtranApp which can be used to communicate via one or more external M3UA or SUA connections.

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

USSD Notify Agent methods are accessed via the “n2.n2svcd.ussd_notify_agent” module:

    local ussdna_api = require "n2.n2svcd.ussd_notify_agent"

Configuring UssdNotifyLuaAgent

The UssdNotifyLuaAgent 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>
            ...
            <parameter name="default_ussd_notify_app_name" value="SIGTRAN-C"/>
          </parameters>
          <config>
            <services>
              ...
            </services>
            <agents>
              <agent module="SigtranApp::UssdNotifyLuaAgent" libs="../apps/sigtran/lib">
                <config tcap_timeout_secs="20"/>
              </agent>
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following agent attributes apply:

In addition, the UssdNotifyLuaAgent must be configured with the name of the SigtranApp with which it will communicate. This is configured within the parameters of the containing LogicApp.

The UssdNotifyLuaAgent API

All methods may raise a Lua Error in the case of exception, including:

• Invalid input parameters supplied by Lua script.
• Unexpected results structure returned from SigtranApp.
• Processing error occurred at SigtranApp.
• Timeout occurred at SigtranApp.

.notify [Asynchronous]

The notify method sends a new MAP UnstructuredSSNotify operation to a handset, and waits for a response (or a timeout).

Specifically it performs the following steps:

• Initialises a new TCAP transaction of the form ttg.hrl.1, etc.
• Constructs an SCCP destination address.
• Encodes the UnstructuredSSNotify operation parameter.
• Sends TCAP-SEND to the SIGTRAN App to have this message sent.
• Waits for ReturnResult or ReturnError.

If no ReturnResult or ReturnError is returned within the allowed window, then a timeout result is returned.

This method will always create a new transaction, and will always attempt to clean-up the transaction immediately after use (if necessary), by sending an empty TCAP END to terminate the transaction. If an TCAP empty END or TCAP ABORT is simultaneously sent by the far-end during the close process, then this is a standard race condition which will not generate any warning from the SIGTRAN stack.

This method accepts the following parameters:

After the notify method, the USSD transaction may or may not be in progress.
The result.controlled field will indicate if the USSD interaction is still under our control.

The notify method returns the following object structure:

[Fragment] Example (USSD Notify):

    ussdna_api.notify ({ msisdn_digits = "49991000", ussdString_text = "En cours.  Patientez SVP.", ussdDataCodingScheme_language = 3 }, { dgt_digits = "6449991000" }, { destination_reference_digits = "6449991000" }, 3.0, nil)

Constants

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

USSD Reason Constants

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

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

USSD Error Constants

The following constants are error code values for ReturnError, as might be returned from the notify method. The network may also return other values not listed here.

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