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:

  1. Determine which Lua script to execute, and
  2. 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 Attribute 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 Attribute 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)
edr_stream_key String Attribute Override the default EDR Stream Key for EDRs written using the n2svcd.write_edr method.
(Default = the default_edr_stream_key value from the Application)
globals Object Element Container for additional service-specific 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. Refer to the Service Global Configuration section for details of the global definitions.
script_reload_secs 0 - 3600 Attribute How long a script is used from cache before a hard reload is requested. A hard reload will ignore any mtime in the database or on the disk file and will reload the script content regardless.
Setting this value to 0 will force hard-reload for every Lua execution.
(Default = 300)
script_check_secs 0 - 600 Attribute How long a script is used from cache before a soft reload check is requested. A soft reload will check the mtime in the database or on the disk file and will reload the script only if it believes that the script source mtime has changed since the last load.
Setting this value to 0 will force soft-reload check for every Lua execution.
(Default = 5)
script_fail_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)
script_purge_secs 0 - 3600 Attribute How long to retain the Lua script and associated compiled Lua state for a script (for a script key) which has no running threads at this time.
Setting this value to 0 will force script/state to be discarded when the last thread ends.
(Default = 600)
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 script key lookup to complete, or for the script load to complete. For loaders which determine both script key and script load asynchronously then the total load time may be up to twice this value.
(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.

Service Global Configuration

Each service may have one or more global definitions configured. Each global may be a simple value such as a string or integer, or may be a complex data structure.

Each global may be defined with:

Parameter Name Type XML Type Description
name String Attribute Mandatory
Defines the name of the global Lua constant value to set.
type string /
integer /
boolean /
hash /
array
Attribute Indicates the type of Lua global, as set out in Service Global Types. (Default = hash for globals with custom attributes or child nodes, otherwise `string`)
value String Attribute Defines the value of the global Lua constant value to set.
Required for simple globals and ignored for complex globals. Some special value types may be used, as set out in Service Global Value Types.

Service Global Types

The string, integer, and boolean global types are converted directly to their base Lua equivalents. Note that N2SVCD common application Boolean types are used to determine a boolean value. For example, the following service global XML definition:

    <globals>
        <global name="GLOBAL_1" value="0"/>
        <global name="GLOBAL_2" value="0" type="integer"/>
        <global name="GLOBAL_3" value="0" type="boolean"/>
    </globals>

… is equivalent to the following Lua global variable definitions:

GLOBAL_1 = "0"
GLOBAL_2 = 0
GLOBAL_3 = false

For complex global definitions, a hash type is implied when the global has child nodes or when global attributes are present. Hash conversion places each attribute and child in an appropriately-named key. A hash type is also used automatically if an XML node has attributes. In such cases, the value of the node, if any, will be placed under the value key.

If an array is required, it must be indicated by setting the type to array.

As an example of complex global definitions, the following service global XML definition:

    <globals>
        <global name="GLOBAL_4" thing1="1">
            <thing2>
                <thing3 thing4="4"/>
                <thing4>4</thing4>
            </thing2>
        </global>
        <global name="GLOBAL_5" type="hash"/>
        <global name="GLOBAL_6" type="array">
            <item thing1="1" thing2="2"/>
            <item thing1="3" thing2="4">5</item>
            <item>
                <thing1a type="boolean">true</thing1a>
                <thing1b type="boolean" value="true"/>
                <thing1c>true</thing1c>
                <thing1d value="true"/>
                <thing1e type="boolean"/>
                <thing2a type="integer">1</thing2a>
                <thing2b type="integer" value="1"/>
                <thing2c>1</thing2c>
                <thing2d value="1"/>
                <thing2e type="integer"/>
                <thing3a type="string">foo</thing3a>
                <thing3b type="string" value="foo"/>
                <thing3c>foo</thing3c>
                <thing3d value="foo"/>
                <thing3e type="string"/>
            </item>
        </global>
        <global name="GLOBAL_7" type="array"/>
        <global name="GLOBAL_8" thing1="1"/>
    </globals>

… is equivalent to the following Lua global variable definitions:

GLOBAL_4 = {
    thing1 = '1',
    thing2 = {
        thing3 = {
            thing4 = '4'
        },
        thing4 = '4'
    }
}
GLOBAL_5 = {}
GLOBAL_6 = {
    {
        thing1 = '1',
        thing2 = '2'
    },
    {
        thing1 = '3',
        thing2 = '4',
        value = '5'
    },
    {
        thing1a = true,
        thing1b = true,
        thing1c = 'true',
        thing1d = 'true',
        thing1e = false,
        thing2a = 1,
        thing2b = 1,
        thing2c = '1',
        thing2d = '1',
        thing2e = 0,
        thing3a = 'foo',
        thing3b = 'foo',
        thing3c = 'foo',
        thing3d = 'foo',
        thing3e = ''
    }
}
GLOBAL_7 = {}
GLOBAL_8 = {
    thing1 = '1'
}

Note that value is ignored for complex globals.

Service Global Value Types

For any simple global value or complex leaf value, the following value formats can be used:

If no value is present, the following defaults apply:

Node attributes are always treated as strings and cannot be cast using type.

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:

Agent libraries are provided in this package which implement the following messgaes:

Service libraries are provided in this package which support the following messages:

Also, the ProcessUSSDLuaService library uses these messages for MAP USSD processing: