Nuance-specific capabilities

Nuance products have capabilities beyond the basics covered by the VoiceXML specification. As a practical matter, supporting Nuance-specific features improves performance, enables application tuning, and reduces your technical support costs.

Although your voice platform can deliver requests to Nuance products without using Nuance-specific functionality, this limits your platform and its applications significantly.

Voice platforms must support application functionality as described in the following sub-sections.

Configurations for application sessions

Application developers use a session.xml file to configure each session as it starts. They can also add a company and application configuration to the file.

An application name is any identifier for the running application.

A companyname is typically the name of a corporation associated with the running application. On a system running a single application, the company is the name of the corporation that developed the application. On a system that host many applications, the company is the name of the tenant corporation for whom the application runs. When used as a tenant grouping, the company name defines a single policy to control configuration and logging for many applications.

The company and application names control the following:

  • Logging file system—The system uses the company and application names to store log files under a single parent folder. This simplifies using the data for operations, reporting, and tuning.
  • Security settings—You can define a single security key to encrypt private data for all applications under the tenant’s control.
  • Adapted recognition models—As part of the recognizer’s self-learning technology, the system automatically adapts all models under the tenant's control.
  • Customized recognition models—The tenant can specify customized models to replace the installation defaults. This is useful when an application has access to highly-customized models (usually provided by Nuance).

For more session.xml information, including MRCP client requirements, see Session configuration (session.xml).

Vendor-specific properties

To support Nuance-specific configurations, the application must specify Nuance parameters, and the browser must pass them to Nuance Speech Server.

The voice browser works as follows:

  1. When an application specifies a <property>, the browser translates the property into a standard MRCP message or passes it as a vendor-specific property (VSP).
  2. Before setting the value of a <property>, the client retrieves the current value using GET-PARAMS. This is required to manage scoping: any parameter set through a <property> element must be reset to its previous value when leaving the scope of that <property> element.
  3. When the property name begins with "swirec," the client sets it as a VSP using a RECOGNIZE or SET-PARAMS call to the recognizer.
  4. When the property name begins with "switts," the client sets it as a VSP using a SPEAK or SET-PARAMS call to the synthesizer.
  5. When leaving the scope of the <property> element in the VoiceXML document, the browser resets the VSP to the original value using SET-PARAMS.

The following example shows how the application uses <property> elements within the scope of a field.

<field ...>
<field ...>
<field ...>
  <property name="swirec.exposeplayable" value="true"/>
  <property name="swirec.callog.grammarlabel" 
      value="getLocality"/>
...
</field>

The next example shows how the browser maps the <property> elements. First, the client checks for the current values of the requested parameters, then sets them to the requested values, and finally resets them to their original values after the recognition is complete:

GET-PARAMS 1 MRCP/1.0
Vendor-Specific-Parameters:
        swirec.exposeplayable;
        swirec.callog.grammarlabel
MRCP/1.0 1 200 COMPLETE
Vendor-Specific-Parameters:
        swirec.exposeplayable="false";
        swirec.callog.grammarlabel="getState"
SET-PARAMS 2 MRCP/1.0
Vendor-Specific-Parameters:
        swirec.exposeplayable="true";
        swirec.callog.grammarlabel="getLocality"
RECOGNIZE 3 MRCP/1.0
Content-Type: application/grammar+xml
Content-Id: mydigits
Content-Length: nnn
No-Input-Timeout: 30000
<?xml version="1.0"?>
<grammar root="digit" version="1.0" xml:lang="en-US"
        xmlns="http://www.w3.org/2001/06/grammar">
  <rule id="digit" scope="public">
    <item>one two three four five</item>
  </rule>
</grammar>
SET-PARAMS 4 MRCP/1.0
Vendor-Specific-Parameters:
        swirec.exposeplayable="false";
        swirec.callog.grammarlabel="getState"

Security levels to protect confidential data

Nuance protects confidential data as it moves between processes and gets written to disk. This might include information such as names, addresses, telephone numbers, account numbers, and passwords. The data can be DTMF touchtone signals, spoken utterances, synthesized speech requests, recognized speech, and saved audio files.

To protect data, the application sets security levels with swirec.secure_context and switts.secure_context, and the browser passes the parameter in RECOGNIZE or SPEAK requests. For details on protecting sensitive data, see Protecting confidential data.

You can also mute audio data with the swirec.mute_wcr and switts.mute_wcr properties. This feature is independent of security levels, and WCR muting overrides the security level behavior in the same scope.

The swirec.mute_wcr/switts.mute_wcr, wcr_encrypt, and swirec.secure_context/switts.secure_context parameters may also interact as follows:

  • If mute_wcr is not enabled (not set by VXML property nor by vendor specific parameter) and wcr_encrypt is 0, the secure_context setting determines whether the recording is muted.
  • If mute_wcr is not enabled and wcr_encrypt is 1, the recording is encrypted rather than muted, even if secure_context is set to "suppress".
  • If mute_wcr is enabled, then it mutes the call even if wcr_encrypt is also enabled, overriding encrypt or open security levels set in the secure_context parameter.

The following example shows how VoiceXML can mix security levels and WCR muting, and is followed by the MRCP translation and a description of the resulting WCR recording.

This VoiceXML example sets security levels at the dialog (session) and request levels.

<form id="form1">
  <property name="switts.secure_context" value="open"/>// dialog scope
  <property name="swirec.secure_context" value="open"/>// dialog scope
  <field name="field1"/>
     <prompt>please say password</prompt> 
     <property name="swirec.secure_context" value="suppress"/>// request

         scope
     <property name="swirec.mute_wcr" value="1"/> //request scope
     <grammar><!-- ... --></grammar>
  </field>
  <field name="field2"/ type="boolean">
     <prompt>did you say</prompt>
     <property name="switts.secure_context" value="suppress"/>// request

         scope
    <property name="swirec.mute_wcr" value="1"/> //request scope
    <prompt><value expr="field1"/></prompt>
    <property name="swirec.secure_context" value="open"/>// request

        scope
    <property name="swirec.mute_wcr" value="0"/> //request scope
  </field>
</form>

The following example illustrates the relevant parts of a typical MRCP call flow using both secure_context and WCR muting parameters:

INVITE Vendor-Specific-Parameters: switts.secure_context=open,

            swirec.secure_context=open
SPEAK–"Please say password"
RECOGNIZE (log is suppressed; WCR records silence)
SPEAK–"Did you say" (WCR default value; includes speech)
SPEAK Vendor-Specific-Parameters: witts.secure_context=suppress,

    switts.mute_wcr=1 - "abc123"
RECOGNIZE (log is suppressed; WCR records silence)

This table shows the approximate contents of the WCR file:

Synthesizer

User

Call log

WCR content

Please say password

  

Please say password

Please say password

abz123

[suppressed]

silence

Did you say

  

Did you say

Did you say

abc123

  

[suppressed]

silence

No

No

No

Merging application logs

Nuance enables you to merge application logs with the Speech Server call logs by using an application session ID, which the call log process uses to match up corresponding application and general call logs. The application inserts that ID into the general call log using two Nuance-specific properties for the VoiceXML <grammar> element:

  • SWI.appsessionid—Session id generated by the application, which it uses in its own (application) logs and seeds in the Nuance call logs.
  • SWI.appstepid—Counter incremented once for each recognition. It helps the log merge process identify each part of a log.

For example, the following VoiceXML code generates a corresponding SWIapps entry in the call log:

<field name="x">
<grammar src="http://my-http-server/my-grammar.grxml

    ?SWI.appsessionid=431cc972eaa41c1a22e99ac59f5e4fa4&SWI.appstepid=3">
</field>
TIME=20070501120415294|CHAN=f66ef6c94ffb0359021a33009a2d69da|EVNT=SWIapps|SESN=431cc972eaa41c1a22e99ac59f5e4fa4|STEP=3|UCPU=0|SCPU=0

Only the first session ID received from the platform is logged for all SWIapps events in a call. If the session ID changes during a call, new IDs are ignored and a warning is issued.

If the application session ID is set at the beginning of a session, prior to any speech processing. it is included in the general call log file name.

For example:

NUAN-mm-ss-machine-sid-APPSESSIONID-LOG

Where sid is the system-generated session ID and APPSESSIONID is the session ID generated independently by the application. See Call log directories and files.