Navigation :

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, the following service parameters apply:

Parameter	Type	XML Type	Description
`module`	`LhoScpApp::LhoScpLuaService`	Attribute	[Required] The module name containing the Lua Service code. Alternatively this may be a derived sub-class of `LhoScpLuaService`.
`libs`	`../apps/lho_scp/lib`	Attribute	Location of the `module` for LhoScpLuaService.
`script_dir`	String	Attribute	[Required] The directory containing scripts used by this service.
`default_pa_wait_secs`	`1` - `600`	Attribute	The number of seconds to wait for a non-`prompt` Interaction action to complete when the service logic does not specify a duration. (Default = `120` seconds).
`default_pacui_wait_secs`	`1` - `600`	Attribute	The number of seconds to wait for a `prompt` Interaction action to complete when the service logic does not specify a duration. (Default = `300` seconds).
`wait_margin_secs`	`1` - `15`	Attribute	The number of seconds to add to the wait time for all asynchronous actions to account for round-trip latency. (Default = `5` seconds).
`triggers`	Array	Element	Array of `trigger` elements specifying Lua scripts to run for SCP calls.
`trigger`	Object	Element	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 configured `script_dir` directory. Note that derived subclasses such as `AcdScpApp::AcdScpLuaService` 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:

The “script_key” is statically defined by the trigger rule.
The Lua script content is read from a file on disk.

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:

The trigger does not define a static script key.
The script key is dynamically determined by a database lookup.
The Lua script content is also read from a subsequent database lookup.

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

Perform a lookup (e.g. from database or via HTTP) to determine which script key to execute.
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.