SRISM Lua Service

Introduction

The SendRoutingInfoForSMLuaService is a service for initiating Lua scripts running within the LogicApp.

The SendRoutingInfoForSMLuaService receives a SendRoutingInfoForSM 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 SendRoutingInfoForSMLuaService communicates with the SigtranApp using the TCAP-SEND and TCAP-RECV messages. See the definition of the TCAP-… messages.

SRISM Scenario One (Result)

There are two typical use-cases for the SendRoutingInfoForSM Service. The first is the simple case where a request is received in TCAP BEGIN and the service completes the transaction by sending a SendRoutingInfoForSM ReturnResult in a TCAP END.

SRISM Scenario Two (Transfer/Proxy)

The second is a “Transfer” or “Proxy” scenario. In this case the service logic is not expected to know the subscriber’s current location within the network. Instead, the role of the service in this Transfer scenario is to look up a Mobile Number Portability database to determine the carrier/node responsible for this subscriber, and which can reply.

The service will transfer the SRISM request by requesting the SigtranApp to send a new TCAP BEGIN:

1. The new TCAP BEGIN will contain an SRISM which may be identical to the original or may be modified.
2. The new TCAP BEGIN will have a modified SCCP Called Party address (not the same as originally received).
3. The new TCAP BEGIN will have an unmodified SCCP Calling Party address (identical as originally received).
4. The SigtranApp will abandon the original inbound transaction.
5. The SigtranApp will abandon the new outbound transaction.

At this point, the n2sns components are no longer involved in the transaction because:

• The SCCP Calling Party address in the sent TCAP BEGIN is the address of the HLR, and is not our address, then we do not expect to receive any subsequent TCAP messages for the second transaction (from the new destination node).
• We did not reply with our own local TCAP Transaction ID to the original BEGIN, then we do not expect to receive any subsequent TCAP messages for the first transaction (from the original source node).

Configuring SendRoutingInfoForSMLuaService

The SendRoutingInfoForSMLuaService 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>
            ...
          </parameters>
          <config>
            <services>
              <service module="SigtranApp::SendRoutingInfoForSMLuaService" libs="../../n2sns/apps/sigtran/lib" script_dir="../../n2sns/test/regression/set6-MAP/logic_app">
                <triggers>
                  <trigger script_key="srism_transfer"/>
                </triggers>
              </service>
            </services>
            <agents>
              ...
            </agents>
          </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 SRISM trigger rule defines the name of a script which is ready to handle an inbound SendRoutingInfoForSM Transaction.

Note that destination and origination addresses may contain hex digits A-F, and the matching is for destination_prefix and origination_prefix is case-insensitive.

Each trigger Object in the config.triggers Array is configured as follows.

Script Selection (SRISM Transaction Request)

The Lua script selection to execute for a SendRoutingInfoForSM takes into consideration the received content of the inbound TCAP_BEGIN transaction and/or the MAP content and/or the SCCP addressing information.

The destination address for matching is:

• The MAP_OPEN Destination Reference Digits.

The origination address for matching is:

• The MAP_OPEN Origination Reference Digits.

The message fields, e.g. msisdn_digits, serviceCentreAddress_digits are not currently available for use in script selection.

The SRISM 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 (SRISM Request)

The Lua script defines the service processing steps, such as the following:

local n2svcd = require "n2.n2svcd"
local srism_service = require "n2.n2svcd.srism_service"

local args = ... 

-- Get the MSISDN, error if it is not present.
n2svcd.debug_var (args)

local request = args.srism

local msisdn_digits = request.msisdn_digits
if (msisdn_digits == nil) then
    return srism_service.ERROR_DATA_MISSING
end

-- Our routing is based on the last three digits.
local suffix = string.sub (msisdn_digits, #msisdn_digits - 2)

-- 203: Success with carrier HOC 1427
if (suffix == '203') then 
    return {
        imsi_digits = 1427 .. "000000000000"
    }

-- 204: Deliberate script error
elseif (suffix == '204') then 
    error ("Script Fail")

-- ERROR_ABSENT_SUBSCRIBER_SM
else 
    return srism_service.ERROR_ABSENT_SUBSCRIBER_SM
end

The service script will be executed with an args entry parameter which is an object with the following attributes:

Script Return Parameters (SRISM Response)

The Lua script is responsible for determing the contents of the ReturnResult for the SendRoutingInfoForSM operation, which will be sent back to the HLR and conclude the transaction.

The simplest way to do this is by the return value given back to the service at the end of script execution.

For full control over the SRISM response, the script return value may be a response object with the following attributes:

Example (returning a Table SRISM Response):

local n2svcd = require "n2.n2svcd"

local args = ...

return ({ imsi_digits = "1444000000000000" })

Alternatively, a script may return a numeric scalar value which is treated as an Error Code to be returned in ReturnError in the same way as a call to the service’s .decline method.

Example (returning an SRISM Error Code):

local n2svcd = require "n2.n2svcd"

local args = ...

-- Check the Database is online.
if (n2svcd.agent_status ("DB") <= n2svcd.STATUS_OFFLINE) then
    srism_service.ERROR_SYSTEM_FAILURE
end

...

return

Alternatively, the script may return nil in which case the SRISM transaction will be closed by sending Empty TCAP END.

Example (returning nothing):

local n2svcd = require "n2.n2svcd"

local args = ...

return nil

In this case, the transaction will be closed with an empty TCAP END to the HLR. This may or may not be something which the HLR is expected to support.

The SendRoutingInfoForSMLuaService API

The SRISM Service API can be loaded as follows.

    local srism_service = require "n2.n2svcd.srism_service"

It is not necessary to load the SRISM Service API if you are only using the simple response mechanism described above. It is only required if you wish to use any of the extended features described below, or any of the constants.

.response [Synchronous]

When a Lua script needs to perform extended processing, it may wish to send an early SRISM response before the script completes. This can be done with the response method on the SRISM Service API.

This method will send a ReturnResult for the SendRoutingInfoForSM operation, within a TCAP_END. The SRISM transaction is over. Subsequent calls to response, decline, or transfer are not permitted, and will generate a runtime script error.

The response method takes a single response parameter.

After the response method, the SRISM transaction is no longer in progress.

The response method returns the following object structure:

[Fragment] Example Early Response specifying Language:

    ...
    srism_service.response ({
        imsi_digits = subscriber_imsi,
        locationInfoWithLMSI = {
            ['networkNode-Number_digits'] = nnn_digits,
            lmsi_hex = 'ffff0123'
        }
    })

    [post-processing logic after SRISM transaction is ended]
    ...

.decline [Synchronous]

If the Lua service logic script does not wish to handle the request, it can indicate error processing by sending a ReturnError for the SendRoutingInfoForSM operation, within a TCAP_END.

The SRISM transaction is over. Subsequent calls to response, decline, or transfer are not permitted, and will generate a runtime script error.

The decline method takes a single error_code parameter.

After the decline method, the SRISM transaction is no longer in progress.

The decline method returns the following object structure:

[Fragment] Decline request using custom error code:

    ...
    srism_service.decline (srism_service.ERROR_UNKNOWN_SUBSCRIBER)

    return nil

.transfer [Synchronous]

The transfer method instructs the SigtranApp to forward/proxy the received SendRoutingInfoForSM operation to a new SCCP Called Party Address, where the following attributes will be the same as the original:

• The SCCP Calling Party Address.
• The Originating Transaction ID.
• The TCAP dialog fields, including MAP Open if present.
• The component type(s), invoke ID(s), and parameter content.

The transaction treatments is as follows:

• A pre-arranged end will be applied to the original TCAP transaction in the SigtranApp.
• This will not create a new TCAP transaction in the SigtranApp app.

The transfer request is sent back to the same SigtranApp which is currently controlling the transaction. That SigtranApp will perform route selection using the same rules as for a new TCAP BEGIN.

To avoid loop scenarios, the SCCP destination address you specify must be strictly different from the original SCCP called party address. Specifically:

• Either the Routing Indicator must be changed, or
• if the address is route-on-point code then the PC must be changed, or
• if the address is route-on-GT then the global title digits must be changed.

The transfer method takes the following parameters.

After the transfer method, the SRISM transaction is no longer in progress.

The transfer method returns the following object structure:

[Fragment] Transaction transfer to new Global Title:

    ...
    -- Specify destination global title digits.  All other values will be set automatically.
    srism_service.transfer ({ dgt_digits = "14449990000" })

    return nil

.close [Synchronous]

The service logic may use this method to conclude the TCAP transaction without sending back a final response message. This has the same effect as returning nil from the service script.

The close method takes no parameters.

The close method returns nil.

[Fragment] Example close transaction using empty TCAP END:

    ...
    -- We wish to close the transaction immediately.
    srism_service.close ()
    ...

Again, note that this behavior may not necessarily be acceptible to the HLR.

Constants

The following SRISM constants are defined on the returned srism object.

SRISM Reason Constants

The following constants are used to indicate the reason that a SRISM interaction succeed or failed.

-- SRISM Reason Constants.
srism_service.REASON_RESPONSE = 'Response'
srism_service.REASON_DECLINE = 'Decline'
srism_service.REASON_ABANDON = 'Abandon'
srism_service.REASON_TRANSFER = 'Transfer'

SRISM Error Constants

The following constants are error code values for ReturnError as passed into the decline method.

-- SRISM Error Constants.
srism_service.ERROR_SYSTEM_FAILURE = 34
srism_service.ERROR_SRISM_NOT_ALLOWED = 49
srism_service.ERROR_DATA_MISSING = 35
srism_service.ERROR_UNEXPECTED_DATA_VALUE = 36
srism_service.ERROR_UNKNOWN_SUBSCRIBER = 1