Navigation :

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:

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:

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:

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