Holly5 VoiceXML Developer Guide Holly Voice Platform 5.1. Document number: hvp-vxml-0009 Version: 1-0 Issue date: December

Transcription

1 Holly5 VoiceXML Developer Guide Holly Voice Platform 5.1 Document number: hvp-vxml-0009 Version: 1-0 Issue date: December

2 Copyright Copyright 2013 West Corporation. These documents are confidential and contain proprietary information. No part of these documents may be reproduced, published or disclosed in whole or part, by any means: mechanical, electronic, photocopying, recording or otherwise without the prior written permission of West Corporation. or Holly Australia Pty Ltd. The information contained in this document is strictly commercial in confidence and can only be provided to persons who have signed a non-disclosure agreement. This document is not to be copied without prior written consent. Control Version Date Change Notes Author Dec 2009 Approved for release A Hunt Related Documents Document Title Holly Voice Platform Release Notes HVP Release 5.1 Holly Management System User Guide HVP Release 5.1 Holly Voice Platform Operations Guide HVP Release 5.1 McGlashan et al., Voice Extensible Markup Language (VoiceXML) Version 2.0, W3C Recommendation 16 March 2004, Oshry et al., Voice Extensible Markup Language (VoiceXML) 2.1, W3C Recommendation 19 June 2007, Doc Number hvp-rpt-141 hvp-hms-0013 hvp-0028 VoiceXML 2.0 VoiceXML 2.1 D. Kristol and L. Montuli, HTTP State Management Mechanism, RFC 2965, October 2000 RFC2965 T. Berners-Lee, R. Fielding, U.C. Irvine and L. Masinter, Uniform Resource Identifiers (URI): Generic Syntax, RFC 2396, August 1998 McGlashan & Hunt, Speech Recognition Grammar Specification Version 1.0, W3C Recommendation 16 March 2004, / Burnett, Walker & Hunt, Speech Synthesis Markup Language (SSML) Version 1.0, W3C Recommendation 7 September 2004, / Tichelen & Burke, Semantic Interpretation for Speech Recognition (SISR) Version 1.0, W3C Working Draft 3 November 2006, / RFC2396 SRGS 1.0 SSML 1.0 SISR 1.0 2/61

3 Table of Contents 1. Introduction VoiceXML Documents and Execution Standards Compliance VoiceXML 2.0 & 2.1 Compliance Compatibility of VoiceXML 2.0 & VoiceXML Extensions Holly Voice Platform Dependent Behaviors VoiceXML Document Handling VoiceXML Document Headers Header and Parsing Scope of VoiceXML Properties Character Sets and Supported Languages Events Errors Fetch Errors Other Errors Fetching Behaviors Initial Document Failover HTTP HTTPS HTTP User-Agent Header DNS Resolving Behavior Cookies Caching Disabling Caching Default Property Values Access Control on <data> Browser Protections Input: Speech Recognition and DTMF Selecting a Speech Recognizer ASR Engine Switching Allowed ASR Engines ASR-Specific Behaviors Engine-Specific Properties vlingo Loquendo /61

4 3.3 ASR Sessions Timeouts (speech) Confidence Scores N-Best Record Recording User Utterances during Recognition Re-Recognition from Recorded Utterances Grammars Standard Grammars Proprietary Grammars External Grammars Pre-built and Binary Grammars Universal Command Grammars Builtin Support Grammar Fetch Behavior DTMF interdigittimeout and termtimeout termchar DTMF Buffering Holly DTMF Recognizer v Output: Prompting and TTS Selecting a TTS Engine TTS Switching Using a Non-default TTS Voice SSML Audio Files Throwing Errors on Audio Fetch Failures <mark> Element Telephony: Session & Transfers Session Variables Session Variables for Outbound Session.connection.aai Example Passing Data Between Sessions Transfers Transfer Types Destination URIs Transfer CLID Recognition During Transfer Whisper Transfer... 33

5 6. Logging Events Configuring Event Logging <log> Element Label on <log> Changing the Event Type Objects and Arrays ECMAScript Log Function Call Record: LOG_CALLS Log Suppression Exceptions to Suppression Record of Suppression Logging Masked Data Raising Alarms A. Appendix: Application Parameters A.1 VoiceXML A.2 Speech Recognition A.3 DTMF A.4 Text to Speech A.5 Logging A.6 Telephony B. Appendix: Re-Recognition from Recorded Utterance B.1 Re-recognition in VoiceXML Applications B.2 Prompts and Barge-in B.3 ASR Configuration C. Appendix: Holly DTMF Recognizer v C.1 SRGS+XML C.2 Sample grammars... 59

6 1. Introduction The purpose of this document is to provide a guide for VoiceXML developers who are constructing VoiceXML applications to run on the Holly Voice Platform. It documents the characteristics of the Holly VoiceXML implementation and details the supported VoiceXML extensions to the standard. This document does not provide a full introduction to programming in VoiceXML and some knowledge of the VoiceXML 2.0 & 2.1 standards is assumed. See VoiceXML 2.0: (16 March 2004) VoiceXML 2.1: (19 June 2007)

7 2. VoiceXML Documents and Execution 2.1 Standards Compliance VoiceXML 2.0 & 2.1 Compliance Holly is VoiceXML 2.0 and VoiceXML 2.1 conformant platform according to the following specifications. VoiceXML 2.0: (16 March 2004) VoiceXML 2.1: (19 June 2007) The Holly Voice Platform supports all required capabilities defined in these standards and supports most of the optional features as documented in this guide. In terms of the VoiceXML architectural model, the Holly Voice Browser comprises a VoiceXML Interpreter and a VoiceXML Interpreter Context integrated with the Holly Voice Platform Compatibility of VoiceXML 2.0 & 2.1 VoiceXML 2.1 is fully compatible with VoiceXML 2.0 so there is no requirement for application migration. Further, Holly enables VoiceXML 2.0 and 2.1 applications to co-reside on the same platform and even allows a single call or application to mix VoiceXML 2.0 and 2.1 content VoiceXML Extensions Holly sees clear benefit to customers by providing faithful and compliant implementation of open standards. In addition to having a Certified 100% Compliant implementation of the VoiceXML standard, Holly has implemented limited extensions where required to provide customers with functionality that cannot be directly implemented through the standard. These extensions are clearly labeled as such in this document Holly Voice Platform Dependent Behaviors In implementing the VoiceXML specification, Holly delivers a range of value-add capabilities that enhance its utility for development and operations staff whilst maintaining full compatibility to the standard. Note: Some properties depend on the configuration of the Holly Voice Platform as described elsewhere in this document. Platform administrators may choose to switch off support for some features and therefore properties may have no effect despite being set correctly. 2.2 VoiceXML Document Handling VoiceXML Document Headers When using VoiceXML 2.1 features, the following declaration must be present in the document header: <vxml version="2.1" xmlns=" Following is a sample VoiceXML 2.1 header:

8 <vxml xmlns=" xmlns:xsi=" xsi:schemalocation=" version="2.1"> Following is a sample VoiceXML 2.0 header: Header and Parsing <vxml xmlns=" xmlns:xsi=" xsi:schemalocation=" version="2.0"> For conforming validation of input VoiceXML documents, the xmlns attribute must be supplied on the root element of the document with the value as required by VoiceXML 2.0. The handling of the xmlns attribute is documented in the following table. xmlns attribute value ml <not defined> <other namespaces> Document Treatment Indicates that the document is a Conforming VoiceXML 2.0 document. The Holly Voice Platform performs strict document checking according to the standard. The Holly Voice Platform assumes a VoiceXML 2.0 document and performs loose validation of the document content. The Holly Voice Platform throws an error.badfetch event. The application parameter nonstrictvxml can be set to true to achieve loose validation of document content even when the xmlns attribute is present on the root element of documents. This parameter affects the parsing of all documents loaded during a call, and also causes the ECMAscript interpreter to ignore references to undefined properties. The nonstrictvxml parameter can only be set as an application parameter via the Holly Management System; it cannot be set as a VoiceXML property. With nonstrictvxml set to true the parser uses DTD rather than VXML schema Scope of VoiceXML Properties The VoiceXML property behaviors are fully implemented following Section 6.3 of VoiceXML 2.0. Properties may be declared with application scope (in the root document), with document scope (within a <vxml> element), or for a particular <menu>, <form>, or form item. Properties apply to their parent element and all the descendants of the parent. A property at a lower level overrides a property at a higher level. When different values for a property are specified at the same level, the last one in document order applies. Properties specified in the application root document provide default values for properties in every document in the application; properties specified in an individual document override property values specified in the application root document. Additionally, the Holly Voice Platform provides the ability to set properties at the session level (interpreter context). Session properties are set as an Application Paramater on the Applications page

9 in the Holly Management System (administrators should refer to the Holly Management System User Guide for details on modifying application parameters). The session scope is above the application scope as defined in VoiceXML 2.0, section Character Sets and Supported Languages By default the Holly Voice Platform assumes a language identifier of en-au. Other values may be specified in VoiceXML documents using the xml:lang attribute, but they will result in error.unsupported.language events being thrown unless they are also listed in the Supported Languages configuration parameter. Note that ASR and TTS engines may require additional configuration to support other languages. HVP 5.1 has support for the Latin-1 character set (ISO ) in grammar files, TTS strings, ECMAScript, in line grammar content, and similar functionality, e.g. é as in café. HVP 5.1 supports UTF-8 in recognizers, TTS, VoiceXML applications, grammars and reporting. 2.3 Events Errors on Document Transition The Holly Voice Platform handles document transition errors, typically error.badfetch, in the scope of the calling document. 2.4 Errors This section documents common errors generated by the Holly Voice Browser as viewable in the event logs through the Holly Management System. For errors not described in this section, please contact Holly Customer Support Fetch Errors All fetch errors result in a fetch failure and an error.badfetch will be thrown within the application. The web fetching architecture of the Holly Voice Browser is implemented in the four layers shown below. Fetch errors propagate through these four layers resulting in multiple error reports for a single anomalous event. Typically for any fetch anomaly there will be an error from each layer (in a few cases there may be two from layer 3). Layer Error numbers 1 High level I/O layer 203, 211, High level network I/O layer 204, 206, HTTP protocol layer 217, 219, 221, 236, 237, 244, Low level socket and SSL layer 241, 500, 700 Error # Distinguishing error text Cause Does Holly terminate call Comments

10 Error # Distinguishing error text Cause Does Holly terminate call Comments 203 Unable to open URI An attempt to fetch a VoiceXML document failed with one of the errors documented above On first document triggers failover; on subsequent documents handled by application The specific error condition will be reflected in other error messages. 204 Open error + <URL> An error occurred while attempting to open a connection to the server No Investigate a network or application server issue. 206 Read error + rc=51 The Holly Voice Browser timed out during a read operation on an HTTP(S) connection No Investigate a network or application server issue. 211 Audio fetch failed + <URL> The audio resource could not be retrieved No This is a top level error message; other messages give more specific explanation. 217 open failed (internal error) + <URL> Failed to open a connection to the server denoted by the URL No Investigate a network or application server issue. 221 Failed to get HTTP status The status line in the HTTP response could not be parsed No More specific errors will also be reported; investigate a network or application server issue. 228 Fetch operation timed out An attempt to fetch a resource exceeded fetchtimeout while creating or reading from a connection No Investigate a network or application server issue, or change the fetchtimeout property. 236 Fetch timeout exceeded during Open An attempt to open a connection exceeded fetchtimeout No Investigate a network or application server issue. 237 Fetch timeout exceeded during read A connection was created successfully, but while attempting to read from it fetchtimeout was exceeded No Investigate a network or application server issue. 241 Socket error timeout connecting to socket Failed to open a connection to a particular IP address No Investigate a network or application server issue. 244 Socket error cannot connect + <URL> An error, other than a timeout, occurred while connecting to a server No More specific errors will also be reported; investigate a network or application server issue.

11 Error # Distinguishing error text Cause Does Holly terminate call Comments 249 No data available on socket for reading An error occurred while trying to read the status line in the HTTP response No Error 221 and more specific errors will also be reported; investigate a network or application server issue. 500 Socket operations: System call failed + errno=131 Socket read failed because the connection was closed by the server No Typically caused by a network timeout on an idle persistent connection. 576 Grammar fetch failed + <URL> An attempt to fetch an external grammar document failed with one of the errors documented above No The specific error condition will be reflected in other error messages. 700 SSL operation failed + SSL_get_error=5 Premature close of an SSL connection No There are two underlying causes of the error: the remote end is not strictly adhering to the SSL protocol, or an idle persistent connection has timed out. In the first case the error can be ignored Other Errors Error # Distinguishing error text Cause Does Holly terminate call Comments 205 Unable to parse contents of URI. The VoiceXML document does not consist of valid VoiceXML. On first document triggers failover; on subsequent document fetches a VoiceXML error is raised and can be handled by the application If the document dump call event is enabled for the application, Holly Management System will show the errors in the document. Correction to the VoiceXML document is required. 212 Licence Manager connection failed The Holly Voice Browser was unable to communicate with any of the configured Holly Licence Managers Yes Check that Holly Licence Managers configured for Holly Voice Browser are correct. Check that Holly Licence Managers are running. 517 Error activating grammar The ASR engine returned an error when the Holly Voice Browser attempted to activate a grammar No There may be a semantic error in the grammar (for example, incorrect tag format), or if the default grammar fetch style is used there may be character encoding problems with XML files. Check the ASR engine logs for details of the grammar error. If the default grammar fetch style is used, set com.holly.grammarfetchstyle to absolute.

12 Error # Distinguishing error text Cause Does Holly terminate call Comments 550 OSBrec: Recognition failed + reason=gramma r error Unknown or illegal grammar not caught as an activation error The Holly Voice Browser throws the event "error.recognition. If the application is unable to handle the event the call terminates. Review the grammar or the ASR engine diagnostic logs for more information. 550 OSBrec: Recognition failed + reason=recogniti on error Unknown or illegal grammar not caught as an activation error. Or, other error raised by the speech recognizer. The Holly Voice Browser throws the event "error.recognition. If the application is unable to handle the event the call terminates. Review the grammar or the ASR engine diagnostic logs for more information. 2.5 Fetching Behaviors Initial Document Failover HTTP The initial URL for an application is configured through the Application page in HMS. Holly allows multiple initial URLs to be specified. The platform starts by attempting to execute from the first URL. Upon failure to execute the first URL the platform will failover to the second defined URL, then to the third and so on. Failover of the initial URL is triggered by any of the following: Failure to fetch an application s initial document or its root document Failure to fetch the application s initial document or root document before a timeout defined on the Application page in HMS Failure to parse either the application s initial document or root document. If failover exhausts all declared initial URIs then the call is rejected. The default behavior is to play the following error message: "We are currently experiencing technical difficulties. Please try again later." The default error message is configurable through the default error handler in the defaults document specified by uriplatformdefaults.browser (URI Platform Defaults). Other rejection behaviors can be configured through HMS (see the Holly Operations Manual). The Holly Voice Platform supports HTTP/1.0 and HTTP/1.1. HVP implements HTTP persistence for both standard HTTP and secure HTTPS. HTTP Persistence

13 2.5.3 HTTPS It is sometimes necessary to align the persistence of HTTP sessions of the VoiceXML browser and application server. The platform may be configured by the platform adminstrator for one of three modes of persistence with the 'httppersistencelevel' configuration property. 10 Request: connection is maintained for a duration of a single HTTP request 20 Session (default): connection is maintained for the duration of a VoiceXML session 30 Indefinite: connection is maintained indefinitely and may be used in subsequent calls The Application Parameter inet.sessionpersistence may be set to overwrite the browser configuration. A value of true is equivalent to Session level. A value of false in equivalent to indefinite. HTTP Retries The browser will always attempt a retry of HTTP or HTTPS GET or POST requests to a server if no data has been sent to the server while attempting the connection. This is a safe retry as the server is unaware of the browser's intention to send a request and thus the server doesn't change state of the call (if any). Application parameters control the retry policy in the situation when the browser was able to send a partial or complete request to the server or received a partial or complete reply from the server but subsequent communication failed on the TCP/IP level or there was a problem parsing the HTTP response from the server. The browser will retry the request if a relevant parameter permits it. Parameter Description Values com.holly.retryget Control HTTP GET request retry policy. true com.holly.retrypost Control HTTP POST request retry policy. true false (default) false (default) In the cases of both safe and unsafe retries the browser will attempt the retry only once. In the case of an unsafe retry the browser won't attempt retrying if it fails when reading the body of a response from the server. The Holly Voice Platform supports the https URI scheme. The HVP fully supports accessing VoiceXML documents over HTTP as well as HTTPS where a secure/encrypted connection is required. The Holly Voice Browser supports certificate-based authentication of a server and certificate-based client authentication (the latter is at the server s request). When configuring an HTTPS-based VoiceXML application server for use with the HVP, please note that SSL certificate validation is dependent on the application parameter ssl.authenticateserver ( false = no certificate validation, true = perform certificate validation) which can be set on the HMS Applications page. The SSL certificate chosen for use can be self-signed, or signed by an authority such as a Certificate Authority. 2.6 HTTP User-Agent Header The Holly Voice Browser sets the User-Agent header in HTTP requests to HVP/5.1. It is configurable via the HTTP User Agent configuration parameter. The User-Agent request-header field contains

14 information about the user agent originating the request. Refer to RFC 2616, Section 14.43, DNS Resolving Behavior Cookies Caching The default behavior is for all fetches to resolve DNS when performing the fetch. Setting the application parameter resolvehostnames=true on the HMS Applications page resolves hostnames on failover and all subsequent fetches will use the IP address(es) obtained from DNS resolution. The Holly Voice Platform supports cookies as described in [RFC 2965]. Multiple cookies are sent as separate Cookie request headers, not as a list in a single Cookie request header. If the application parameter singlecookieheader is set, and there is more than one cookie for an HTTP request, the browser sends the cookies folded into a single HTTP Cookie header, as described in RFC 2965, section Document caching on the Holly Voice Platform is determined by the HTTP cache control headers supplied by the application server. The VoiceXML cache control properties documentmaxage, documentmaxstale, grammarmaxage, grammarmaxstale, datamaxage, objectmaxage, objectmaxstale, scriptmaxage, and scriptmaxstale can be used to control caching from within VoiceXML applications. Refer to [VoiceXML 2.0] section HTTP headers give a lot of control over caching. Voice applications, CGI scripts, or Web server may generate them in response to HVP browser requests (see the diagram above). A typical HTTP response header might look like this: HTTP/ OK Date: Thr, 22 Jun :37:45 GMT Server: Apache/1.3.3 (Unix) Cache-Control: max-age=3600 Expires: Fri, 23 Jun :30:45 GMT Last-Modified: Mon, 19 Jun :07:15 GMT ETag: "3e c6faaf" Content-Length: 2040 Content- Type: audio/x-wav Cache related HTTP headers Header max-age=seconds s-max-age=seconds no-store Semantic Specifies the maximum amount of time in seconds when a cached copy will be considered fresh. This directive is relative to the time of the request. Setting this parameter to zero (max-age = 0) suppresses caching. Example: Cache-Control: max-age=60 Same as max-age. s-max-age takes precedence over max-age if both headers are present. Example: Cache-Control: s-max-age=60 Instructs the cache not to keep a copy of the resource under any conditions Example:

15 Header no-cache Pragma: no-cache Expires: date Last-Modified: date Semantic Cache-Control: no-store The cache doesn t use the response without revalidation with the origin server. This prevents caching or forces revalidation of the resource on every request. Example: Cache-Control: no-cache Same as no-cache. Used in HTTP/1.0 protocol. Example: Pragma: no-cache The field gives the date/time after which the response is considered stale. The cache does not return a stale cache entry without revalidation with the origin server. This header may be useful in some situations, but it has certain limitation. First it is easy to forget to update this header, which will suppress caching after the set date. Second, if the server clock and HVP clock are not synchronized then this header may cause an undesired effect. The max-age directive, if specified, overrides the Expires header. Example: Expires: Fri, 23 Jun :30:45 GMT Indicates the date and time at which the origin server believes the resource was last modified. If none of Expires, max-age, or s-maxage appears in the response, and the response does not include other restrictions on caching, the cache computes a freshness lifetime using a heuristic. The cache copy expires in a period which is 10% of the difference between now time and Last-Modified time. E.g. if Last-Modified is 60 seconds before now, then the entry stales in approximately 6 seconds in a future. Servers should send Last-Modified header whenever feasible to provide means of validating of resources. Example: Last-Modified: Mon, 19 Jun :07:15 GMT private ETag: entity-tag Indicates that the response is intended for a single user and must not be cached by a shared cache. HVP cache doesn t store the response. Example: Cache-Control: private Provides the current value of the entity tag. If a cashed copy of the resource is stale then ETag value may be used for the resource validation. Entity tag must change whenever the associated resource changes in any way. Servers should send an entity tag unless it is not feasible to generate one. Example: ETag: "3e c6faaf" If no cache-related headers (excluding the ETag header) are specified in the response then the cache treats it as not cacheable and does not save a copy of the response Disabling Caching A common requirement during development is to disable caching so that all content is always fetched from the application server. To achieve this set the maxage properties to zero, i.e. audiomaxage, documentmaxage, grammarmaxage, scriptmaxage. These can be set as application parameters via the Holly Management System. Alternatively they can be set in the VoiceXML application using the <property> element (typically in the application root document so it affects overall behavior).

16 2.7 Default Property Values The following are the factory-default settings for VoiceXML properties. The platform defaults may be changed as a browser configuration (via HMS Configuration by the Administrator). The defaults for individual applications may be changed by setting an Application Parameter via HMS Application Configuration). Applications may also change the properties using the VoiceXML <property> element. Key audiofetchhint bargein bargeintype Default Value prefetch true speech confidencelevel 0.5 documentfetchhint fetchaudiodelay fetchaudiominimum fetchtimeout grammarfetchhint inputmodes safe 2s 5s 7s prefetch dtmf voice maxnbest 1 objectfetchhint scriptfetchhint prefetch prefetch sensitivity 0.5 speedvsaccuracy 0.5 termchar # termtimeout universals 0s none 2.8 Access Control on <data> Access control on <data> (see Section 5 of VoiceXML 2.1) allows an application server to indicate that XML content is authorized for use by only selected applications. The Holly Voice Platform implements this behavior to complement its multi-tenancy. Access control element may specify virtual hosts as well as IP addresses and hostnames. Virtual host is specified using Application, Affiliate and Service Provider name separated with dots. The attribute is case insensitive. <?access-control allow="application.affiliate.service_provider.host"?> There are two exceptions to VXML 2.1 specification: * '.com' part of fully qualified name is omitted * if there is no access control instruction then access is allowed by default

17 2.9 Browser Protections The Holly Voice Browser imposes the following constraints on running applications to ensure a rogue application does not reduce the platform s capacity to service other applications. Each constraint is configurable via the Holly Management System (administrators should refer to the Holly Management System User Guide for details on modifying configuration parameters). Configuration Parameter JavaScript Max Branches ECMAScript Max Object Depth Maximum Documents Maximum Event Count Maximum Event Rethrows Maximum Execution Stack Depth Maximum Loop Iterations Maximum Dialogs with no User Input Description A count is kept of each time a script jumps backward or returns from a function; the count is not permitted to exceed this value. When serializing objects -- for example, for logging or transferring between execution contexts on return from a subdialog -- the browser will generate an error if objects are nested to a depth greater than this value. The browser is not permitted to fetch more document instances than this value. This value provides an upper limit to the number of events that can be thrown by a particular condition within a single form; this value is included to assist in the detection of infinite loops or bugs. This value provides an upper limit to the number of times a particular event can be rethrown. This value effectively limits the depth of subdialog calls within an application. This value limits the number of iterations of the form interpretation algorithm on a single form. The number of transitions between forms without entering a wait state is limited to this value. Default Value

18 3. Input: Speech Recognition and DTMF 3.1 Selecting a Speech Recognizer The Holly Voice Platform supports a broad range of speech recognition products. Developers should contact the platform administrator to confirm which ASR products are available. Administrators should refer to the ASR Configuration information in the Holly Voice Platform Operations Guide. A single installation may be configured to support many speech recognizers. Holly allows for each Application to select its preferred speech recognizer or it may use the platform s default. The default speech recognizer for an Application is determined by the value of the asrengine property (a VoiceXML property extension). The Application default may be set as an Application Parameter through HMS or can be set using a VoiceXML <property> element with appropriate scope. For example: <property name="asrengine" value="dtmf"/> The table shows the list of speech recognition products and the corresponding asrengine value. Vendor ASR Engine Value Holly Holly DTMF (Direct API) dtmf IBM IBM Websphere Voice Server (MRCP v1) wvs513-mrcp1 Loquendo Loquendo 7.8 ASR (MRCP v1) loquendo-mrcp1 LumenVox LumenVox lumenvox-mrcp1 Nuance Nuance 8.5 ASR (Direct API) nuance Nuance Nuance 8.5 ASR (MRCP v1) nuance85-mrcp1 Nuance Nuance 9.0 ASR (MRCP v1) nuance90-mrcp1 Nuance OSR - Open Speech Recognizer (Direct API) scansoft Nuance SpeechWorks Media Server 4.0 (MRCP v1) swms40-mrcp1 Siemens Siemens (MRCP v1) siemens Telisma Telisma 1.3 Patch 1 (MRCP v1) telisma-mrcp1 vlingo vlingo Network ASR Service vlingo Note: Note: The Nuance 8.5 ASR (via direct API) recognition interface is not available on Linux HVP deployments. The ASR asrengine values may be customized at a platform installation. The table shows the default values which may not apply if customized ASR Engine Switching The Holly Voice Platform performs all recognitions (voice or dtmf) using the default ASR engine. The Holly Voice Platform permits switching between ASR engines within a call and within a single VoiceXML document. To switch engines set the asrengine in a <property> element with appropriate scope (e.g. field, form or document scope).

19 3.1.2 Allowed ASR Engines The Holly Voice Platform allows an Administrator to restrict an application to the use of specific named speech recognizers. This is achieved by setting gw.asrallowed as Application Parameter. The value is a comma-separated list of allowed engines. For example, setting gw.asrallowed=nuance90-mrcp1,dtmf means the ASR engine can only be switched between Nuance 9.0 ASR (MRCP v1) and the Holly DTMF Recognizer. 3.2 ASR-Specific Behaviors This section documents configuration and behaviors that are specific to the ASR products supported by the Holly Voice Platform Engine-Specific Properties The Holly Voice Platform allows for any Nuance property defined in the respective reference manuals to be set using the VoiceXML <property> element and passed to the engine. Recognizers Property Prefixes Example Nuance Recognizer 9 Nuance OSR 3.0.x Nuance SWMS Nuance 8.5 Nuance 8.5 MRCP swirec_ swiep_ nuance.core.rec nuance.core.ep <property name="swirec_state_beam" value="-20"/> <property name="swiep_audio_environment" value=" channel=cellular "/> A full property list is available in the Reference Guides for these products. <property name="nuance.core.rec.genepfeedback" value=" TRUE "/> <property name="nuance.core.ep.endseconds" value=" 1.50 "/> A full property list is available in Nuance 8.5 Documentation vlingo The developer must ensure the value they set the property to is valid for the underlying speech recognizer. Standard VoiceXML properties are submitted to the speech recognizer before ASR-specific properties, so ASR-specific properties will override any parameter mapping made from a VoiceXML property to an ASR property. vlingo is a network-hosted speech recognition service that facilitates open grammar recognition with very large vocabularies. Unlike the other speech products supported by Holly it does not provide declarative grammar support (using SRGS or any other grammar standard). The platform administrator can contact Holly Connects Support to obtain information on licensing vlingo and documentation on writing VoiceXML applications with vlingo Loquendo To support DTMF-only input with Loquendo ASR (inputmodes=dtmf) the system administrator must set set the parameter enablediscontinuousinboundstream=true in the Loquendo Management Console. To support hash input with termination the system administrator must set the dtmfnomatchifonlytermcharpressed=enable in the Loquendo Management Console. This parameter can be found under Configuration Advanced MRCPv1Server.

20 3.3 ASR Sessions ASR session IDs and the relevant recognizer name are logged as events in the Holly Management System; this ID can be used to correlate ASR logs with HVP logs. The event is logged on the first use of the speech recognizer (or DTMF) and each time the application switches ASR engine. The format of the log event is: asrengine=<name> sessionid=<id> address=<host:port> server=<server> endpoint=<address> 3.4 Timeouts (speech) As required by [VoiceXML 2.0], section 6.3.2, the Holly Voice Platform uses the maximum of the completetimeout and incompletetimeout properties as the actual value of the end of utterance timeout during recognition. The default behavior of the platform is to use the larger of the two properties completetimeout and incompletetimeout as the actual value of the end of utterance timeout during recognition. For recognizers that do enable the platform to distinguish completetimeout and incompletetimeout, the com.holly.distincttimeout property can be set to true to permit the timeouts to be treated differently. 3.5 Confidence Scores The Holly Voice Platform sets name$.confidence to the utterance confidence in a range of 0.0 to 1.0 as required by VoiceXML 2.0 (see Section 2.3.1). Although the Holly Voice Platform normalizes the confidence value received from ASR engines to the VoiceXML 2.0 range, the specific interpretation of values is relative to the ASR engine. The default confidence level is 0.5. This value can be changed using the standard VoiceXML 2.0 <property> tag to set the confidencelevel property (see VoiceXML 2.0, Section 6.3.2). The value can also be changed for each application by setting confidencelevel as an Application Parameter through HMS. 3.6 N-Best Following the VoiceXML 2.0 Specification, the N-best list contains a list of recognition results matching all active grammars ordered by their confidence score (highest confidence to lowest). Active grammars include those explicitly specified by the VoiceXML application plus application requested platform grammars such as links, universals, menus and field options. For application-defined grammars the slot filling follows the explicit specification of the applicationsupplied grammar. For platform-generated grammars there is no standard as to how the slots should be filled for those grammars (if any slots at all) so it is recommended that applications do not rely on slots for those grammars. 3.7 Record Recordings are stored as WAV (RIFF header) 8kHz 8-bit mono mu-law single channel. The maxtime attribute on the <record> element defaults to 300 seconds. The Holly Voice Platform does not currently support speech recognition on <record>.

21 DTMF recognition during record is supported by the behavior is determined by the currently selected speech recognizer as follows: The MRCP recognizers handle arbitrary DTMF grammars The API recognizers handle a single digit DTMF grammar The Holly DTMF Recognizer handles arbitrary DTMF grammars. 3.8 Recording User Utterances during Recognition The Holly Voice Platform permits user utterances to be recorded during recognition as per VoiceXML 2.1 (see section 7). Recordings are stored as WAV (RIFF header) 8kHz 8-bit mono mu-law single channel. Note: Recording of utterances must be enabled by the administrators of the Holly Voice Platform. Administrators of the platform should refer to the Holly Voice Platform Operations Guide for more information. 3.9 Re-Recognition from Recorded Utterances HVP 5.1 introduces the ability for an application to pe-perform re-recognition from a recorded waveform. Audio recorded from caller input using <record> or an utterance recorded during recognition may be stored by the application then declared as input by the application to a subsequent recognition attempt typically using a different set of grammars. The full description of application development using re-recognition is provided in Appendix B Grammars Standard Grammars The Holly Voice Platform supports the standard XML form of SRGS as per the Speech Recognition Grammar Specification Version 1.0, W3C Recommendation 16 March The content type for SRGS grammars should be specified as application/srgs+xml. Recognizers Grammar Format Semantic Format Nuance Recognizer 9 SRGS 1.0 XML SISR 1.0 Others look up doc Nuance OSR 3.0.x Nuance SWMS XX Nuance 8.5 IBM WVS LumenVox 8 SRGS 1.0 XML SRGS 1.0 XML Draft GSL SRGS 1.0 XML SRGS 1.0 ABNF SRGS 1.0 XML SRGS 1.0 ABNF SISR 1.0 and SWI extensions. GSL SISR 1.0 SISR 1.0 Loquendo SRGS 1.0 XML SISR 1.0

22 Recognizers Grammar Format Semantic Format vlingo Custom Custom Proprietary Grammars Holly supports the use of proprietary grammar formats. Other supported formats are ASR enginespecific and developers should refer to the relevant production documentation. Proprietary grammar types, such as Nuance 8.5 GSL grammars, must be put inside CDATA sections when used as inline VoiceXML grammars External Grammars Note that external grammars declared as ISO do not support non-ascii (i.e. Latin-1) characters in default mode. In order to use Latin-1 characters in external grammars the property com.holly.grammarfetchstyle should be set to absolute Pre-built and Binary Grammars Holly supports pre-compiled and binary grammar formats for most recognizers. For example, Holly supports pre-compiled grammars for OSR and Nuance 9 (these are.gram files created with the sgc Grammar Compiler tool). Contact Holly for information on using Nuance 8.5 static grammar packages, note that this is not recommended in Virtual IVR systems Universal Command Grammars The Holly Voice Platform supports the optional default grammars for help, cancel, and exit. These are controlled by the VoiceXML 2.0 universals property; see [VoiceXML 2.0], section These are available in English only. The platform administrator may define new universal command grammars for an MRCP recognizer by setting the following platform configurations: uriuniversalcancel, uriuniversalexit, and uriuniversalhelp Builtin Support The Holly Voice Platform supports the builtin grammar types as summarized in the following table. Recognizer Language Status Nuance 8.5 en-au All builtin grammar types supported as listed in Appendix P of [VoiceXML 2.0]. Other languages Contact Holly Customer Support. Nuance 9 en-au All builtin grammar types supported as listed in Appendix P of [VoiceXML 2.0]. Nuance OSR (Scansoft) Other languages en-au Other languages Implemented as Nuance 9 builtin grammars. See the relevant Nuance 9 Language Supplement. All builtin grammar types supported as listed in Appendix P of [VoiceXML 2.0]. Additional non-standard types supported as per the ScanSoft OSR documentation. Implemented as OSR builtin grammars. See the relevant OSR Language Supplement.

23 Recognizer Language Status Holly DTMF Recognizer Any language All builtin grammar types as listed in Appendix P of [VoiceXML 2.0]. DTMF only. Holly supports the <type> attribute on a field tag with the builtin grammar types defined in the table above. Developers may also reference a builtin grammar by specifying a grammar src attribute of builtin:<name>. The syntax builtin:grammar/<type> and builtin:dtmf/<type> can be used to specify the input mode for a particular builtin grammar type; see [VoiceXML 2.0], section Note: This method can also be used for non-standard builtin grammars provided by a particular ASR engine Grammar Fetch Behavior By default the Holly Voice Platform fetches external grammars and passes them to ASR engines. This behavior can be changed by means of the com.holly.grammarfetchstyle property. The possible values of the property are default, absolute, and relative. There is no one method of handling grammars that will work for all cases, for instance absolute or relative may be more efficient if big grammars are frequently passed to ASR. Note: Caching may not work with absolute or relative as VXML side cache control information is not passed to the ASR engine. Also, ASR may not have its own caching facility, and even if ASR is able to use HTTP cache control mechanism to store grammars in its own cache this may cause problems in a virtual environment (multi-tenancy). Value Description Comments default absolute Holly Voice Platform fetches grammars Holly Voice Platform resolves relative URI references and passes the absolute URI to the ASR default requires that the browser fetch and manipulate the grammar. The browser converts these to multi-byte strings. Proper cookies (if any) are passed to an application server and cache control directives specified in VXML document are honoured. default reverts to absolute if the grammar URI uses anything other than the root rule (i.e. the grammar URI contains a fragment) or if the grammar is a binary grammar (determined by the file name extension, either.gram or.ngo). default does not work if there are additional URIs specified in the grammar passed to ASR. Note: The HVP sends the contents of the grammar in a buffer to the ASR engine, this may affect performance. absolute requires both platform and ASR engine to have access to the application server. External grammars in proprietary formats (such as Nuance binary grammars) are always processed as though the com.holly.grammarfetchstyle property as absolute. The absolute URI is passed to the ASR engine to fetch. Support for HTTPS is vendor specific. Grammar URIs with query parameters of fragment identifiers are also passed to the recognizer as absolute URIs regardless of the property setting. If cookies or session identifiers are required the ASR may not be able to fetch the grammars. Check with your network owner if the platform s load balancing configuration is able to pass cookies. relative Holly Voice Platform passes the value of relative is typically used with OSR where large grammar files are stored in the OSR grammar root directory which is controlled by the property

24 Value Description Comments the src attribute to the ASR (it does not resolve relative URI references) SWIsvcRootGrammarDirectory. For example, the file street-names.gram can be copied to $SWISRSDK/config (the default value of the grammar root) and referenced in VoiceXML as street-names.gram. OSR fetches the file from disk rather than HTTP. If cookies or session identifiers are required the ASR may not be able to fetch the grammars. Check with your network owner if the platform s load balancing configuration is able to pass cookies DTMF interdigittimeout and termtimeout The Holly Voice Platform supports the properties interdigittimeout and termtimeout. The HVP uses the maximum of these parameters combined as the actual value of the end of DTMF timeout, the default value of which is 2 seconds. For the Nuance 8.5 ASR engine termtimeout should be disabled (i.e. termtimeout=0 ) as Nuance does not provide sufficient information in its DTMF parse results to determine whether a parse is complete, incomplete, invalid or a valid prefix. Use interdigittimeout to control DTMF recognition timing. This should generally be set per recognition state (usually a field) to an appropriate value for the input required. The interdigittimeout property can also be set globally for the application by setting an application parameter. Use 0s for a menu application that accepts a single digit (e.g. interdigittimeout=0 ); use something larger, e.g. 2s, when collecting information that callers will have to check such as a credit card number. Note: Note: The default value of termtimeout is 0s in HVP 5.0 to comply with the VoiceXML standard. The Holly DTMF recognizer and ScanSoft OSR support both interdigittimeout and termtimeout termchar The VoiceXML property termchar is set to # by default and can be changed by setting the <property> element in the VoiceXML application. For example to set termchar to empty: Note: <property name="termchar" value=" "/> VoiceXML <property> scoping rules apply. The allowable scopes are application, document, form, menu, form item see VoiceXML 2.0 S6.3. The default termchar property can be modified by creating an Application Parameter through HMS DTMF Buffering Interactive DTMF parsing is a different mode of DTMF treatment available for HVP 5.0 and later with the ability to be disabled for compatibility with HVP 4.1 and earlier. At a global level Interactive DTMF parsing can be enabled or disabled for an ASR engine by setting the parameter dtmfinteractive to true or false under the appropriate ASR Plug-in component on the Holly Configuration page via the Holly Management System. Interactive DTMF parsing can be enabled or disabled at the application level via the sr.dtmfinteractive application parameter on the Applications page in the Holly Management System (administrators should refer to the Holly Management System User Guide for details on modifying application parameters).

25 The DTMF buffer is cleared whenever prompts that have been queued are played to completion before continuing processing. One such scenario is when prompts are queued with bargein disabled; another is when prompts are queued before a fetch that specifies fetchaudio. In the latter case there is an ambiguity in the VoiceXML 2.0 specification about the handling of DTMF input during the playing of the prompts and the fetch. By default, the Holly Voice Browser clears the DTMF buffer after playing the fetchaudio, so any DTMF collected during the prompt playback or during the fetch will be lost. If the proprietary VoiceXML property com.holly.fetchaudiodtmf is set, the Holly Voice Browser will not clear the buffer after playing the fetchaudio, and any DTMF collected during the prompt playback or during the fetch is fed to the next recognition (unless some other action such as a non-bargeinable prompt clears the buffer first). The DTMF buffer is also cleared when the ASR engine switches. If the Holly Voice Browser parameter asrengine is used to make the switch this will occur immediately before the first recognition in the scope of the property. If this switch is performed using the VoiceXML asrengine property, it won t take effect until the first recognition in the application and any DTMF digits collected to that point are lost. This can be prevented by setting the VoiceXML application parameter asrengine to the same value as the Holly Voice Gateway component configuration parameter srdefault so that the ASR engine switch takes place at the very beginning of the call (administrators should refer to the Holly Management System User Guide for details on modifying application and configuration parameters) Holly DTMF Recognizer v2 The Holly DTMF Recognizer v2 is a conforming XML form grammar processor, as specified in SRGS section 5.4, except that it does not support references to rules defined in external grammars. Other notes on its implementation: Full schema validation of SRGS+XML documents is not performed Recursive grammars are not supported xml:lang attributes are ignored (following the SRGS specification) Grammars with mode attribute of voice are ignored. Only grammar documents that explicitly set the mode to dtmf are processed The <record> element is supported. Tokens The tokens (terminal symbols) supported by the Holly DTMF Recognizer v2 are shown in the following table; entries in the same row are synonymous. Uppercase or lowercase alphabetic characters may be used. 1, one, dtmf-1 2, two, dtmf-2 3, three, dtmf-3 4, four, dtmf-4 5, five, dtmf-5 6, six, dtmf-6

26 7, seven, dtmf-7 8, eight, dtmf-8 9, nine, dtmf-9 *, dtmf-*, star, dtmf-star #, dtmf-#, hash, pound, dtmf-hash, dtmf-pound Further information on the Holly DTMF Recognizer v2 is available in Appendix B.

27 4. Output: Prompting and TTS 4.1 Selecting a TTS Engine The Holly Voice Platform supports a broad range of text-to-speech products. Developers should contact the platform administrator to confirm which TTS products are available. Administrators should refer to the TTS Configuration information in the Holly Voice Platform Operations Guide. A single installation may be configured to support many text-to-speech engines. Holly allows for each Application to select its preferred text-to-speech engine or it may use the platform s default. The default text-to-speech engine for an Application is determined by the value of the ttsengine property (a VoiceXML property extension). The Application default may be set as an Application Parameter through HMS or can be set using a VoiceXML <property> element with appropriate scope. For example: <property name="ttsengine" name="realspeak45-mrcp1"/> The table shows the list of text-to-speech products and the corresponding ttsengine value. Vendor TTS Engine Value Acapela Acapela (MRCP v1) acapela-mrcp1 IBM IBM Websphere Voice Server (MRCP v1) wvs513-mrcp1 Nuance Speechify 3.0 (Direct API) scansoft Nuance SpeechWorks Media Server 4.0 (RealSpeak TTS engine) (MRCP v1) swms40-mrcp1 Nuance RealSpeak 4.5 (MRCP v1) realspeak45-mrcp1 Nuance Recognizer to RealSpeak 4.0 (Direct API) realspeak Loquendo Loquendo (MRCP v1) loquendo-mrcp1 Note: The ttsengine values may be customized at a platform installation. The platform administrator can advise if any values are different from those shown in the table TTS Switching The Holly Voice Platform performs all text-to-speech using the default TTS engine. The Holly Voice Platform permits switching between TTS engines within a call and within a single VoiceXML document. To switch engines set the ttsengine in a <property> element with appropriate scope (e.g. field, form or document scope). It is, however, not possible to have prompts in the same queue using a different TTS setting. A switch will only take place when the queue is flushed (usually by performing a recognition). Note: The ttsengine property is a proprietary extension to VoiceXML Using a Non-default TTS Voice The ttsvoice property is used to set a specific TTS voice for a VoiceXML document. The available values for this parameter are dependent on the TTS voices installed on the platform. Note: The ttsvoice property is a proprietary extension to VoiceXML.

28 4.1.3 SSML The Holly Voice Platform supports SSML for TTS and audio output. Prompts consisting of unmarked-up text are wrapped in SSML tags before being sent to the TTS engine. SSML tag support depends on the capabilities of the TTS engine. The IBM WVS proprietary alphabet and other proprietary alphabets not starting with the x- prefix are supported. The Holly Voice Platform does not support the VoiceXML 2.0 extension of the <say-as> SSML element described in Appendix P of [VoiceXML 2.0]. That is, the results from a recognition using one of the builtin grammar types cannot be passed directly to a <say-as> element to be read as a valid value of that type for the current language. 4.2 Audio Files The Holly Voice Platform supports the required audio formats specified in VoiceXML (see VoiceXML 2.0, Appendix E). All audio files must have an 8KHz sample rate. All audio files must contain single channel mono recordings. The audio file must have a file extension matching the file format as shown in the table. Audio is fetched by the Holly Voice Platform and played by the Holly Voice Gateway. The TTS server is not used to fetch audio data or generate an audio stream. Audio Format and Supported Content Media Type File Extension.WAV (RIFF header) 8kHz 8-bit mono mu-law single channel 8kHz 8-bit mono A-law single channel 8KHz 16-bit mono linear [PCM] single channel Raw (headerless) mu-law 8kHz 8-bit mono mu-law single channel (G.711) Raw (headerless) A-law 8kHz 8 bit mono A-law single channel. (G.711) Raw (headerless) mu-law 8kHz 8-bit mono mu-law single channel (G.711) audio/x-wav audio/basic [RFC1521] audio/x-alaw-basic audio/basic [RFC1521].wav.ulaw.alaw.au Note: There is no support for audio/basic.au with au header format Throwing Errors on Audio Fetch Failures VoiceXML 2.0 specifies that failure to fetch an audio file does not result in an error.badfetch event being thrown, even when there is no alternative content. The Holly Voice Platform recognizes a property com.holly.audiobadfetch which, when set to true, results in an error.badfetch event being thrown if an audio file cannot be fetched. Note: Setting this property to true results in behavior that does not conform to VoiceXML 2.0, but can be very useful for development. Holly also recognizes the VoiceXML property com.holly.audiofetchalarm to enable SNMP and alarming for missing prompts, this can be turned on or off as required.

29 The VoiceXML property can be set either at the application level (in the Holly Management System) or for individual dialogs within an application. Setting the property off suppresses the alarm (SNMP, etc) and also suppresses the error events in the Holly Management System Call_Events for audio files fetch errors. The fetch failure would still be logged as "outcome=error" within the fetch parameter details. Note: Some lower level socket fetch errors may still be written to the Holly Management System log. These are outside of the browser control, but have no effect on processing and do not raise alarms. Setting the property to on returns behavior to normal, raising both an alarm and writing the severe errors to the Holly Management System log. By default the property is off. 4.3 <mark> Element The standard <mark> tag is supported as in the VoiceXML 2.0 standard. From HVP 5.1, <mark> may be used without a TTS engine being invoked so long as the prompt content comprises only <audio> and <mark> elements.

30 5. Telephony: Session & Transfers 5.1 Session Variables The following are the VoiceXML variables set by the Holly Voice Browser. Note that for outbound calls there are some differences as documented in the following section. Variable session.connection.local.uri session.connection.remote.uri session.connection.aai Description Set to the URI in the SIP To header. Set to the URI in the SIP From header (prior to any CTI Manager lookup), this will be "anonymous" if CLI is restricted. Variables received from CTI. In AIN calls, this is an object whose property/value pairs are the key/value pairs returned as call data by the CTI Manager. The CTI keys become the property values, and they resolve to the corresponding CTI values (interpreted as strings). In other calls it is defined, but has no properties. session.connection.originator session.connection.protocol.name session.connection.protocol.sip.call id session.connection.protocol.version session.connection.redirect session.telephone.ani session.telephone.clearani session.telephone.moli session.telephone.dnis session.telephone.iidigits session.telephone.uui session.telephone.rdnis session.telephone.redirect_reason session.telephone.follow_on session.com.holly.callid session.com.holly.switchmessageid session.com.holly.trunkgroupid session.com.holly.trunkid Always points to the same object as session.connection.remote. sip for SIP calls; an empty string for any other signaling type. Set to the value of the Call-ID header field from the SIP INVITE that initiated the call (inbound calls only). 2.0 for SIP calls; an empty string for any other signaling type. Always an empty string. ANI if CLIR is not set or the passcli application parameter is set; a masked ANI otherwise. Only defined (to be ANI) if the passcli application parameter is set. MOLI; only defined if the passmoli application parameter is set. DNIS after any CTI Manager lookup. Always an empty string. Always an empty string. Always an empty string. Always an empty string. Only defined if this is a AIN follow-on call; set to one of busy, noanswer, invalid, congestion, hangup. The call ID assigned to this call. These three variables come from the CTI Manager. The message ID is used to determine the follow-on status.

31 Variable session.com.holly.applicationid session.com.holly.affiliateid session.com.holly.servprovid session.com.holly.initialuri session.com.holly.channelid session.com.holly.browserid session.com.holly.correlationid session.com.holly.scfid session.com.holly.callerlocation Description These four variables come from the Licence Manager. This variable comes from the HVG. The IP address of the host this browser is running on. These variables are only set if the CTI Manager returns them to the browser in the call data Session Variables for Outbound After a call is answered by a remote party the Holly Voice Browser commences execution of the VoiceXML session. The session is started with the outbound parameters of the original call request placed into ECMAScript variables in the session scope of the VoiceXML context. The mapping of parameters is shown in the table below. For outbound calls the CLID/ANI corresponds to the Remote party and the DNIS to the platform service calling the Remote party. The Holly License Manager uses the DNIS to retrieve the virtual IVR data for the call handling. VoiceXML Variable session.connection.local.uri session.connection.remote.uri session.connection.originator session.telephone.ani session.telephone.dnis session.com.holly.callid session.com.holly.userdata PLACECALL/PLACECALLRESULT Field Local (number of the calling application) Remote (number of the called party). Local (the party that initiated the call, this is a reference to either session.connection.local or session.connection.remote) Remote Local Holly Call ID (returned in PLACECALLRESULT) User Data 5.2 Session.connection.aai Example In certain telephony configurations the Holly Voice Platform populates the VoiceXML session with CTI or other connection-related data. This section documents how VoiceXML applications can access this call data. For the following examples, suppose the call data returned by the CTI Manager for a call is fruit = apple beer = lager If the name of a property is known in advance, it can be accessed directly: <var name="fruit" expr="session.connection.aai.fruit"/> With error-checking:

32 <var name="fruit"/> <script> <![CDATA[ if (typeof(session.connection.aai.fruit)!= "undefined") fruit = session.connection.aai.fruit; else fruit = unknown ; ]]> </script> If the property names are not known in advance, the ECMAScript for/in operator can be used to iterate through the properties defined on the session.connection.aai object. Here is an example of iterating through the session.connection.aai object and reading out the name/value pairs: <?xml version="1.0" encoding="utf-8"?> <vxml version="2.0" xmlns=" <form id="example"> <var name="text" expr=" "/> <script> <![CDATA[ for (var prop in session.connection.aai) text += prop + " is " + session.connection.aai[prop] + ", "; ]]> </script> <block> <value expr="text"/> <disconnect/> <exit/> </block> </form> </vxml> With the call data above this would result in the prompt fruit is apple, beer is lager. 5.3 Passing Data Between Sessions HVP 5.1 introduces a mechanism for an application to store data to the Holly CTI Manager so that it is available for a subsequent VoiceXML session in a follow-on call (where the same call results in more than one VoiceXML session). Contact Holly Support for details. 5.4 Transfers Transfer Types Support for transfers varies for each installation, depending upon the telephony environment within which the Holly Voice Platform is deployed. The VoiceXML interpreter will attempt both blind and bridge transfer types, according to the rules in VoiceXML 2.0; however, if a particular type is not supported in a given environment, an error.unsupported.transfer.<type> event is thrown. Note that <transfer> does not set extra shadow variables as described in VoiceXML 2.1, section 7.

33 5.4.2 Destination URIs The allowed transfer destination URIs in VoiceXML applications depends on the deployment environment. The VoiceXML interpreter recognizes tel URIs, but the actual digits needed to establish a transfer depend on carrier business rules. Therefore the processing of tel URIs is installationdependent. The VoiceXML interpreter recognizes sip URIs. Contact the system administrator to determine whether they are supported in the deployment environment and for content information. As a special case the Holly Voice Platform treats relative URIs, understood here as those with no scheme component, as belonging to an unnamed proprietary scheme in which the string is passed without modification to the telephony integration. For example, <transfer dest="code1">... results in the string CODE1 being passed to the telephony interface as the destination for the transfer. Contact the system administrator to determine whether they are supported in the deployment environment and for content information Transfer CLID If the VoiceXML property com.holly.transferclid is set in the scope of the transfer element (typically within the element), its value is supplied as the CLID in the transfer-initiating SIP message Recognition During Transfer The Holly Voice Platform does not support speech or DTMF recognition during transfer Whisper Transfer Holly supports whisper transfer as an extension to the set of standard VoiceXML transfer types. In a whisper transfer the VoiceXML application is able to interact fully with the C-party (recipient of the transfer) prior to either completing or rejecting the transfer. Examples of its use: Perform a transfer with the application passing information about the call to the C-party (transfer recipient) so that they can continue the call smoothly; Provide the C-party with the option to accept or reject the transfer request (e.g. I have Joe Smith on the line. Would you like to take the call? ). To achieve both a transfer and a separate dialog with the C-party the VoiceXML code for whisper transfer combines the standard <transfer> elements (used like a bridge transfer) and <subdialog> element. For reference, <subdialog> element is described in Section of VoiceXML 2.0 and bridge transfer is described in Section of VoiceXML 2.0. Executing whisper transfer causes the following sequence of events: Any queued prompts are played to completion to the A-party (caller) before they are put on hold. A-party is put on hold and may be played transferaudio (as for standard bridge transfer). Platform initiates a new call to the C-party indicated by the dest or destexpr attribute of the <transfer> element (as for any transfer).

34 Once a connection to the C-party is established a subdialog is invoked to interact with the answerer. As with standard subdialogs this is executed in its own execution context. As with <subdialog> variables may be passed and returned through the <subdialog> mechanism only. Note: recognition on transfer (or transfer barge-in) is not supported. To combine <transfer> and <subdialog> capabilities the <transfer> element is extended to allow the <param> element (which is standard for the <subdialog> element). There are four specific values of the <param> element within a <transfer> element that have special interpretations. The values may be provided by either the value or expr attributes. Parameter Name Description Example com_holly_uri com_holly_namelist URI reference to the subdialog to execute with the C-party. The URI may be a fragment referencing the current document. The list of ECMAScript variables to submit as URI query parameters. Equivalent of namelist attribute on <subdialog>../whisper_dialog.vxml#form #whisper_dialog var1 var2 status com_holly_method Method of fetch. get (default) com_holly_enctype Encoding type of the fetch. application/x-www-formurlencoded (default) post multi-part/form-data <any other name> Parameter is passed as a <param> to the subdialog. There must be a corresponding <var> element in the subdialog. Attributes The <transfer> maxtime attribute can be used to limit the duration of the transfer. This limits the combined duration of both the interaction within the subdialog and the subsequent bridge connection. During the transfer operation and while the subdialog executes the current interpreter session is suspended. If a transferaudio attribute is provided the audio resource will be played to the caller until the connections are bridged or the subdialog ends. Properties Four standard VoiceXML properties apply to the fetch behavior: fetchtimeout fetchhint maxage maxstale The fetchaudio property does not apply to the fetch since the transferaudio attribute of the <transfer> extension applies. Error Handling

35 The following events might be thrown during the attempt to establish the new connection. They will all be thrown in the context of the calling dialog. error.semantic: The com_holly_uri parameter is not supplied. error.badfetch: The URI referenced by the com_holly_uri parameter is invalid. error.connection.baddestination: The URI reference com_holly_uri is malformed. error.unsupported.uri: The platform does not support the URI scheme in the URI reference. error.connection.noroute: The platform is not able to make the connection. error.connection.noresource: The platform cannot allocate resources to create the new connection. Connecting A-Party to C-Party A <transfer> element with the type of com.holly.join must be executed in the subdialog to connect the A-party to the C-party (i.e. to join the whisper transfer). (Alternatively the subdialog can <return> or <exit> as described in the following section.) The dest, destexpr, connecttimeout, maxtime and transferaudio attributes of the <transfer> element are ignored for this type of transfer. If the application executes a <transfer> of type com.holly.join then the platform will join the A-party and C-party legs as a bridge transfer which completes the whisper transfer. The A-party and C-party remain connected until one of the following: A-party hangs up C-party hangs up maxtime property is reached There can be no failures before the bridge is established with this type of transfer (because connection to C-party has already been established). The only conditions are thus post-connection conditions, as listed in Table 2 (but excluding the subdialog disconnect condition). The results of a join transfer are automatically copied to the corresponding whisper transfer element variable, and once the bridge is complete control continues with any <filled> element in the whisper <transfer> element in the calling dialog. If the A-party hangs up, a connection.disconnect.hangup is thrown in the calling dialog. If the C-party hangs up, the calling dialog <transfer> item variable is populated accordingly. Once the connections are bridged, no further interaction in the subdialog will take place. The VoiceXML execution next returns to the VoiceXML context in which the whisper transfer was initiated and the behavior follows the specification for returning from a bridge transfer. If the join <transfer> element specifies a com.holly.join.namelist <param> element, the whisper <transfer> element result shadow variable will be populated with the variable values returned, as if the subdialog had terminated with a <return> with a namelist attribute. Whisper Subdialog <return> or <exit> If the application does not complete the transfer with a join then the subdialog execution will complete either when the application executes a <return> element or when there is an explicit or implicit <exit>. With a <return> the control and data are returned to the calling whisper transfer with behavior following the specification for returning from a sub-dialog. This also results in the connection to the C-party being closed and the subdialog execution context being deleted. (Note that because the application has not executed a <transfer> with holly.com.join there will be no connection between the A-party and C-party.)

36 The <return> element may specify a list of variable values to return (namelist attribute) and these populate the shadow variable of the calling <transfer> element. Alternatively the <return> element may specify an event to throw in the calling dialog (event or eventexpr attribute) with an associate message (message or messageexpr attribute). The standard <transfer> shadow variables are set as in VoiceXML 2.0. For subdialogs that end with either a join or a <return> the duration shadow variable is set to the duration of the whisper transfer which is the sum of the time the caller is on hold and the time the two connections are bridged. Also, an extension shadow variable, holdduration, is set to the time the caller spent on hold. If the subdialog ends, explicitly or implicitly, with an <exit> interpretation terminates and any remaining connections are released following the VoiceXML <subdialog> behavior. After Completion of Whisper Transfer When execution returns to the initiating <transfer> element (of type whisper) the item variable contains an indication of the final condition of the transfer. Following the specification for bridge transfers in VoiceXML 2.0 the return behavior is different according to whether connection is established to the C-party. For whisper transfer there is the additional distinction that the platform can connect successfully to the C-party but the application does not join the A- and C-parties. The possible values of the transfer item variable depend on the stage reached. Table 1 shows the possible values assigned to the item variable before the connection to C-party is established. Condition target busy no answer before connect timeout other Value busy `noanswer' unknown Table 1: Values of the transfer item variable before the new connection is established (prior to execution of subdialog) Table 2 shows the possible values after the connection is established. The possible values after the connections are joined are a subset of these, and are distinguished using a non-standard boolean shadow variable name.joined that indicates whether the connections were joined or not. This shadow variable is not defined if the new connection fails to be established. Condition C-party disconnects maxtime reached Subdialog disconnects other Value far end disconnect maxtime disconnect application disconnect unknown Table 2: Values of the transfer item variable after the new connection is established but before joining (i.e. during execution of subdialog) At any stage, if the A-party disconnects a connection.disconnect.hangup is thrown. If this occurs during the establishing of the new connection or after the connections are joined, it will be thrown in

37 the context of the calling dialog. If it occurs while the caller is on hold, it will be thrown in the context of the subdialog as a connection.disconnect.hangup.a. Example: Initiating Whisper Transfer <?xml version="1.0"?> <vxml xmlns=" version="2.1"> <catch event="connection.disconnect.hangup.c"> <log>the C party hung up: caught in whisper-call</log> <script>result.condition = "disconnect"</script> <return namelist="result"/> </catch> <catch event="connection.disconnect.hangup"> <log>the A party hung up: caught in whisper-call</log> <exit/> </catch> <form> <!-- At this point we have a connection. --> <var name="com_holly_uri"/> <var name="com_holly_namelist"/> <var name="karma"/> <var name="result" expr="{}"/> <field name="proceed" type="boolean"> <prompt>are you willing to help improve a karma of <value expr="karma"/>?</prompt> <filled> <if cond="proceed"> <script>result.condition = "accepted"</script> <goto nextitem="join"/> <else/> <script>result.condition = "rejected"</script> <return namelist="result"/> </if> </filled> </field> <transfer name="join" cond="false" dest="ignored" type="com.holly.join"> <param name="com_holly_namelist" value="result"/> </transfer> </form> </vxml> Example: Whisper Subdialog <?xml version="1.0"?> <vxml xmlns=" version="2.1"> <catch event="connection.disconnect.hangup"> <log>the A party hung up: caught in whisper-main</log> <exit/> </catch> <catch event="error"> <exit/> </catch> <form> <field name="karma" type="digits?minlength=3;maxlength=10"> <prompt>what's your karma?</prompt>

38 </field> <transfer name="guru" destexpr="karma" type="com.holly.whisper" connecttimeout="15s" maxtime="60s" transferaudio="chicken.wav"> <param name="com_holly_uri" value="whisper-call.vxml"/> <param name="com_holly_namelist" value="karma"/> <param name="karma" expr="karma"/> <prompt> Please wait while your karma works for you or against you. </prompt> <filled> <log>whisper transfer returned: guru$=<value expr="guru$"/>, duration=<value expr="guru$.duration"/>, holdduration=<value expr="guru$.holdduration"/>, result=<value expr="guru$.result"/></log> <if cond="guru$.result"> <goto nextitem="subdialogresult"/> <else/> <goto nextitem="transferresult"/> </if> </filled> </transfer> <block name="subdialogresult" cond="false"> <!-- Post-connection conditions --> <if cond="guru == 'application_disconnect'"> <prompt>application disconnect</prompt> <elseif cond="guru == 'unknown'"/> <prompt>outcome is unknown</prompt> <elseif cond="guru == 'far_end_disconnect'"/> <prompt>we hope your conversation with the guru improved your already excellent karma.</prompt> <elseif cond="guru == 'maxtime_disconnect'"/> <prompt>sorry, the guru is a busy, important person, and he has other karmae to attend to. We hope the abrupt termination has not karmed your harma too much.</prompt> <elseif cond="guru$.result.condition == 'rejected'"/> <prompt>sorry, the guru does not wish to address your karma. Try again in your next life.</prompt> <else/> <prompt>well, look at that. A guru meditation error. We hope your karma hasn't been bruised.</prompt> </if> </block> <block name="transferresult" cond="false"> <!-- Pre-connection conditions --> <if cond="guru == 'busy'"> <prompt>sorry, with your karma you're condemned to be a silent follower, never even observed. Try again in your next life.</prompt> <elseif cond="guru == 'noanswer'"/> <prompt>sorry, with your karma you are not important enough to talk to the guru. Try again in your next life.</prompt> <elseif cond="guru == 'unknown'"/> <prompt>sorry, it seems the guru's karma is worse than yours, so you probably don't wan't to talk to him anyway.</prompt> </if>

39 </block> <block> all over, disconnect call <log>all over.</log> <exit/> </block> </form> </vxml>

40 6. Logging The Holly Voice Platform provides in-depth logging, reporting and analytics to facilitate development, debugging and support for production applications. This section documents the logging as used by application developers. The Holly Management System Guide provides information on using HMS for reporting and analytics. The Holly Reference Manual and Holly Operations Guide provide platform administrators with information on configuration of a platform to enable logging and reporting. The Holly Voice Platform has two key forms of logging: Call Detail Record: stored as LOG_CALLS in Holly, this is a summary table containing around 90 properties. Core information in the CDR includes call start/end times, call duration, ANI, DNIS, use of ASR and TTS, use of logging and much more. Call Event Record: stored as LOG_EVENTS in Holly, this is a event-by-event record that documents the progress of a call from initiation to completion. 6.1 Events The Holly Voice Platform can be configured to record over 30 different types of event during execution of each call. These events are recorded in real-time during the call by the Holly Voice Browser. The events are submitted to the platform database via the Holly Log Manager. The events can be viewed and analyzed through the Holly Management System. The <log> element of VoiceXML is used by application developers to insert a Log type event. All the other event types are generated by the Holly Voice Platform. (The set of events configured for recording can be configured at the platform and application levels as described in the following section.) For optimal platform and database efficiency it is recommended to remove any logging options that are not required. EVENTID PARAM Description Answer result=%s Indicates the call has been answered or not. The parameter result may be success or failure. ASR Session Call end Call start Disconnect Document dump asrengine=%s sessionid=%s address=<host:port> server=<server> endpoint=<address> cpu=%.3f normalcpu=%.3f callduration=%.3f reccount=%d ttscount=%d ttsduration=%.3f logcount=%d logbytes=%d ANI=%s DNIS=%s VURL=%s follow on,reason=%s List of variables and corresponding values specified with VXML attribute namelist. <a reference to the VoiceXML document> Logs the ASR session event. The endpoint address of the recognizer is also included. Summary call statistics recorded irrespective of the level of logging. At the start of a call logs the Caller Line Identifier, DNIS, and the initial applications document identifier. Records a hang-up event. Logs the whole VoiceXML document as it is fetched.

41 EVENTID PARAM Description Document transition uri=%s cpu=%.3f normalcpu=%.3f Written when document scope changes. Error Critical error=%d msg=%s Logged when a critical error occurs. Error Severe error=%d msg=%s Logged when a severe error occurs. Error Warning error=%d msg=%s Logged when a warning error occurs. Exit result=%s Logs exit event Fetch Grammar activation Grammar deactivation License uri=%s fetchtype=(vxml audio grammar other) incache=(true false) latency=%.3f documentsize=%d outcome=(success no response error timeout) failover=(true false) localport=%s hostname=%s URI=%s URI=%s mode=(acquire resolve) key=nnn outcome=(success maximum licence number reached or exceeded license key not found socket error message encode error message decode error application not found affiliate not found service provider not found licences do not reconcile licence manager not seeded connect failure) service=<service provider ID>:<affiliate ID>:<application ID> Logged for each document fetch. When external scripts are fetched they are logged with a fetch type of 'vxml'. Fetch and/or activation of a new grammar. Logged when a grammar is deactivated. The first event for a session, preceding the call start event representing the license lookup. Values are: mode=acquire or resolve. The value 'acquire' means that this license is being requested for the duration of the call; this is the license that authorizes all sessions within the call. The value 'resolve' means that this license is being requested solely to obtain application data for a new session -- the Holly License Manager will not increase the license allocation for the application. key=the key for the license lookup. outcome= outcome of the request If the key lookup is successful, a fourth field will be present: service=<service provider ID>:<affiliate ID>:<application ID> Note: by default this event is not included in the Holly Voice Browser callevents parameter which determines which events are logged.

42 EVENTID PARAM Description Log Event Placecall start Placecall end EVNT=<event id> Label=<label in log tab> expr=<expression in log tag> content=<user defined parameter remote=<sip URI> local=<app number> result=(no reason supplied user disconnect silent maximum duration special information tones fax busy cti no answer error bad destination bad format answering machine) Logged as a result of a <LOG> tag included in the VoiceXML document.. The VoiceXML log tag format includes the attributes label and expr in addition to the log tag content. The format and contents of the PARAM field are under the control of the application builder. The VoiceXML log tag format includes the attributes label and expr. Note: The browser treats <log> content differently if it is of the form 'EVNT=<txt>...'. This content will be logged to the ASR engine with the event name <txt> and content all the text after the ' '. If <txt> begins with 'SWI' or 'calllog:?' the event will NOT be logged to HMS; otherwise the event will also be logged to HMS with the event name <txt>. This format is supported by the SpeechWorks/ScanSoft/Nuance OSDM (OpenSpeech DialogModule) products which log a lot of useful dialog state information with events that start with EVNT=SWI. This information can then by used by the OpenSpeech Insight reporting tool to do some powerful ASR analysis. Logs the SIP URI and application number. Logs the result of the outbound call. Prompt (external) type=external URI=%s Logged when an external prompt is played. URI is the uri of the audio file Prompt (SSML) type=ssml content=%s Logged when a TTS prompt is played. Content is the TTS string. Prompt (disconnect ) Recognition start Recognition end (fail) Recognition end (success) status=disconnect inputmodes=(dtmf voice dtmf,voice) threshold=%d timeout=%.3f bargeintype=(speech hotword) result=(no input disconnect no match error) bargein=(true false) inputmode=unknown dtmfinput=%s result=success utterance=%s confidence=%d bargein=(true false) inputmode=(dtmf speech) utterance=%s confidence=%d Logged when the Holly Voice Gateway attempts to play a prompt but the call has already disconnected. This is common in normal operation for most applications. Start of recognition. This event contains information such as inputmodes, timeout, threshold and bargein type. End of recognition when the recognition fails. The PARAM value indicates the failure reason. Failed DTMF input (if applicable) is also logged. End of a successful recognition.

43 EVENTID PARAM Description Recording start Recording end (fail) Recording end (success) SIP session maxtime=%.3f dtmfterm=(true false) type=%5 result=(maxtime exceeded no input disconnect max speech timeout error) result=success duration=%d callid=<sip called> remotertp=%s local-rtp=%s Start of voice recording. End of voice recording when the recording has failed. The PARAM value indicates the failure reason. End of a voice recording when successful. SIP Session Call ID. System response latency=%.3f Logged whenever a recognition event occurs, in seconds to millisecond resolution. Transfer start Transfer end(fail) Transfer end(success) VXML Event mode=(network blind bridge conditional) {URI=%s destination=%s} result=(bad destination disconnect error remote busy timeout network busy maxtime exceeded) result=success duration=%.3f event=%s or event=%s message=%s Start of a call transfer. Given either the URI or the destination. End of a call transfer. PARAM value indicates the failure reason. End of a call transfer when successful. Duration is only present for a successful bridge-transfer, value in seconds to millisecond resolution. Logs events thrown by VXML application Configuring Event Logging Each event has a default configuration (on or off) at the platform level. This is determined by the platform administrator and may vary from the factory default settings provided by Holly. Through the Application Parameters in HMS it is possible to enable or disable individual events separately for each Application. The parameter name is client.log.<event name> and the parameter value is true or false. The event name must be lower case and any space should be replaced by underscore. For example: client.log.system_response = true For optimal platform and database efficiency it is recommended to remove any logging options that are not required. 6.2 <log> Element VoiceXML provides the standard <log> element for use in applications. The standard states that the behavior of <log> is platform-specific. The Holly Voice Platform logs each <log> event as an event record. All events for a call - including <log> and many other events - can be displayed and analyzed through the Holly Management System.

44 This section defines Holly's specific behaviors relating to the <log> element. These capabilities have been implemented to simplify application development and debugging, as well as platform operation. The format of the log event is: ID log Param ID label=<label in log tab> expr=<expr in log tag> content=<user defined parameter> Label on <log> The VocieXML <log> element allows a label attribute. If this attribute is provided by the application then the label is inserted into the text of the logged event. For example, the following code: <log label="mylabel"> dialog state info </log> would result in the following event being recorded in the LOG_EVENTS table. ID log Param ID label=mylabel content=dialog state info Changing the Event Type Holly can log over 30 different event types. Holly also allows applications to create custom event types. This is often used when generating custom reports from the platform database. If the content of the <log> tag is of the form EVNT={name} {description} then the event will be logged as: ID name Param ID description For example the code: <log>evnt=myevent This is the text of myevent.</log> would result in the following record in the LOG_EVENTS table: ID myevent Param ID This is the text of myevent Any spaces in the event ID field are stripped, and any consecutive white space in the Param ID field is converted to a single space Objects and Arrays For convenience objects and arrays can be inserted into <log> elements using <value> elements. HVP 5.0 can report display object arrays as per the following examples: The array: values[0] = zero values[1].name = one values[1].value = 1 values[2] = two

45 values[3][0] = cero values[3][1] = uno values[3][2] = dos will be logged as: The object: values=[ zero, [object], two, [array] ] result.fruit = apple result.pizza.base = thin result.pizza.topping = hawaiian result.drink = juice result.lotto[0] = 21 result.lotto[1] = 17 result.lotto[2] = 31 will be logged as: result={ fruit:apple; pizza:[object]; drink:juice; lotto:[array] } ECMAScript Log Function Holly has extended VoiceXML with the built-in function session.logevent() to enable logging from ECMAScript scripts within VoiceXML applications. The effect of the function is as though the argument had been included in a <log> tag in VoiceXML. The log message will appear with a script= prefix. 6.3 Call Record: LOG_CALLS The Call Detail Record (or LOG_CALLS in the Holly database) contains three attributes that can be set by an application to indicate the characteristics or outcome of a call. These application-specific fields can be used in HMS to enhance reporting and analysis (e.g. what is the average duration of calls from gold card members ). The values of the field are set by a VoiceXML application during execution of the call at any time from start to end of VoiceXML execution. The fields are: outcome: If set, it must be one of SUCCESS, FAIL or UNKNOWN. No other values are allowed. Lower case values will be converted automatically to uppercase. If outcome is not defined then the record will be null. calldesc1 and calldesc2: Call Descriptions 1 & 2 are application-defined values and can be any string up to 100 characters. Strings over 100 characters are truncated. If the values are not defined then the value will be null. Use of this capability is optional. If not set then null values are recorded. The values can be logged by the <disconnect> and <exit> tags and specifically the namelist attribute. The VoiceXML/ECMAScript variable of the same name (i.e. outcome, calldesc1 or calldesc2) must be declared and assigned in advance. The variable (or variables) can then be referenced as below: Or <var name="calldesc1" expr="payment Completed by Credit Card"/> <disconnect namelist="calldesc1"/> <var name="calldesc1" expr="payment Completed by Credit Card"/> <exit namelist="calldesc1"/>

46 More than one attribute can be set using the <disconnect> or <exit> tag by including the variable names in the namelist expression separated by a space. For example: <var name="calldesc1" expr="payment Completed by Credit Card"/> <var name="calldesc2" expr="gold Status Account Holder"/> <var name="outcome" expr="success"/> <disconnect namelist="calldesc1 calldesc2 outcome"/> The attribute can also be set using the <log> tag. This mechanism is different because it uses the label section of the <log> tag to reference the attribute rather than a variable name and to derive the value to be logged in the attribute from the expr section. For example: <log label= calldesc1 expr= Payment Completed by Credit Card \> This mechanism does not require a variable to be declared (but a variable can be referenced in the expr section in the normal way if desired.) Only one attribute can be set in a single <log> expression, so multiple <log> expressions must be used to set all the attributes: <log label= outcome expr= SUCCESS \> <log label= calldesc1 expr= Payment Completed by Credit Card \> <log label= calldesc2 expr= Gold Status Account Holder \> If any attribute is set more than once during the execution of a call then previous values are overwritten. 6.4 Log Suppression Some deployments of DTMF and speech applications involve the collection and/or presentation of sensitive information. Examples of sensitive information might include security identifiers (e.g. PIN), or private caller data (e.g. phone number, credit card number, name, address and bank account balance). To protect this information, log suppression can be enabled and disabled around sensitive information within an application through the VoiceXML extension property suppresslogs. When set the Holly Voice Platform will suppress all logging of events. Additionally, Holly will suppress logging by the following speech recognizers if they are currently in use: Nuance 8.5 MRCP v1 Nuance 9.0 MRCP v1 Nuance ASR ScanSoft OSR Holly DTMF. To enable log suppression the following should be included in the VoiceXML document. It affects only the current scope (field, form, document etc). <property name="com.holly.suppresslogs" value="true"/>

47 Note: VoiceXML <property> scoping rules apply. The allowable scopes are application, document, form, menu, form item see VoiceXML 2.0 S6.3. The suppression applies to trace logging by all Holly components. Suppression also blocks audio recording of utterances and data logging by the recognizers stated above Exceptions to Suppression The suppression does not affect the following: Explicit requests for logging by an application using the <log> tag of logevent() function Logging of warnings or errors Full call recording "call start" event An initial ASR Session event "exit" and "call end" events Call detail record (LOG_CALLS record) Record of Suppression An event with the event ID note is logged to indicate when logging as suppression is applied and as logging is re-enabled. Both events can be viewed in the Customer Usage report Call Event log and are controlled by the callevents.browser configuration parameter. The note event is enabled by default. Figure 1 Notification of log suppression