Navigation :

N2SRP-VXML Lua Application

N2SRP-VXML Lua Application Configuration

The LUA SRP (Specialised Resource Platform) VXML Application is a SIP-Controlled, SIP-Trunked SRP whose VoiceXML interpreter is implemented in the Lua scripting language. VoiceXML is transpiled to be interpreted as Lua by the SRP. In this VoiceXML interpreter:

SIP/RTP is used for audio stream control.
The VoiceXML interpreter controls the announcements played and interaction requests made to the caller.

This page describes the configuration parameters specifically for the Lua Logic script. There is also a general N2SRP (VXML) Deployment Guide page which describes all of the components which are required to implement the N2SRP-VXML solution in a typical deployment model.

Here is a N2SRP-VXML Lua Application config example showing the specific configuration within the LogicApp.

    <application name="VXML-SRP" module="LogicApp" admin_alloc="1m" user_alloc="64m">
        <include>
            <lib>../apps/logic/lib</lib>
            <lib>../../n2sip/lib</lib>
            <lib>../apps/rest_c/lib</lib>
        </include>
        <parameters>
            <parameter name="edr_enabled" value="1"/>
            <parameter name="default_edr_app_name" value="EDR"/>
            <parameter name="default_edr_stream_key" value="vxmlsrp"/>
            <parameter name="trace_level" value="0"/>
            <parameter name="max_trace_level" value="3"/>
            <parameter name="trace_per_second" value="20"/>
            <parameter name="default_lua_lib_path" value="../lua/lib/?.lua;../lua/lib/3rdparty/?.lua;../../n2sip/lua/lib/?.lua"/>
            <parameter name="default_rest_app_name" value="VXML-REST-Client"/>
        </parameters>
        <config>
            <services>
                <service module="LhoSipApp::LhoSipIncallLuaService"
                    libs="../../n2sip/apps/lho_sip/lib"
                    script_dir="../../n2sip/lua/svc"
                    >

                    <globals>
                        <!-- section for custom configuration for the VXML SRP service -->
                    </globals>

                    <script_check_secs>5</script_check_secs>

                    <triggers>
                        <!-- section for explicitly defining the called party numbers which trigger the SRP VXML interpreter -->
                        <trigger called_prefix="64" script_key="n2srp_vxml"/>
                    </triggers>
                </service>
            </services>
            <agents>
                <agent module="LhoSipApp::LhoSipOutcallLuaAgent" libs="../../n2sip/apps/lho_sip/lib"/>
                <agent module="VxmlLuaAgent" libs="../../n2sip/apps/vxml_lua_agent/"/>
            </agents>
        </config>
    </application>

Configuration Details

Parameters

The default_lua_lib_path must include the n2svcd and n2sip default lua/lib paths. The default_rest_app_name must point to a REST Client app which will be used to request VoiceXML documents from a VoiceXML server.

Service

The LhoSipIncallLuaService service must be configured as per the LhoSipIncallLuaService Configuration page.

It should have a service-level edr_stream_key attribute present which defines the default stream key to which the SRP (VXML) EDRs will be written.

The service-level script_dir should be configured as “../../n2sip/lua/svc” which is typically the relative path from the n2svcd/bin directory to the n2sip/lua/svc directory which contains the required service script n2srp_vxml.lua.

Agents

The VXML service requires the use of the VxmlLuaAgent for querying VoiceXML servers.

Triggers

At least one trigger must be defined which points to the script with script_key configured as n2srp_vxml. Refer to the LhoSipIncallLuaService configuration page for possible trigger-matching parameters.

Globals

SERVICE_IDENTIFICATION

The SERVICE_IDENTIFICATION global parameter must be defined for the service. This array of mappings will define which VoiceXML document URI should be used to retrieve the initial VoiceXML document for each possible inbound called prefix

Refer to the Logic App Configuration page for a description of how to defined global constants as arrays. The SERVICE_IDENTIFICATION must be an array of hashes. The format is as follows:

    <global name="SERVICE_IDENTIFICATION" type="array">
        <mapping type="hash"> <called_prefix>64910010011</called_prefix> <uri>https://voicexml.nsquared.nz/info.jsp</uri> </mapping>
        <!-- more mappings as required can be defined -->
    </global>

Each <mapping> must have the following elements defined, which become key/value pairs of the mapping itself:

Property	Description
`called_prefix`	The prefix of the called party number (taken from the `To:` SIP header) to match against a mapping. More specific mappings must be defined before less specific mappings.
`uri`	The HTTP(S) URI to retrieve the first VoiceXML document from, for the call interaction. If the host & port are not defined, then the default host and port of the associated `RestClientApp` will be used. Note that any SSL/TLS connectivity required must be defined on the `RestClientApp` itself.

VXML_SESSION_VARIABLES

The VXML_SESSION_VARIABLES global parameter may be defined for the service. This table of session varaibles will be made available as session variables to the VoiceXML interpreter and can be accessed within VoiceXML documents using:

    <var name="myvar" expr="session.connection.aai"/>

All listed properties will become session variables.

Refer to the Logic App Configuration page for a description of how to defined global constants such as VXML_SESSION_VARIABLES. The VXML_SESSION_VARIABLES value if declared must be a hash, with the element names as the session variable name, and element values as the session variable values.

For example, VXML_SESSION_VARIABLES might be defined as:

    <global name="VXML_SESSION_VARIABLES" type="hash">
        <connection.aai>VXML Application (N2SRP)</connection.aai>
    </global>

VXML_PROPERTIES

The VXML_PROPERTIES global parameter may be defined for the service. This table of properties will define the initial value of VoiceXML properties, i.e. those document in Section 6.3 of the VoiceXML 2.0 specification. Properties not listed in this table are ignored by the N2SRP VXML interpreter and need not be defined. If defined, they will be ignored.

Refer to the Logic App Configuration page for a description of how to defined global constants such as VXML_PROPERTIES. The VXML_PROPERTIES value if declared must be an object. Any of the following properties may be defined. If a property is not defined, the default as described will be used.

Property	Default	Description
`interdigittimeout`	4s	The inter-digit timeout value to use when recognizing DTMF input. Defined as a Time Designation value.
`termtimeout`	0s	The terminating timeout to use when recognizing DTMF input. Defined as a Time Designation value.
`termchar`	#	This is the termination digit to use to determine input termination by the user during an IVR interaction. This must be defined as one of: 0,1,2,3,4,5,6,7,8,9,*,#. The termination digit may be undefined. When undefined, the default termination digit for the SRP RTP application will be used.
`bargein`	true	Whether to allow users to interrupt announcements being played with DTMF digits. Default is true. May be set to "true" or "false".
`bargeintype`	speech	Type of announcement interrupt analysis to use. The N2SRP only supports "speech" interrupts (i.e. DTMF detection). When "hotword" is defined, the SRP will raise an error during call processing.
`timeout`	8s	The timeout waiting for the user to input a DTMF tone before a noinput event is generated by the VXML interpreter. Defined as a Time Designation value.
`documentmaxstale`		The maximum 'staleness' to allow for cached documents. Set to an empty value by default, which causes the VXML HTTP request engine to not define the `Cache-Control` `max-stale` header value. When specified, must be specified as a number indicating the number of seconds to allow stale cache value to be used. Note that the VXML SRP does not cache documents. This value is only relevant if a downstream HTTP proxy is caching VXML documents.
`documentmaxage`		The maximum age a downstream HTTP cache should allow when providing cached documents in response to a HTTP request by the VXML SRP. When set to an empty value (the default), the HTTP request engine will not set the the `Cache-Control` `max-age` header value. When specified, must be specified as a number indicating the maximum age (in seconds) a reqested document may be before a fresh document must be retrieved. Note that the VXML SRP does not cache documents. This value is only relevant if a downstream HTTP proxy is caching VXML documents.
`documentfetchhint`	safe	When set to `safe` all requests for documents by the VXML SRP will be made at the time the document is required. A value of `prefech` is ignored (all HTTP requests for documents are performed in safe mode)
`audiomaxstale`		Ignored. All audio is read at the moment it is required from the SRP's local audio storage - whether from disk, or local database.
`audiomaxage`		Ignored. All audio is read at the moment it is required from the SRP's local audio storage - whether from disk, or local database.
`audiofetchhint`	prefech	Ignored. All audio is read at the moment it is required from the SRP's local audio storage - whether from disk, or local database.
`fetchaudio`		When audio should be played to the caller during the retrieval of documents from a VoiceXML server, the audio file to play must be defined by this property. The value of this property must be a valid audio file name as stored by the SRP.
`fetchaudiodelay`	2s	The delay before initiating playback to the caller of the audio defined by the fetchaudio parameter. Defined as a Time Designation value.
`fetchaudiominimum`	5s	The minimum time to play the audio defined by fetchaudio once started. If the VXML SRP receives the VXML document prior to this minimum timeframe completing, then execution of the document is delayed until the minimum timeframe is complete.
`fetchtimeout`	0s	Ignored. All audio is read at the moment it is required from the SRP's local audio storage - whether from disk, or local database. Defined as a Time Designation value.
`maxnbest`	1	Ignored. In this N2SRP VXML service release, `maxnbest` is always limited to 1.

MAX_TRANSITIONS

The MAX_TRANSITIONS global parameter may be defined for the service. This variable defines the maximum number of transitions allowed between VoiceXML documents (either internally with a document via <goto> or between documents via <goto> or <submit>).

This variable ensures infinite loops do not occur. The default is set to 10.

    <global name="MAX_TRANSITIONS" type="integer">1</global>

DEFAULT_LANGUAGE

The DEFAULT_LANGUAGE global parameter may be defined for the service. This variable defines the name, as known in N2SRP’s UI configuration and in the N2SRP database, of the language to treat as the default to use for audio announcements.

    <global name="DEFAULT_LANGUAGE">English</global>

LANGUAGE_MAPPING

The LANGUAGE_MAPPING global parameter may be defined for the service. This hash defines the mapping of xml:lang attributes that may be present in VoiceXML documents to named languages in the N2SRP configuration. Where a VoiceXML document language is defined without a mapping, or where a VoiceXML document does not have a xml:lang attribute, the default langauge will be used.

    <global name="LANGUAGE_MAPPING" type="hash">
        <en-EN>English</en-EN>
    </global>

Time Designation Values

VoiceXML time designation values are supported as configuration values for variables and properties where appropriate. A time designation value is a number, such as 250 or 1.1 or +0.5 followed by either ms (indicating milliseconds) or s (seconds).

Example values:

1s
250ms
+3.0s