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_appname<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
orReturnError
.
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