USSD Notify Lua Agent

Introduction

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

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:

Parameter Name Type XML Type Description
module SigtranApp:: UssdNotifyLuaAgent Attribute [Required] The module name containing the Lua Agent code.
libs ../apps/sigtran/lib Element Location of the module for UssdNotifyLuaAgent.
config Object Element Container for extended configuration for this Application instance.
.tcap_timeout_secs Integer Attribute How long to wait for an expected TCAP message to arrive.
(Default = 10 seconds)

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.

Parameter Name Type XML Type Description
parameters Array Element Array of name = value Parameters for this Application instance.
.default_ussd_notify_app_name String Attribute Default name for the SigtranApp with which UssdNotifyLuaAgent will communicate.
.tcap_app_name_<route> String Attribute Use this format when UssdNotifyLuaAgent will communicate with more than one SigtranApp.
(Default = UssdNotifyLuaAgent uses only the default route/SIGTRAN connectivity application).

The UssdNotifyLuaAgent API

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

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

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:

Field Type Description
ussd Table Container for the USSD request 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)
.msisdn Binary The MSISDN (raw bytes) encoded as MAP Address String.
This is not typically required when a Notify occurs with the context of an established dialog.
.msisdn_digits HEX String The digits of the MSISDN address.
This is not typically required when a Notify occurs with the context of an established dialog.
.msisdn_noa Integer The Nature Of Address of the MSISDN address.
This is not typically required when a Notify occurs with the context of an established dialog.
.msisdn_npi Integer The Numbering Plan Indicator of the MSISDN address.
This is not typically required when a Notify occurs with the context of an established dialog.
.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)
sccp_dest_address Table The SCCP address to which the TCAP BEGIN should be sent.
Subsequent messages will be sent to the SCCP address which responds back to us for that transaction.
.dri 0 / 1 SCCP Destination Routing Indicator
(Default = Automatically Determined).
.dpc Integer SCCP Destination Point Code
(Default = Does not route on PC/SSN).
.dssn Integer SCCP Destination Subsystem Number
(Default = Does not route on PC/SSN).
.dgt_digits String SCCP Destination Global Title Digits
(Default = Does not route on GT).
.dgt_noa Integer SCCP Destination Global Title Nature of Address
(Default = Varies).
.dgt_np Integer SCCP Destination Global Title Numbering Plan
(Default = Varies).
.dgt_tt Integer SCCP Destination Global Title Translation Type
(Default = Automatically Determined).
map_open Object Specifies the MAP-OPEN for the AARQ dialogue sent with the TCAP BEGIN.
(Default = An empty MAP-OPEN is sent).
.destination_reference_digits Hex String The digits for the Destination Reference address in the MAP-OPEN.
(Default = destination reference is not present).
.destination_reference_noa Integer The Nature of Address for the Destination Reference address in the MAP-OPEN.
(Default = 0).
.destination_reference_npi Integer The Numbering Plan Indicator for the Destination Reference address in the MAP-OPEN.
(Default = 1).
.origination_reference_digits Hex String The digits for the Origination Reference address in the MAP-OPEN.
(Default = orgination reference is not present).
.origination_reference_noa Integer The Nature of Address for the Origination Reference address in the MAP-OPEN.
(Default = 0).
.origination_reference_npi Integer The Numbering Plan Indicator for the Origination Reference address in the MAP-OPEN.
(Default = 1).
seconds Number The timeout in seconds for the script to wait for an ReturnResult/ReturnError response from the network.
(Default = Service configured notify_timeout value).
route String The identifier of the SIGTRAN application to use, or nil for the default.

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:

Parameter Type Description
controlled Boolean This attribute is true if the USSD session is still proceeding.
It will be always true in the case of reason Notify.
It will be always false in the case of reason Abandon.
reason Notify / Error / Abandon / Timeout Notify - Acknowledgement was received. controlled may be true or false.
Error - A user/network error code was received within the timeout window. controlled may be true or false.
Abandon - The user/network abandoned with TCAP ABORT or TCAP Empty END. controlled = false.
Timeout - The handset did not acknowledge the notify within the timer. controlled = true.
error_code Integer Present if and only if reason = Error.
The user/network-provided error code number.

[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