LogicApp
Logic Application Configuration
The N2SVCD Logic Application is an extensible, general-purpose application which runs Lua scripts to perform control logic. The scripts can be initiated by various inbound agents, via Lua Services.
Lua scripts running within LogicApp may perform additional actions by calling upon Lua Agents.
This page describes general information about configuring LogicApp
. Please
refer to the relevant Service or Agent
documentation for examples and API specifications for each of the different use-cases.
A sample LogicApp configuration entry is as follows:
<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
...
<applications>
...
<application name="Logic" module="LogicApp">
<include>
<lib>../apps/logic/lib</lib>
</include>
<parameters>
<parameter name="trace_level" value="0"/>
<parameter name="edr_enabled" value="1"/>
<parameter name="edr_directory" value="/tmp/edr"/>
<parameter name="default_lua_lib_path" value="../lua/lib/?.lua;../../n2sip/lua/lib/?.lua"/>
<parameter name="default_smpp_app_name" value="SMPP-Client-Tester"/>
<parameter name="default_rest_app_name" value="REST-CLIENT"/>
<parameter name="default_outcall_app_name" value="IVR"/>
</parameters>
<config>
<auto_ids>
<auto_id key="call_id" length="10" charset="alphanum"/>
</auto_ids>
<services>
<service module="IvrApp::IvrIncallLuaService" libs="../../n2sip/apps/ivr/lib" script_dir="../../n2sip/demo/logic/incall">
<triggers>
<trigger called_prefix="800" script_key="800_digit_menu"/>
<trigger called_prefix="811" script_key="811_rest"/>
<trigger called_prefix="822" script_key="822_smpp"/>
<trigger called_prefix="900" script_key="900_mca"/>
</triggers>
</service>
<service module="RestServerApp::RestLuaService" libs="../apps/rest_s/lib" script_dir="../../n2sip/demo/logic/rest"/>
</services>
<agents>
<agent module="RestClientApp::RestLuaAgent" libs="../apps/rest_c/lib"/>
<agent module="SMPPApp::SMPPLuaAgent" libs="../apps/smpp/lib"/>
<agent module="IvrApp::IvrOutcallLuaAgent" libs="../../n2sip/apps/ivr/lib"/>
</agents>
</config>
</application>
...
</application>
...
</n2svcd>
Configuration Details
The application
element attributes for a Logic Application instance may include the below.
For details of the various parameter types used, refer to Common Configuration.
Parameter Name | Type | XML Type | Description |
---|---|---|---|
See: Common Application configuration | |||
module
|
String | Attribute |
[Required] LogicApp
|
include.lib
|
String | Element |
[Required] ../apps/logic/lib
|
parameters
|
Array | Element |
[Required] As per Common Configuration Application parameters .
|
"edr_enabled"
|
String | Parameter |
As per common Application configuration for edr_enabled .(Default = NO , do not send EDRs for writing)
|
"edr_app_name"
|
String | Parameter |
As per common Application configuration for edr_app_name .(Default = EDR )
|
"default_edr_stream_key"
|
String | Parameter |
As per common Application configuration for default_edr_stream_key .(Default = n2logic )
|
"default_lua_lib_path"
|
String | Parameter |
Additional paths to search when loading Lua libraries with the require statement.This has the same rules as the LUA_PATH environment variable, i.e. must use ?.lua .Multiple paths may be separated with a ; semicolon.This value may be overridden (not extended) by individual service libraries. (Default = empty) |
"default_lua_clib_path"
|
String | Parameter |
Additional paths to search when loading Lua C-libraries with the require statement.This has the same rules as the LUA_CPATH environment variable, i.e. must use ?.so .Multiple paths may be separated with a ; semicolon.This value may be overridden (not extended) by individual service libraries. (Default = empty) |
"max_chain_count"
|
Integer | Parameter |
The maximum number of times this service may be chained to a new script. (Default = 5 )
|
"default_<action>_app_name"
|
String | Attribute |
Agents will use a parameter of this form to configure the name of the Agent Application
which will perform its activity, e.g. default_rest_app_name is used by the
RestClientLuaAgent to specify which RestClientApp will handle outbound REST Client actions.
Refer to the documentation for the specific Lua Agent to determine which values it uses.(Default = Agent Actions cannot talk to Agent Applications) |
"<action>_app_name_<route>"
|
String | Attribute |
Agents use the concept of "routes" to handle case such as the need to communicate
with more than one end-point. Refer to the documentation for the specific Lua Agent
for more information. (Default = Agent Actions use only the default route) |
config
|
Object | Element | This is a container for extended configuration for the LogicApp. |
.auto_ids
|
Array of auto_id Objects
|
Element | Defines any configured Auto IDs for this LogicApp. |
.services
|
Array of service Objects
|
Element | Defines the configured Services for this LogicApp. At least one service must be defined in order to use the LogicApp. One LogicApp may handle more than one service. |
.agents
|
Array of agent Objects
|
Element | Defines the configured Agents for this LogicApp. Agents are not required in order to execute a LogicApp Lua Script, but they can extend the functionality available. |
Auto ID Configuration
Automatically generated sequential IDs are a feature available to Lua scripts running within the service logic framework. Each automatic ID must be pre-configured here before it can be used by the service logic scripts.
An auto_id
entry within the auto_ids
element of the LogicApp configuration has
the following attributes:
Parameter Name | Type | XML Type | Description |
---|---|---|---|
key
|
String | Parameter | [Required] The key for the automatically generated ID. |
charset
|
alphanum / alpha / decimal / hexadecimal
|
Parameter |
The character set to use for the auto-incrementing identifier string. (Default = the hexadecimal character set).
|
length
|
Integer | Parameter |
The maximum length to use for the automatically generated result. The length may be shorter than this value but will never be longer. (Default = the maximum possible length for the value). |
Each instance of the LogicApp will manage its own auto-incrementing sequences. This does mean that when performing load-sharing across multiple logic apps, there is a small but non-zero chance that the auto-incrementing ID will overlap.
Service Configuration
A Lua Service Library handles an inbound message from a Service Application and uses the contents of that message to:
- Determine which Lua script to execute, and
- Determine what arguments to supply to that executing Lua script.
When the Lua script completes, the Lua Service Library may send back a final response the originating application.
This section describes the common configuration for adding a Lua Service Library to the Logic Application. For more information on per-Service configuration, please refer to the individual documentation for each Service Library.
A service
entry within the services
element of the LogicApp configuration has
the following attributes:
Parameter Name | Type | XML Type | Description |
---|---|---|---|
module
|
String | Attribute | [Required] The module name containing the Lua Service Library code. |
libs
|
String | Attribute |
Optional library path to include when searching for the module for this Service Library.
|
lua_lib_path
|
String | Parameter |
Additional paths to search when loading Lua libraries with the require statement.This has the same rules as the LUA_PATH environment variable, i.e. must use ?.lua .Multiple paths may be separated with a ; semicolon.If specified at the service level, this will replace the Application-level configured path. (Default = the default_lua_lib_path value from the Application)
|
lua_clib_path
|
String | Parameter |
Additional paths to search when loading Lua C-libraries with the require statement.This has the same rules as the LUA_CPATH environment variable, i.e. must use ?.so .Multiple paths may be separated with a ; semicolon.If specified at the library level, this will replace the Application-level configured path. (Default = the default_lua_clib_path value from the Application)
|
globals
|
Object | Element | Container for additional service-specifical Lua globals which will be defined for every Lua instance. |
global
|
Object | Element |
Defines a global Lua constant value to be set in the Lua globals for all scripts initiated by this service entry. In the case where a Lua instance is cached and re-used, the global variables listed here will be initialized every time. |
name
|
String | Attribute | Defines the name of the global Lua constant value to set. |
value
|
String | Attribute | Defines the value of the global Lua constant value to set. |
integer
|
0 / 1 / yes / no
|
Attribute |
If present and set to a "true" value, the value must be an integer, and is set with Lua type of number .(Default = the global Lua constant is set as a scalar of type string )
|
use_stale_lua
|
0 / 1
|
Attribute |
When reading Lua scripts from file or from database, if the reload or the version freshness check fails,
we may still have a stale Lua chunk (and associated cached contexts) in memory. This flag determines
if we should continue to process the stale script, or if we should fail and tear down the instance. (Default = 0 , do not use stale Lua chunks/contexts)
|
chunk_reload_secs
|
0 - 3600
|
Attribute |
When reading Lua scripts from file or from database, the Lua script loader will periodically
perform a full reload of the chunk. This attribute specifies how many seconds must pass before the
script loader will force-reload the Lua script chunk. Setting this value to 0 will force full-reload check for every Lua execution.(Default = 300 )
|
mtime_check_secs
|
0 - 600
|
Attribute |
When reading Lua scripts from file or from database, the Lua script loader will periodically check
the disk or database to determine if the script modified time has changed. This attribute specifies
how many seconds must pass before the script loader will re-examine the on-disk or database row to
check for a change in the modified time for the Lua script body. Setting this value to 0 will force modification check for every Lua execution.(Default = 5 )
|
failure_retry_secs
|
0 - 600
|
Attribute |
When a Lua script read from file or database fails, then the Lua script loader will reject
Lua script execution for that same Script Name for this number of seconds, before checking again
to see if the on-disk or in-database lookup succeeds. Setting this value to 0 will force disk/database lookup for every Lua execution after failure.(Default = 5 )
|
cc_free_per_script
|
0 - 1000
|
Attribute |
When Lua processing finishes, the Lua context may be retained to use for subsequent logic performed
using the exact same Script Name, for the purpose of reducing script start-up overhead and improving
performance. However, a burst of simultaneous calls for the same script may generate an excess of Lua contexts which subsequently are not needed. This attribute defines the maximum number of Lua contexts which will ever be cached as free/spares for any single Script Name. Setting this value to 0 will disable caching/re-use of Lua contexts.(Default = 10 )
|
cc_unused_secs
|
0 - 3600
|
Attribute |
When Lua processing finishes, the Lua context may be retained to use for subsequent logic performed
using the exact same Script Name, for the purpose of reducing script start-up overhead and improving
performance. However, a burst of simultaneous calls for the same script may generate an excess of Lua contexts which subsequently remain idle. Free Lua context which are not used for this number of seconds will be discarded. Setting this value to 0 will disable caching/re-use of Lua contexts.(Default = 300 )
|
load_timeout_ms
|
100 - 10000
|
Attribute |
Applies for asynchronous loaders only (e.g. loaders fetching Lua script from Database). This is the allowed time in milliseconds for the Lua script load to complete. (Default = 1000 )
|
Many Lua Service Libraries also define additional configuration elements within the service
element.
For example, Service Libraries which read their Lua scripts from disk will typically define a script_dir
attribute. Refer to the per-Service Library documentation for N2SVCD,
N2SCP, or
N2SIP for details.
Agent Configuration
A Lua Agent is used to send messages to an AgentApp, typically for the purpose of communicating with external agents. The Lua script execution will suspend while the agent waits for its response.
This section describes the common configuration for adding a Lua Agent to the Logic Application. For more information on per-Agent configuration, please refer to the individual documentation for each Agent Library.
An agent
entry within the agents
element of the LogicApp configuration has
the following attributes:
Parameter Name | Type | XML Type | Description |
---|---|---|---|
module
|
String | Attribute | [Required] The module name containing the Lua Agent code. |
libs
|
String | Attribute |
Optional library path to include when searching for the module for this Agent.
|
A Lua Agent typically also requires the configuration of a default_<action>_app_name
entry
specifying the name of the AgentApp which will receive the messages sent by the Lua Agent.
Refer to the per-Agent documentation for details.
Message Handling
In addition to the common Application management messages, the LogicApp uses the following messages:
- DB Messages (
DB-REQUEST
outbound).
Agent libraries are provided in this package which implement the following messgaes:
- DIAMETER-C Messages (
DIAMETER-C-REQUEST
outbound). - REST-C Messages (
REST-C-REQUEST
outbound). - SMPP-C Messages (
SMPP-C-REQUEST
outbound). - SOAP-C Messages (
SOAP-C-REQUEST
outbound). - FOX-C Messages (
FOX-C-REQUEST
outbound).
Service libraries are provided in this package which support the following messages:
- DIAMETER-C Messages (
DIAMETER-C-REQUEST
outbound). - REST-S Messages (
REST-S-REQUEST
inbound). - SMPP-S Messages (
SMPP-S-REQUEST
inbound). - SOAP-S Messages (
SOAP-S-REQUEST
inbound).
Also, the ProcessUSSDLuaService
library uses these messages for MAP USSD processing:
- TCAP Messages (
TCAP-BEGIN
inbound).