InitialDPSMS Lua Service
Introduction
The InitialDPSMSLuaService is a service for initiating Lua scripts running within the LogicApp.
The InitialDPSMSLuaService receives a InitialDPSMS
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 InitialDPSMSLuaService communicates with the SigtranApp using the
TCAP-SEND
and TCAP-RECV
messages. See the definition of the
TCAP-… messages.
Message Flows
The following message flows show the direct and reservation mechanisms.
Configuring InitialDPSMSLuaService
The InitialDPSMSLuaService is configured within a LogicApp.
<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
...
<applications>
...
<application name="Logic" module="LogicApp" stderr_debug="0">
<include>
<lib>../apps/logic/lib</lib>
</include>
<parameters>
<parameter name="trace_level" value="1"/>
<parameter name="default_lua_lib_path" value="../../n2scp/lua/lib/?.lua;../lua/lib/?.lua"/>
</parameters>
<config>
<services>
<service module="SigtranApp::InitialDPSMSLuaService" libs="../../n2scp/apps/sigtran/lib" script_dir="../../n2scp/test/regression/set7-SMS/logic_app">
<triggers>
<trigger script_key="camel_sms"/>
</triggers>
</service>
</services>
</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:
Parameter Name | Type | XML Type | Description |
---|---|---|---|
module
|
String | Attribute |
[Required] The module name containing the Lua Service code: SigtranApp::InitialDPSMSLuaService
|
libs
|
String | Element |
Location of the module for InitialDPSMSLuaService.(Default: ../../n2scp/apps/sigtran/lib )
|
script_dir
|
String | Attribute | [Required] The directory containing scripts used by this service. |
default_release_cause
|
Integer | Element |
The release cause to use in the ReleaseSMS sent by us, if not explicitly specified by service logic.
|
default_submit_timeout
|
Float | Element |
The default duration (in seconds) after which the script will resume if no EventReportSMS operation is received when using the continue_attempt method.This timeout applies only for InitialDPSMS processing with eventTypeSMS = 1 (SMS Collected Info).
|
default_deliver_timeout
|
Float | Element |
The default duration (in seconds) after which the script will resume if no EventReportSMS operation is received when using the continue_attempt method.This timeout applies only for InitialDPSMS processing with eventTypeSMS = 11 (SMS Delivery Requested).
|
.triggers
|
Array | Element |
Array of trigger elements specifying Lua scripts to run for InitialDPSMS Inbound Transactions.
|
.trigger
|
Object | Element | Provisions a Lua script to run for a InitialDPSMS Inbound Transaction for received InitialDPSMS operations. |
Script Trigger Rules
Each InitialDPSMS trigger rule defines the name of a script which is ready to handle an inbound InitialDPSMS Transaction.
Note that destination and calling addresses may contain hex digits A-F, and the
matching is for destination_prefix
and calling_prefix
is case-insensitive.
Each trigger
Object in the config
.triggers
Array is configured as follows.
Parameter Name | Type | XML Type | Description |
---|---|---|---|
ssn
|
1 -255
|
Attribute |
This trigger applies for only InitialDPSMS to this exact SCCP subsystem number. (Default = Trigger applies to all SCCP subsystem numbers). |
service_key
|
Integer | Attribute |
This trigger applies for only InitialDPSMS to this exact service key. (Default = Trigger applies to all InitialDPSMS). |
destination
|
Hex Digits | Attribute |
This trigger applies for only InitialDPSMS to this exact destination subscriber number digits (in InitialDPSMS). (Default = Trigger applies to all InitialDPSMS). |
destination_prefix
|
Hex Digits | Attribute |
This trigger applies for only InitialDPSMS to destination subscriber number digits (in InitialDPSMS) with this prefix. (Default = Trigger applies to all InitialDPSMS). |
calling
|
Hex Digits | Attribute |
This trigger applies for only InitialDPSMS from this exact calling party number digits (in InitialDPSMS). (Default = Trigger applies to all InitialDPSMS). |
calling_prefix
|
Integer | Attribute |
This trigger applies for only InitialDPSMS from calling party number digits (in InitialDPSMS) with this prefix. (Default = Trigger applies to all InitialDPSMS). |
script_key
|
String | Attribute |
The name for the Lua script to load (excluding the ".lua" or ".lc" suffix). The script should reside in the configured script_dir directory.
|
Script Selection (InitialDPSMS Transaction Request)
The Lua script selection to execute for a InitialDPSMS takes into consideration the received content of the inbound TCAP_BEGIN transaction and/or the SCCP addressing information.
The destination address for matching is:
- The InitialDPSMS Destination Subscriber Number Digits.
The calling address for matching is:
- The InitialDPSMS Calling Party Number Digits.
The InitialDPSMS 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 (InitialDPSMS Request)
The Lua script defines the service processing steps, such as the following:
local n2svcd = require "n2.n2svcd"
local idpsms_service = require "n2.n2svcd.idpsms_service"
local args = ...
n2svcd.debug ("RECEIVED InitialDPSMS")
n2svcd.debug_var (args)
local scenario = string.sub (args.initialdpsms.callingPartyNumber_digits, -2)
-- This will return ContinueSMS
if (scenario == "01") then
idpsms_service.continue_final ()
-- This will crash out and return InitialDPSMS-Error (Error Code 11)
elseif (scenario == "02") then
error ("Deliberate Error")
-- This will return ReleaseCall with cause 7
elseif (scenario == "03") then
return 7
-- This will return ReleaseCall with cause default (= 1)
elseif (scenario == "04") then
return
-- This will return ReleaseCall with cause 127
elseif (scenario == "05") then
idpsms_service.release (127)
return
end
return
The service script will be executed with an args
entry parameter which is an object with the
following attributes:
Attribute | Type | Description |
---|---|---|
.remote_sccp
|
SCCP Address Object | The far-end SCCP address, as per the TCAP-RECV Message. |
.local_sccp
|
SCCP Address Object | The near-end SCCP address, as per the TCAP-RECV Message. |
.collected_info
|
1
|
This value is present only when the InitialDPSMS has eventTypeSMS = 1 (Collected Info).
|
.delivery_requested
|
1
|
This value is present only when the InitialDPSMS has eventTypeSMS = 11 (Delivery Requested).
|
.initialdpsms
|
Object |
The decoded attributes of the InitialDPSMS operation.CAMEL3 InitialDPSMS, or CAMEL4 InitialDPSMS. |
Script Return Parameters (InitialDPSMS Response)
The Lua script is responsible for determing the message(s) to send in reply to the received
InitialDPSMS
operation.
The service provides a short-cut mechanism for doing this. If the service has not yet
performed an idpsms_service
API action such as continue_final ()
or release ()
then
returning from the script will cause a ReleaseSMS
operation to be sent back in TCAP END,
exactly as if the release ()
method has been called.
If the return value is an integer in the range 0
-127
then this will be used as the release
cause. If not specified, then the service default value will be used.
Example (returning a ReleaseSMS with cause 7):
local n2svcd = require "n2.n2svcd"
local args = ...
return 7
The InitialDPSMSLuaService API
The InitialDPSMS Service API can be loaded as follows.
local idpsms_service = require "n2.n2svcd.idpsms_service"
This will provide access the following methods and constants.
.release [Synchronous]
This method will cause the ReleaseSMS
CAMEL operation to be returned as Invoke
in TCAP END.
This instructions the SMSC to deny the SMS delivery.
The InitialDPSMS transaction is over.
Subsequent calls to other InitialDPSMS Service API methods are not permitted, and will generate a runtime script error.
The release
method takes the following parameters.
Parameter | Type | Description |
---|---|---|
cause
|
0 - 127
|
The numeric cause value to include.(Default = 1 )
|
The release
method returns true
.
[Fragment] Example ReleaseSMS specifying cause:
...
idpsms_service.release (3)
[post-processing logic after InitialDPSMS transaction is ended]
...
.continue_final [Synchronous]
This method will cause the ContinueSMS
CAMEL operation to be returned as Invoke
in TCAP END.
This instructions the SMSC to continue with the SMS delivery.
The InitialDPSMS transaction is over. The service logic does not arm any event detection points, and will not be subsequently informed if the delivery is successful or not.
Subsequent calls to other InitialDPSMS Service API methods are not permitted, and will generate a runtime script error.
The continue_final
method takes no parameters.
The continue_final
method returns true
.
[Fragment] Example ContinueSMS without arming EDPs:
...
idpsms_service.continue_final ()
[post-processing logic after InitialDPSMS transaction is ended]
...
.continue_attempt [Asynchronous]
This method will cause the RequestReportSMSEvent
and ContinueSMS
CAMEL operations to be returned as Invoke
components in TCAP CONTINUE.
This instructions the SMSC to continue with the SMS submission (SMS-MO) or delivery (SMS-MT) and report the success/failure of this attempt.
For SMS submission, the EDPs 2 (failure) and 3 (submitted) will be armed. For SMS delivery, the EDPs 12 (failure) and 13 (delivered) will be armed.
The service logic will suspend until a response is received - being either:
- A
EventReportSMS
operation, or (in error cases) - a
ReturnError
component, or - a returned empty TCAP END message, or
- a returned TCAP ABORT.
The service will also start a timer. If none of the above responses are returned then the continue attempt
will be interrupted and will return with Reason = Timeout
. An empty TCAP END will be sent to the SMSC to
terminate the continue attempt. Note that this library does not support use of the ResetTimer
operation, and so the timer duration must be a value agreed with the SMSC as being acceptable within the
maximum TCAP transaction timers.
An all return cases, subsequent calls to other InitialDPSMS Service API methods are not permitted, and will generate a runtime script error.
The continue_attempt
method takes the following parameters.
Parameter | Type | Description |
---|---|---|
seconds
|
Number |
The duration of the timer in seconds. (Default = the service configured default value) |
The continue_attempt
method returns the following object structure:
Parameter | Type | Description |
---|---|---|
result
|
Abandon / Failure / Submitted / Delivered / Error / Timeout / Abort
|
Indicates the reason for the completion of the operation. |
ok
|
Boolean |
A convenience flag which is true iff result is = Submitted or Delivered .
|
[Fragment] Example ContinueSMS with armed EDPs:
...
local result = idpsms_service.continue_attempt (20.0)
if (result.ok) then
diameter_lib.commit_charge ()
else
diameter_lib.revert_charge ()
end
...
Constants
The following constants define the supported values for the result.reason
field returned from the .continue_attempt
method.
-- Our possible result.reason values (for methods above).
idpsms_service.REASON_FINAL = 'Final' -- We sent ReleaseSMS OR ContinueSMS (without RequestReportSMSEvent).
idpsms_service.REASON_ABANDON = 'Abandon' -- The SMSC abandoned the transaction by sending empty TCAP END instead of EventReportSMS.
idpsms_service.REASON_FAILURE = 'Failure' -- The SMSC reported failure to collect or failure to deliver.
idpsms_service.REASON_SUBMITTED = 'Submitted' -- The SMSC reported that the message was submitted.
idpsms_service.REASON_DELIVERED = 'Delivered' -- The SMSC reported that the message was delivered.
idpsms_service.REASON_ERROR = 'Error' -- The SMSC returned an ReturnError component.
idpsms_service.REASON_TIMEOUT = 'Timeout' -- The SMSC did not report any result within the allowed timeout period.
idpsms_service.REASON_ABORT = 'Abort' -- The SMSC abandoned the transaction by sending TCAP ABORT instead of EventReportSMS.