ATI Lua Service

Introduction

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

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

Configuring AnyTimeInterrogationLuaService

The AnyTimeInterrogationLuaService 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::AnyTimeInterrogationLuaService" libs="../../n2sns/apps/sigtran/lib" script_dir="../../n2sns/test/regression/set6-MAP/logic_app">
                <triggers>
                  <trigger script_key="ati_success"/>
                </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 ATI trigger rule defines the name of a script which is ready to handle an inbound AnyTimeInterrogationRequest 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 (ATI Transaction Request)

The Lua script selection to execute for a AnyTimeInterrogationRequest 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 operation fields e.g. subscriberIdentity.msisdn_digits, subscriberIdentity.imsi_digits, gsmSCF-Address_digits are not currently available for use in script selection.

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

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

local n2svcd = require "n2.n2svcd"
local ati_service = require "n2.n2svcd.ati_service"

local mnp_db = {
    ['61426300203'] = '1427'
}

local args = ... 

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

local request = args.ati
if (request.subscriberIdentity == nil) then
    return ati_service.ERROR_DATA_MISSING
end

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

-- Find the carrier for this MSISDN, error if we don't have a matching record.
local carrier_hoc = mnp_db[msisdn_digits]
if (carrier_hoc == nil) then
    return ati_service.ERROR_UNKNOWN_SUBSCRIBER
end

local nps = ati_service.NPS_OWN_PORTED_OUT

-- Return the matched prefix.
return {
    subscriberInfo = {
        mnpInfoRes = {
            routeingNumber_digits = carrier_hoc,
            numberPortabilityStatus = nps
        }
    }
}

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

Script Return Parameters (ATI Response)

The Lua script is responsible for determing the contents of the ReturnResult for the AnyTimeInterrogationRequest 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 ATI response, the script return value may be a response object with the following attributes:

Example (returning a Table ATI Response):

local n2svcd = require "n2.n2svcd"

local args = ...

return ({ subscriberInfo = { mnpInfoRes = { numberPortabilityStatus = ati_service.NPS_NOT_KNOWN_PORTED } } })

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 ATI Error Code):

local n2svcd = require "n2.n2svcd"

local args = ...

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

...

return

Alternatively, the script may return nil in which case the ATI 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 AnyTimeInterrogationLuaService API

The ATI Service API can be loaded as follows.

    local ati_service = require "n2.n2svcd.ati_service"

It is not necessary to load the ATI 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 ATI response before the script completes.
This can be done with the response method on the ATI Service API.

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

The response method takes a single response parameter.

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

The response method returns the following object structure:

[Fragment] Example Early Response specifying Language:

    ...
    ati_service.response ({ subscriberInfo = { mnpInfoRes = { numberPortabilityStatus = ati_service.NPS_NOT_KNOWN_PORTED } } })

    [post-processing logic after ATI 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 AnyTimeInterrogationRequest operation, within a TCAP_END.

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

The decline method takes a single error_code parameter.

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

The decline method returns the following object structure:

[Fragment] Decline request using custom error code:

    ...
    ati_service.decline (ati_service.ERROR_UNKNOWN_SUBSCRIBER)

    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.
    ati_service.close ()
    ...

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

Constants

The following ATI constants are defined on the returned ati object.

ATI Reason Constants

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

-- ATI Reason Constants.
ati_service.REASON_RESPONSE = 'Response'
ati_service.REASON_DECLINE = 'Decline'
ati_service.REASON_ABANDON = 'Abandon'

ATI Error Constants

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

-- ATI Error Constants.
ati_service.ERROR_SYSTEM_FAILURE = 34
ati_service.ERROR_ATI_NOT_ALLOWED = 49
ati_service.ERROR_DATA_MISSING = 35
ati_service.ERROR_UNEXPECTED_DATA_VALUE = 36
ati_service.ERROR_UNKNOWN_SUBSCRIBER = 1

ATI Number Port Status Constants

The following constants are provided for convenience as standard values typically used for the subscriberInfo.mnpInfoRes.numberPortabilityStatus field value.

-- ATI Number Port Status Constants.
ati_service.NPS_NOT_KNOWN_PORTED = 0,
ati_service.NPS_OWN_PORTED_OUT = 1,
ati_service.NPS_FOREIGN_PORTED_FOREIGN = 2,
ati_service.NPS_OWN_NOT_PORTED_OUT = 3,
ati_service.NPS_FOREIGN_PORTED_IN = 4,