SCP Lua Service

LhoScpLuaService Module

Introduction

The LhoScpLuaService is a service for initiating LUA scripts running within the LogicApp (see core n2svcd documentation). It operates in conjunction with the Logic Hand-Off SCP Application, LhoScpApp and the SigtranApp.

The SigtrapApp receives the TCAP over SIGTRAN and passes it to the LhoScpApp which contains the INAP/CAMEL Codecs and performs the SCP state-machine management for each call.

The LhoScpApp sends SCP messages to the LhoScpLuaService which is a plugin configured within the LogicApp. The LhoScpLuaService receives the SCP-... messages and initiates a LUA script execution within the LogicApp. The LUA script contains the service logic which makes calls back via the LhoScpLuaService plugin to instruct the LhoScpApp to perform SCP functions.

For underlying details, see the documentation for the SCP-… messages.

Note that LhoScpLuaService is a base service class which is designed to be extended by other derived classes. In practice you will not configure this class directly, but instead will configure a derived sub-class such as AcdApp::AcdService.

Configuring LhoScpLuaService

The LhoScpLuaService is configured within a LogicApp as follows:

    <?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="LhoScpApp::LhoScpLuaService" libs="../../n2scp/apps/lho_scp/lib">
                <triggers>
                  <trigger called_suffix="02" script_key="scenario_02_release_call"/>
                  <trigger called_suffix="03" script_key="scenario_03_continue"/>
                  <trigger called_suffix="04" script_key="scenario_04_abort"/>
                  <trigger called_suffix="05" script_key="scenario_05_connect"/>
                </triggers>
              </service>
            </services>
            <agents>
              ...
            </agents>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Under normal installation, following service attributes apply:

Attribute Type Description
module LhoScpApp::LhoScpLuaService [Required] The module name containing the LUA Service code.
Alternatively this may be a derived sub-class of LhoScpLuaService.
libs ../apps/lho_scp/lib Location of the module for LhoScpLuaService.
script_subdir String An optional subdirectory for scripts used by this service.
.triggers Array Array of trigger elements specifying LUA scripts to run for SCP calls.
.trigger Object Provisions a trigger which guides LUA script selection.

Script Trigger Rules

Each SCP trigger rule defines the name of a script which is ready to handle a call for some/all service key, called party address, and/or calling party address combinations.

Note that called and calling party addresses may contain hex digits A-F, and the matching is case-insensitive.

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

Attribute Type Description
service_key Integer This trigger applies for only calls for which the InitialDP service key matches this exact service key.
(Default = Trigger applies to all SCP calls).
service_key_min Integer This trigger applies for only calls for which the InitialDP service key is greater than or equal to this service key.
(Default = Trigger applies to all SCP calls).
service_key_max Integer This trigger applies for only calls for which the InitialDP service key is less than or equal to this service key.
(Default = Trigger applies to all SCP calls).
called Hex Digits This trigger applies for only calls to this exact called party.
(Default = Trigger applies to all SCP calls).
called_prefix Hex Digits This trigger applies for only calls to called parties starting with this prefix.
(Default = Trigger applies to all SCP calls).
called_suffix Hex Digits This trigger applies for only calls to called parties ending with this prefix.
(Default = Trigger applies to all SCP calls).
calling Hex Digits This trigger applies for only calls from this exact calling party.
(Default = Trigger applies to all SCP calls).
calling_prefix Hex Digits This trigger applies for only calls from calling parties starting with this prefix.
(Default = Trigger applies to all SCP calls).
calling_suffix Hex Digits This trigger applies for only calls from calling parties ending with this suffix.
(Default = Trigger applies to all SCP calls).
script_key String [Required] The key of the LUA script to load and run. This is the file name excluding the ".lua"/".lc" suffix. The script should reside in the directory configured for the LogicApp's lua_script_dir, or in the specified subdirectory if script_subdir is configured for this service library.
Note that derived subclasses such as AcdApp::AcdService may allow script_key to be undefined here, and will instead perform a dynamic database lookup to determine the script key.

Note that the base service class LhoScpLuaService as documented here provides only simple, static trigger processing. Specifically it has the following limitations as documented:

These static script keys and disk-based file loaders are suitable for simple, static services. However, a more sophistical service such as AcdApp::AcdService will sub-class this base service class, and will use a more sophisticated Lua Loader which will typically support extended script loading features such as:

A trigger without a “script_key” requires a “two-phase loader” to fetch the script. The phases are:

  1. Perform a lookup (e.g. from database or via HTTP) to determine which script key to execute.
  2. Check for a cached script that matches this script key. If not found, then load the script (e.g. from database or via HTTP).

Again, this base class LhoScpLuaService does not support two-phase loaders. Sub-classes may do so.

Script Selection (SCP call Request)

The LUA Script selection to execute for a SCP InitialDP incall is a function of the service key, called party digits, and/or calling party digits derived from the InitialDP. The called and calling party digits will have been normalised before handover.

The SCP LUA Service will iterate the configured trigger entries in the sequence in which they are configured and find the first trigger with conditions that match the InitialDP’s parameters (this may be a trigger which matches all calls).

Refer to the LogicApp configuration for more information on directories, library paths, and script caching parameters.

Script Entry Parameters (SCP Call Request)

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

local n2svcd = require "n2.n2svcd"
local scp_api = require "n2.n2svcd.scp"

local scp_call, extra_args = ...

scp_api.release_call (31)

return

The service script will be executed with the scp_call and extra_args parameters.

Field Type Description
scp_call Table [Required] The SCP control parameters for the message.
.ssp_inap String [Required] INAP/CAMEL variant.
The name of the INAP/CAMEL variant for the selected SSP Model handling this call.
This is `camel1`, `camel2`, etc.
.supported Table [Required] Container for supported feature flags.
.release_tone 0 / 1 [Required] Does the SSP Model support setting of `release_tone`.
If this flag is not = 1 then service logic attempts to set `release_tone` in charged call terminations or extensions will result in call-processing failure.
.fci 0 / 1 [Required] Does the SSP Model support sending of FCI information.
If this flag is not = 1 then service logic attempts to send FCI content in call terminations will result in call-processing failure.
.sci 0 / 1 [Required] Does the SSP Model support reception of SendChargingInformation (SCI).
If this flag is not = 1 then service logic attempts to send SCI content in call terminations will result in call-processing failure.
.interaction 0 / 1 [Required] Does the SSP Model support use of interaction using PlayAnnouncement or PromptAndCollectUserInformation.
If this flag is not = 1 then service logic attempts to perform interaction during the call control will result in call-processing failure.
.call_information 0 - 31 [Required] Which information does the SSP Model support reporting via CallInformationReport (CIR).
Bitmask:
  • 1 = call attempt elapsed time (CAET); "ring time"
  • 2 = call stop time (CST)
  • 4 = call connected elapsed time (CCET); "talk time"
  • 8 = called address
  • 16 = release cause
If this field value = 0 then service logic attempts to use CIR features in call terminations or extensions will result in call-processing failure.
.activity_test 0 / 1 [Required] Does the SSP Model support the use of gap-filling ActivityTest.
If this flag is not = 1 then service logic attempts to enable gap-filling ActivityTest in call terminations or extensions will result in call-processing failure.
.max_charged_call_secs Integer This is the maximum number of talk-time seconds which the SSP protocol can support for a charged call.
The service logic must never grant a total talk-time greater than this value.
For most CAMEL protocols this is typically 86400 but it may be configured lower than this value on a per-SSP basis.
.remote_sccp Table [Required] The address of the SCCP node that triggered the call to us.
This is the actual on-the-wire address extracted from the TCAP BEGIN.
The remote address typically does not change during the transaction. Yes, in theory the far-end may perform some sort of service handover but in practice this would be very unusual behavior.
.ri 0 / 1 [Required] Routing Indicator.
1 = route on PC + SSN, 0 = Route on GT)
.pc Integer Point Code.
This field is present if and only if the address specifies a point code.
.ssn Integer Sub-System Number.
This field is present if and only if the address specifies a sub-system number.
.gt_digits Hex Digits Hex Digits for Global Title address.
This field is present if and only if the address specifies a global title.
.gt_noa Integer Global Title Nature of Address (0-127).
This field is present if and only if the address specifies a global title. (Default = 0)
.gt_np Integer Global Title Numbering Plan (0-7).
This field is present if and only if the address specifies a global title. (Default = 1, E.164)
.gt_tt Integer Global Title Translation Type (0-255).
This field is present if and only if the address specifies a global title.
.local_sccp Table [Required] The address of the SCCP node that received the call trigger.
This is the actual on-the-wire address extracted from the TCAP BEGIN.
In practice this will typically be the load-sharing "virtual" address, and when the SigtranApp continues the transaction, it will replace this address with a different address which is specifically assigned only to this particular SCP node.
.ri 0 / 1 [Required] Routing Indicator.
1 = route on PC + SSN, 0 = Route on GT)
.pc Integer Point Code.
This field is present if and only if the address specifies a point code.
.ssn Integer Sub-System Number.
This field is present if and only if the address specifies a sub-system number.
.gt_digits Hex Digits Hex Digits for Global Title address.
This field is present if and only if the address specifies a global title.
.gt_noa Integer Global Title Nature of Address (0-127).
This field is present if and only if the address specifies a global title. (Default = 0)
.gt_np Integer Global Title Numbering Plan (0-7).
This field is present if and only if the address specifies a global title. (Default = 1, E.164)
.gt_tt Integer Global Title Translation Type (0-255).
This field is present if and only if the address specifies a global title.
.call_trigger ORIG / TERM / FWD [Required] Indicator of the call trigger.
This distinguishes between originating, terminating, and forwarded call triggers.
.normalised_calling_party Digit String [Required] (Normalised) Calling Party Number address digits.
This is the calling party address digits after any configured 'calling_party' normalisation rules have been applied.
It is determined from the callingPartyNumber element of the InitialDP.
It is guaranteed to contain only 0-9A-F digits.
.normalised_called_party Digit String [Required] (Normalised) Called Party (BCD) Number address digits.
This is the called party address digits after any configured 'called_party' or 'called_party_bcd' normalisation rules have been applied.
It is determined from the calledPartyBCDNumber or calledPartyNumber element of the InitialDP.
It is guaranteed to contain only 0-9A-F digits.
.normalised_redirecting_party Digit String (Normalised) Redirecting Party ID address digits.
This is the redirecting party address digits after any configured 'calling_party' normalisation rules have been applied.
It is determined from the redirectingPartyID element of the InitialDP, if present.
It is guaranteed to contain only 0-9A-F digits.
.normalised_original_called_party Digit String (Normalised) Original Called Party address digits.
This is the original called party address digits after any configured 'called_party' normalisation rules have been applied.
It is determined from the originalCalledPartyID element of the InitialDP, if present.
It is guaranteed to contain only 0-9A-F digits.
.forwarding_pending 1 This field is present and 1 if and only if the gsm-ForwardingPending or callForwardingSS-Pending element is present in the InitialDP.
.pending_tn Digit String [Required]
The normalised pending termination number inferred from the InitialDP.
.initialdp_arg Table [Required] Complete decoded InitialDP structure.
extra_args Table An optional table containing additional implementation-specific arguments provided by the service's LuaLoader implementation.

Script Return Parameters (SCP Call Response)

The return value from the LUA script should always be nil. Returning any other value will generate a warning to the syslog.

The LhoScpLuaService API

A script processing SCP incalls must use the SCP API.

    local scp_api = require "n2.n2svcd.scp"

The following telephony functions are available for a controlled call.