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:

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.

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:

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.

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.

The continue_attempt method returns the following object structure:

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