VO Deployment

7/31/2019 VO Deployment

http://slidepdf.com/reader/full/vo-deployment 1/207

VoiceObjects 11

Deployment Guide



VoiceObjects 11

Copyright © 2001-2011 Voxeo Germany GmbH 2

Deployment Guide

VoiceObjects 11.1

To ensure that you are using the documentation that corresponds to the VoiceObjects software you are licensed

to use, compare this version number with the software version shown in the Help menu of the VoiceObjectssoftware you are using.

Copyright

Copyright © 2001-2011 Voxeo Germany GmbH and its licensors. All rights reserved.

Published in Germany – Legal information 2011

Information in this document is subject to change without notice and does not represent a commitment on the partof Voxeo or any of its affiliated companies (collectively “Voxeo”). The software described in this document isfurnished solely under a license agreement. The software may be used or copied only in accordance with theterms of the license agreement. You shall not reverse engineer the software or sub-license, distribute or make thesoftware available to third parties by other means except as specifically allowed in the l icense agreement or by

mandatory law. No part of this document may be reproduced or transmitted in any form or by any means,electronic or mechanical, including photocopying and recording, for any purpose, without the express writtenpermission of Voxeo.

Protected by German, European and US patents. Further patents pending.

Companies, names, and dates used in examples herein are fictitious unless otherwise noted. If such names affectcopyrights or trademarks or others, please notify Voxeo by e-mail at [email protected].

Trademarks

VoiceObjects is a registered trademark. Any other trademarks, trade names or service marks mentioned in thisdocument belong to their respective owners.

The material presented herein is based upon information that we consider reliable, but we do not represent that it

is error-free and complete. Voxeo is not making any representation or granting any warranty with respect to suchmaterial, and the distribution of such material shall not subject Voxeo to any liability.

Third-Party Products

If Licensed Products are distributed together with third-party software or if this is contained in the LicensedProducts, which are subject to additional license provisions, Licensee undertakes to observe the licenseprovisions of the third party.

Explicit Copyright Notice

The VoiceObjects software includes software developed by the Apache Software Foundation (www.apache.org).Copyright © 1999-2011 – The Apache Software Foundation. All rights reserved.

Java and all Java-related trademarks and logos are trademarks or registered trademarks of Sun Microsystems,Inc. in the U.S., other countries, or both.

Specific versions of the VoiceObjects software contain copyright material authorized by the Eclipse Foundation(www.eclipse.org), their contributors and others. All rights reserved.

Specific versions of the VoiceObjects software work with Microsoft Excel or make use of copyright material fromMicrosoft Corporation (www.microsoft.com). All rights to such copyright material rest with Microsoft. Microsoft andExcel are registered trademarks of Microsoft Corporation.

The VoiceObjects software is bundled with the software NuGram IDE Basic Edition developed by Nu Echo Inc.(www.nuecho.com). All title and copyrights in and to the software NuGram IDE Basic Edition, the accompanyingprinted materials, and any copies of the software are owned by Nu Echo Inc. and its suppliers.

Document Number: E-009-20111215-VO11

mailto:[email protected]

http://www.apache.org/

http://www.eclipse.org/

http://www.microsoft.com/

http://www.nuecho.com/

http://www.nuecho.com/

http://www.microsoft.com/

http://www.eclipse.org/

http://www.apache.org/




VoiceObjects 11


Table of Contents

TABLE OF CONTENTS ...................................................................................................3 ABOUT THE DEPLOYMENT GUIDE..................................................................................8

Organization of the Deployment Guide ................................................................ 8 Typographical Conventions .................................................................................. 8 Feedback and Questions ...................................................................................... 9

1 DEPLOYMENT ARCHITECTURE .................................................................................10 2 CONFIGURING SERVERS AND SERVICES................................................................... 13

Configuring a Server ........................................................................................... 13 Configuring a Service ......................................................................................... 16

Application parameters ..................................................................................17

Communication parameters .......................................................................... 18 Logging parameters ....................................................................................... 20 Default parameters ........................................................................................ 23 Proxy parameters .......................................................................................... 29

Deploying a Service on a Server ........................................................................ 31 3 MANAGING SERVERS AND SERVICES ....................................................................... 32

Control Center .................................................................................................... 32 Desktop for Eclipse Control Center ............................................................... 32 Desktop for Web Control Center ................................................................... 33 Control Center communication ...................................................................... 34

Server Manager Overview .................................................................................. 34 Server Management ........................................................................................... 35

Server statistics ............................................................................................. 35 Server context menu ..................................................................................... 36 Server details ................................................................................................. 40

Server Instance Management ............................................................................ 41 Server instance statistics ............................................................................... 41 Server instance context menu ....................................................................... 42 Server instance details .................................................................................. 43

Service Manager ................................................................................................. 44 Service statistics ............................................................................................ 47 Service context menu .................................................................................... 48 Service details ............................................................................................... 52

Maintenance Operations..................................................................................... 54 Take a machine out of a cluster .................................................................... 54 Bring a machine back into a cluster .............................................................. 55



VoiceObjects 11


Add a new machine to a cluster .................................................................... 55 Change the VSN of a service ........................................................................ 55 Cluster split-up ............................................................................................... 56 Database maintenance .................................................................................. 56

4 SERVICE DEPLOYMENT ...........................................................................................58 Permanent and Temporary Deployment ............................................................ 58

Deploy an application permanently ............................................................... 58 Deploy an application temporarily ................................................................. 59

Media Platform Setup ......................................................................................... 59 Direct URL connection ................................................................................... 59 Static markup ................................................................................................. 60

Service URL Configuration ................................................................................. 62 Service URL parameters ............................................................................... 63

Application Defaults ............................................................................................ 65 Dialog Exit Type .................................................................................................. 66 Connection Test .................................................................................................. 67 Debug Viewer ..................................................................................................... 68

Start a Debug Viewer session ....................................................................... 69 How to step through a dialog session ........................................................... 71

Phone Simulator ................................................................................................. 75 Start a Phone Simulator session ................................................................... 75 Navigate in the Phone Simulator ................................................................... 76

5 LOGGING AND TRACING ..........................................................................................79 Server Logs ........................................................................................................ 79 Service Logs ....................................................................................................... 80 Session Tracing .................................................................................................. 81 Trace Viewer ....................................................................................................... 82

6 RECORDING OF UTTERANCES ..................................................................................87 Introducing Utterance Recording ........................................................................ 87

Use cases ...................................................................................................... 87

Quick start ...................................................................................................... 88 Setting up Utterance Recording for a Service .................................................... 88

Server configuration file definition ................................................................. 88 Full duplex call recording ............................................................................... 89 User object definition ..................................................................................... 89 Server object definition .................................................................................. 90 Service object definition ................................................................................. 91

Defining What to Record ..................................................................................... 95 Plug-in object ................................................................................................. 97



VoiceObjects 11


How the Recordings are Stored ......................................................................... 98 Construct the base path ................................................................................ 98 The subfolder structure .................................................................................. 99 The filename structure .................................................................................100 Failure to store a recording ..........................................................................101

Collected Data in Infostore ............................................................................... 101 Example Setups ................................................................................................ 102

Static, unfiltered utterance recording in a single-tenant environment ......... 102 Static, filtered utterance recording in a multi-tenant environment ............... 103 Time-dependent, filtered utterance recording in a single-tenant environment103

7 COMMAND LINE INTERFACE (CLI) .......................................................................... 105 How to Start the Command Line Interface (CLI) .............................................. 105

Windows ...................................................................................................... 105 Linux / Unix .................................................................................................. 105

Commands ....................................................................................................... 105 Server .......................................................................................................... 106 Server instance ............................................................................................109 Service ......................................................................................................... 110

XML Output Format ..........................................................................................111 Query result ................................................................................................. 111 Command result .......................................................................................... 119

8 NOTIFICATIONS .....................................................................................................122 Configuration .................................................................................................... 122

Enable the notification feature ..................................................................... 122 Configure SNMP trap receivers ................................................................... 123 Configure e-mail receivers ...........................................................................125 Assignment of categories to notifications .................................................... 129

Traps ................................................................................................................. 133 Java Management Extensions (JMX) ............................................................... 141

Server Information ....................................................................................... 142 Service Information ...................................................................................... 142 Cache Information ....................................................................................... 143 Queue Information ....................................................................................... 143

9 SERVICE LEVEL AGREEMENTS (SLA) .................................................................... 145 Using Session Partitioning ................................................................................ 145 Configuring Session Partitioning ...................................................................... 145

Site ............................................................................................................... 146 Server .......................................................................................................... 146 Service ......................................................................................................... 147



VoiceObjects 11


Applying Session Partitioning ...........................................................................147 Session guarantees ..................................................................................... 148 Session limits ...............................................................................................149 Session distributions .................................................................................... 150

Monitoring Session Partitioning ........................................................................150 Control Center ............................................................................................. 151 Web Services Interface ............................................................................... 153 Notifications ................................................................................................. 153

Infostore ............................................................................................................ 153 10 MESSAGING SUPPORT .........................................................................................154

Architecture ....................................................................................................... 154 Configuration ............................................................................................... 155

SMS (Clickatell XML API) ................................................................................. 155 Configuration ............................................................................................... 156 Service mapping ..........................................................................................157 Dialog mapping ............................................................................................157 Clustered environment ................................................................................157

Skype ................................................................................................................ 157 Configuration ............................................................................................... 157 Service mapping ..........................................................................................157 Dialog mapping ............................................................................................158

Windows Live Messenger ................................................................................. 158 Configuration ............................................................................................... 158 Service mapping ..........................................................................................158 Dialog mapping ............................................................................................158

Infostore ............................................................................................................ 159 A – MEDIA PLATFORM DRIVERS ...............................................................................160 B – CONTROL CENTER REPORTS .............................................................................197

Report View ...................................................................................................... 197 Server Reports .................................................................................................. 198

Number of Sessions .................................................................................... 198 Sessions by Instance ...................................................................................198 Sessions by Service .................................................................................... 198 Session Duration ......................................................................................... 199 Session Status .............................................................................................199

Server Instance Reports ...................................................................................199 Number of Sessions .................................................................................... 199 Sessions by Service .................................................................................... 200



VoiceObjects 11


Session Duration ......................................................................................... 200 Session Status .............................................................................................200 Memory Usage ............................................................................................ 200 Queue Usage ..............................................................................................201 Cache Usage ............................................................................................... 201

Service Reports ................................................................................................201 Number of Sessions .................................................................................... 201 Session Duration ......................................................................................... 201 Session Status .............................................................................................202 Business Tasks ........................................................................................... 202

C – VIRTUAL CONTROL CENTER ...............................................................................203 Setting up a Virtual Control Center ................................................................... 203

Prerequisites ................................................................................................ 203 Configuration ............................................................................................... 203

Using a Virtual Control Center .......................................................................... 206 Virtual Control Center process .................................................................... 206 Control Center connection ...........................................................................207



About the Deployment GuideOrganization of the Deployment Guide

VoiceObjects 11


About the Deployment Guide

This Deployment Guide contains detailed information on how to configure and manage servers andservices, how to set up the communication with the media platform, and how to monitor servers.

Organization of the Deployment GuideThis Deployment Guide consists of the following chapters:

Chapter 1 – Deployment Architecture – explains the core architecture of theVoiceObjects platform.

Chapter 2 – Configuring Servers and Services – describes how to configure newservers and services.

Chapter 3 – Managing Servers and Services – describes how to manage existingservers and services from within the Control Center.

Chapter 4 – Service Deployment – explains how to configure the communicationbetween the media platform and the server, and how to dynamically configureservices.

Chapter 5 – Logging and Tracing – describes how to use the advanced logging andtracing capabilities of VoiceObjects Server.

Chapter 6 – Recording of Utterances – explains how the feature of utterancerecording is set up and made use of in a voice application.

Chapter 7 – Command Line Interface (CLI) – describes the deployment andmonitoring of servers and services from a terminal console.

Chapter 8 – Notifications – describes how to monitor servers and services throughSNMP and e-mail notifications.

Chapter 9 – Service Level Agreements (SLA) – describes how to configure and usesession partitioning to enable multi-tenant Service Level Agreements.

Chapter 10 – Messaging Support – describes the adapter approach of VoiceObjectsto support text messaging from various communication devices.

Appendix A – Media Platform Drivers – lists the legal values for the driverparameters for all supported media platforms.

Appendix B – Control Center Reports – describes the pre-configured reportsintegrated into the Control Center to allow for easy access and convenient monitoring

of system performance on multiple levels.

Appendix C – Virtual Control Center – describes how to set up and use the VirtualControl Center component for consolidated monitoring and managing of multipleVoiceObjects installations as an integrated unit.

Typographical ConventionsThis document contains the following typographical conventions:

Italic Font Used to indicate names of applications, projects, objects,

variables, files, and folders; output text, and book titles.



About the Deployment GuideFeedback and Questions

VoiceObjects 11


Bold Font Used to indicate any screen terminology like names ofwindows, worksheets, editors, sections, boxes, tabs, fields,

and menus.

Courier New Used for grammar code.

All path specifications in this document use slashes (/) to apply to both Linux andWindows. If you work on Windows you may also use backslashes (\).

Feedback and QuestionsIf you have any comments on this document please send your feedback [email protected].

If you have technical difficulties please contact your local VoiceObjects administrator

or if you have a valid software support and maintenance contract in place send anemail describing your problem to [email protected].







Deployment Architecture

VoiceObjects 11


1 Deployment Architecture

A VoiceObjects Server is a logical entity that is represented by an object in theVoiceObjects Metadata Repository. Multiple physical machines can run one or moreserver instances that each implement this logical entity.

All of the instances derive their configuration, including the set of hosted services,from the central Metadata Repository. This approach enables the simple andtransparent management of both single-machine installations and large server clustersfrom a unified Control Center, both locally and remotely. A server reads thedefinitions of the services it hosts from the VoiceObjects Metadata Repository at starttime, or whenever an individual service is redeployed. At call time, the server thendynamically creates markup code from its internal memory cache without accessingthe database system.




VoiceObjects 11


VoiceObjects uses a server/service paradigm for the deployment of phone services.There can be multiple servers, and each of them can run multiple services. In amodern three-tier architecture, VoiceObjects Server assumes the middle role betweenthe media platform, which connects directly to the telephony network, and the back-end, which provides customer data, dynamic content, etc. As such it also is the linkbetween the telephony world on the one hand and the web-centric IT world on theother hand.VoiceObjects supports multiple phone channels including voice (which covers bothspeech and DTMF input), video, text (USSD), and Web. Within each of thesechannels, different browsers for the corresponding markup (VoiceXML for voice andvideo; various XML markups for text; XHTML for Web) are supported using the mediaplatform driver concept.

In order to achieve failover capabilities or serve large numbers of sessions,VoiceObjects supports clustering using standard IP-based load balancing. Thediagram below shows a typical clustered installation.




VoiceObjects 11


Associated with each server instance is a component called server manager . It acts asa supervisor for the various server processes running on the various machines in thecluster network, and provides the link between the server and the Control Center within VoiceObjects Desktop. This makes it possible to administrate multiple logicalserver clusters from a single Control Center, both locally and remotely.

At any given time, one of the server managers operates in master mode while all theothers in the same cluster operate in inactive mode. If the machine that the masterserver manager runs on should fail then one of the inactive server managersautomatically takes over. The server manager operating in master mode isresponsible for overall cluster management, which includes tasks such asadministration of application caches and license management.

Tip: When starting multiple server instances in a cluster setup, we recommend doing

it in sequence, and to wait until one instance has started completely before starting thenext one.

By default, VoiceObjects Server is configured to run in local cluster mode (for moreinformation see Cluster mode in Chapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide ). In this mode, each individual physical machine has itsown master server manager. This setup is useful for local development and testingthat is not intended to disturb other installations within the same network. For realcluster deployments, the cluster mode needs to be set to network either during theinstallation process or as explained in the Administration Guide .



Configuring Servers and ServicesConfiguring a Server

VoiceObjects 11


2 Configuring Servers and Services

This chapter explains how to configure servers and the services to run on them within VoiceObjectsDesktop.

Configuring a ServerTo configure a new server, do the following:

In the Object Palette, open the Configuration folder and double-click Server. TheServer editor will open up in the editor area.

In Desktop for Web you open up the Server editor by selecting Configure NewServer from the Tools menu.

Note that creating new Server objects requires a controller or administrator role.

Enter a name for the new Server object in the Name field at the top of the editorwindow.

The Configuration Parameters section contains the following fields:

Reference ID Specifies the reference ID of the server.Note that in order for the installation to work properly, the reference ID specifiedhere needs to be identical with the <servername> specified in theVOServer_Configuration.xml file. The default value entered by the installer isVOServer , which corresponds to the default value for a new Server object. Formore information see Server name in Chapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide.

This parameter is mandatory.




VoiceObjects 11


Caution: Only alphanumeric characters (a-z, A-Z, 0-9) and underscoresare allowed. No special characters like blanks, ‘?’, ‘!’, ‘%’, ‘<’, ‘>’ etc., and no

characters coming from character sets other than ISO-8859-1 can be used. Notethat the ID is not case-sensitive, so you cannot have two reference IDs in yourproject that only differ in case.

Caution: Never change this value for a server that has active serverinstances. In particular, never change this value in an operational deploymentenvironment. Service outages may occur as a result.

Session guaranteeSpecifies the guaranteed number of concurrent dialog sessions available to thisserver. Guaranteed sessions are set aside in a separate pool that can only beaccessed by the respective server. This ensures that the session partitioningdefined for a specific server can be met. For more information see Chapter 9 –

Service Level Agreements (SLA).Note that if the number of guaranteed sessions specified here exceeds thenumber of available sessions licensed for the VoiceObjects installation, it islimited accordingly. This parameter is optional. If it is not defined, no guaranteed number ofconcurrent sessions is set aside for this server.To activate changes made to the session guarantee, the server needs to be reset.

Session limitSpecifies the maximum number of concurrent dialog sessions available on thisserver. If this number is reached, then additional attempts to create a dialogsession for any service hosted on this server are rejected. In this case, the callerhears or sees a configurable message indicating that the service is currently notavailable. Once the number of concurrently active sessions drops below the limit,

new calls are accepted again. For more information see Chapter 9 – Service Level Agreements (SLA). This parameter is optional. If it is not defined, the maximum number of concurrentsessions for this server coincides with the number of concurrent sessionslicensed for the VoiceObjects installation.To activate changes made to the session limit, the server needs to be reset.

Control Center URLSpecifies the URL to be used to access the Control Center for this server.Typically, it is of the formhttp://server:port/VoiceObjects/Services/WSProvider?wsdl.To simplify configuration, a default value for localhost is provided.In a cluster configuration, the URL may point to any available server instance in

the cluster.

Caution: This value is crucial to be able to open the Control Center for aserver.

Certificate URLSpecifies the path to a SSL certificate, which is used for authentication if theControl Center URL defined above uses an HTTPS connection. The path caneither be defined by using the HTTP or file protocol.

Testing URLSpecifies the URL to be used to initiate Debug Viewer or Phone Simulatorsessions for this server. Typically, it is of the form http://server:port/VoiceObjects/.To simplify configuration, a default value for localhost is provided.

For a change to take effect, the Control Center must be closed and re-opened.




VoiceObjects 11


Enable System DB loggingIndicates whether System DB logging is enabled for this server. If it is disabled,individual service settings are overridden and dialog statistics are not logged tothe Infostore Repository. In addition, attempts by Log objects to write to thedestination System DB are ignored.This setting can be overridden from within the Control Center.By default, this check box is selected.Note that System DB logging is only available if Infostore is licensed.

Enable Custom DB loggingIndicates whether Custom DB logging is enabled for this server. If it is disabled,individual service settings are overridden and attempts by Log objects to write tothe destination Custom DB are ignored.This setting can be overridden from within the Control Center.By default, this check box is selected.Note that Custom DB logging is only available if Infostore is licensed.

Enable utterance recordingIndicates whether utterance recording is enabled for this server. If it is disabled,individual service settings are overridden and no utterance recording files arecreated.

In the Hosted Services section the set of services that are hosted on this server islisted. See Configuring a Service for more details.

Tip: In a server farm scenario, it is necessary to use IP-based load balancing in

between the media platform and the server farm. Depending on the specific needs,either hardware-based or software-based load balancers can be used. Refer to thedocumentation of the respective products for more information on their configuration.More information can also be found in Appendix A – Sizing and Configuration Recommendations in the Administration Guide .

Note: If a Server object has been locked by some other user, neither its settings

(including its reference ID) nor the list of hosted services can be modified. The Serverobject first needs to be unlocked.For more information on the locking and unlocking of objects, refer to Chapter 7 – Basic Commands in the Desktop for Eclipse Guide or Desktop for Web Guide .



Configuring Servers and ServicesConfiguring a Service

VoiceObjects 11


Configuring a ServiceTo configure a new service, do the following:

In the Object Palette, open the Configuration folder and double-click Service. TheService editor will open up in the editor area.

In Desktop for Web you open up the Service editor by selecting Configure NewService from the Tools menu.

Note that creating new Service objects requires a controller or administrator role.

Enter a name for the new Service object in the Name field at the top of the editor

window.

There are four sections to specify application parameters, communication parameters,logging parameters, and default parameters.

To activate changes made to these settings, the service needs to be redeployed. SeeService Manager in Chapter 3 – Managing Servers and Services for details.




VoiceObjects 11


Application parameters

Application parameters specify the basic behavior of the service including the startobject of the application, the language, and the input mode.

The Application Parameters section contains the following fields:

• Start objectSpecifies the start object of the application associated with this service. Typically,this is a Module object. When the service is requested by the media platform atcall time, the start object is processed, initiating the dialog flow enclosed within it.For XDK applications, the start object may be defined using a URL pointing to astart object within an XDK file, e.g.http://myserver/PrimeInsurance.xml#rootModule . The reference ID of the objectmust be used to identify it, not the name.

In Desktop for Web, the Context Menu button to the right of the Start object field is only available when working within a project.

This parameter is mandatory.

• LanguageSpecifies the initial language the service runs in. This parameter can beoverwritten at call time by passing the parameter vsLanguage in the initial URLrequest from the media platform that initiates the dialog. See Service URLConfiguration in Chapter 4 – Service Deployment for details. The default setting Default indicates that the default language specified for thedriver is used. If no default language is specified for the driver the defaultlanguage specified for the server is used. For more information on the serverdefault language see the Installation Guide.Appendix A – Language Codes in the Object Reference contains a list of alllanguage codes available in VoiceObjects together with the respective language

they represent.

• Input modeSpecifies the initial active input mode for the dialog. This parameter can beoverwritten at call time by passing the parameter vsInputMode in the initial URLrequest from the media platform that initiates the dialog. See Service URLConfiguration in Chapter 4 – Service Deployment for details.Voice indicates that caller input can only be made by voice.DTMF indicates that caller input can only be made by DTMF.Voice+DTMF indicates that caller input can be made by either voice or DTMF.The default setting is Voice+DTMF .

Caution: When changing the input mode to either Voice or DTMF youneed to make sure that you specify the required grammars and outputs for therespective input modes.




VoiceObjects 11


When working in text-based channels, the input mode is automatically set toVoice through a switch in the corresponding driver definition.

• Enable validationIndicates whether the server should validate the integrity of the application whenloading the service either upon start-up or when the service is redeployed. It isstrongly recommended to enable validation in order to detect applicationproblems. This also enables the automatic safeguard capabilities, which leave adeployed application intact instead of replacing it with a broken one.By default, this check box is selected.

Caution: If this check box is clear, applications may be deployed that fail atcall time due to structural problems.

• Retain caches on shutdownIndicates whether the active and restore caches for this service should beretained even when the server is completely shut down. If selected, theapplication definition is not newly loaded when the server starts up the next time,but instead restored from the persisted cache in the Metadata Repository. Thisoption is particularly relevant for volatile services that can be created using theWeb Services Interface. For more details, refer to the Web Services Guide .By default, this check box is clear.

Note: When changing this setting on a service that is already deployed on

a server, it is necessary to redeploy the service to activate the change. This istrue both when activating the retain option (to create the retained caches) as wellas when deactivating it (to remove the retained caches).

Communication parameters

Communication parameters provide the essential information to connect the mediaplatform to the server including the service name, and the media platform driver to beused.Depending on a user’s role, this section may be inaccessible.

The Communication Parameters section contains the following fields:

• VSN (reference ID)VoiceObjects Service Name. Specifies the unique name of the service. The VSN

can be used to identify a service when initiating it by means of an HTTP requestfrom the media platform. See Service URL Configuration in Chapter 4 – Service




VoiceObjects 11


Deployment for details.

Caution: Only alphanumeric characters (a-z, A-Z, 0-9) and underscores are

allowed. No special characters like blanks, ‘?’, ‘!’, ‘%’, ‘<’, ‘>’ etc., and nocharacters coming from character sets other than ISO-8859-1 can be used. Notethat the ID is not case-sensitive, so you cannot have two reference IDs in yourproject that only differ in case.

Caution: Note that the VSN must not end in either “_shadow” or“_inactive”, as the server uses these strings internally.This parameter is mandatory.

Note: For information on how to change the VSN of a deployed service see

Maintenance Operations in Chapter 3 – Managing Servers and Services .

• DNIS mappingSpecifies a comma-separated list of phone numbers that are mapped to this

service. See Service URL Configuration in Chapter 4 – Service Deployment fordetails.This parameter is optional.

• Startup modeSpecifies what is to be done with this service when a server hosting it is started.Automatic indicates that the service is started together with the server.Manual indicates that the service is not started together with the server, andshows up in the list of hosted services as stopped.Disabled indicates that the service is not started together with the server, andshows up in the list of hosted services as disabled.The default setting is Automatic .

•

Cache standbySpecifies whether the cache for this service may dynamically be dropped frommemory when there is insufficient space to hold all service caches in memorysimultaneously. For details on cache configuration refer to Cache Management inChapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide. On demand indicates that the cache may be dropped.Never indicates that the cache must always be kept in memory.

The default setting is On demand . Note: It is recommended to use Never very sparingly since VoiceObjects

Server is typically better positioned to decide which services to keep in memory.

• Driver

Specifies the media platform that the service runs on. This parameter can beoverwritten at call time by passing the parameter vsDriver in the initial URLrequest from the media platform that initiates the dialog. See Service URLConfiguration in Chapter 4 – Service Deployment for details. The default setting Default indicates that the default driver selected for the serveris used. For more information on specifying the default driver see the Installation Guide.

• Respect user-agent in Web channelIf the check box Respect user-agent in Web channel is selected the serverreads out the user-agent header information in the initial HTTP request comingfrom the client; this is a string that identifies the browser so that Web servers canrespond with optimized code. Based on an up-to-date list of Web browser user-agents the server tries to map the agent to one of the available VoiceObjects Webdrivers. If the mapping succeeds, then this driver is taken for the session insteadof the driver defined in the Service object or in the service URL parameter




VoiceObjects 11


vsDriver .Since the Web channel is the only channel for which the requesting platform(=browser) is unknown before the call comes in, this setting is required to be ableto dynamically select a suitable Web driver that presents the application in anoptimal way.If no corresponding driver can be found in the lookup phase or the driver is notfrom the Web channel, the driver setting from the service or URL parameter istaken and the user-agent is ignored.This parameter can be overwritten at call time by passing the parametervsRespectUserAgent in the initial URL request from the media platform thatinitiates the dialog. See Service URL Configuration in Chapter 4 – Service Deployment for details. If both vsRespectUserAgent and vsDriver are provided inthe URL the server first tries to do a mapping of agent to driver, and if that fails ittakes the vsDriver value.By default, this check box is clear.

• Session guaranteeSpecifies the guaranteed number of concurrent dialog sessions available to thisservice. Guaranteed sessions are set aside in a separate pool that can only beaccessed by the respective service. This ensures that the session partitioningdefined for a specific service can be met.Note that if the number of guaranteed sessions specified here exceeds thenumber of guaranteed sessions for the site this service belongs to or for theserver it is hosted on, the number of guaranteed sessions is limited accordingly.For more information see Chapter 9 – Service Level Agreements (SLA). This parameter is optional. If it is not defined, no guaranteed number of concurrentsessions is set aside for this service.

• Session limit

Specifies the maximum number of concurrent dialog sessions allowed for thisservice. If this number is reached, then additional attempts to create a dialogsession for this service are rejected. In this case, the caller hears a configurablemessage indicating that the service is currently not available. Once the number ofconcurrently active sessions drops below the limit, new calls are accepted again.For more information see Chapter 9 – Service Level Agreements (SLA).This parameter is optional. If it is not defined, the maximum number of concurrentsessions for the service coincides with the maximum number for the server it ishosted on.

• Session distributionSpecifies the distribution of concurrent dialog sessions among services within asite and on a given server.The session distribution specifies a percentage indicating the allocation of

available dialog sessions to the respective service. Note that this setting is onlyrelevant if a session limit is defined for the site.The sum of all percentage values assigned to services within a single site mustnot exceed 100. If it does, all session distribution settings for this site are ignored.For more information see Chapter 9 – Service Level Agreements (SLA).The default setting is Disabled .Instead of selecting one of the values from the drop-down list, it is also possible totype in a custom value. In this case, the value must lie between 0 and 1. E.g. toselect a session distribution of 27%, the value 0.27 needs to be entered.

Logging parameters

Logging parameters specify the logging behavior of the service including the defaultlogging destination, the list of activated logging categories, and the activation settings




VoiceObjects 11


for database logging.

The Logging Parameters section contains the following fields:

• Enable System DB loggingIndicates whether System DB logging is enabled for this service. If it is disabled,dialog statistics are not logged to the Infostore Repository. In addition, attemptsby Log objects to write to the destination System DB are ignored.This setting can be overridden from within the Control Center.By default, this check box is clear.

• Enable Input State loggingIndicates whether System DB logging writes detailed information for eachindividual input state visited by a caller. If it is disabled, only a single data recordis written per call indicating information such as ANI, DNIS, length and time of

call, etc. Also business task, layer and module related data is stored in theInfostore Repository.For further information, refer to the Infostore Guide .By default, this check box is clear.

• Enable Script object backend loggingIndicates whether Script objects should create records for backend accessanalysis.For further information, refer to the Infostore Guide .By default, this check box is clear.

• Enable Custom DB loggingIndicates whether Custom DB logging is enabled for this service. If it is disabled,attempts by Log objects to write to the destination Custom DB are ignored.This setting can be overridden from within the Control Center.By default, this check box is clear.




VoiceObjects 11


• CoverageSpecifies the percentage of dialogs that should be written to System DB logging(and, optionally, Custom DB logging; see Filter scope below).In deployments with high call volumes, it is sometimes desirable to not write outdetailed statistics on each and every call, but only on a fraction thereof. Coveragecan be selected from 10% to 100% of all dialogs. Each individual dialog is thenlogged either completely or not at all. The coverage selection algorithm uses auniform distribution on dialog sessions to minimize the impact of coverage filteringon subsequent reporting.The default is 100%.Instead of selecting one of the values from the drop-down list, it is also possible totype in a custom value. In this case, the value must lie between 0 and 1. E.g. toselect a coverage of 27%, the value 0.27 needs to be entered.

• Filter scopeSpecifies whether the coverage defined above extends only to input states, to

System DB logging (the default), or to System DB and Custom DB logging.If coverage is less than 100% and System DB and Custom DB is selected, thendialogs that do not write to System DB logging will also not write to Custom DBlogging. This option should be chosen if Custom DB logging is used as anextension of System DB logging.If coverage is less than 100% and System DB is selected, then dialogs that do notwrite to System DB logging will still write to Custom DB logging. This optionshould be chosen if Custom DB logging is used e.g. to trigger back-endprocessing (such as making an entry into an ordering system).If coverage is less than 100% and Input State is selected, then dialogs alwayswrite a single record but only write detailed Input State logging in the selectedpercentage of cases (but any individual dialog either writes all input states ornone).

The default is System DB .

• Enable utterance recordingIndicates whether utterance recording is enabled for this service. If it is disabled,no utterance recording files are created.By default, this check box is clear.

• Utterance recording pathSpecifies the path that utterance recording files are written to.For more information see Chapter 6 – Recording of Utterances .

• Utterance recording URLSpecifies the URL through which utterance recording files can be retrieved.For more information see Chapter 6 – Recording of Utterances .

• CoverageSpecifies the percentage of dialogs that should create utterance recording files.In deployments with high call volumes, it is sometimes desirable to not write filesfor each and every call, but only for a fraction thereof. Coverage can be selectedfrom 10% to 100% of all dialogs. The coverage selection algorithm uses a uniformdistribution on dialog sessions to minimize the impact of coverage filtering onsubsequent reporting.The default is 100%.Instead of selecting one of the values from the drop-down list, it is also possible totype in a custom value. In this case, the value must lie between 0 and 1. E.g. toselect a coverage of 3%, the value 0.03 needs to be entered.For more information see Chapter 6 – Recording of Utterances .

• Enable OSDM Event LoggingIndicates whether OSDM Event Logging is enabled for this service.




VoiceObjects 11


If enabled, the OSDM Event Log Destination field can be used to define a file towhich the data is logged. If not defined, the default file as defined in the OSDMconfiguration is used. Note that paths in the OSDM Event Log Destination fieldneed to use forward slashes, even on Windows.By default, this check box is clear.

• Default logging destinationSpecifies the default location for Log objects to write to.Custom DB indicates that the information is written to a custom database table.Log File indicates that the information is written to a server log file that can beaccessed through the Control Center.Log OSDM indicates that the information is written to the OSDM log.Media Platform indicates that the information is written to the media platform logby using the <log> element in VoiceXML.System DB indicates that the information is written to a special field within theSystem DB logging.

For more information, refer to the Log object in the Object Reference .This parameter can be overwritten at call time by passing the parametervsLoggingDestination in the initial URL request from the media platform thatinitiates the dialog. See Service URL Configuration in Chapter 4 – Service Deployment for details. The default setting is Log File .

• Logging categoriesSpecifies which log categories are active for this service. Multiple check boxescan be selected, and only Log items that match one of the selected categories willbe activated at call time. This makes it easy e.g. to integrate debuggingmessages into an application for development and testing purposes, and then todisable those messages with a single click as the application goes into

deployment.Info is intended for informational messages that do not necessarily indicate errorconditions, but provide information on the dialog processing.Debug is intended for messages only used during application development anddebugging. This category should typically be disabled for deployed services.Error is intended for messages indicating error situations in the application. Thiscategory should typically be enabled for deployed services.Statistics is intended for messages that provide statistical information on howcallers use the application.Billing is intended for messages that are used for billing purposes.The set of selected categories can be overwritten at call time by passing theparameter vsLoggingCategories in the initial URL request from the media platformthat initiates the dialog. See Service URL Configuration in Chapter 4 – Service

Deployment for details. By default, all check boxes are selected.

• Maintainer e-mailSpecifies an e-mail address that error messages are sent to by the mediaplatform.This parameter is optional.

Note: System and Custom DB logging are only available with a valid Infostore license.

Default parameters

Default parameters specify the defaults for a variety of service settings including e.g.

barge-in and dialog exit type. Default parameters come in three groups:




VoiceObjects 11


• those that are relevant for the entire dialog and that can be changed by use ofexpression functions;

• those that are relevant for specific types of objects and that can be overriddenlocally within such objects;

• and those that are relevant for the entire dialog and that cannot be changed atcall time.




VoiceObjects 11


The Default Parameters section contains the following fields:

• Grammar type

Specifies the standard grammar type. All Grammar items with type setting Default are controlled by this setting, so that the grammar type can be changedthroughout an entire service with a single switch.SRGS ABNF indicates W3C speech recognition grammar format in BNF notation.Nuance GSL indicates Nuance GSL grammar format.JSGF indicates Java speech grammar format.SRGS XML indicates W3C speech recognition grammar format in XML notation.Cisco Regular Expression indicates Cisco regular expression format.Precompiled indicates precompiled grammar format.None indicates that no standard grammar format is used.Built-in indicates built-in grammars as defined in the VoiceXML specification. The default setting Default indicates that the default grammar type for theselected driver is used.

Note that if a grammar type is selected which is not supported by the selectedmedia platform, the platform’s default type is used instead by the server.

• Video typeSpecifies the standard video type. All Video objects with type setting Default arecontrolled by this setting, so that the video type can be changed throughout anentire service with a single switch.Note that if a video type is selected which is not supported by the selected mediaplatform, the platform’s default type is used instead by the server.

• Barge-inSpecifies the standard setting for barge-in. All Output items with barge-in settingDefault are controlled by this setting, so that barge-in can be enabled or disabledthroughout an entire service with a single switch.

True indicates that barge-in is allowed.False indicates that barge-in is not allowed. The default setting is True .

• Grammar controlSpecifies the standard setting for grammar control. All Input objects with grammarcontrol setting Default are controlled by this setting, so that grammar control canbe enabled or disabled throughout an entire service with a single switch.True indicates that grammar control is enabled.False indicates that grammar control is disabled. The default setting is False .For more information on grammar control, refer to Input in the Object Reference .

• Output modeSpecifies whether audio or TTS should be the preferred output mode. The output mode is useful for testing whether all required audio files andalternative texts have been defined.Audio:TTS indicates that audio is used if available, otherwise TTS.TTS:Audio indicates that TTS is used if available, otherwise audio. The default setting is Audio:TTS .

• Record utterancesSpecifies whether utterances should be recorded for this service (True ) or not(False ). The default setting is True .Note that this setting only has relevance if the setting Enable utterance recoding in the Logging Parameters section has been selected.

•

Recording scopeSpecifies the scope to be covered by utterance recording.




VoiceObjects 11


All indicates that all utterances are recorded.No Match indicates that only utterances causing a No Match event are recorded.Recognition indicates that only utterances leading to a successful recognition arerecorded.The default setting is All .

• Standby timeoutSpecifies the time after which a dialog session is removed if there is no activity.As opposed to the dialog timeout, the standby timeout is applied during theprocessing of Plug-In, Transfer, or Recording objects. These are objects wheresome processing takes place “outside” of VoiceObjects, which can take longerthan the usual dialog timeout. The standby timeout allows you to increase thetimeout temporarily for these objects.The default setting is 10 minutes .Instead of selecting one of the values from the drop-down list, it is possible to typein a custom value. This value is interpreted as seconds. E.g. for a custom timeout

of 5.5 minutes, type in 330.

• Dialog timeoutSpecifies the time after which a dialog session is removed if there is no activity.Note that if you use call pausing (see Pause object in the Object Reference ) orplay long audio files to the caller, it might be necessary to increase this value inorder to ensure that the dialog is not unintentionally terminated.The default setting is 5 minutes .For applications working in the text or Web channel, a shorter dialog timeout maybe desirable, e.g. 40 seconds. In Input, Menu, Confirmation, and List objects, thedialog timeout can temporarily be increased in order to give callers more time torespond to them if required (e.g. when entering an address).Instead of selecting one of the values from the drop-down list, it is also possible to

type in a custom value. This value is interpreted as seconds. E.g. for a customtimeout of 1.5 minutes, type in 90.

• HTTP connector timeoutSpecifies the time after which a HTTP request issued by a Connector object isaborted if no answer is received from the back-end.The default setting is 10 Seconds .Instead of selecting one of the values from the drop-down list, it is possible to typein a custom value. This value is interpreted as seconds. E.g. for a custom timeoutof fifteen seconds, type in 15.

• Dialog exit type Specifies what should be done when the end of the dialog is reached and the lastobject processed was not an Exit object (if it was, the exit type defined in that

object is taken).Disconnect indicates that the call is terminated with a hang-up by sending a<disconnect> tag to the media platform.Exit indicates that control over the call is handed back to the media platform.Return indicates that a <return> tag is sent to the media platform. This enablesthe continuation of an ongoing dialog that was initiated outside VoiceObjects.The behavior in these cases is described by VoiceXML files that are sent to themedia platform. The behavior can be modified by adjusting these files, which canbe found under

..\VoiceObjects\Platform\Resources\System\VXML\<VoiceXML version>\<Media Platform Provider>\

with the names Disconnect.vxml , Exit.vxml , and Return.vxml .The default setting is Disconnect .




VoiceObjects 11


• Grammar precedenceSpecifies the precedence in case both embedded and external grammardefinitions are present in a Grammar object item.Embedded:External indicates that an embedded definition takes precedence overan external grammar reference. External:Embedded indicates that the externalgrammar file will be taken rather than an embedded grammar definition.The default setting is Embedded:External .

• Audio file extensionSpecifies an audio file extension that overwrites all file extensions defined locallyin Audio objects.The default setting None indicates that the locally defined audio file extensionsare used.

• Grammar file extensionSpecifies a grammar file extension that overwrites all file extensions defined

locally in Grammar objects.The default setting None indicates that the locally defined grammar file extensionsare used.

• Video file extensionSpecifies a video file extension that overwrites all file extensions defined locally inVideo objects.The default setting None indicates that the locally defined video file extensionsare used.

• Text file extensionSpecifies a text file extension that overwrites all file extensions defined locally inText objects.The default setting None indicates that the locally defined text file extensions are

used. • Reject response

Defines the way in which the server responds to requests when no more licensesare available for the service.Overflow indicates that a file overflow.vxml is sent, usually to indicate that theservice is not available at the moment.Redirect indicates that a file redirect.vxml is sent, usually to transfer the call e.g.to a call center agent.The default setting is Overflow .The behavior in both cases can be modified by adjusting the corresponding file,which can be found under

..\VoiceObjects\Platform\Resources\System\VXML\<VoiceXML version>\<Media Platform Provider>\

The reject response behavior can be overwritten at call time by passing theparameter vsRejectResponse in the initial URL request from the media platformthat initiates the dialog. See Service URL Configuration in Chapter 4 – Service Deployment for details.

• Standard navigationStandard navigation provides functionality such as Go back or Repeat . It isconfigured in the Module object by providing appropriate grammars for thevarious commands. Disabled indicates that standard navigation is disabled, regardless of whethergrammar entries are defined for it or not.

The default setting is to remember the last three dialog steps (3 Steps ). This




VoiceObjects 11


means that the caller can use the standard navigation command Back threetimes, and thus go back at most three steps in a dialog.

• Service chainingDefines how service chaining transmits parameters.External indicates that parameters are transmitted through markup and HTTPrequests.Internal indicates that parameters are transmitted internally within theVoiceObjects Server instance. This requires that the service chain target remainson this same instance.The default setting is External .

• Session variablesSpecifies a comma-separated list of media platform session variables. This canbe used for two purposes:1 If a media platform calls the server through a custom VoiceXML page using

<subdialog> and the platform wants to submit parameters to the applicationusing <param> elements, define all required parameter names in this field.2 If you want to fetch variables from the platform session context other thanthose already specified in the driver (like ANI, DNIS, etc.), define all additionallyrequired variables with syntax vo_name (mp_name) in this field, where vo_name is the parameter name you want to use within the application and mp_name is thename used by the media platform.Example: ANI (session.connection.remote.uri)In both cases, the variables can be accessed through the expression functionSESSION(vo_name).

• Resource pathSpecifies a physical path that is used in Resource Locator objects using theoption Allow service overwrite .The default is not to use a resource path.

• Resource URLSpecifies a URL that is used in Resource Locator objects using the option Allow Service overwrite .The default is not to use a resource URL.

• Configuration URLSpecifies the location of a configuration file that defines application default values.Both HTTP and file URLs are allowed. Note that it is required to mention theprotocol (http:// or file:// ) in the URL.The use of basic authentication and/or SSL is supported by using the notation<configURL>||<certificateURL>||<user>||<password>.

Note that if the configuration file cannot be fetched during a redeploy, theredeploy fails and the service remains in its previous state.See Application Defaults in Chapter 4 – Service Deployment for details. The default is not to use a configuration URL.

• OSDM URLSpecifies the URL that points to an installation of OpenSpeech DialogModules(OSDMs). This value overrides the one defined in the <osdmURL> element withinthe VOServer_Configuration.xml .This parameter is only relevant if OSDMs have been licensed.

• Loop abort handler URLSpecifies the location of a file holding valid VoiceXML code that will be put in anevent handler of type error for level 10 on each rendered VoiceXML document.

Both HTTP and file URLs are allowed. Note that it is required to mention theprotocol (http:// or file:// ) in the URL.




VoiceObjects 11


Using this feature, you can define custom code to be executed on the mediaplatform in case of subsequent error events that would otherwise not be caught.Typically, this is code that deliberately does not lead back to the server, inscenarios where the error occurred due to connection problems.The default is not to use a loop abort handler. If no location is defined in this field,the server will include an error handler holding a VoiceXML command thatcorresponds to the currently active dialog exit type. E.g., if the exit type iscurrently Disconnect , the server will render the following code into eachVoiceXML document:<catch event="error" count="10">

<disconnect/>

</catch>

• Render templatesSpecifies a comma-separated list of render templates to use for this service. BothHTTP and file URLs are allowed. Note that it is required to mention the protocol

(http:// or file:// ) in the URL.The use of basic authentication and/or SSL is supported by using the notation<templateURL>||<certificateURL>||<user>||<password>.See Appendix E Defining Custom Rendering Templates in the Administration Guide for details.Note that if one of the template files listed cannot be fetched during a redeploy,the redeploy fails and the service remains in its previous state. The default is not to use custom render templates.

• TTA librariesSpecifies a comma-separated list of TTA libraries to use for this service. BothHTTP and file URLs are allowed. Note that it is required to mention the protocol(http:// or file:// ) in the URL.The use of basic authentication and/or SSL is supported by using the notation

<libraryURL>||<certificateURL>||<user>||<password>.See Appendix B How to Use the Formatting Bus in the Administration Guide fordetails.Note that if one of the TTA libraries listed cannot be fetched during a redeploy,the redeploy fails and the service remains in its previous state. The default is not to use a configuration URL.

Proxy parameters

Proxy parameters specify which proxies to use (if any) for HTTP, HTTPS, and FTPrequests.




VoiceObjects 11


The Proxy Parameters section contains the following fields, all of which are empty bydefault:

• HTTP proxy host

Specifies a proxy host to be used for all HTTP requests.

• HTTP proxy portSpecifies a proxy port to be used for all HTTP requests.

• HTTP proxy userSpecifies a proxy user to be used for all HTTP requests.

• HTTP proxy passwordSpecifies the password for the proxy user to be used for all HTTP requests.

• HTTPS proxy hostSpecifies a proxy host to be used for all HTTPS requests.

• HTTPS proxy port

Specifies a proxy port to be used for all HTTPS requests.

• HTTPS proxy userSpecifies a proxy user to be used for all HTTPS requests.

• HTTPS proxy passwordSpecifies the password for the proxy user to be used for all HTTPS requests.

• FTP proxy hostSpecifies a proxy host to be used for all FTP requests.

• FTP proxy portSpecifies a proxy port to be used for all FTP requests.

• FTP proxy use

Specifies a proxy user to be used for all FTP requests.



Configuring Servers and ServicesDeploying a Service on a Server

VoiceObjects 11


• FTP proxy passwordSpecifies the password for the proxy user to be used for all FTP requests.

• HTTP(S) proxy bypassSpecifies a comma-separated list of hosts for which HTTP(S) requests do not usethe configured proxy.

• FTP proxy bypassSpecifies a comma-separated list of hosts for which FTP requests do not use theconfigured proxy.

Note: If a Service object has been locked by another user, none of its settings can be

modified. The Service object first needs to be unlocked.For more information on the locking and unlocking of objects, refer to Chapter 7 – Basic Commands in the Desktop for Eclipse Guide and Desktop for Web Guide .

Deploying a Service on a ServerIn order for it to be available to a media platform, a service needs to be deployed on aserver.

To deploy a service, open an existing Server object, add the service to the list ofhosted services and save the Server object. For details on how to add elements to alist refer to Chapter 6 – Object Editors in the Desktop for Eclipse Guide and Desktop for Web Guide .

In the Control Center select the corresponding server on the Server Manager tab (inDesktop for Web on the Server Management tab) and right-click it. From the context

menu select Reload Service List. The new service will then be listed on the ServiceManager tab (in Desktop for Web to be found in the Service Manager section on theServer Management tab).

In order to call into a service, it is necessary to also configure the media platformappropriately. For more information on this, refer to Media Platform Setup in Chapter 4 – Service Deployment .



Managing Servers and ServicesControl Center

VoiceObjects 11


3 Managing Servers and Services

Control CenterThe Control Center is the graphical interface component within VoiceObjectsDesktop that enables the deployment and monitoring of servers and services.

As an alternative to the graphical Control Center, the Web Services Interface may beused. Details can be found in the Web Services Guide .

There is also a text-based Command Line Interface (CLI), which is explained inChapter 7 – Command Line Interface (CLI). It is recommended, however, to use theWeb Service Interface instead since it provides more flexibility.

Finally, notifications about specific conditions on servers can be received through

SNMP and e-mail as explained in Chapter 8 – Notifications .

Desktop for Eclipse Control Center

To open the Control Center for a given server in Desktop for Eclipse, first acorresponding Control Center connection has to be defined in the VoiceObjectspreferences of Desktop for Eclipse. Refer to Chapter 10 – VoiceObjects Preferences in the Desktop for Eclipse Guide for details on how to do this.

Once one or more Control Center connections have been configured the ControlCenter will be shown, initially located at the bottom of Desktop for Eclipse.

The drop-down box in the upper right corner allows switching between the configuredControl Center connections.

Using the Filter field you can restrict a list of server and server instances, services, logfiles, or trace files to those items that contain a certain text string within their name, orthat have a name starting with a certain text string (when selecting the Starts with check box).

The content of the Control Center is automatically refreshed to show the currentlyactive service states, call statistics, etc., according to the refresh cycle, which can bespecified in the Advanced preferences page. A manual refresh can be activated by

clicking the Refresh button in the upper right corner of the Control Center.

Below the header bar, the Control Center displays six tabs. Server Manager andService Manager are explained in this chapter, Server Logs, Service Logs, andSession Tracing are described in Chapter 5 – Logging and Tracing , and SessionPartitioning is described in Chapter 9 – Service Level Agreements (SLA).



Managing Servers and ServicesControl Center

VoiceObjects 11


Desktop for Web Control Center

In Desktop for Web the Control Center for a given server can be opened by doing the

following:1. In the Object Browser, open the Configuration folder and then the Server folder.

You need to have a Controller or Administrator role to see the Configuration folder.

2. Right-click the Server object for which you want to open the Control Center. Andin the context menu that comes up, click Control Center.Note that to open the Control Center it is necessary to configure the appropriateControl Center URL within the Server object. For details, see Chapter 2 – Configuring Servers and Services.

The Control Center is loaded into a new tab in the right-hand pane of VoiceObjectsDesktop. If this tab already exists, the view switches to it.

In the header bar of the Control Center, the display Refresh Cycle can be selectedin various intervals between thirty seconds and one hour. After a refresh cycle hasexpired, the display of the Control Center is automatically refreshed to display thecurrently active service states, call statistics, etc. A manual refresh can be activated by

clicking the Refresh button in the menu bar of VoiceObjects Desktop.

Below the header bar, the Control Center displays five tabs: Server Management(see Server Manager and Service Manager below) is explained in this chapter,Server Logs, Service Logs, and Session Tracing are described in Chapter 5 – Logging and Tracing , and Session Partitioning is described in Chapter 9 – Service Level Agreements (SLA).



Managing Servers and ServicesServer Manager Overview

VoiceObjects 11


Control Center communication

VoiceObjects uses the Web Service Interface to communicate between the Control Center and servers that are monitored and controlled by it. This has the advantagethat VoiceObjects Desktop does not need to be part of the same cluster as the serverto be monitored, and that both local servers (within the same network) and remoteservers (in other networks) can be monitored and controlled. Finally, even serversrunning on different Metadata Repositories can be monitored and controlled. Thismakes it possible, for instance, to administrate both a test and a production installationfrom a single VoiceObjects Desktop.

Tip: The Control Center remembers all server instances that were present at some

time during the current session (i.e. as long as the Control Center is open) and triesto re-connect to any of them when the server instance it is currently connected tobecomes unavailable. This means that when you shut down instances in a cluster, you

do not need to manually adjust the URL defined in the Server object. A manual refreshof the Control Center may be required at times to trigger the re-connect to a differentserver instance.When you open a new Control Center, it always tries to connect to the serverinstance reachable at the URL defined in the Server object. If this fails, you will see anerror message. In this case, adjust the URL to an available server instance and tryagain.

Server Manager OverviewThe Server Manager tab displays detailed information about the server and allrunning server instances.

In Desktop for Web this information can be found in the Server Manager section ofthe Server Management tab.

The Server column shows the logical name of the server, which corresponds to thereference ID of the Server object. Each server instance is represented by its name, orby its IP address and port (as configured in the corresponding configuration file). Tobetter separate the server from the server instances, a prefix “S: ” for the server and

“I ”: for the server instances is added to their names. Desktop for Web does not addany prefix as here the server is visually separated from the server instances. In asingle server setup, only one instance is available. In a cluster setup, it may be anynumber of instances.



Managing Servers and ServicesServer Management

VoiceObjects 11


To the left of the Server column, the server and server instance status is indicated bya traffic light icon:

Icon Server Status

(Green light) Started

(Yellow light) Idled

(Red light) Stopped

If one of the server instances listed acts as master server manager for the cluster, thisis indicated by the Crown icon next to the traffic light icon.

Note: There may be cases in which none of the server instances acts as master

server manager, because this role is taken by a server instance of a different server.Thus, if you do not see a crown icon next to any of the server instances this does notnecessarily indicate a problem.

Refer to Server Management and Server Instance Management below for moredetails about the shown information as well as on the available control functions forthe server and the server instances.

Server ManagementThis paragraph describes the server statistics shown in the nine additional columns ofthe Server Manager tab, all commands available in the server context menu and theServer Details info box providing a summary of various server information.

Server statistics

To the right of the Server column, the next set of six columns provides sessionstatistics for the server, displaying:

• Start TimeIndicating the most recent time the server has been (re-)started. In the case of acluster, the start time indicates the earliest start time of any of the individualserver instances involved.

• ActiveNumber of currently active sessions on this server.

• FinishedNumber of sessions on this server that were completed successfully.

• AbortedNumber of sessions on this server that were aborted due to an error condition(including dialog timeout).

• RejectedNumber of sessions on this server that were rejected. This may happen because

the corresponding service was not started when the session came in, or becauseno matching service could be found for the VSN and/or DNIS provided. It may




VoiceObjects 11


also happen when no more concurrent sessions are available for a certainservice, server, site, or the entire VoiceObjects installation.

• TotalSum of the previous four columns.

The following two columns, System DB Logging and Custom DB Logging, indicate

the currently applicable DB logging options for the server as enabled (green light ),

disabled (red light ), unavailable (yellow light ), or not licensed (grey light ).DB logging requires a valid license for Infostore.

Note: While the red or green light indicates a specific administrator setting, the yellow

light indicates that the respective logging option should be enabled, but failed due to adatabase connection problem. In order to resolve this, the respective server instance

needs to be fully restarted (including its JVM) once database connectivity has beenrestored.The grey light indicates that the license key for the server does not allow DB logging.Contact VoiceObjects regarding a license for Infostore.

The final column Tracing indicates whether tracing is currently enabled (green light

) or disabled (red light ) for this server. More information on tracing is providedin Chapter 5 – Logging and Tracing .

Server context menu

To access server control functions, right-click anywhere in the row of the server entry.

In Desktop for Web click the Context Menu button to the right of the server name.

The following list describes the server control functions that are available from thecontext menu. Note that most of them are only available to Server Administrators orServer Controllers. Other user roles only see a subset of the functions. For moreinformation on user roles and their privileges refer to Chapter 2 – User Management – Basic Topics in the Administration Guide .

• Edit Opens up the Server editor. Note that this entry is only available if the Serverobject for which the Control Center is shown comes from the Metadata Repositoryto which Desktop for Eclipse is currently connected. In addition the user accountused for both the connections needs to be the same.

• Reload Service List Reloads the list of services hosted on this server. This is used when you have

added a new service to a server, or removed a service from a server.After reloading the service list, the Control Center will display any newly addedservices as stopped (see description of service states below). You need to startthe service before it can be called.Services that have been deleted from the server will only be removed from theControl Center if they have been stopped before reloading the service list.

• StartStarts this server. For a cluster this means that all individual server instances inthe cluster are started.This command is only available when the server is stopped. Note that whenstarting a stopped server, all active and restore caches are restored from theirpreviously persisted state, and application definitions are not reloaded from

scratch. Services will be started according to their startup mode, i.e. services with




VoiceObjects 11


startup mode automatic will be started and services with startup mode manual (ordisabled) will remain stopped.




VoiceObjects 11


• ResumeResumes this server. For a cluster this means that all individual server instances(both idled and stopped) in the cluster are resumed.This command is only available when the server is idled. When resuming an idledserver, all idled services are also resumed.

• ResetResets this server to essentially the state it would be in immediately after a freshstart. The difference is that if a redeploy would break a currently running service,then it is kept in its current state. After a reset, all restore caches are gone.For a cluster, Reset means that all individual server instances in the cluster arereset. A warning window will appear to indicate that all currently active sessionswill be terminated immediately. If you confirm by clicking OK, all currently activesessions are terminated, and the server resets. During reset, all services arestopped and their application caches are loaded. If the server was started, theservices are then started according to their startup mode settings.

This command is only available when the server is started or idled.

• IdleIdles this server. For a cluster this means that all individual started serverinstances in the cluster are idled. A warning window will appear to indicate thatthe server will be idled. This does not affect currently active sessions, which areallowed to finish normally. If you confirm by clicking OK, the server attempts toidle and the Control Center shows the “Please wait” icon. When the serverreaches idled state (after all active sessions on the server have terminated), theserver’s status light changes to solid yellow.This command is only available when the server is started.

• StopStops this server. For a cluster this means that all individual server instances in

the cluster are stopped. A warning window will appear to indicate that all currentlyactive sessions will be terminated immediately. If you confirm by clicking OK, allcurrently active sessions are terminated, and the server stops.When the server stops, all services hosted on it also stop. Their persisted activeand restore caches remain intact. When you start the server again using the Start command, these caches are restored.

• ShutdownShuts down this server. For a cluster this means that all individual serverinstances in the cluster are shut down. A warning window will appear to indicatethat all currently active sessions will be terminated immediately. If you confirm theshutdown by clicking OK, all currently active sessions are terminated, and theserver shuts down.

When the server shuts down, all active and restore caches are cleaned (exceptfor those services that explicitly use the Retain caches on shutdown option). Theserver cannot be started up again from within the Control Center or CLI after ithas been shut down. The server process needs to be re-started manually.

Note: Shutting down the server will not stop the JVM it is running in.

• DB Logging Options Used to modify the currently applicable DB logging configuration for the server.




VoiceObjects 11


In the cascading submenu that comes up, both System DB logging and CustomDB logging can be enabled or disabled by clicking the respective entry. Changesmade here have immediate effect, but they do not change the permanent settingsmade in the Server object. The modified status is indicated by the appropriatelights in the System DB Logging and Custom DB Logging columns as well asby a tick mark (or its absence) in the context menu itself.DB logging settings made in the server override those made in services that arehosted on this server. Thus by disabling System or Custom DB logging on theserver, it is automatically disabled for all services. This override is indicated by a

black light ( ) in the respective DB Logging column for the service.Note that when resetting a server, the default values defined in the Server objectare restored.

• Disable/Enable Tracing Used to modify the currently applicable tracing configuration for the server.By clicking the context menu entry, tracing can be enabled or disabled. Changesmade here have immediate effect. The modified status is indicated by theappropriate light in the Tracing column as well as by a tick mark (or its absence)in the context menu itself.The tracing setting made in the server overrides those made in services that arehosted on this server. Thus by disabling tracing on the server, it is automatically

disabled for all services. This override is indicated by a black light ( ) in theTracing column for the service.Note that after resetting a server, tracing is enabled by default.

•

Details (only available in Desktop for Eclipse) Opens up the Server Details with the Server tab in front showing a summary ofserver information. In Desktop for Web the info box is opened by clicking the

Maximize button at the right end of the row. Refer to Server details below fordetails on the information that is displayed.

• Refresh (only available in Desktop for Eclipse) Used to manually refresh the Control Center to display the currently active

service states, call statistics, etc. In Desktop for Web the Refresh button inthe menu bar can be used instead.

• Properties (only available in Desktop for Web) Opens up the Properties window of the Server editor.

• Reports (only available in Desktop for Eclipse)Provides a cascading submenu of reports available for the server. For details,




VoiceObjects 11


refer to Appendix B – Control Center Reports .This command is only available if Infostore is enabled for the server.

Server details

The Server Details info box can be opened by double-clicking the server entry on theServer Manager tab or by selecting Details from its context menu.

In Desktop for Web the info box is opened by clicking the Maximize button at theright end of the row.The Server Details info box opens up showing the Server tab in front.

It provides a summary of the following information about the server:

System DB Logging Shows the status of System DB logging, which is also indicated by the

appropriate light in the System DB Logging column in the Control Center.

Custom DB Logging Shows the status of Custom DB logging, which is also indicated by theappropriate light in the Custom DB Logging column in the Control Center.

Site ID (only shown in Desktop for Web)ID of the site this server belongs to. For more information on sites, refer toChapter 3 – User Management – Managing Sites in the Administration Guide .

Session guarantee / limit (Session guarantee only shown in Desktop for Web)The number of guaranteed sessions available to this server and the concurrentsession limit for this server. If no limit has been set, Not limited is shown. Notethat the actual limit also depends on the limit set by the license key of the

VoiceObjects installation.The numbers shown in front are the granted guarantee and limit; the numbersshown in parentheses are the requested guarantee and limit.

License expires The expiration date for the license key of the VoiceObjects installation. Starting

ten days before the expiration date, a yellow triangle icon is shown next to thisentry (and to the right of the server name) to indicate that a new license needs tobe acquired.

Server version (only shown in Desktop for Eclipse)Shows the build version of VoiceObjects Server.

Tracing (only shown in Desktop for Eclipse)

Shows the status of the tracing, which is also indicated by the appropriate light inthe Tracing column in the Control Center.



Managing Servers and ServicesServer Instance Management

VoiceObjects 11


Utterance recording (only shown in Desktop for Web) Indicates whether utterance recording is enabled or disabled for this server.

Errors (only shown in Desktop for Eclipse) If an error occurred a corresponding message, explaining the problem, is shownhere.

Details (only shown in Desktop for Eclipse) Shows the session statistics for the server. These figures are identical with thoseshown in the corresponding columns of the Server Manager tab.

Server Instance ManagementThis paragraph describes the server instance statistics shown in the nine additionalcolumns of the Server Manager tab, all commands available in the server instancecontext menu, and the info box for the server instance details providing a summary of

various server instance information.

Server instance statistics

To the right of the Server column, the next set of six columns provides sessionstatistics for the server, displaying:

• Start TimeIndicating the time the server instance has been started.

• ActiveNumber of currently active sessions on this server instance.

• Finished

Number of sessions on this server instance that were completed successfully.

• AbortedNumber of sessions on this server instance that were aborted due to an errorcondition (including dialog timeout).

• RejectedNumber of sessions on this server instance that were rejected. This may happenbecause the corresponding service was not started when the session came in, orbecause no matching service could be found for the VSN and/or DNIS provided. Itmay also happen when no more concurrent sessions are available for a certainservice, server, or the entire VoiceObjects installation.

• Total

Sum of the previous four columns.

The following two columns, System DB Logging and Custom DB Logging, indicatethe currently applicable DB logging options for the server instance as enabled (green

light ), disabled (red light ), unavailable (yellow light ), or not licensed (grey

light ).DB logging requires a valid license for Infostore.

Note: While the red or green light indicates a specific administrator setting, the yellow

light indicates that the respective logging option should be enabled, but failed due to adatabase connection problem. In order to resolve this, the respective server instance

needs to be fully restarted (including its JVM) once database connectivity has beenrestored.




VoiceObjects 11


The grey light indicates that the license key for the server does not allow DB logging.Contact VoiceObjects regarding a license for Infostore.

The final column Tracing is empty as this setting is not available on sever instances,but only on servers and services.

In Desktop for Web the last three columns System DB Logging, Custom DBLogging and Tracing are not provided. Instead, two Memory columns are displayed,showing the used and free memory for the Java Virtual Machine (JVM) in which theserver instance runs.

Note: Depending on the JVM that is used, the amounts of memory shown here may

differ from those configured in the start scripts for VoiceObjects Server.

Server instance context menu

To access server instance control functions, right-click anywhere in the row of thecorresponding server instance entry. In Desktop for Web click the Context Menu

button to the right of the server instance name. The following list describes theserver control functions that are available from the context menu. Note that most ofthem are only available to Server Administrators or Server Controllers. Other userroles only see a subset of the functions. For more information on user roles and theirprivileges refer to Chapter 2 – User Management – Basic Topics in the Administration Guide .

The following server instance control functions are available from the context menu:

IdleIdles this instance. A warning window will appear to indicate that the instance willbe idled. This does not affect currently active sessions, which are allowed to finish

normally. If you confirm by clicking OK, the instance attempts to idle and theControl Center shows the “Please wait” icon. When the instance reaches idledstate (after all active sessions on the instance have terminated), the instance’sstatus light changes to solid yellow.This command is only available when the server instance is started.If a media platform request comes into an idled server instance, it is automaticallyredirected to a started instance within the same cluster (as long as such aninstance exists). This redirection uses the standard HTTP redirection mechanism.

ResumeResumes this instance.This command is only available when the server instance is idled.

StopStops this instance. A warning window will appear to indicate that all currentlyactive sessions on this instance will be terminated immediately. If you confirm byclicking OK, all currently active sessions on the instance are terminated, and theinstance stops.When an instance stops, all active and restore caches remain intact. When youstart the instance again using the Start command, these caches are restored.If a media platform request comes into a stopped server instance, it isautomatically redirected to a started instance within the same cluster (as long assuch an instance exists). This redirection uses the standard HTTP 302mechanism.

StartStarts this instance.

This command is only available when the server instance is stopped.When starting a stopped instance, all active and restore caches are restored from




VoiceObjects 11


their previously persisted state, and application definitions are not reloaded fromscratch. This ensures that the instance starts up again in the exact sameconfiguration in which it was stopped.

Details (only available in Desktop for Eclipse) Opens up the Server Details with the Instance tab in front showing a summaryof server instance information. In Desktop for Web the info box is opened by

clicking the Maximize button at the right end of the row. Refer to Serverinstance details below for more details about the information displayed.

Refresh (only available in Desktop for Eclipse) Used to manually refresh the Control Center to display the currently active


Reports (only available in Desktop for Eclipse)

Provides a cascading submenu of reports available for the server instance. Fordetails, refer to Appendix B – Control Center Reports .This command is only available if Infostore is enabled for the server instance.

Server instance details

The info box for the server instance details can be opened by double-clicking theserver instance entry on the Server Manager tab or by selecting Details from itscontext menu.

In Desktop for Web the info box is opened by clicking the Maximize button at theright end of the row.The Server Details info box opens up showing the Instance tab in front.

For each available server instance a corresponding section is shown on the Instance tab, providing a summary of the following information about the server instance:

System DB Logging Indicates whether System DB logging is enabled or disabled for this serverinstance. Note that even when System DB logging is enabled for the server, DBconnection problems or other issues may lead to situations in which it cannot beactivated for certain server instances.

Custom DB Logging Indicates whether Custom DB logging is enabled or disabled for this serverinstance. Note that even when Custom DB logging is enabled for the server, DBconnection problems or other issues may lead to situations in which it cannot be

activated for certain server instances.



Managing Servers and ServicesService Manager

VoiceObjects 11


Used memory (only shown in Desktop for Eclipse)Shows the used memory for the Java Virtual Machine (JVM) in which the serverinstance runs.

Free memory (only shown in Desktop for Eclipse)Shows the free memory for the Java Virtual Machine (JVM) in which the serverinstance runs.

Configured IP address The IP address and port as defined in the configuration file for this serverinstance.

Detected IP address The IP address as detected by the server instance itself.

Cluster Group The cluster group this server instance belongs to.

• Errors Shows any errors that may have occurred on this server instance, such as e.g.DB connectivity problems. If any errors have occurred, this is indicated by a

yellow triangle icon to the right of the server instance name.

• Details (only shown in Desktop for Eclipse) Shows the session statistics for the server instance. These figures are identicalwith those shown in the corresponding columns of the Server Manager tab.

Service ManagerThe Service Manager section displays the list of services hosted on the server,

together with their current status and session statistics. Services are identified by theirVoiceObjects Service Name (VSN).

In Desktop for Web this information can be found in the Service Manager section ofthe Server Management tab.

The Service column shows the logical name of the service, which corresponds to theVSN of the Service object.

The Source column to the right of the Service column shows whether this servicecontains a start object from a project version (Project ), a start object from aVoiceObjectsXML file (File ), or is deployed from string (String ).

For a detailed description of the remaining nine columns to the right refer to servicestatistics below. All available service commands are described in the service contextmenu paragraph and additionally the Service details paragraph gives an summary ofvarious service information shown in the service info box.

At the top of the list of services hosted on this server, there is an entry “Invalidrequests”. It serves to display session statistics for requests directed to non-existing orbroken services, and for requests that could not be associated with any service. This

may happen if the request did not indicate any service either by VSN or by DNIS.Such invalid requests may only lead to aborted or rejected sessions.




VoiceObjects 11


In Desktop for Web, services deployed directly from an XDK file are indicated by the

file icon next to the VSN. For more information, refer to the XDK Guide .

Volatile services, i.e. services deployed directly from a string, are indicated by thestring icon next to the VSN. For more information, refer to theredeployXDKApplication() method in Chapter 3 – Using the Web Services Interface (Deploy from string) and in Chapter 4 – Command Reference both in the Web Services Guide .

The service status is indicated by a traffic light symbol:

Icon Service Status

(Green light)

Started.Existing sessions (if any) are being

processed. New incoming sessions areaccepted.

(Yellow light)

Idled.Existing sessions (if any) are beingprocessed. New incoming sessions arerejected and will only receive a messageindicating that the service is currentlyunavailable.

(Red light)

Stopped.No existing sessions are beingprocessed. New incoming sessions are

rejected and will only receive a messageindicating that the service is currentlyunavailable.

(Black light)

Disabled.No existing sessions are beingprocessed. New incoming sessions arerejected and will only receive a messageindicating that the service is currentlyunavailable. A disabled service cannot bestarted. In order to start it, its startupmode first needs to be set to somethingother than Disabled , and the service then

needs to be redeployed to bring it intostopped mode.




VoiceObjects 11


Services can transition from one status to another as outlined in the following diagram.

Next to the status, the service startup mode is indicated by an icon:

Startup mode is Automatic Upon starting the server, the service definition is loaded and the service is startedautomatically. This is the default for new services.

Startup mode is Manual

Upon starting the server, the service definition is loaded, but the service is not startedautomatically.

Startup mode is Disabled Upon starting the server, the service definition is not loaded.

The startup mode icons may also occur with an additional red dot ( , , ) toindicate that the option Retain caches on shutdown is active on the respective service.

Knowing the startup mode is useful to quickly check whether all hosted services startup in their desired configuration when starting a server.

If a problem occurs during the loading of a service definition, a yellow triangle iconis displayed to the right of the VoiceObjects Service Name. The tool tip for this icon

describes the problem in more detail. The exact error message can also be found inthe info box for the service.

Note: A stopped service cannot be started if it shows the yellow triangle icon . It

must first be redeployed to a valid application definition.

If the media platform tries to access a service that is idled or stopped, a failoverVoiceXML file using the settings defined in the corresponding service (language,media platform driver, etc.) is returned.

If the media platform tries to access a service that does not exist or is disabled, afailover VoiceXML file using the default settings of the server is returned.

In either case, the appropriate VoiceXML file is dynamically generated based on

configurations defined in the files SystemFailovers.xml and SystemFailoverTexts.xml in the folder ..\VoiceObjects\Platform\WEB-INF\config .




VoiceObjects 11


It is possible to provide a static alternative file instead in the following location:

..\VoiceObjects\Platform\Resources\System\VXML\<LanguageCode>\dialogs\VXML\<

VoiceXML version>\<Media Platform Provider>\<ProductVersion>\Unavailable.vxml

The file may contain custom VoiceXML or other markup code appropriate for therespective media platform. In this way, custom behavior can be achieved for failovercases.

A simpler variation is to just modify the audio played within the failover VoiceXML. Tomodify it, the audio file

..\VoiceObjects\Platform\Resources\System\Audio\<LanguageCode>\service_unavailable_formal.wav

can be replaced by a custom recording.

If a request for a new dialog session cannot be granted due to an insufficient numberof available concurrent sessions, separate failover files are played depending on theconfigured Reject response . They are also dynamically generated or can be providedat

..\VoiceObjects\Platform\Resources\System\VXML\<LanguageCode>\dialogs\VXML\< VoiceXML version>\<Media Platform Provider>\<ProductVersion>\Overflow.vxml

and

..\VoiceObjects\Platform\Resources\System\VXML\<LanguageCode>\dialogs\VXML\< VoiceXML version>\<Media Platform Provider>\<ProductVersion>\Redirect.vxml

As above, it is also possible to modify the audio file

..\VoiceObjects\Platform\Resources\System\Audio\<LanguageCode>\

service_overflow_formal.wav

Service statistics

The next set of columns on the Service Manager tab provides session statistics forthis service, displaying:

• Start TimeDate and time the service was most recently started or redeployed.

• ActiveNumber of currently active sessions for this service.

• Finished

Number of sessions for this service that were completed successfully.

• AbortedNumber of sessions for this service that were aborted due to an error condition(including dialog timeout).

• RejectedNumber of sessions for this service that were rejected because the service wasnot started when the session came in, or because no more concurrent dialogsessions were available.

• TotalSum of the previous four columns.

The following two columns, System DB Logging and Custom DB Logging, indicatethe currently applicable database logging options for the service as enabled (green




VoiceObjects 11


light ), disabled (red light ), or overridden (black light ). If Infostore filtering isused, the icon will be partly red and partly green depending on the selected coverage.

The final column Tracing indicates whether tracing is currently enabled (green light

or yellow light ), disabled (red light ), or overridden (black light ) for thisservice.

More details on the logging and tracing functionalities of VoiceObjects can be found inChapter 5 - Logging and Tracing .

Service context menu

To access service control functions, right-click anywhere in the row of the

corresponding service entry. In Desktop for Web click the Context Menu button tothe right of the service name. The following list describes the available service control

functions:• Edit

Opens up the Service editor. Note that this entry is only available if the Serviceobject comes from the Metadata Repository to which Desktop for Eclipse iscurrently connected. In addition the user account used for both the connectionsneeds to be the same.

• Reload Service List (only available in Desktop for Eclipse)Reloads the list of services hosted on this server. This is used when you haveadded a new service to a server, or removed a service from a server.After reloading the service list, the Control Center will display any newly addedservices as stopped (see description of service states below). You need to startthe service before it can be called.

Services that have been deleted from the server will only be removed from theControl Center if they have been stopped before reloading the service list.

• Redeploy Deploys an updated version of this service.A warning window will appear to indicate that the service will be updated to thelatest dialog definition. This does not affect currently active sessions, which areallowed to finish using the current dialog definition. If you confirm by clicking OK,a “Please wait” message comes up while the service is being redeployed.Depending on the size of the dialog definition, this process may take some time tocomplete.If there are active sessions on the service when it is being redeployed, theControl Center will introduce an additional row for the service (a “shadowservice”), displayed directly below the original service entry in orange.

This row summarizes all active sessions that still use previous dialog definitions.Once all of these active sessions have terminated, the row is removed and thesession statistics are consolidated into the normal row for the service.When redeploying a service, its tracing and logging settings are maintained.

If the updated cache cannot be loaded due to an error condition such as aninvalid object definition in the application, the built-in safeguard mechanism keeps




VoiceObjects 11


the currently active cache intact. The error condition is indicated by a yellow

triangle icon to the right of the VoiceObjects Service Name, and the full error

message is provided both as the tool tip for this icon, and in the service info box(see below). After having corrected the problem, redeploy again to activate thenew cache. The warning icon will then disappear.

• RestoreReverts back to the previously stored version of the application definition.A warning window will appear to indicate that the service will be restored to itsstatus prior to the most recent redeploy. This does not affect currently activesessions, which are allowed to finish using the current dialog definition. If youconfirm by clicking OK, a “Please wait” message comes up while the service isbeing restored.If there are active sessions on the service when it is being restored, the Control Center will introduce an additional row for the service, displayed directly belowthe original service entry in orange.

The Restore command is only available after a previous Redeploy .

• IdleSets this service into idled status. This command is only available if the service is started.A warning window will appear to indicate that the service will be idled. This doesnot affect currently active sessions, which are allowed to finish normally. If youconfirm by clicking OK, the service attempts to idle and the Control Center shows the “Please wait” icon. When the service reaches idled state (after allactive sessions on the service have terminated), the service’s status lightchanges to solid yellow.

• ResumeResumes this service.This command is only available if the service is idled.

• Start Starts this service. This command is only available if the service is stopped.When a service is started, it attempts to claim any guaranteed sessions assignedto it. For more information, see Chapter 9 – Service Level Agreements (SLA).

Note: It may not be possible to start a service if the yellow triangle icon

is displayed to the right of the VoiceObjects Service Name. In such cases, checkthe error description shown in the service info box (see below), correct the issue,and then redeploy the service. If the warning icon disappears, you can then startthe service.

• Stop Stops this service.This command is only available if the service is started or idled. A warning window will appear to indicate that all currently active sessions on thisservice will be terminated immediately. If you confirm by clicking OK, all currentlyactive sessions on this service are terminated, and the service stops.When a service is stopped, it releases all guaranteed sessions assigned to it. Formore information, see Chapter 9 – Service Level Agreements (SLA).

• DB Logging Options Used to modify the currently applicable options for System and Custom DBlogging.




VoiceObjects 11


In the cascading submenu that comes up, both System DB logging and CustomDB logging can be enabled or disabled by clicking the respective entry. Changesmade here have immediate effect, but they do not change the permanent settingsmade in the Service object. They influence the service behavior while the serverthat hosts the service is running. After a restart of the server, or a redeploy of theservice itself, the service behavior reverts to what is defined in the Service objectdefinition itself.Note that the logging options settings made on the server level override thosemade on the service level. Thus, if System or Custom DB logging is disabled onthe server level, it is automatically disabled for all services. This is indicated by

the black light ( ) in the respective DB Logging column of the ServiceManager section.

• Tracing OptionsUsed to modify the currently applicable tracing options for the service.

In the window that comes up you can enable or disable tracing, restrict tracing tospecific channels, as well as define a comma-separated list of ANIs for which totrace sessions. No wildcards (such as ? or *) are allowed in this list.Enabling tracing with an empty ANI list means that all sessions will be traced.This is strongly discouraged in a production deployment, as it negatively impactsperformance. Tracing is reset to Disabled when restarting the server that hosts




VoiceObjects 11


the respective service. Tracing settings are kept intact during a service redeploy.For a more detailed description of the tracing functionality refer to Chapter 5 – Logging and Tracing .

When tracing is enabled for a service, this is indicated by a green light ( ) in therespective Tracing column on the Service Manager tab. If tracing is restricted to

certain channels or to a certain list of ANIs, this is indicated by a yellow light ( ).Note that the tracing options settings made on the server level override thosemade on the service level. Thus, if tracing is disabled on the server level, it is

automatically disabled for all services. This is indicated by a black light ( ).

Note: By default, tracing is disabled on all services after the server is reset.

This can be changed by using the setting<enableTracingByDefault>true</enableTracingByDefault> incomponents_VOServer.xml .It is strongly recommended to not change this setting in production installationsdue to the amount of data that can get generated.

• Debug ViewerStarts a Debug Viewer session for this service. For further information refer toDebug Viewer in Chapter 4 – Service Deployment .This command is only available if the service is started.

• Phone SimulatorStarts a Phone Simulator session for this service.

From the cascading submenu that comes up, you can select to start the PhoneSimulator in the text or Web channel.For further information refer to Phone Simulator in Chapter 4 – Service Deployment .

• Details (only available in Desktop for Eclipse) Opens up the Service Details showing a summary of service information. In

Desktop for Web the info box is opened by clicking the Maximize button at theright end of the row. Refer to Service details below for more details about theinformation displayed.

• Refresh (only available in Desktop for Eclipse) Used to manually refresh the Control Center to display the currently active




VoiceObjects 11



• Properties (only available in Desktop for Web) Opens up the Properties window for this service.

• Reports (only available in Desktop for Eclipse)Provides a cascading submenu of reports available for the service. For details,refer to Appendix B – Control Center Reports .This command is only available if Infostore is enabled for the service.

Service details

The Service Details info box can be opened by double-clicking the service entry onthe Service Manager tab or by selecting Details from its context menu.

In Desktop for Web the info box is opened by clicking the Maximize button at theright end of the row.

For each available service a corresponding section is shown, providing a summary ofthe following information about the service:

Service objectName of the Service object for this service.

ProjectName of the project in which the start object can be found.For XDK services deployed from a file or for volatile services, the project is shownas Unavailable . Refer to the XDK Guide for more information.

Project versionName of the project version in which the start object can be found.For XDK services deployed from a file or for volatile services, the project versionis shown as Unavailable . Refer to the XDK Guide for more information.

Start objectName of the start object defined for the service.For XDK services, the start object may be a URL. Refer to the XDK Guide formore information.For volatile services, the start object is only the reference ID of the start objectitself. For more information, refer to the redeployXDKApplication() method inChapter 3 – Using the Web Services Interface (Deploy from string) and in Chapter4 – Command Reference both in the Web Services Guide .




VoiceObjects 11


Site IDID of the site the service belongs to. For more information on sites, refer toChapter 3 – User Management – Managing Sites in the Administration Guide .

Utterance recording (only shown in Desktop for Web) Indicates whether utterance recording is enabled or disabled for this service. Notethat this setting may be overridden by the one on server level.

System DB Logging (only shown in Desktop for Eclipse)Indicates whether System DB logging is enabled or disabled for this service. Notethat even when System DB logging is enabled for the server, DB connectionproblems or other issues may lead to situations in which it cannot be activated fora certain service.

Custom DB Logging (only shown in Desktop for Eclipse)Indicates whether Custom DB logging is enabled or disabled for this serverinstance. Note that even when Custom DB logging is enabled for the server, DB

connection problems or other issues may lead to situations in which it cannot beactivated for a certain service.

Infostore filtering (only shown in Desktop for Eclipse)Shows the current coverage of the Infostore logging as selected in the Serviceobject.

Active cache timestampTime when the currently active cache was created. If no active cache is available,this is shown as Unavailable .

Active cache sizeSize of the currently active cache.For reference purposes, the internal cache ID is also provided.

Restore cache timestampTime when the current restore cache was created. If no restore cache isavailable, this is shown as Unavailable .

Restore cache sizeSize of the current restore cache.For reference purposes, the internal cache ID is also provided.

Session guarantee / limit (Session limit only shown in Desktop for Web)The number of guaranteed sessions available to this service and the concurrentsession limit for this service. If no limit has been set, Not limited is shown.The numbers shown in front are the granted guarantee and limit; the numbersshown in parentheses are the requested guarantee and limit.

A yellow triangle icon at the end of this entry indicates that either the sessionguarantee or the session limit was overridden. The tool tip for the icon providesdetails.

Session distributionThe session distribution percentage defined for this service, or Disabled if none isdefined.

A yellow triangle icon at the end of this entry indicates that the sessiondistribution is ignored.

Tracing (only shown in Desktop for Eclipse) Shows the status of the tracing, which is also indicated by the appropriate light inthe Tracing column in the Control Center.



Managing Servers and ServicesMaintenance Operations

VoiceObjects 11


Filter scope (only shown in Desktop for Eclipse) Shows the filter scope of the Infostore logging as selected in the Service object.This can either be Input State , System DB or System and Custom DB .

ErrorsShows any errors that may have occurred during the most recent (re-)

deployment of this service. If errors have occurred, a yellow triangle icon isshown to the right of the VoiceObjects Service Name.

Details (only shown in Desktop for Eclipse) Shows the session statistics for the service. These figures are identical with thoseshown in the corresponding columns of the Service Manager tab.

When running a server in a cluster configuration, each new server instancesynchronizes with the current state of the instances in the portion of the cluster that isalready running.

Upon starting the first server instance in a cluster, its hosted services come up asconfigured in the corresponding Service objects, i.e. they come up as started if theirmode is set to Automatic and they come up as stopped if their mode is set to Manual (assuming there are no problems during startup; see Configuring a Service in Chapter2 – Configuring Servers and Services for details). Manual changes can then be madeto their states via the Control Center or the Command Line Interface.

As a new instance in the server cluster for the respective server is started, it restoresthe previously determined application cache and status. As all changes to the clusterconfiguration are persisted to the database and restored from there, the entire clusteris always maintained in a consistent state.

Caution: When a service needs to be completely removed from a server, make sure

that the service is first stopped. If there are active sessions, this should be done byfirst idling the service, waiting until all active sessions have finished, and then stoppingit so as not to interrupt the ongoing sessions. Then remove the respective Serviceobject from the list of hosted services in the Server object. Finally, use the ReloadService list command discussed above to synchronize the state of the server with itsdefinition.

Maintenance OperationsIn a production deployment, it becomes necessary from time to time to perform certainmaintenance operations such as swapping a hard drive, adding memory, etc. Thisparagraph describes how to perform such actions on a VoiceObjects installation

without creating downtime. Of course this is only possible when using a cluster setupwith multiple machines. For details on cluster configuration refer to Chapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide .

In addition to possible cluster operations it is strongly recommended to regularlyperform maintenance operations on the used database system in order to secure bestperformance. See the paragraph on Database Maintenance for details.

Take a machine out of a cluster

To perform maintenance on a machine, it typically needs to be shut down. To do thisgracefully without impacting call sessions, proceed as follows:

1. Idle all server instances on the machine.




VoiceObjects 11


2. Reconfigure the load balancer that assigns requests coming from the mediaplatform to server instances such that the machine that is to be taken down doesnot receive new requests.

3. Wait until all active dialog sessions on any server instance on this machine havefinished.

4. Stop all server instances on the machine.

5. Shut down the machine.

Note that while the server instances are idled (after the first step), new sessions thatare routed to any of these instances by the load balancer will automatically beredirected to other active server instances within the cluster. This ensures that duringthe intermediate time until the second step has been completed, all incoming sessionsare answered and handled correctly.

Bring a machine back into a cluster

After having completed maintenance work on a machine taken out of the cluster asdescribed above, the machine needs to be brought back into the cluster. To do so,simply start the respective server instances on the machine. They will automaticallymerge back into the cluster and start the same services as all other instances withinthe cluster.

After all server instances on the machine have started successfully, reconfigure theload balancer that assigns requests coming from the media platform to serverinstances such that the machine is included again.

Add a new machine to a cluster

As an installation may grow with more call traffic on existing applications or theaddition of new applications, an existing cluster configuration sometime needs to beextended by adding more hardware. Adding a new machine to an existing clustershould be done as follows:

1. Configure the new machine as described in Chapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide . Make sure that the list of clustermembers contains all existing machines as well as the new one.

2. Start all server instances on the new machine.

3. Reconfigure the load balancer that assigns requests coming from the mediaplatform to server instances such that the new machine is included.

4. For each of the “old” machines in the cluster, follow the steps described above totake it down. Then adjust its cluster configuration to include the new machine, andbring it back into the cluster.

5. After the previous step has been performed for all “old” machines in the cluster,the new cluster is set up and contains all machines, including the newly addedone.

Change the VSN of a service

In rare case, it becomes necessary to change the VoiceObjects Service Name (VSN)of a deployed service. Note that this is an operation that requires changes on both theVoiceObjects and the media platform side.

To gracefully change the VSN, follow these steps (assuming that the service iscurrently started):




VoiceObjects 11


1. In the Service object, change the VSN to the new value and save the object.

2. Reload the service list on the server. This adds the service with its new VSN, in

stopped state. Note that the service is also still present with its old VSN.3. Start the service with the new VSN.

4. Once the service is started, adjust the media platform configuration such thatrequests now use the new VSN instead of the old one.

5. Wait until all existing calls on the service with its old VSN are completed. Thenstop the service.

6. Reload the service list on the server once again. This removes the stoppedservice with the old VSN.

Cluster split-up

If there are problems in the network such as outages of switches or routers or networkcables that accidentally get unplugged, a cluster of VoiceObjects Server instancesmay temporarily break up into smaller sub-clusters. When network connectivity isrestored, the cluster usually merges back together within a matter of minutes.

While the cluster is split up, the following guidelines should be followed:

• Do not take any special actions to manually merge the cluster. It will merge backautomatically. This process can take anywhere from a few seconds to a couple ofminutes, counting from the time that network connectivity is restored between allmembers of the cluster.

• Do not perform any Control Center operations (such as starting, stopping, orredeploying services) while the cluster is split. If you do, the cluster state will

become inconsistent and operations may have strange effects after the clustermerges back together.

• Avoid starting up or bringing down instances while the cluster is split.

• The Control Center may block temporarily while the cluster is split. The CLI mayblock or return error messages.

• In isolated cases it might be required to bring down and restart an instance if itfails to reappear in the Control Center.

• In isolated cases it might be required to close the Control Center tab and open itagain if it continues to show an empty list of instances.

Database maintenance The following steps are important in order to maintain optimal database performance:

Regular statistics update

To improve the performance it is necessary to regularly run the statistics scriptsMDStatistics.sql and LDStatistics.sql located at:

<VoiceObjects_HOME>\Platform\WEB-INF\driver\db\<DBMS>

Typically, this is done by using a batch job.




VoiceObjects 11


Regular deletion of logging data

The amount of data that is logged by Infostore to the database can significantly growover time especially in large installations with high call volumes. Depending on theavailable resources and business requirements it might be necessary to establish aprocess that removes old logging data from the database.

Typically, this is done by using a batch job.



Service DeploymentPermanent and Temporary Deployment

VoiceObjects 11


4 Service Deployment

In order to provide end-to-end connectivity, the media platform or browser that issues requests to theserver must be configured properly. Typically, each service is accessed through a specific phonenumber in the voice and video channel, short code in the text channel, or URL in the Web channel. Inthis case, the media platform or browser uses a URL pointing to the server that returns the correctmarkup code (VoiceXML, XHTML, or a USSD markup) for the specific service. The URL mapping caneither be specified directly, or a static file can be used to point to the server.

Details on service deployment are provided in the following sections:

• Permanent and Temporary Deployment – describes the two different ways of either permanentlyor temporarily deploying an application.

• Media Platform Setup – explains how to configure the media platform to connect to the server.

• Service URL Configuration – explains how to pass additional parameters to a service as part ofthe initial request, and how to make these parameters available in the application.

• Application Defaults – explains how default values for objects used within a service can be setthrough an XML file.

• Dialog Exit Type – explains the different exit types that are available for leaving a service.

• Connection Test – explains how to test the availability of a service or server.

• Debug Viewer – explains the debug mode functionality and how to use it to test voice, video, textor Web applications when no media platform is available.

• Phone Simulator – explains the phone simulator functionality and how to use it to test and demoapplications in the text and Web channel.

Permanent and Temporary DeploymentIn addition to permanently deploying an application as a service on a server in theControl Center, VoiceObjects Desktop for Eclipse allows deploying an applicationtemporarily by using the Test Monitor (this option is not available when using Desktopfor Web).

Deploy an application permanently

To deploy an application permanently do the following:

1. Create a new Service object and link the object which represents the applicationyou want to call as start object.

Note: If you intend to use an existing service replace its start object and

redeploy the service in the Control Center. Afterwards proceed with step four.

2. Add the new Service object to the list of hosted services in the Server object youwant to use and select Reload Service List from the context menu of the Serverobject in the Control Center.

3. Start the new service in the Control Center.

4. Point your media platform to the service and call your application. Refer to MediaPlatform Setup below for more details on how to do this.

For details on how to configure servers and services refer to Chapter 2 – Configuring Servers and Services in the Deployment Guide .



Service DeploymentMedia Platform Setup

VoiceObjects 11


For details on how to manage servers and services in the Control Center refer toChapter 3 – Managing Servers and Services in the Deployment Guide .

Deploy an application temporarily

To deploy an application temporarily in Desktop for Eclipse do the following:

1. Select the object which represents the application you want to call in the ObjectBrowser, Dialog Designer or Search Result and right-click it. From the contextmenu select Test Application. The Test Monitor opens up and validates theselected object.

2. Point your media platform to the embedded server. Refer to Connecting to the Media Platform in Chapter 1 – Getting Started with Desktop for Eclipse in theDesktop for Eclipse Guide for a description on how to do this.

3. Call your application by using the Call button in the Test Monitor.For further details on how to test an application using the Test Monitor refer toTest Application in Chapter 7 – Basic Commands in the Desktop for Eclipse Guide .

Media Platform SetupThere are two possible ways to set up the connection on the media platform orbrowser.

First, a direct URL connection can be used to point to the server. Second, the servercan be called through a static index file.

Desktop for Eclipse also provides a third option to directly include a media platform

into Desktop for Eclipse and to call the application from within the Test Monitor. Inthis case the application is deployed temporarily on the embedded server (see Deployan application temporarily above). This option should only be used for testingpurposes, though.

Note: In case of Web applications built with VoiceObjects, the callers usually need to

type the URL into the browser of their mobile device. To avoid lengthy URLs, setup aproxy server with a simple and intuitive URL that redirects requests to the address ofVoiceObjects Server.

Direct URL connection

In this case, the media platform uses a URL that points directly to a service hosted ona server. The connection URL should have the following format (assuming the defaultservlet context is used):

http://server:port/VoiceObjects/DialogMapping?VSN=[VSN]

where

server denotes the network name or IP address of the physicalserver running the VoiceObjects Server process. Note thatthe server machine must be accessible for the mediaplatform, which is especially important if the mediaplatform is located outside the company network. Refer toConnector URL in Chapter 1 – Advanced Configuration of

VoiceObjects in the Administration Guide for more details.




VoiceObjects 11


port denotes the connector port for the VoiceObjects Serverprocess. The port is set to 8099 (8070 when connecting to

the embedded server in Desktop for Eclipse) by default,but can be modified during installation and configuration.See the Installation Guide for details.

VSN denotes the unique VoiceObjects Service Name (VSN)that identifies the service when initiating it through anHTTP request from the media platform. Since eachservice must have a unique VSN, the media platform mustbe configured in order to map the dialed phone number tothe correct VSN. When connecting to the embeddedserver in Desktop for Eclipse the VSN has to be set totestService .

If a service with the given VSN does not exist, a static failover page will be returned.For more information, refer to Chapter 3 - Managing Servers and Services .

Note: If you deploy a service that supports multiple phone channels, you typically

define one default driver in the Service object (for a channel of your choice), and allother platforms need to include the parameter vsDriver in the initial request URL, tostart the session for that specific driver. See Service URL Configuration for moreinformation.

VoiceObjects Server also supports the mapping of DNIS (Dialed Number IdentificationService) numbers to specific services. To use a DNIS number instead of theVoiceObjects Service Name (VSN) as a mapping to the application, the DNIS must bepassed as a parameter in the URL:

http://server:port/VoiceObjects/DialogMapping?DNIS=[DNIS]

where

DNIS denotes the DNIS on which the incoming call wasreceived.

If no service can be determined for the given DNIS, a static failover page will bereturned. For more information, refer to Chapter 3 - Managing Servers and Services .

If both VSN and DNIS are specified, VSN takes precedence.

Note: Initial requests from the media platform that contain neither VSN nor DNIS will

normally be rejected by the server. This behavior is configurable, but should typicallynot be changed.

Static markup

The media platform or browser can also call the server indirectly, i.e. from a staticVoiceXML/XHTML/USSD markup file. In this case, the URL has the same format asfor a direct URL connection. In voice and video applications, the URL can be called forexample in a GOTO statement as shown in the following VoiceXML code:

<?xml version="1.0" encoding="ISO-8859-1"?>

<vxml xml:lang="de-DE" version="2.0">

<form id="frmInitial">

<block name="blkInitial">

<gotonext="http://voserver:port/VoiceObjects/DialogMapping?VSN=[VSN]" />




VoiceObjects 11


</block>

</form>

</vxml>

This setup can also be used to quickly start playing a welcome prompt to a caller whileperforming additional background tasks, or to provide a limited amount of failovercapability between different server instances. The following VoiceXML code gives anexample:


<vxml version="2.0" xml:lang="en-US">

<property name="timeout" value="3s" />

<property name="fetchtimeout" value="20s" />

<var name="ANI" expr="session.telephone.ani"/>

<var name="DNIS" expr="session.telephone.dnis"/>

<var name="submitURL" expr="'http://

vo-server:8099/VoiceObjects/DialogMapping?VSN=myservice'"/>

<var name="submitURL2" expr="'http://

backup-server:8099/VoiceObjects/DialogMapping?VSN=myservice'"/>

<catch event="exit">

<disconnect/>

</catch>

<catch event="error.badfetch">

<submit fetchaudio="http://server/resources/Jingle.wav"

expr="submitURL2" namelist="ANI DNIS"/></catch>

<form id="MAIN">

<block>

<submit fetchaudio="http://server/resources/Jingle.wav"

expr="submitURL" namelist="ANI DNIS"/>

</block>

</form>

</vxml>

As soon as the call comes into the media platform, a jingle is played. In parallel, a newdialog session is initiated on the server running on the machine “vo-server”. Should

this fail, an attempt is made to initiate this dialog session on the server running on themachine “backup-server”.

In Web applications, an XHTML page can be prepared that essentially does the samething: show some welcoming message and provide a button to start the session onVoiceObjects Server. Here is an example:


<html>

<body>

<h1>Prime Insurance</h1>

Thanks for calling our service.

<form action="http://

http://voserver:port/VoiceObjects/DialogMapping?VSN=[VSN]"

<input type="submit" value="Start" /></form>



Service DeploymentService URL Configuration

VoiceObjects 11


</body>

</html>

In text applications, the markup depends on the driver. The following is an example forthe Cellicium Cellcube 3.6 USSD browser, which also supports an immediate redirect:

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE pages SYSTEM "cellflash.dtd">

<pages>

<page backtext="notext" menutext="notext">

<redirect src="http://

http://voserver:port/VoiceObjects/DialogMapping?VSN=[VSN]" />

</page>

</pages>

The Sicap USSD Menu Browser 3.2 browser uses a small subset of HTML as itsmarkup language, so the code for that platform could look as follows:

<html><body>

Prime Insurance.<br/>

Thanks for calling our service.

<a href="http://

http://voserver:port/VoiceObjects/DialogMapping?VSN=[VSN]" />

</body>

</html>

Note: If a media platform or browser applies document caching mechanisms to

reduce response times, it might use a cached version of the document rendered bythe server in case the URL has the same form as an earlier request. To avoid this addthe parameter msec to the request URL with a unique numeric value. This parameter

is ignored by the server but prevents the media platform from using a cacheddocument if the value is different on each request.This is a mechanism that works on all possible platforms, i.e. voice or video platforms,Web and USSD browsers. The following example for voice and video applicationsshows how to use ECMAScript to generate the value from the timestamp of the serverhosting the VoiceXML file:


<vxml xml:lang="de-DE" version="2.0">

<form id="frmInitial">

<block name="blkInitial">

<goto

expr="'http://server:port/VoiceObjects/DialogMapping?VSN=[VSN ]&msec='+new Date().getTime()" />

</block>

</form>

</vxml>

Since mobile Web browsers usually do not provide embedded scripting engines,calculating a unique value for the msec parameter is not possible in XHTML for thiskind of browsers. Use a CGI script (e.g. JSP) to generate dynamic URLs in this case.The same approach would be required for USSD browsers, due to the same reasons.

Service URL ConfigurationA service is usually configured in the Service editor. In addition the service can be (re-)configured at call time by passing configuration parameters to the service in the initial

request URL. The supplementary parameters can be passed in the following way,assuming the service is called using the VSN as described in the previous paragraph:




VoiceObjects 11


http://server:port/VoiceObjects/DialogMapping?VSN=[ReferenceID]&param=value

The possible parameters are listed in the following table. All parameters are case

sensitive and start with the prefix vs for VoiceObjects Service. Variable and layervalues can also be passed; they use the var and lay prefix, respectively. Details arealso described in the following table.

The legal values for the vsDriver parameter are listed in Appendix A – Media Platform Drivers.

Service URL parameters

Parameter Description

vsAudioExtension Overrides the audio file extension specified in the

service.vsBargein Overrides the default barge-in setting specified in the

service. Possible values are true and false .

vsContentType Overrides the content type specified in the service.

vsDefaultResourcePath Overrides the default resource path specified in theservice.

vsDefaultResourceURI Overrides the default resource URL specified in theservice.

vsDialogTimeout Overrides the dialog timeout specified in the service.Value is interpreted in seconds.

vsDriver Overrides the media platform driver specified in theservice. In order to activate a specific driver its id orinternalName from the configuration file MPDrivers.xml must be provided.

vsExitType Overrides the dialog exit type specified in the service.Possible values are disconnect , exit , and return .

vsGrammarExtension Overrides the grammar file extension specified in theservice.

vsGrammarControl Overrides the grammar control setting specified in theservice. Possible values are true and false .

vsGrammarMediaType Overrides the default grammar type specified in theservice. Possible values are abnf , gsl , jsgf , srgs_xml ,regex , precompiled , and none .

vsGrammarMode Overrides the default grammar mode specified in theservice. Possible values are embedded:external andexternal:embedded .

vsInputMode Overrides the default input mode specified in theservice. Possible values are voice , dtmf , and voicedtmf .

vsLanguage Overrides the application language specified in theservice.

vsLoggingCategories Overrides the default logging categories specified in the

service. Possible values are comma-separated lists ofcategories from among info , debug , error , stats , billing .




VoiceObjects 11



vsLoggingDestination Overrides the default logging destination specified in the

service. Possible values are db (= Custom DB), file (=Log File), logOSDM (= Log OSDM), sp (= MediaPlatform), dialogContext (= System DB).

vsOutputMode Overrides the default output mode specified in theservice. Possible values are audio:tts and tts:audio .

vsProxyHost Overrides the HTTP proxy host specified in the service.

vsProxyPort Overrides the HTTP proxy port specified in the service.

vsRejectResponse Overrides the reject response specified in the service.Possible values are overflow and redirect .

vsRecordingScope Overrides the default recording scope specified in the

service. Possible values are all, noMatch, andrecognition .

vsRecordUtterances Overrides the default value of the Record utterances setting specified in the service. Possible values are true and false .

vsRespectUserAgent Overrides the value of the Respect user-agent in Web channel setting specified in the service. Possible valuesare true and false .

vsSessionVariables Overrides the default value of the Session variables setting in the service.

vsStandbyTimeout Overrides the standby timeout specified in the service.

Value is interpreted in seconds.

vsVideoExtension Overrides the video file extension specified in theservice.

varVarID Overrides the value of the specified variable.VarID must match the reference ID of the variable thatshould be overwritten with the specified value.

layLayerID Overrides the initial state of the specified layer.LayerID must match the reference ID of the layer, thedefault state of which should be overridden with thespecified state ID.

The content type of the markup returned to the media platform depends on theselected driver and is set to application/voicexml+xml in most voice and video drivers.To change this value, specify vsContentType as parameter and the required setting asthe value in the connection URL.

Variable values can be set by passing the desired value of the variable as the value,and the reference ID of the variable with the prefix var as the parameter name. E.g. toset the value of a variable with the reference ID Status to gold the followingparameter/value setting must be appended to the URL:

http://…/DialogMapping/VSN=[VSN]&varStatus=gold

In a similar way, layers can be set to a specific state by passing the ID of the desired

state as the value and the reference ID of the layer with the prefix lay as the



Service DeploymentApplication Defaults

VoiceObjects 11


parameter name. E.g. to set the state of a layer with the reference ID Persona to alice the following parameter/value setting must be appended to the URL:

http://…/DialogMapping/VSN=[VSN]&layPersona=alice Parameters that cannot be recognized by the prefixes vs , var , or lay will be assumedto be session parameters and are placed into the session context. This includes theparameters ANI, DNIS, RDNIS, MPSID, AAI, CRMID, and GCID. Their values can beretrieved or set using the SESSION() function.

Application DefaultsIn addition to passing initial values for objects in the request URL as described abovein Service URL Configuration, they can also be provided in an XML file that isreferenced within the service definition. Moreover, Variable, Collection and Layerobjects can be defined as a parameter in the Expression function

APPLYCONFIGURATION(configurationXML).Note that Resource Locator objects can only be defined through a reference in theservice definition.

See Default Parameters in Chapter 2 – Configuring Servers and Services for moreinformation on how to specify the location of this file in a Service object.

Tip: Passing parameters through the initial request URL should be done for all those

parameters that are platform-specific, since the request URL is set on the mediaplatform. All those parameters that are application-specific should be defined using theXML file. Note that if an object is defined both in the request URL and in an applicationdefaults file, the request URL takes precedence.

Application defaults are defined using an XML notation. The corresponding XSD filefor validation can be found at

...\VoiceObjects\Platform\WEB-INF\schemas\ApplicationConfiguration.xsd

The following code provides a sample configuration:

<?xml version="1.0" encoding="UTF-8"?>

<configurations>

<configuration>

<referenceID>minimumAge</referenceID>

<type>variable</type>

<value>18</value>

</configuration>

<configuration>

<referenceID>location</referenceID>

<valuePath>C:\</valuePath>

<valueURL>http://dataserver/</valueURL>

</configuration>

</configurations>

The entire set of application defaults must be enclosed within a <configurations> element; each individual value assignment must be enclosed within a

<configuration> element.





Service DeploymentConnection Test

VoiceObjects 11


The behavior in all cases and in call channels is defined by static markup files that aresent to the media platform. The behavior can be modified by adjusting these files,which can be found under

..\VoiceObjects\Platform\Resources\System\VXML\<LanguageCode>\dialogs\VXML\< VoiceXML version>\<Media Platform Provider>\<ProductVersion>\

with the names Disconnect.vxml , Return.vxml , and Exit.vxml .

While they are originally motivated for VoiceXML-based platforms only, they can alsobe defined in the text and Web channel. The names and extension (.vxml) are thesame, though.

Note: This mechanism of using external files is only applied when the dialog finishes

because there are no more objects to process or in error cases if there is no errorhandler defined. It is not applied in case the dialog finishes with an Exit object.

Connection TestAfter completing the configuration of the service and setting up connectivity betweenthe media platform and the server, the availability of the server, server instances, andservices can be tested. To do this, the following URLs must be loaded e.g. in a Webbrowser:

http://server:port/VoiceObjects/DialogMapping?ping=server

tests the availability of the server. If a server is available at the specified URL, itsreference ID is returned.

http://server:port/VoiceObjects/DialogMapping?ping=instance

tests the availability of a specific server instance. If an instance is available at thespecified URL, it returns its current status:

Value Description

STARTED The server instance is started and ready to serverequests.

REQUEST_IDLE The server instance does not accept any new sessionsbut is still processing currently active sessions.

IDLED The server instance is idled and does not accept anynew sessions.

STOPPED The server instance is stopped and does not accept anynew sessions.

http://server:port/VoiceObjects/DialogMapping?VSN=[ReferenceID]&ping=server

tests the availability of a specific service on the server. Depending on the status of theservice, the following values are returned:

Value Description



Service DeploymentDebug Viewer

VoiceObjects 11


Value Description

UNAVAILABLE The service is not available, or no service matches theVSN. This may also indicate that the entire server isstopped.

STARTING The service is currently starting.

STARTED The service is started and ready to serve requests.

REQUEST_IDLE The service does not accept any new sessions but is stillprocessing the currently active sessions.

IDLE The service is idled and does not accept any newsessions.

STOPPING The service is stopping and aborting all currently activesessions.

STOPPED The service is stopped and does not accept any newsessions.

Note that in a cluster setup, a service can be in status STARTED yet still not beavailable on certain server instances since these instances are idled or stopped. Tocheck this, there is the command

http://server:port/VoiceObjects/DialogMapping?VSN=[VSN]&ping=instance

which tests the availability of a specific service on a specific server instance. Theresult is of the form <Instance status>:<Service status>.So e.g. in a cluster setup with three instances one of which is idled and the others

started, a service that is started on the cluster would produce STARTED:STARTED onthe started instances and IDLED:STARTED on the idled instance.

The connection test functionality can be used in combination with a load balancersetup to repeatedly check whether a server running on a specific machine stillresponds appropriately.

The list of hosts that are allowed to issue ping requests can be restricted using the

<pingIPFilter>*</pingIPFilter>

setting in the VOServer_Configuration.xml file. The default setting is “*”, whichindicates that any host may issue ping requests. It may be set to a comma-separatedlist of IP addresses or host names, which indicates that only these hosts may issueping requests. Finally, if left empty then no ping requests are allowed at all.

Caution: Note that the old connection test syntax

http://server:port/VoiceObjects/DialogMapping?ping=true

is deprecated.

Debug ViewerSometimes it is desirable to test application functionality without having access to amedia platform. This can be accomplished by using the Debug Viewer. It is a codeviewer that shows the rendered markup for each dialog step and offers ways for the

tester to interact with the application. In the voice and video channel, the code is




VoiceObjects 11


VoiceXML. In the text channel, it is proprietary markup code used by thecorresponding platform vendor, whereas in the Web channel it is HTML.

Start a Debug Viewer session

The Debug Viewer is initiated by appending the setting mode=Debug to the initialrequest URL, which must be called in a Web browser:

http://server:port/VoiceObjects/DialogMapping?VSN=[ReferenceID]&mode=Debug

When using a connector URL (e.g. in case the server is behind a firewall), theexternally visible address may not be usable for internal testing. For these cases it ispossible to specify a separate address for the debug mode. This is defined using theparameter address in the initial request URL, e.g.

http://…/DialogMapping?VSN=[ReferenceID]&mode=Debug&address=127.0.0.1

All references to the normal server address are replaced by the specified alternativeaddress. All other functionality remains as described above. In addition to the IPaddress, it is also possible to modify the port by using the notation

http://…/DialogMapping?VSN=[ReferenceID]&mode=Debug&address=127.0.0.1:8097

Note that a Debug Viewer session can also be directly started from within the ControlCenter using the entry Debug Viewer in a service’s context menu. This entry is onlyavailable for started services.

When starting a Debug Viewer session from the Control Center, a dialog box comesup to enter the testing URL to be used for the session. This allows you for example toconnect to different server instances within a cluster.

By default, this dialog box contains the testing URL configured in the preferences ofthis Control Center connection. In Desktop for Web the dialog box contains the testingURL configured in the Server object.

Internally the string DebugviewInfo, the name of the corresponding servlet, isautomatically added to the testing URL.

After an IP address and port have been confirmed by clicking OK, the Debug ViewerConfiguration window is shown.




VoiceObjects 11


In the Parameter(s) field, you may enter additional parameters to be passed to theapplication, as described in the section on Service URL Configuration. In addition,various parameters such as ANI, DNIS, etc. may be set. The exact list of parametersdepends on the media platform that is used. For most of these parameters, default

values are provided.To start the dialog, click the Start Session button. The reply from the server is shownas follows:

The Debug Viewer shows the markup code generated by the server, color-coded andenhanced for HTML display. Blocks of markup code may be expanded and collapsedusing the plus [+] and minus [-] buttons. In the voice and video channel, the bottom ofthe VoiceXML code is displayed first for each dialog step, since this is where theprompts of this step are typically located. Use the scroll bar to move the code up and

down, and use the two buttons and to jump to the top or bottom of the code.

Some links in the rendered code are color-coded and clickable. Three different types

of active links are available:




VoiceObjects 11


Audio files are displayed in red font and can be played in the operating system’sdefault media player by clicking them.

Grammar files are displayed in blue font and can be viewed in a pop-up window byclicking them.

Requests that go back to the server are displayed in black font and can be activatedby clicking them.

How to step through a dialog session

To step through a dialog, either click the black-colored links that lead back to theserver, or use the Next Step > button at the top. Additional parameters that you wantto include in a request to the server during a dialog session can be added manually inthe Parameter(s ) text field, if required.When using the Debug Viewer, do not use the Web browser’s navigation buttons(such as Back), because this will interfere with the navigation logic maintained on theserver.If you want to end a call, click the Hang up button. The last markup page is thenrendered, and you can close the window by clicking Close. If you close the Debug

Viewer window without hanging up first (using the Close icon on the tab header),




VoiceObjects 11


the dialog session will remain as an active session on the server until it runs into thedialog timeout.

Hyperlinks in the voice and video channel that lead back to the server can beactivated by clicking the black-colored <submit> element associated with a green-colored <link> element.

How to navigate through and interact with an application depends on the object type ofthe current dialog step.

The following sections describe the interaction with voice and video applicationsthrough VoiceXML. In the text and Web channel, corresponding code is shown thatalso allows interacting with the application.

Output objects

Output objects do not gather any caller input; therefore you can skip them by clicking

Next Step >.




VoiceObjects 11


Input objects

For Input objects that need to fill slots, input fields are generated below the

Parameter(s) field, one for each slot:

To fill the slots, type in the slot values in the format provided by the grammar. Notethat you cannot enter real caller utterances in these fields, as there is no parsing of thegrammar taking place in the server. Only slot values (i.e. the semantic interpretation )as needed by the Input object are allowed. In a multi-slot example like the above oneyou can leave out a slot if you want to simulate that only one of several slots has beenfilled by the caller. If you want to simulate a No Input event in order to auto-advance tothe next dialog step, do not click Next Step > with empty slots, but instead click theblack-colored <submit> element nested in a <catch event="noinput"> eventhandler element.

Menu objects

For Menu objects, the server generates <choice> elements that represent the Menuitems. To select a Menu item, identify the correct <choice> element by looking at thegrammar of that <choice>, and click the black-colored <submit> element locateddirectly above the <choice>.

Confirmation objects

The Confirmation object allows confirming or denying a summary of gathered inputitems. To confirm, click the <submit> element nested in the <catchevent=”summary.yes”> element at the bottom of the VoiceXML code. To deny, clickthe <submit> element nested in the <catch event=”summary.no”> element.

List objects

The List object allows navigating through a list of items. If you want to use a specificnavigation command, enter the required slot value (like nextRow , start , etc.) in theinput field called sltNavigation located right below the Parameter(s) field. If you wantto simulate a No Input event in order to auto-advance to the next item, click the<submit> element nested in the <catch count="1" event="noinput">.

Pause objects

If the Pause object does not have a redirect object defined, leave the Pause object byclicking Next Step >. If a redirect object is defined, click the <submit> element nestedin the <catch event=”noinput”> element with the highest count attribute value,located at the bottom of the VoiceXML code. This value corresponds to the number of

reiterations defined in the Pause object, plus 1.




VoiceObjects 11


Connector and Script objects

In case a wait loop audio is played while the server is processing a Connector orScript object, simply jump to the next dialog step by clicking Next Step >.

Plug-In objects

Fill any parameters required for a plug-in in the Parameter(s) field and click NextStep >.

Recording objects

Real recordings cannot be simulated with the Debug Viewer. To simply skip aRecording object, click Next Step >.

Transfer objectsBlind transfers will not lead back to the application, instead the platform activates adisconnect.transfer event which will be caught by the server to terminate the dialogsession. To simulate a blind transfer, click the black-colored <submit> element belowthe <catch count="1" event="connection.disconnect.transfer"> eventhandler which is typically located right above the <transfer> element

Note: If you click Next Step > for a blind transfer, the application continues, which is

not the behavior you would get when calling through a media platform.

Bridged transfers do lead back to the application, so simply click Next Step > tosimulate a completed transfer.

Exit objects

If an output is defined inside the Exit object, first click Next Step > to leave this dialogstep. The Exit object always terminates the session on the server, so the VoiceXMLcode produced by the Exit object is the last dialog step for an application.

OSDM objects

When using the Debug Viewer in combination with OSDMs, embedded grammardefinitions that are passed to the OSDMs in variables cannot be displayed correctlywithin the Debug Viewer due to the use of masked XML characters. So even thoughthey may look strange in the Debug Viewer output, they are passed correctly into theOSDMs.

Furthermore, if a Variable or Script object as part of an Output object holds XMLcontent that has the structure of a collection (<root> as the top-level element, with

<row> and <col> children), it will be read out cell by cell. In the Debug Viewer youwill therefore not see the XML structure, but only the text content of the cells. If theXML is of a different structure, the content is fully retained. Note that in this case, thedisplay in the Debug Viewer might be broken if the content holds an XML header (i.e.an XML processing instruction).



Service DeploymentPhone Simulator

VoiceObjects 11


Phone SimulatorThe Phone Simulator is a graphical tool to simulate calls in the text and Webchannels. It can be used to test and demo applications in the text channel when noUSSD gateway is available. While the Web channel can easily be tested directlythrough a browser, Web sessions can also be simulated using this tool. The PhoneSimulator shows an image of a mobile phone (offering three different skins) and allowsthe navigation within an application by entering text or activating hyperlinks.

Start a Phone Simulator session

The Phone Simulator is launched externally by calling the PhoneSimulator servlet in aWeb browser:

http://server:port/VoiceObjects/PhoneSimulator?VSN=[ReferenceID]

When using a connector URL (e.g. in case the server is behind a firewall), theexternally visible address may not be usable for internal testing. In this case it ispossible to specify a separate address for the Phone Simulator. This is defined usingthe parameter address in the initial request URL, e.g.

http://…/PhoneSimulator?VSN=[ReferenceID]&address=127.0.0.1

All references to the normal server address are replaced by the specified alternativeaddress. All other functionality remains the same. In addition to the IP address, it isalso possible to modify the port by using the notation

http://…/PhoneSimulator?VSN=[ReferenceID]&address=127.0.0.1:8097

In addition, the following four parameters can be added to the external request. They

will make the configuration page preset the corresponding settings.


phoneSimSkinThe desired phone style. This can be one of thethree values standard , blackberry , or iphone .

phoneSimHeaderA Boolean parameter with values true (the default)and false . If set to true , the session information willbe shown; if set to false , it will not.

phoneSimChannelThe desired phone channel. This can be text (the

default) or web .

phoneSimCharLimitThe desired character limit. The default is 182. If thevalue is not a number or <1, it is set to 182.

A full URL could look like this:

http://localhost:8099/VoiceObjects/PhoneSimulator?VSN=abc&phoneSimSkin=iphone &phoneSimHeader=false&phoneSimChannel=text&phoneSimCharLimit=91

If all four parameters are set, the configuration page is skipped and the dialog isstarted right away.

Note that a Phone Simulator session can also be directly started from within the

Control Center using the entry Phone Simulator in a service’s context menu. This




VoiceObjects 11


entry is only available for started services. From the upcoming submenu, select thechannel you want to test, Text or Web.

When starting a Phone Simulator session from the Control Center, a dialog boxcomes up that asks for the testing URL to be used for the session. This allows you forexample to connect to different server instances within a cluster.

By default, this dialog box contains the testing URL configured in the preferences ofthis Control Center connection. In Desktop for Web the dialog box contains the testingURL configured in the Server object.

Internally the string PhoneSimulator, the name of the corresponding servlet, isautomatically added to the testing URL.

After an IP address and port have been confirmed by clicking OK, the PhoneSimulator Configuration window is shown.

To specify the skin, i.e. the image of the phone used during a session, select one ofthree available skins from the Skin field.

In the Character limit field, specify the character limit to be applied during thesession. This can be used in the text channel, to verify whether an output exceeds theallowed number of characters. The default is 182 in non-Unicode USSD deployments.The number of characters is displayed during the session. If an output hits the limit,the number is displayed with red color, otherwise black.Use the checkbox Show session information during dialog to toggle an info boxduring a session that shows the following call time details: step number, processingtime, current module name, driver, language, and characters used in output.

Navigate in the Phone Simulator

To start the dialog, click the Start Session button in the Phone SimulatorConfiguration window.




VoiceObjects 11


The server opens up the Phone Simulator, showing the information box if selected andthe image of the selected phone, and starts the session.

In the text channel, navigation within a session works as follows:

• To reply to a system prompt, first click Reply, either by clicking the link directly, orby clicking the button on the phone right below the link.

• Enter the response by either using the keyboard, or the phone buttons. Whenclicking a phone button once, the number character is printed on the screen. Toget the other available characters on a button, point the mouse to the button, waitfor the tool tip to appear, and click the desired character to print it on the screen.

• Send your response by clicking the Send link or the corresponding phone button.

In the Web channel, navigation within a session works as follows:

• To select a hyperlink, radio button, or drop-down entry, simply click it.

• To fill in an input field, enter the text by either using the keyboard or the phonebuttons. When clicking a phone button once, the number character is printed onthe screen. To get the other available characters on a button, point the mouse tothe button, wait for the tool tip to appear, and click the desired character to print iton the screen.

• Send your response by clicking the proceed button.

To end a call, press the red button on the phone. The VoiceObjects logo appears. Toclose the entire window, press the red button again. To restart the session with the

same settings as before, press the green button on the phone.




VoiceObjects 11


Note: Font sizes and input fields in the Web channel most likely appear larger in the

Phone Simulator than on a real phone. This is due to a technical restriction related to

the CSS file used (default.css if no custom file is defined) and can only be changed bymanually adjusting the sizes and widths inside the style sheet definition. For demopurposes, a customized CSS file should therefore be deployed, which is optimized foruse with the Phone Simulator.



Logging and TracingServer Logs

VoiceObjects 11


5 Logging and Tracing

The Control Center provides access to detailed log information both on the level of the server as wellas on the level of each individual service.

In addition, sophisticated session tracing capabilities are provided to support designers in analyzingand debugging applications.

Server LogsThe Server Logs tab provides access to the server log files, for both single server andcluster server setups. Server Administrators and Server Controllers have access tothis tab for all servers. Site Administrators and Site Controllers have access to it forservers from within their own site. For more information on user roles and their

privileges refer to Chapter 2 – User Management – Basic Topics in the Administration Guide .

The different server instances are identified by their name (if defined) or by their IPaddress and port, shown in the Server Instance column.

To open a log file double-click it or right-click it and select View from its context menu(note that this is only available on non-empty log files). The log file is then opened as anew tab in the editor area of Desktop for Eclipse.



Logging and TracingService Logs

VoiceObjects 11


Using the Filter field at the top you can restrict the list of log files to those that containa certain text string within their name, or that have a name starting with a certain textstring (when selecting the Starts with check box).

In Desktop for Web a separate box is shown for each server instance. Log files can beviewed (up to a maximum size of 1 MB), or downloaded (both only possible on non-empty log files). To view a log file, click its name. It will be displayed in a new window.To download a log file, click the Download button to the right of the log file name.

Note: When log files are viewed in a browser window, note that character entities are

unmasked. As an example, a & in the log file will show up as &.

Note: To ensure that log file viewing and downloading works in cluster environments,

it is required that the correct mapping between IP addresses and host names isavailable for the machines that are involved in the cluster. In Unix environments, thismay require the correct setup of host tables.

Service LogsThe Service Logs tab provides access to the log files for all services, for both singleserver and cluster server setups. It is accessible to all users who may access theControl Center. Only log files for those services listed on the Server Manager tab areshown, which may be a subset of the total list of services hosted on this server. Formore information on user roles and their privileges refer to Chapter 2 – User Management – Basic Topics in the Administration Guide .


To open a log file double-click it or right-click it and select View from its context menu(note that this is only available on non-empty log files). The log file is then opened as a

new tab in the editor area of Desktop for Eclipse.

Each service has two associated log files named VSN_service.log and VSN_error.log (where VSN stands for the VoiceObjects Service Name of the respective service).The VSN_service.log file contains messages written by the Log object with destinationFile . The VSN_error.log file contains all error messages related to this service. Theseerror messages are additionally shown in the server log files.


In Desktop for Web a separate box is shown for each server instance. Log files can beviewed (up to a maximum size of 1 MB), or downloaded (both only possible on non-

empty log files). To view a log file, click its name. It will be displayed in a new window.To download a log file, click the Download button to the right of the log file name.



Logging and TracingSession Tracing

VoiceObjects 11


Session TracingThe Session Tracing tab provides access to the server trace files, for both singleserver and cluster server setups. It is accessible to all users who are allowed toaccess the Control Center. Only trace files for those services listed on the ServerManager tab are shown, which may be a subset of the total list of services hosted onthis server. For more information on user roles and their privileges refer to Chapter 2 – User Management – Basic Topics in the Administration Guide .


To open a trace file double-click it or right-click it and select View from its contextmenu (note that this is only available on non-empty log files). The Trace Viewershowing the content of the trace file is then opened as a new tab in the editor area ofDesktop for Eclipse.To delete trace files, select the appropriate file entries, right-click on one of them andselect the Delete entry from the context menu. This opens up a confirmation window,and if confirmed deletes the selected trace files. It is strongly recommended to deletetrace files when they are no longer required in order to keep the list manageable.

The list of trace files is ordered by time of file creation, with the newest file at the top ofthe list. Trace files can be viewed while the corresponding call is still going on, or atany time after the call has finished.


Session tracing can be enabled and disabled individually for each service and list ofANIs. The section on the Server Management in Chapter 3 – Managing Servers and Services provides more details.

Note: By default, tracing is disabled on all services after the server is reset. This can

be changed by using the setting<enableTracingByDefault>true</enableTracingByDefault> incomponents_VOServer.xml .It is strongly recommended to not change this setting in production installations due tothe amount of data that can get generated.

In Desktop for Web a separate box is shown for each server instance. In total amaximum of 1,000 trace files is shown. To view a file, click its name. This opens theTrace Viewer in a new window. To delete trace files, select the appropriate checkboxes and click the Delete button. This opens up a confirmation window, and ifconfirmed deletes the selected trace files. All files can be selected or de-selected at

once by using the extra check boxes at the top and bottom of the list. It is strongly



Logging and TracingTrace Viewer

VoiceObjects 11


recommended to delete trace files when they are no longer required in order to keepthe list manageable.

Refer to the Trace Viewer paragraph below for detailed information on the TraceViewer.

Trace ViewerThe Trace Viewer is used to display the content of a trace file.

It displays general session information at the top of the window:the name of the server that processed the session, the VoiceObjects Service Name(VSN), the media platform driver that was used, the ANI of the caller, and the internaldialog ID assigned to the session.






VoiceObjects 11


particular that for each dialog step, there is a block of markup code that was sent fromthe server to the media platform. This block of markup code is part of the tracing dataavailable for each dialog step. Note that a dialog step may contain multiple dialogobjects since not all of them actually generate markup code. Objects such asExpression for example are evaluated internally within the server. Other objects suchas Input or Menu on the other hand generate markup code that needs to be sent tothe media platform for interaction with the caller.

The Processed objects column shows the icons for all objects that were processedduring this dialog step. Their names are provided as tooltips.

The Last processed object column provides the name of the last object that wasprocessed in this dialog step. This is the object that created the markup code sent tothe media platform for this dialog step.

The Processing column shows the time (in milliseconds) the server needed toprocess the entire dialog step.

The Dialog column shows the accumulated elapsed time for the entire dialog.

Individual dialog steps can be expanded using the Maximize button to reveal thedetailed sequence of objects that were processed internally by the server during thisdialog step. Additional information about each object can be obtained by expandingthe object itself. By clicking the object icons it is also possible to immediately open upthe corresponding object editor, provided that the project from which the objects comeis currently open in VoiceObjects Desktop.

In addition to the individual objects processed during the dialog step, the markup codethat was sent to the media platform is also available under the heading RenderingOutput.




VoiceObjects 11


The Trace Viewer can be used after a session has been completed, as well as duringongoing sessions. In this case, use the Refresh button (currently only available inDesktop for Web) at the top of the Trace Viewer window to refresh the contentperiodically as the session progresses.

Additional settings sent as part of the initial request URL, or parameter values sent by

the media platform (such as slot values) can be found within the Session Information sections:




VoiceObjects 11


The example above shows an initial request URL. In addition to the standardparameters such as ANI, DNIS, etc. two variables were set to initial values: Thevariable with reference ID drink was set to the value tea , and the variable withreference ID food was set to cake .

Caution: Session tracing is intended to be used during development. As it impacts theperformance of VoiceObjects Server, it is strongly recommended to keep sessiontracing disabled in production environments or in any case at least to restrict the list ofANIs to one or two. For information on how to do this, refer to Server Management inChapter 3 – Managing Servers and Services .

For the exceptional case that tracing is enabled in a production environment it isrecommended to configure the operating system such that the trace folder is cleanedon a regular basis to avoid problems with disk space being filled up.

Note: Session tracing can be disabled completely in order to protect sensitive data.

For details, refer to Chapter 1 – Advanced Configuration of VoiceObjects in theAdministration Guide .



Recording of UtterancesIntroducing Utterance Recording

VoiceObjects 11


6 Recording of Utterances

VoiceObjects allows storing recordings of utterances made by the caller during normal speechrecognition, e.g. in Input or Menu objects. This includes utterances that lead to successful recognitions(filling a slot in an Input object, selecting a Menu item, activating hyperlinks etc.), as well as those thattrigger a No Match event on the media platform.

This chapter explains how this feature is set up and made use of in a voice application. It starts withIntroducing Utterance Recording showing up some use cases and explaining how to quick start thisfeature.

The remainder of the chapter describes the full range of the utterance recording feature:

• Setting up Utterance Recording for a Serviceexplains how to configure utterance recording in your installation, on server, site and service

level.• Defining What to Record

describes how you define on dialog object level which recordings are to be stored.

• How the Recordings are Storedexplains the folder and file name structure of stored recordings, so you can easily find therecordings you are looking for.

• Collected Data in Infostore describes what kind of data about recorded utterances is stored inInfostore. Refer to the Analyzer Guide for a detailed description of reports available to analyzecaller behavior through the recordings.

• Example Setupsprovides a step-by-step description of sample configurations, which helps you in setting up

utterance recording for your specific needs.

Introducing Utterance Recording

Use cases

Being able to listen to what a caller said at specific points in a voice applicationprovides valuable insight into the usage of the application. It can show issues withgrammar definitions, with misleading prompts, even with ill-designed menu or dialogflow structures in your application. Evaluating caller utterances is an essential part intuning a voice application and assessing its overall functionality, i.e. making sure thatit does what it is supposed to do.

A typical use case of analyzing the usage of an application is to look at input statesthat produce a significantly high number of No Match events. Listening to therecordings immediately tells you about bad grammar or prompt design.But analyzing successful recognitions can also be worthwhile. An utterance string canonly consist of tokens found in the grammar activated for a specific dialog step. E.g., ifa grammar allows saying “yes” only, but the caller says “yes please”, it might happenthat the recognizer matches this to “yes” and returns a confidence value above theconfidence level (the threshold for successful recognition). In this case, the utterancestring found in Infostore is “yes” and the confidence value suggests a successfulrecognition. This might lead to the assumption that the grammar is fine and does notneed any change or refinement, whereas in fact it falls short of the actual usage of theapplication by the callers. By exploiting the utterance recording feature of

VoiceObjects, you can easily detect input states that cause problems and listen to theuser interaction that took place.





Recording of UtterancesSetting up Utterance Recording for a Service

VoiceObjects 11


<utteranceRecordingBasePath>C:\VoiceObjects\Platform\Resources\<uttera

nceRecordingBasePath>

In addition to the physical path, a base URL can be defined in the element<utteranceRecordingBaseURL>. It will be used by VoiceObjects Analyzer to locatethe files through its web interface, so that a report can allow listening to the recordingsby simply clicking a hyperlink. To be able to retrieve the files, a web server must besetup to deliver them.

A setting pointing to a web server could look like this:

<utteranceRecordingBaseURL>http://myserver.com/Resources/<utteranceRec

ordingBaseURL>

Besides the definition of the base path and URL at server level, additional path andURL settings can be made for a site (in a User object), and in the Service object.For more information on how and where recordings are stored, and on how thesepaths are connected, see the paragraph How the Recordings are Stored below.

Full duplex call recording

For selected media platforms it is possible to control full duplex call recording incombination with utterance recording. This is currently supported for all Voxeo driversas well as for VoiceGenie 7.2 and Genesys Voice Platform 8.0. Linking call recordingto utterance recording ensures that the same coverage filter is used in both cases.

Full duplex call recording is enabled by the following switch in thecomponents_VOServer.xml file located in the Platform\WEB-INF\config directory ofyour VoiceObjects installation:

<enableCallRecordingLink>true</enableCallRecordingLink>

When enabled, each call that uses utterance recording automatically creates a fullduplex call recording. For details on where the call recording files are stored, refer tothe documentation of your media platform.

User object definition

If your installation is working with sites, you can define a base path for utterancerecordings that gets prefixed to the path definitions of all services in a site (and is itselfprefixed by the base path defined in the Server configuration file definition, if given).This base path is set in the User object of the root Site Administrator.

At the same place, you can define a base URL as described above.

VoiceObjects Desktop

In the Site Settings in the Security section of the User object, enter the path in theUtterance recording path field and the URL in the Utterance recording URL field:




VoiceObjects 11


Setting a path or URL is not required, if the server configuration file defines one. Formore information on how and where recordings are stored, see the paragraph How

the Recordings are Stored below.

VoiceObjectsXML

In the <user> element, use the attributes utteranceRecordingPath andutteranceRecordingURL to define the base path and URL, respectively. The default forboth is the empty string.

Server object definition

The Server object allows controlling if recordings of utterances are generally allowedor not.


In the Configuration Parameters section of the Server object, select the check boxEnable utterance recording to enable utterance recording. It is selected by default.




VoiceObjects 11


If you want to switch off utterance recording globally for all services hosted on thatserver, clear this check box.

Any change made to this setting is only activated after resetting the server. To do this,click Reset in the context menu of the logical server in the Control Center (note thatthis will terminate all current dialog sessions running on that server).

In Desktop for Web the current setting of Enable utterance recording is displayed inthe info box of a server in the Control Center. It can be either Enabled or Disabled .

VoiceObjectsXML

In the <server> element, use the attribute enableUtteranceRecording to controlutterance recording on server level. It can take the values true or false . The default istrue .

Service object definition

The Service object offers options to switch utterance recording on and off, define abase path to store the recordings in, set a coverage filter to restrict the number of




VoiceObjects 11


recordings made, and set initial values for the two dialog context settingsRECORDUTTERANCES and RECORDINGSCOPE.


In the Logging Parameters section of the Service object there are four settings thatcontrol utterance recording on service level:

The check box Enable utterance recording controls if recordings of utterances aregenerally allowed for this service, or not. It is clear by default, so that utterancerecording is not automatically turned on for new services. Note that this setting can beoverridden by the server. If the corresponding setting on the Server object is disabled,the service setting is overridden. If the setting on the Server object is enabled, theService object can decide to enable or disable it.

The text field Utterance recording path allows defining a path that gets prefixed to allstored recordings. You can leave this field empty, if the site and/or server settingsprovide paths. For more information on how and where recordings are stored, see theparagraph How the Recordings are Stored below.

The text field Utterance recording URL allows defining a URL that gets prefixed to allstored recordings within reports generated by VoiceObjects Analyzer, which offers to




VoiceObjects 11


listen to the recordings from within a report. You can leave this field empty, if the siteand/or server settings provide URLs. For more information on how and whererecordings are stored, see the paragraph How the Recordings are Stored below.

The Coverage filter is used to restrict the amount of stored recordings, which can getquite high in high-call-volume deployments. It is a percentage filter that is appliedacross all dialog sessions for a given service. If it is left at 100%, the default value,then all calls are eligible for utterance recording. A value of 0% has the same effect asdeselecting Enable utterance recording. Any other value will affect the givenpercentage of calls.

The coverage filter for utterance recording is closely related to the coverage filter forSystem DB logging, to support the scenario described in the paragraph on Use casesabove. Listening to caller utterances is typically connected to looking at the recognitionresults, i.e. utterance strings, confidence values, the context of where the utterancewas made, etc. This means that for all recordings stored, you want to havecorresponding entries in the input state-related tables of Infostore. This is ensured bythe server in the following way:

• If the option Enable Input State logging is selected, then the utterance recordingcoverage filter is applied after the System DB logging filter. This means that theserver first applies the System DB logging filter to arrive at a subset of all calls,and then applies the utterance recording filter on that subset. The result of this isthat for all recordings stored, there will be corresponding Infostore data.

• If the option Enable Input State logging is not selected, then the utterancerecording filter is applied on its own, i.e. irrespective of the System DB loggingfilter. In that case, Infostore does not log any input state-related information, so arelation from the recordings to any other information from Infostore cannot beestablished anymore. As an example, if the filter is set to 50%, half of all calls are

eligible for utterance recording.

Note: The evaluation of Enable Input State logging actually relies on the option

being selected or not. It does not rely on whether Input State logging is currently activefor a session or not. So, if the option is selected, which means you actually intend toenable Input State logging, then even if some runtime problem prevents Input Statelogging (for instance due to DB failure), the two coverage filters are applied one afterthe other nonetheless. This avoids the effect in high-call-volume applications that dueto a DB problem the amount of utterances recorded suddenly drastically increases(which would be the case if the filters were interpreted independently from each otheragain).

See some more examples on this in the paragraph Example Setups below.

In Desktop for Web the current setting of Enable utterance recording is displayed inthe info box of a service in the Control Center. It can be Enabled , Disabled orOverridden . The Coverage filter percentage value is shown in parentheses behindthat:




VoiceObjects 11


In the Default Parameters section of a Service object there are two settings that can

control on object level if utterances should be recorded, and which utterances:

The setting Record utterances defines the initial value of the corresponding dialogcontext setting RECORDUTTERANCES, which will be applied on a dialog object if ithas its Record utterances property set to Default . It can either be True or False . Thissetting can be overridden by the service URL parameter vsRecordUtterances . SeeDefining What to Record for more information on turning on recording for individualdialog objects.

The setting Recording scope defines the initial value of the corresponding dialogcontext setting RECORDINGSCOPE, which will be applied on a dialog object if it hasits Recording scope property set to Default . It can be one of Recognition , No Match ,or All . This setting can be overridden by the service URL parametervsRecordingScope . Again, the paragraph Defining What to Record describes in moredetail how recording works on individual dialog objects.



Recording of UtterancesDefining What to Record

VoiceObjects 11


VoiceObjectsXML

In the <service> element, the following attributes can be used:

Attribute Values Default

enableUtteranceRecording true, false false

recordUtterances true, false true

recordingScope noMatch, recognition, all all

utteranceRecordingPath CDATA

utteranceRecordingURL CDATA

recordingCoverage 0 - 1.0 1.0

Defining What to RecordWhile you can control on server and service level if utterance recording is generallyallowed or not, it is up to the developer of an individual application to define whichutterances in which dialog objects should be recorded.

The following dialog objects that interact with the caller offer settings to switch onutterance recording:

• Input

• Menu

• Confirmation

• List

• Hyperlink (the autonomous object in the confirmed version, not the embeddedobject)

• Pause

These objects have two properties in their respective Options section, Recordutterances and Recording scope (Example taken from Input object):

The property Record utterances defines whether utterances should be recorded forthis object or not. It can have one of the four values True , False , Always , and Default (the default). The meaning of these values is as follows:




VoiceObjects 11


Record utterances Description

True

Utterances made while processing this dialog object willalways be recorded if utterance recording is enabled for theservice and the dialog is eligible for utterance recording onthe basis of the Coverage filter.

False No utterances are recorded for this dialog object.

Always

Utterances made while processing this dialog object willalways be recorded if utterance recording is enabled for theservice regardless of whether the dialog is eligible forutterance recording on the basis of the Coverage filter ornot.This option is very useful if you want to apply a Coverage

filter to limit the amount of statistical data, but needrecordings in a few specific objects for all calls e.g. forsecurity purposes or for subsequent processing.

Default

The value of the dialog context settingRECORDUTTERANCES is taken (True or False ). Theinitial value of this setting can be defined in the Serviceobject or through the service URL parametervsRecordUtterances ; at call time, the value can be changedusing the RECORDUTTERANCES function through anExpression object.

See Example Setups for examples of how to define time-dependent utterancerecording by using this dialog context setting.The Record utterances property can also be defined dynamically at call time bylinking a Script, Variable, Expression, or Layer object.

The property Recording scope defines in which scope utterances should be recordedin this object. It can be set to one of Recognition , No Match , All , or Default . Themeaning of these values is as follows:

Recording Scope Description

Recognition

All utterances that led to a successful recognition arerecorded and stored, i.e., utterances that filled slots in anInput object, selected a Menu item, confirmed or denied asummary in a Confirmation object, navigated in a Listobject, etc. Activating hyperlinks also falls into this category.

No Match All utterances that triggered a No Match event are recordedand stored, and no others.

All All utterances made by the caller are recorded and stored.

Default

The value of the dialog context settingRECORDINGSCOPE is taken (recognition , noMatch , orall ). The initial value of this setting can be defined in theService object or through the service URL parameter

vsRecordingScope ; at call time, the value can be changedusing the RECORDINGSCOPE function through an




VoiceObjects 11


Recording Scope Description

Expression object. See Example Setups for examples of

how to define time-dependent utterance recording by usingthis dialog context setting.

The Recording scope property can also be defined dynamically at call time by linkinga Script, Variable, Expression, or Layer object.

Plug-in object

In a Plug-in object, utterance recording works automatically for all inherited No Matchevents, for inherited custom and standard navigation as well as for the last successfulrecognition that happened within the plug-in. In addition, you can write VoiceXML codethat manually submits recordings to the server to get stored.

If you want to store the recording of a No Match utterance, put the following code inthe corresponding <catch> element, before any other code of that handler:

<script>

<![CDATA[countForUtteranceRec( 'nomatch' );]]>

</script>

<assign name="savebinaryonly" expr="’true’"/>

<assign name="uttRecSample"

expr="application.lastresult$.recording"/>

<data name="reco" method="post" srcexpr="returnURL" maxage="0s"

enctype="multipart/form-data" namelist="dialogID

shadow recType uttRecSample"/>

If you want to store the recording of a recognized utterance, put the following code inthe place where the recognition is handled (e.g. in the <filled> section of a field/form),before any other code:

<script>

<![CDATA[countForUtteranceRec( 'filled' );]]>

</script>

<assign name="savebinaryonly" expr="’true’"/>

<assign name="uttRecSample"

expr="application.lastresult$.recording"/>

<data name="reco" method="post" srcexpr="returnURL" maxage="0s"

enctype="multipart/form-data" namelist="dialogID

shadow recType uttRecSample"/>

The <data> element submits the recording to the server without leaving theprocessing context, i.e., processing continues with the next VoiceXML statement afterthe recording has been sent. The variables savebinaryonly , uttRecSample , returnURL dialogID , and shadow are automatically declared by the server, so you don’t need todeclare them yourself.

In the Options section of the Plug-in object, the Record utterances property allowsturning on utterance recording for the plug-in, and Recording scope sets the scope,which is applied only to the inherited No Match event handlers and standard andcustom navigation, as well as the last successful recognition.



Recording of UtterancesHow the Recordings are Stored

VoiceObjects 11


If Record utterances is set to True or Always , the server renders the necessarytuning parameters

<property name="recordutterance" value="true"/>

and

<property name="recordutterancetype" value="..."/>

In addition, it will accept all recordings submitted to it and store them. If the property isset to False , though, any requests to store a recording will be rejected, but processingwill continue normally. Thus it is possible to leave the <data> element and all relatedcode in the VoiceXML, but turn off utterance recording if desired.Again, Default means taking the corresponding dialog context setting.

How the Recordings are StoredThe server stores the recordings in a subfolder structure that reflects the date & timeof the session in which the recordings were stored, among other information. Thisfolder structure is prefixed with a base path structure that you can flexibly defineyourself on server, site and service level. This section talks about what these folder

structures can look like.

Construct the base path

The paragraph Setting up Utterance Recording for a Service describes how to setuppaths that get prefixed to the actual path used to store a recording.

The following rules are applied to put together the full path for a recorded utterance:

• The utterance recording path defined in the service always gets applied.

• If a service is run in the system site, the VOServer_Configuration.xml setting<utteranceRecordingBasePath> defines a base path that is put in front of whatis defined as utterance recording path in the Service object:

Final base path: [ServerInstancePath] + [ServicePath]

• If the <utteranceRecordingBasePath> definition is left empty, the Service objectsetting needs to define a full and valid path. Vice versa, if the Service objectsetting is left empty, the <utteranceRecordingBasePath> must define a validpath.Defining the <utteranceRecordingBasePath> is useful for installations that donot work with sites, where you might have many services running on the sameserver. The Service objects then don’t require an utterance recording path to beset.

• If a service is run in a non-system site and there is no utterance recording path

defined in the site, the VOServer_Configuration.xml setting<utteranceRecordingBasePath> again defines a base path that is put in front of




VoiceObjects 11


what is defined as utterance recording path in the Service object:

Final base path: [ServerInstancePath] + [ServicePath]

• If a service is run in a non-system site and there is an utterance recording pathdefined for the site, then the VOServer_Configuration.xml setting will be ignoredand the utterance recording path will be used instead and put in front of theService object setting (if there is any).

Final base path: [SitePath] + [ServicePath]

This is useful in particular in managed service provider installations that work withsites, where it must be possible to define separate utterance recording baselocations for each site.

Note: The path resulting from these concatenations must be a valid path that theserver can write to, and it must end with a back-slash. If the path is not valid, norecordings will be stored by the server instance running your service.

The same rules apply when putting together the Utterance recording URL, which isused by VoiceObjects Analyzer to provide hyperlinks to the recordings, that the usercan click to listen to them.

The subfolder structure

Since the number of recordings can be substantial for a high call volume application,the server stores the recordings in a predefined subfolder structure, reflecting the date& time of the session in which the recordings were made.

This folder structure looks as follows:

Base/VSN/YEAR/MONTH/DAY/HOUR/MINUTE/SESSION/

All time-related parts correspond to the timestamp of when a session was started,which is the same timestamp used in Infostore. This enables you to relate theutterances to a record in Infostore.

The following table describes what each part of the folder structure is about:

Folder Part Description

Base

The base path constructed on the basis of the server, site,

and service settings described in the paragraph Constructthe base path above

VSN The VSN (=reference ID) of the service for which theutterances are stored

YEAR A four-digit number reflecting the year part of the timestamp

MONTH A two-digit number reflecting the month part of thetimestamp

DAY A two-digit number reflecting the day part of the timestamp

HOUR A two-digit number reflecting the hour part of thetimestamp, in 24h format




VoiceObjects 11


MINUTE A two-digit number reflecting the minute part of thetimestamp

SESSION The dialog ID of the session the utterances are stored for

The filename structure

A recording gets stored under a filename that follows a clear naming conventioncovering details on the dialog object in which the recording was made.

The filename will always look as follows:

RecCount_ObjectType_ObjectName_Phase_RecScope_OccCount.Extension

Filename Part Description

RecCount

A counter from 1 to N over all recordings made for a dialogsession. This allows following the order of the recordingsaccording to the actual dialog flow.The counter includes recordings made by Recordingobjects. The files generated by Recording objects aretypically located somewhere else, so that gaps in thenumbering may occur here.

ObjectType The type of the object in which the recording was made(e.g. “Input”).

ObjectName

The name of the object in which the recording was made.The name will be cut off after 20 characters and any

character other than [a-z] | [A-Z] | [0-9] | “_” | “-“ will beremoved.

Phase

The “phase” of the object in which the recording was made,independent of whether it was a recognition or a No Matchrecording

• for Input objects, this is always "Request"

• for Confirmation objects, this is either "Conf " or "Corr",depending on whether the recording was made duringthe confirmation or the correction phase of the object

• for Menu objects, this is always "Selection"

• for List objects, this is always "Navigation"

• for Pause objects, this is always "Wakeup"• for Plug-in objects, this is always "Request"

• for confirmed Hyperlink objects, this is always “Conf”

RecScope

The recording scope information. Can be either Reco , for allsuccessfully recognized utterances, or NM , for allutterances that activated the No Match event. In Plug-inobjects, this will be Unknown , as the server cannot knowthe scope.

OccCount The occurrence count for the object in the current session.

Extension The file extension of the recording, which is platform-dependent.





Recording of UtterancesExample Setups

VoiceObjects 11


• The recording type (Recognition , Hyperlink , Nomatch 1-4 , Audio or Video recording).

• The recording URL, path and filename.In addition more detailed information about the session and the input state can beretrieved by combining the utterance recording table with the other Infostore tables.

For a more in-depth description of the table structure refer to Chapter 3 – The Physical Data Model in the Infostore Guide .

Refer to the Analyzer Guide for a detailed description of reports available to analyzecaller behavior through the recordings.

Note: VoiceObjects Infostore does not delete any records from the table storing the

utterance recordings. Thus, when manually deleting recording files associated entriesin Infostore might still point to files that no longer exist.

Example SetupsThis paragraph describes some scenarios of enabled utterance recording that mighthelp you in setting this feature up in your environment.

Static, unfiltered utterance recording in a single-tenant environment

Scenario

You run your services in the system site of a single server instance setup and do nothave any custom sites in your environment. You want to enable utterance recordingby default for your main Menu object and for all calls coming in, to find out what callers

say when activating Menu items. Input State logging is switched on, so you see thecorresponding entries for application usage in Infostore. The files shall be storedbelow a path of the local file system of the machine that runs VoiceObjects Server.

Setup

1. In the server configuration file of your single server instance, leave the<utteranceRecordingBasePath> definition undefined, as you want to definedifferent base paths for your different services.

2. In your Server object, make sure Enable utterance recording is selected. If not,select it, save the object and reset the server.

3. In your Service object, set Utterance recording path toC:\VoiceObjects\UtteranceRecordings\to instruct the server to store allrecordings below this path for this service. Switch utterance recording on byselecting Enable utterance recording. Set the Coverage filter to 100%. SetRecord utterances to False , so that all dialog objects that have this setting atDefault have utterance recording turned off, and set Recording scope to All .

4. In the dialog object where you want to have the utterances recorded (the mainMenu object), set Record utterances to True , to always activate the recording forthis object. Set Recording scope to Default , if you want to be able to control thescope through the dialog context setting RECORDINGSCOPE, otherwise to All , ifyou know you always want recordings for all utterances.

Redeploy your service, and all utterances made in the main Menu object should berecorded below the C:\VoiceObjects\UtteranceRecordings\ folder, starting with a

subfolder for the service.



Recording of UtterancesExample Setups

VoiceObjects 11


In case you want to switch off utterance recording temporarily for that service, e.g. formaintenance purposes, deselect Enable utterance recording on the Service objectand save it. After having redeployed the service, no utterances are stored anymore,even though the Menu object has Record utterances set to True , since the Serviceobject is a general switch that overrules individual dialog objects.

Static, filtered utterance recording in a multi-tenant environment

Scenario

You have an environment with sites in a clustered server setup. In a given site “Site1”,you want to enable utterance recording for No Match utterances, in order to find outwhat goes wrong when the ASR engine cannot recognize a caller input. You want thatfor all objects of a specific service, but since your service is called by more than200,000 callers a day, you want to store recordings only for 50% of the calls, to reducethe amount of data. Input State logging is switched on, so you see the corresponding

entries for application usage in Infostore. It is set to 80%, also to reduce the amount ofdata stored. The files are to be stored in a shared network path.

Setup

1. Since you want to be able to define different base paths for your sites leave the<utteranceRecordingBasePath> empty in the server configuration files of allyour server instances.

2. In your Server object, make sure Enable utterance recording is selected. If not,select it, save the object and reset the server.

3. In the User object of the root Site Administrator of your site, set Utterancerecording path to \\UttRecServer\UttRecordings\site1\ to instruct the server tostore all recordings below this path for any service in this site.

4. In the specific Service object associated with your application, you do not needany utterance recording path definition, as the corresponding site definitionalready takes care of the path. Switch utterance recording on by selecting Enableutterance recording. Set the Coverage filter to 50%. Set Record utterances toTrue , so that all dialog objects have utterance recording turned on by default, andset Recording scope to No Match .

5. In all dialog objects, make sure that both Record utterances and Recordingscope are set to Default .

Redeploy your service. Now the server applies the Input State logging filter of 80%,i.e. it ignores 20% of all calls. For these 80%, Infostore writes detailed data onapplication usage. Now the server applies the utterance recording filter, so that 50% of

the 80% of dialog sessions will have utterance recording enabled, and from theseremaining sessions all utterances that activate the No Match event will be recordedand stored below the \\UttRecServer\UttRecordings\site1\ folder. All in all you’ll havethe No Match utterances of 40% of all calls coming in on your service.

Time-dependent, filtered utterance recording in a single-tenant environment

Scenario

You run your services in the system site of a single server instance setup and do nothave any custom sites in your environment. You want to enable utterance recordingdepending on the time of day. Each morning from 8 A.M. to 9 A.M., when a certainpart of your customer base calls in, you want to activate utterance recording for No

Match utterances in a specific Input object of your application for 75% of all callscoming in. Input State logging is switched off, as you are not interested in the general















Command Line Interface (CLI)Commands

VoiceObjects 11


Service

The services hosted on a server can be controlled by the commands explained in thefollowing.

• service (-y) : Specifies the VoiceObjects Service Name (VSN) of the service to becontrolled.

• tracingService: Used to activate or deactivate tracing functionality on the service.Possible values are on and off .

• restrictANI: Restricts tracing to a comma separated list of ANIs for this service.Double quotes must be used to comprise the ANIs, e.g. “ANI1,ANI2,…”

• dbLoggingService: Used to configure the active DB logging options for theservice. Possible values are none , custom , system , and both .

• startService: Starts the service.This command is only available if the service is stopped or idle.The counter for rejected calls will be set back to 0.

• redeployService (-r) : Deploys an updated version of the service. This commandis available if the service is started, stopped or idled. A warning message willappear to indicate that the service will be updated to the latest service and dialogdefinition. This includes also refreshing the cache for this service. Existingsessions are not affected by redeploying the service. These sessions arecompleted using the current dialog definition. If the redeployment is confirmed bytyping “y”, the service will be redeployed. Depending on the size of the applicationdefinition, this operation can take several minutes. Nonetheless, the ControlCenter CLI returns immediately.If there are active sessions for the service that is being redeployed, a service withthe suffix SHADOW will appear the next time the server is queried. After the lastcall that was dependent on the previous dialog definition has finished, theSHADOW service will be removed. Additionally all session counters are added tothe currently active service.

• restoreService: Reverts the service back to the previously stored version of theapplication definition.A warning message will appear to indicate that the service will be restored to itsstatus prior to the most recent redeploy. This does not affect currently activesessions, which are allowed to complete using the current dialog definition. Ifconfirmed by typing “y”, the service is restored.The restoreService command is only available after a previous redeployService .

•

idleService: Sets the service into the idle status. This command is only availableif the service is started. A warning message will appear to indicate that the servicewill be idled. If the idling is confirmed by typing “y”, the service will be idled. Thisdoes not affect any active sessions, which are allowed to complete normally. Allincoming new sessions to the service will be rejected.All session counters are preserved.

• resumeService: Resumes the service. This command is only available if theservice is idled. After a successful resume the service is started and can againaccept new sessions.

• stopService: Stops the service. This command is only available if the service isstarted or idled. A warning message will appear to indicate that the service will bestopped. If the stopping is confirmed by typing “y”, the service will be stopped.

Any active sessions will be terminated immediately.All session counters are set back to 0.









Command Line Interface (CLI)XML Output Format

VoiceObjects 11


XML Element Description and Example

<sessionLimit> Shows the granted and requested session limit forthis server. The string unlimited is used if thenumber of sessions is not limited,e.g. 300(400).

<sessionGuarantee> Shows the granted and requested guaranteednumber of sessions for this server. 0 indicates thatno sessions are guaranteed for this server,e.g. 100(100).

<group> Shows the group this server belongs to.

<licenseExpireDate> Shows the date when the license for thisVoiceObjects Server expires. This information isstored following the ISO 8601 format YYYY-MM-DDThh:mmTZD,e.g. 2007-07-16T19:20+01:00.

<serverInstances>

Shows the list of existing server instances. Note that there can be various instancesfor one server, so there are N tags <serverInstance> that each contain allinformation about one specific server instance.


<instanceName> Shows the name for this instance. The nameis defined in the configuration fileVOServer_Configuration.xml .

<configuredIP> Shows the internal IP address for thisinstance, e.g. 192.168.0.1.The internal IP address is defined in theconfiguration fileVOServer_Configuration.xml .

<configuredPort> Shows the port that is used by this instance,e.g. 8099 .The port is defined in the configuration fileVOServer_Configuration.xml .

<detectedIP> Shows the detected IP address for thisinstance, e.g. 192.168.0.1

<master> Identifies if this server instance is currently themaster instance. Allowed values are:truefalse




VoiceObjects 11



<status> Status of this instance. Possible values are:STARTEDSTARTINGSTOPPEDSTOPPINGIDLEDIDLING

<startTime> Start time of this instance. This information isstored following the ISO 8601 format YYYY-MM-DDThh:mmTZD,e.g. 1997-07-16T19:20+01:00 .

<activeSessions> Shows the number of currently activesessions for this instance.

<finishedSessions> Shows the number of finished sessions forthis instance.

<abortedSessions> Shows the number of aborted sessions forthis instance.

<rejectedSessions> Shows the number of rejected sessions forthis instance.

<totalSessions> Shows the total number of sessions for thisinstance (sum of active, finished, aborted andrejected sessions).

<usedMemoryMB> Shows the size of the currently used memoryin megabytes.

<freeMemoryMB> Shows the size of the currently free memoryin megabytes.

<error> Lists error messages, e.g.Missing database connection for logging .

<infostoreErr>Lists the System DB error messages for thisserver instance.

<customDBErr>Lists the Custom DB error messages for thisserver instance.

<systemDBLogging> Status of System DB logging for this instance.Possible values are:EnabledDisabledUnavailableEnabled / Not available

Not licensed














VoiceObjects 11


<commandDetails>

Includes general information about the command processing.


<command> Shows the command, e.g. stopServer .

<executionResult> Shows the execution result. Possible values are:1 (indicates that an error occurred duringprocessing)0 (indicates that the command was processedsuccessfully)

<message> Shows the message that was produced by theserver. This can either be a specific errormessage or the known message from CLI thatasks you to check the status page.

And includes information about occurred errors and warnings.


<errorCode> Shows an internal error code, -1 is shown if noerror occurred.

<errorMessage> Shows an explanative error message.

<warningCode> Shows an internal warning code, -1 is shown if nowarning occurred.

<warningMessage> Shows an explanative warning message.



NotificationsConfiguration

VoiceObjects 11


8 Notifications

VoiceObjects provides two different ways of receiving notifications, i.e. either through SNMP (SimpleNetwork Management Protocol) or by e-mail. In addition it is possible to monitor VoiceObjects Serverusing Java Management Extensions (JMX).

The usage of notifications needs to be licensed separately. To find out whether the notificationmechanism is licensed for your VoiceObjects installation, contact your local VoiceObjectsadministrator. If it is not currently included in your license key and you want to use it, contactVoiceObjects.

If the feature is included in your license key you might need to enable it in the configuration fileVOServer_Configuration.xml as described below (Enable the notification feature). In addition,corresponding SNMP trap receivers and/or e-mail receivers have to be defined in the configurationfiles TrapReceivers.xml and/or EmailConfigurations.xml .

If the notification feature is enabled, VoiceObjects Server sends out the SNMP trap and/or e-mail tothe corresponding receivers (SNMP and/or e-mail) that are defined. See Assignment of categories tonotifications below for a complete list of all available notifications and their category assignments.Optionally, you may also assign custom categories to any notification or adjust the default assignmentof categories to notifications, in order to customize the behavior according to your preferences.

Note: When using SNMP, your VoiceObjects installation can be monitored using any SNMP

2.0 (or higher) compliant client. If SNMP traps of Version 3 should be used the correspondingSNMP receiver has to work without requiring communicating with a SNMP agent, asVoiceObjects is not including a SNMP agent.

Configuration

Enable the notification feature

To enable the notification mechanism, the configuration fileVOServer_Configuration.xml in the folder ../VoiceObjects/Platform/WEB-INF/config/ must be configured as follows for each VoiceObjects server instance participating inyour cluster.

<notificationEnabled>all</notificationEnabled>

The table below lists all values that can be used to define the coverage of thenotification feature:

Value Description

falseThe notification feature is disabled completely; neither SNMPtraps nor e-mails will be sent. This is the default setting.

trapsNotifications will only be sent through SNMP traps if properreceivers are defined in the corresponding xml file(TrapReceivers.xml ).

emailNotifications will only be sent through e-mail if proper receiversare defined in the corresponding xml file(EmailConfigurations.xml ).






VoiceObjects 11


<trapReceiver id="Machine3" categories="INFO,WARN,ERROR"

version="v3" enabled="false">

<hostIP>127.0.0.1</hostIP>

<port>162</port>

<maxCountPerNotification>10</maxCountPerNotification>

<resetTimeInterval>60</resetTimeInterval>

<locale>de</locale>

<userName>noAuthUser</userName>

</trapReceiver>

</trapReceivers>

Attribute/Child Description

trapReceivers Root tag.

trapReceiver Block to define a connection to a SNMP receiver.

trapReceiver/id Unique ID to identify this SNMP receiver.

trapReceiver/categories Specifies that SNMP traps should be sent via thisconnection if the notification matches one of thedefined categories. Allowed values are ERROR ,WARN , INFO . To specify more than one category,a comma-separated list can be defined. In

addition also custom categories might be added.Examples:

• categories=”WARN”Only includes notifications of category WARN

• categories=”CUSTOM1”Only contains notifications of categoryCUSTOM1

• categories=”INFO,WARN,ERROR”Includes all notifications of categories INFO ,WARN , and ERROR

trapReceiver/version Defines the SNMP version to be used for thisconnection. Allowed values are v2 , v2c and v3 .

trapReceiver/protocol Optional attribute to define the protocol to be usedfor sending out SNMP traps. Allowed values areudp (the default) and tcp .

trapReceiver/enabled Optional setting to disable the corresponding trapreceiver. Allowed values are true (the default) andfalse .

hostIP IP address of the machine running the SNMP

receiver.




VoiceObjects 11


Attribute/Child Description

port

Port number on which the SNMP receiver islistening (typically the default SNMP port 162 isused here).

community Authentication parameter (only used for SNMPreceivers of version 2c).

locale Defines the locale to be used for the messages ofthe SNMP traps sent out for this receiver. Allowedvalues are either en (the default) or de .

userName Authentication parameter (only used for SNMPreceivers of version 3).

maxCountPerNotification Optional setting to define a maximum number ofsame SNMP traps that will be sent out for thesame notification. If the maximum number isexceeded, for instance when running out oflicenses, no further SNMP traps will be sent outfor this notification.

resetTimeInterval Defines the time interval in minutes after whichthe limit defined in the attributemaxCountPerNotification is reset, if not defineda default value of 60 (1 hour) is used.

Configure e-mail receivers

In order to receive e-mails from VoiceObjects Server, the file EmailConfigurations.xml in the folder ../VoiceObjects/Platform/WEB-INF/config needs to be configuredappropriately. Within this file multiple e-mail receivers can be defined, each of whichmay receive different e-mails based on the settings you specify. The table below theexample describes the XML structure and lists all attributes and their possible values.

Example of EmailConfigurations.xml (relevant section for notifications):

<notificationEmailReceivers>

<emailReceiver id ="myReceiver" categories="INFO,WARN,ERROR"

enabled="true">

<from>[email protected]</from>

<to>[email protected]</to>

<cc>[email protected]</cc>

<bcc>[email protected]</bcc>

<priority>normal</priority>

<smtpServer>myServer.myCompany.com</smtpServer>

<smtpPort>25</smtpPort>

<locale>en</locale>

<maxCountPerNotification>10</maxCountPerNotification>






VoiceObjects 11


Attribute Description

emailReceiver/categories

Specifies that e-mails should be sent via thisconnection if the occurring notification matchesone of the defined categories. Allowed valuesare ERROR , WARN , INFO . To specify morethan one category, a comma-separated list canbe defined. In addition also custom categoriesmight be added. Examples:

• categories=”WARN”Only includes notifications of categoryWARN

• categories=”CUSTOM1”Only contains notifications of category

CUSTOM1 • categories=”INFO,WARN,ERROR”

Includes all notifications of categoriesINFO , WARN , and ERROR

emailReceiver/enabled Optional setting to disable the corresponding e-mail receiver. Allowed values are true (thedefault) and false .

from Defines the From field of the sent e-mail. Hasto be a valid e-mail address. As an alternativeto providing an e-mail address the placeholder

@INSTANCE_NAME@ can be used. In this caseVoiceObjects Server will automatically fill theFrom field with:instanceName@logical_Server , whereinstanceName identifies the corresponding

server instance and logical_Server is thereference ID of the used Server object.

Caution: Some SMTP servers require avalid domain to be used in the from e-mail field.In these cases the placeholder can not beused.

to Defines the To field: e-mail is sent to all e-mailaddresses defined in a comma-separated list.This setting is optional, but at least one valid e-mail address has to be defined for at least oneof the settings to, cc or bcc in order to definea valid e-mail receiver.

cc Defines the CC field: e-mail is sent to all e-mailaddresses defined in a comma-separated list.This setting is optional, but at least one valid e-mail address has to be defined for at least oneof the settings to, cc or bcc in order to define

a valid e-mail receiver.




VoiceObjects 11


Attribute Description

bcc

Defines the BCC field: e-mail is sent to all e-mail addresses defined in a comma-separatedlist. This setting is optional, but at least onevalid e-mail address has to be defined for atleast one of the settings to, cc or bcc in orderto define a valid e-mail receiver.

replyTo Defines the ReplyTo field of the e-mail. Thissetting is optional.

priority Optionally sets the priority for the e-mail; caneither be low , normal (the default) or high .

smtpServer Defines the address of the SMTP server usedfor sending out e-mails. This can either be anopen SMTP server or one that requiresauthentication. Note that in the latter case thesettings for user and password are mandatory.

smtpPort Optional setting to define the port number ofthe SMTP server. If not specified the defaultSMTP port 25 or 465 (for SSL) is used.

user Defines the user to be used for a SMTP serverthat requires authentication. Optional.

password Defines the password to be used for a SMTPserver that requires authentication. Optional.

secure Defines whether a starttsl flag should be sent tostart the encoding or not. Allowed values aretrue or false , the default is false . Optional.

startTLS Defines whether startTLS is used to negotiatethe connection security level with the SMTPserver. Allowed values are true or false , thedefault is false . Optional.

locale Defines the locale to be used for the messagesof the e-mails sent out for this receiver. Allowedvalues are en (the default) or de .

maxCountPerNotification Optional setting to define a maximum numberof same e-mails that will be sent out for thesame notification. If the maximum number isexceeded, for instance when running out oflicenses, no further e-mails will be sent out forthis notification.






VoiceObjects 11


<notification id="serverStopped"

locale="SNMP_Trap_serverStopped" masterOnly="true" categories="WARN"/>

<notification id="serverIdle" locale="SNMP_Trap_serverIdle"

masterOnly="true"/>

<notification id="serverIdled" locale="SNMP_Trap_serverIdled"

masterOnly="true"/>

<notification id="serverReloadingServiceList"

locale="SNMP_Trap_serverReloadingServiceList" masterOnly="true"/>

<notification id="serverReloadedServiceList"

locale="SNMP_Trap_serverReloadedServiceList" masterOnly="true"/>

<notification id="serverInstanceStarting"

locale="SNMP_Trap_serverInstanceStarting"/>

<notification id="serverInstanceStarted"

locale="SNMP_Trap_serverInstanceStarted"/>

<notification id="serverInstanceIdle"

locale="SNMP_Trap_serverInstanceIdle"/>

<notification id="serverInstanceIdled"

locale="SNMP_Trap_serverInstanceIdled"/>

<notification id="serverInstanceStopping"

locale="SNMP_Trap_serverInstanceStopping" categories="WARN"/>

<notification id="serverInstanceStopped"

locale="SNMP_Trap_serverInstanceStopped" categories="WARN"/>

</group>

<group name="service" categories="INFO">

<notification id="serviceStarting"

locale="SNMP_Trap_serviceStarting" masterOnly="true"/>

<notification id="serviceStarted"

locale="SNMP_Trap_serviceStarted" masterOnly="true"/>

<notification id="serviceStopping"

locale="SNMP_Trap_serviceStopping" masterOnly="true"

categories="WARN"/>

<notification id="serviceStopped"

locale="SNMP_Trap_serviceStopped" masterOnly="true"

categories="WARN"/>

<notification id="serviceIdle" locale="SNMP_Trap_serviceIdle"

masterOnly="true"/>

<notification id="serviceIdled"

locale="SNMP_Trap_serviceIdled" masterOnly="true"/>

<notification id="serviceRedeploying"

locale="SNMP_Trap_serviceRedeploying" masterOnly="true"/>

<notification id="serviceRedeployed"

locale="SNMP_Trap_serviceRedeployed" masterOnly="true"/>

<notification id="serviceRestoring"

locale="SNMP_Trap_serviceRestoring" masterOnly="true"/>

<notification id="serviceRestored"

locale="SNMP_Trap_serviceRestored" masterOnly="true"/>

</group>




VoiceObjects 11


<group name="unsolicited" categories="ERROR">

<notification id="licenseRequestFailed"

locale="SNMP_Trap_licenseRequestFailed"/>

<notification id="noSNMPLicense"

locale="SNMP_Trap_noSNMPLicense" masterOnly="true"/>

<notification id="newMasterElected"

locale="SNMP_Trap_newMasterElected" categories="WARN"/>

<notification id="serviceNA" locale="SNMP_Trap_serviceNA"/>

<notification id="urlNA" locale="SNMP_Trap_urlNA"/>

<notification id="infostoreNA" locale="SNMP_Trap_infostoreNA"

categories="WARN"/>

<notification id="customNA" locale="SNMP_Trap_customNA"

categories="WARN"/>

<notification id="repositoryNA"locale="SNMP_Trap_repositoryNA"/>

<notification id="repositoryRS"

locale="SNMP_Trap_repositoryRS"/>

<notification id="dlgExpired" locale="SNMP_Trap_dlgExpired"

categories="WARN"/>

<notification id="requestRedirect"

locale="SNMP_Trap_requestRedirect" categories="WARN"/>

<notification id="callRejectedInvalidChannelOrPartner"

locale="SNMP_Trap_invalidChannelPartner"/>

<notification id="licenseExpiredWarn"

locale="SNMP_Trap_licenseValidity_Warn" categories="WARN"/>

<notification id="licenseExpired"

locale="SNMP_Trap_licenseValidity_Expired"/>

<notification id="infostoreRS" locale="SNMP_Trap_infostoreRS"

categories="INFO"/>

<notification id="statInfoDropped"

locale="SNMP_Trap_statInfoDropped" categories="WARN"/>

<notification id="lastOperationFailed"

locale="SNMP_Trap_lastOperationFailed"/>

<notification id="licenseNotAvailable"

locale="SNMP_Trap_licenseNotAvailable"/>

<notification id="ntfBarrierReset"

locale="SNMP_Trap_ntfBarrierReset" categories="WARN"/>

<notification id="statQueueSizeWarning"

locale="SNMP_Trap_statQueueSizeWarning" categories="WARN"/>

<notification id="statQueueConsumerDisabled"

locale="SNMP_Trap_statQueueConsumerDisabled" categories="WARN"/>

<notification id="statQueueConsumerEnabled"

locale="SNMP_Trap_statQueueConsumerEnabled" categories="WARN"/>

<notification id="serviceCacheNotLoadedFromSwapFile"

locale="SNMP_Trap_serviceCacheNotLoadedFromSwapFile"

categories="WARN"/>

</group>











NotificationsTraps

VoiceObjects 11


Notification ID Description

The license key willexpire within the next%1 days. ContactVoiceObjects TechnicalSupport to get a validkey.

6.14 Your current license key is about to run out.Take care to contact VoiceObjects earlyenough to secure that you receive anupdated license key in time. Refer toChapter 4 - Managing Licenses in theAdministration Guide for further information.

The license key forVoiceObjects Server isnot valid anymore.Contact VoiceObjectsTechnical Support to geta valid key.

6.15 Your license key has already been expired.Contact VoiceObjects as soon as possible toget a new license key, as your currentVoiceObjects installation will becomeunmanageable and your applications mayalso stop answering calls soon. Refer to

Chapter 4 - Managing Licenses in theAdministration Guide for further information.

Server instance %1 isnow running in mastermode.

6.4 A new master server instance has beenselected in your VoiceObjects cluster. Atypical reason for this might be that thecurrent master server instance has beenshutdown due to maintenance situations.Refer to Chapter 1 - Deployment Architecture in the Deployment Guide forfurther information.

Requested service not

available (VSN=%1,DNIS=%2).

6.5 The service that has been requested by the

media platform is not available. This mighthave several reasons like e.g.:

• The service is not started

• The used VSN does not match the VSNof the corresponding Service object

Rejected URL due toinactive server/service(VSN=%1).

6.6 VoiceObjects Server rejects the URL sincethe server or service that has been intendedto handle the dialog is not available. Makesure that the service or server is started inthe Control Center.

Connection to InfostoreRepository notavailable. Possiblereason: %1

6.7 The database connection to your InfostoreRepository is not available. Check themessage of the notification for hints on thepossible reason.

Connection to InfostoreRepository is availableagain.

6.16 The database connection to your InfostoreRepository has been re-established.

Connection to CustomDB logging database isnot available. Possible

reason: %1

6.8 The database connection to your CustomDB logging repository is not available. Checkthe message of the notification for hints on

the possible reason.







NotificationsTraps

VoiceObjects 11


Notification ID Description

License Manager notavailable, returningfailover license. %1 ofthe grace periodremaining, %2 sessionsleft.

7.5 A failover license has been issued.This indicates that a temporary problem hasoccurred in the VoiceObjects cluster. If thisonly happens in isolated cases and correctsitself after a short period of time, it does notconstitute an issue.If, however, this message persists for longerperiods of time or occurs frequently, contactVoiceObjects Technical Support forassistance.

Maximum limit ofconcurrent dialogs

reached. %1

7.6 VoiceObjects Server has stopped acceptingany additional concurrent dialogs as the

session limit (= concurrent dialogs) has beenexceeded. This already includes theoverdraft of 20%, which VoiceObjects grantsto guarantee full availability during peektimes.

Object %1 triggerederror. %2.

8.1 An error occurred during the call. Check theerror message mentioned in the notificationand refer to the listed object for furtherinvestigation.

VoiceObjects session%1 is already in use!

8.2 VoiceObjects Server rejected to answer arequest from the media platform since it has

already been processing a request with thesame ID.

Initial request heldparameter dialogID(dialogID=%1).

8.3 The initial request sent from the mediaplatform to VoiceObjects Server alreadycontains the parameter dialogID . As thisparameter is generated by VoiceObjectsServer based on the first request, this is aconflict and leads to an aborted call. Check ifthe media platform has cached some VXMLpages, which might be a typical reason forthis issue.

Invalid assignment ofparameter in initial URL(Parameter=%1,Value=%2).

8.4 The initial request sent from the mediaplatform contains an invalid parameterassignment; check and correct the syntax.

Invalid assignment ofparameter in requestURL (Parameter=%1,Value=%2).

8.5 The request sent from the media platformcontains an invalid parameter assignment;check and correct the syntax.

























Service Level Agreements (SLA)Monitoring Session Partitioning

VoiceObjects 11


monitoring and management capabilities. This enables administrators to ensure thatthe session partitioning settings that are currently applied are consistent.

Session partitioning monitoring is available using the Control Center and the WebServices Interface.

Control Center

Session partitioning summary information is provided on the Session Partitioning tabwithin the Control Center.

This tab is only accessible to Server Administrators, Server Controllers, SiteAdministrators, and Site Controllers. The content of the Session Partitioning tab

always provides an overview of the session partitioning settings for the entirerepository (for Server Administrators/Controllers) or for the entire site (for SiteAdministrators/Controllers).

Information is displayed grouped by Sites, Servers, and Services. For all threesections, there is a set of columns displaying the granted session settings that arecurrently applied, and a set of columns displaying the requested session settings asthey are provided in the respective object definition.

The Sites section displays the session partitioning settings for all sites that are activein the installation, including the system site. Custom sites are identified by their site IDas defined in the respective site settings.

The Sites section shows the following information:

Granted Sessions – Guarantee The session guarantee that has been set aside for this site.If this number is smaller than the requested session guarantee, a yellow triangle

icon is shown to the right of the site name.

Granted Sessions – Pool The pool of floating sessions available to this site. This is the difference betweenLimit and Guarantee.

Granted Sessions – Limit The maximum number of concurrent sessions available to this site.

If this number is smaller than the requested session limit, a yellow triangle icon

is shown to the right of the site name.





Service Level Agreements (SLA)Infostore

VoiceObjects 11


Granted Sessions – Limit The maximum number of concurrent sessions available to this service.

If this number is smaller than the requested session limit, a yellow triangle iconis shown to the right of the service name.

Requested Sessions – Guarantee The session guarantee requested by this service within its object definition.

Requested Sessions – Limit The maximum number of concurrent sessions defined for this service within itsobject definition.

Requested Sessions – DistributionThe session distribution percentage defined for this service.

Web Services Interface

Session partitioning information can be obtained through the Web Services Interface(WSI) using the getSessionPartitioning method. It returns an XML structurerepresenting the same data that is displayed in the Control Center.

For more information on the Web Services Interface, refer to the Web Services Guide .

Note: The Web Services Interface is licensed separately and can only be used if it is

available in the license key.

Notifications

If notifications are enabled, notifications are sent whenever a session limit isexceeded. This applies to the service, server, and site level. For more information,refer to Chapter 8 – Notifications .

Note: Notification is licensed separately and can only be used if it is available in the

license key.

InfostoreIf Infostore is active, session partitioning settings made on servers, services, and sitesare written to the database. In addition, current session partitioning information iswritten out in regular intervals to enable subsequent analysis of actual load situationsversus SLA limits. For more information, refer to the Infostore Guide.

Note: Infostore is licensed separately and can only be used if it is available in the

license key.







Messaging SupportSMS (Clickatell XML API)

VoiceObjects 11


Configuration

The configuration settings for the Clickatell SMS adapter can be found in the fileMessagingConfiguration.xml . Locate the following element:

<adapter name="Clickatell"

factory="com.voiceobjects.improxy.sms.clickatell.ClickatellFactory"

enabled="true">

To enable or disable the Clickatell SMS adapter, change the value of the enabled attribute to true or false, respectively.

In addition the following properties can be set:

Property name Function

url Specifies the URL of the SMS gateway. This valueshould not be changed.

user Specifies the user name to be used for authenticatingwith the SMS gateway.

password Specifies the password to be used for authenticatingwith the SMS gateway.

api_id Specifies the API ID to be used for authenticating withthe SMS gateway.

If you need a proxy you can specify this through the Java properties http.ProxyHostand http.ProxyPort. Note that this proxy configuration will be used for all HTTPconnections installation-wide.









A – Media Platform Drivers

VoiceObjects 11



The media platform drivers are defined in the MPDrivers.xml configuration file, which is situated in theWEB-INF\config\ folder of your VoiceObjects installation. This file holds valid definitions for allsupported media platforms and should not be modified, as this might directly affect the functionality ofVoiceObjects Server. If a new driver is required, e.g. due to new media platform releases in betweenthe release dates of the VoiceObjects platform, the [Custom] driver, which acts as a placeholder driverdefinition for these cases, can be modified in the MPDrivers.xml file. This driver is not configured towork on any new media platform as is; it always requires a modification corresponding to the platformspecifics. You can use it as a driver when testing an application in debug mode (using the DebugViewer), though.If you need a custom driver definition for your environment, contact your VoiceObjects Salesrepresentative.The following table lists the legal values for the vsDriver parameter for all supported media platforms.The vsDriver parameter is used in the service URL configuration (see Service URL Configuration in

Chapter 4 – Service Deployment ). In addition, it lists the default language, encoding and grammartype settings. If a platform has specifics that can influence the functionality of your application, checkthe comments for your driver (if available).

Property Value

Alcatel-Lucent 8855 Multimedia Browser 4.3 [ ID = 11, Channel = Video ]

vsDriver Alcatel_8855_MB_4_3_VXML_2_0

vsLanguage en-US

vsEncoding ISO-8859-1

vsGrammarMediaType srgs_xml (Possible: srgs_xml, builtin) [DTMF only]

Comments • Input mode DTMF only (no ASR supported).

• Slot assignments not supported for non-TTG DTMFgrammars (inline or external).

• Recordings made using the Recording object will be storedon the media platform instead of VoiceObjects Server. Makesure to use correct resource locator definitions in Recordingobjects.

• Utterance recording not supported

Alcatel-Lucent 8855 Voice Browser 3.1/4.2 (Nuance) [ ID = 31, Channel = Voice ]

vsDriver Alcatel_8855_VB_3_1_VXML_2_0_ASR_Nuance

vsLanguage en-US


vsGrammarMediaType srgs_xml (Possible: srgs_xml, builtin)

Comments • Slot assignments not supported for non-TTG DTMF

grammars (inline or external).

• Recordings made using the Recording object will be storedon the media platform instead of VoiceObjects Server. Makesure to use correct resource locator definitions in Recording

objects.








VoiceObjects 11


Property Value



Comments • In some installations there might be an issue with the

playback of prompts when there is a Silence object present,which is rendered through the <break> element by default. Ifyour installation has a problem with this, set the<breakAudioSupport> element to true for this driver.

Avaya IR 2.0 (Nuance) [ ID = 105, Channel = Voice ]

vsDriver Avaya_IR_2_0_VXML_2_0_ASR_Nuance

vsLanguage en-US

vsEncoding ISO-8859-1vsGrammarMediaType srgs_xml (Possible: srgs_xml, builtin)

Avaya IR 2.0 (Nuance OSR) [ ID = 104, Channel = Voice ]

vsDriver Avaya_IR_2_0_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US



Avaya IR 3.0 (IBM) [ ID = 116, Channel = Voice ]

vsDriver Avaya_IR_3_0_VXML_2_1_ASR_IBM

vsLanguage en-US



Comments • In some installations there might be an issue with the

playback of prompts when there is a Silence object present,which is rendered through the <break> element by default. Ifyour installation has a problem with this, set the<breakAudioSupport> element to true for this driver.

Avaya IR 3.0 (Nuance) [ ID = 117, Channel = Voice ]

vsDriver Avaya_IR_3_0_VXML_2_1_ASR_Nuance

vsLanguage en-US



Avaya IR 3.0 (Nuance OSR) [ ID = 118, Channel = Voice ]

vsDriver Avaya_IR_3_0_VXML_2_1_ASR_SpeechWorks

vsLanguage en-US












VoiceObjects 11


Property Value

Comverse Media Server 3.0.3/3.1 (Nuance) [ ID = 25, Channel = Voice ]

vsDriver Comverse_MS_3_0_VXML_2_1_ASR_Nuance

vsLanguage en-US

vsEncoding UTF-8

vsGrammarMediaType srgs_xml (Possible: srgs_xml, jsgf, abnf, builtin)

Comments • Utterance recording not supported

Comverse Media Server 3.0.3/3.1 (Nuance OSR) [ ID = 7, Channel = Voice ]

vsDriver Comverse_MS_3_0_VXML_2_1_ASR_SpeechWorks

vsLanguage en-US

vsEncoding UTF-8

vsGrammarMediaType srgs_xml (Possible: srgs_xml, jsgf, abnf, builtin)


Comverse USSD Center 4.3 Browser Interface [ ID = 177, Channel = Text ]

vsDriver Comverse_USSD_Browser

vsLanguage en-US


vsGrammarMediaType “none”

CreaLog CreaVoice VoiceXML Gateway [ ID = 49, Channel = Voice ]

vsDriver CreaLog_CreaVoice_VG_VXML_2_0

vsLanguage de-DE




Edify EVIP 9.0-10.0 (Nuance OSR) [ ID = 54, Channel = Voice ]

vsDriver Edify_EVIP_9_0_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US




Edify EVIP 9.0-10.0 (Nuance) [ ID = 53, Channel = Voice ]

vsDriver Edify_EVIP_9_0_VXML_2_0_ASR_Nuance

vsLanguage en-US







VoiceObjects 11


Property Value


vsGrammarMediaType srgs_xml (Possible: srgs_xml, abnf, precompiled, builtin)

Comments • Slot names used in external grammars, but also internally for

TTG, might need to be all lower-case.

• If you want to have the session variable SPSID available inthe dialog context as well as in Infostore, you need toinclude the CGI string “SPSID=$sessionid$” in the mediaplatform’s initial request.


Genesys Voice Platform 6.5-7.2 (Nuance OSR) [ ID = 33, Channel = Voice ]

vsDriver Genesys_GVP_6_5_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US







Genesys Voice Platform 6.5-7.2 (Nuance) [ ID = 32, Channel = Voice ]

vsDriver Genesys_GVP_6_5_VXML_2_0_ASR_Nuance

vsLanguage en-US


vsGrammarMediaType gsl (Possible: gsl, builtin)





Genesys Voice Platform 6.5-7.2 (Telisma) [ ID = 52, Channel = Voice ]

vsDriver Genesys_GVP_6_5_VXML_2_0_ASR_Telisma

vsLanguage en-US












VoiceObjects 11


Property Value

HP OpenCall Media Platform 2.4 (Nuance) [ ID = 42, Channel = Voice ]

vsDriver HP_OCMP_2_4_VXML_2_0_ASR_Nuance

vsLanguage en-US


vsGrammarMediaType srgs_xml (Possible: srgs_xml, gsl, builtin)


HP OpenCall Media Platform 2.4 (SpeechPearl) [ ID = 43, Channel = Voice ]

vsDriver HP_OCMP_2_4_VXML_2_0_ASR_SpeechPearl

vsLanguage en-US




HP OpenCall Media Platform 3.0 (Nuance OSR) [ ID = 63, Channel = Voice ]

vsDriver HP_OCMP_3_0_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US




HP OpenCall Media Platform 3.0 (Nuance) [ ID = 62, Channel = Voice ]


vsLanguage en-US


vsGrammarMediaType srgs_xml (Possible: gsl, srgs_xml, builtin)


HP OpenCall Media Platform 3.1–4.3 (Nuance OSR) [ ID = 77, Channel = Voice ]

vsDriver HP_OCMP_3_1_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US




HP OpenCall Media Platform 3.1–4.3 (Nuance) [ ID = 76, Channel = Voice ]


vsLanguage en-US




VoiceObjects 11


Property Value


vsGrammarMediaType srgs_xml (Possible: gsl, srgs_xml, builtin)


HP OpenCall Media Platform 1.0 (Video) [ ID = 99, Channel = Video ]

vsDriver HP_OCMPV_1_0_VXML_2_0_Video

vsLanguage en-US




HP OpenCall speechWeb 2.3 (Nuance OSR) [ ID = 26, Channel = Voice ]

vsDriver HP_OCSW_2_3_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US




HP OpenCall speechWeb 2.3 (Nuance) [ ID = 22, Channel = Voice ]

vsDriver HP_OCSW_2_3_VXML_2_0_ASR_NuancevsLanguage en-US




HP OpenCall speechWeb 2.3 (SpeechPearl) [ ID = 19, Channel = Voice ]

vsDriver HP_OCSW_2_3_VXML_2_0_ASR_SpeechPearl

vsLanguage en-US




Holly Voice Gateway 4.0 (Nuance) [ ID = 46, Channel = Voice ]

vsDriver Holly_HVG_4_0_VXML_2_0_ASR_Nuance

vsLanguage en-AU-NZ


vsGrammarMediaType srgs_xml (Possible: srgs_xml, gsl, builtin)









VoiceObjects 11


Property Value

Holly Voice Platform 5.0/5.1 (Nuance OSR) [ ID = 153, Channel = Voice ]

vsDriver Holly_HVP_5_0_VXML_2_1_ASR_SpeechWorks

vsLanguage en-US



Holly Voice Platform 5.0/5.1 (Siemens) [ ID = 156, Channel = Voice ]

vsDriver Holly_HVP_5_0_VXML_2_1_ASR_Siemens

vsLanguage en-US


vsGrammarMediaType srgs_xmlHolly Voice Platform 5.0/5.1 (Telisma) [ ID = 157, Channel = Voice ]

vsDriver Holly_HVP_5_0_VXML_2_1_ASR_Telisma

vsLanguage en-US



I6NET VXIasterisk 1.5 [ ID = 113, Channel = Voice ]

vsDriver I6NET_VXIasterisk_1_5_VXML_2_0

vsLanguage en-US



Comments • Input Mode DTMF only (no ASR)


I6NET VXIasterisk 1.5 (Video) [ ID = 114, Channel = Video ]

vsDriver I6NET_VXIasterisk_1_5_VXML_2_0_Video

vsLanguage en-US

vsEncoding ISO-8859-1vsGrammarMediaType srgs_xml (Possible: srgs_xml, builtin)

Comments • Input Mode DTMF only (no ASR)


IBM WVR 3.1/4.2 VXML 1.0 [ ID = 4, Channel = Voice ]

vsDriver IBM_WVR_3_1_VXML_1_0

vsLanguage en-US


vsGrammarMediaType jsgf (Possible: jsgf, builtin)












VoiceObjects 11


Property Value

vsLanguage en-US


vsGrammarMediaType dtmf (Possible: dtmf, builtin)

Comments • Slot assignments not supported for non-TTG DTMFgrammars (inline or external).


Netcentrex MCS 6 (Nuance OSR) [ ID = 83, Channel = Voice ]

vsDriver Netcentrex_MCS_6_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US



Comments • Recordings made using the Recording object will be storedon the media platform instead of VoiceObjects Server. Makesure to use correct resource locator definitions in Recordingobjects.


Netcentrex MCS 6 (Telisma) [ ID = 84, Channel = Voice ]

vsDriver Netcentrex_MCS_6_VXML_2_0_ASR_Telisma

vsLanguage en-US



Comments • Recordings made using the Recording object will be storedon the media platform instead of VoiceObjects Server. Makesure to use correct resource locator definitions in Recordingobjects.


Nortel Hosted IVR [ ID = 170, Channel = Voice ]

vsDriver Nortel_VXML_2_0_ICP_VXML_2_1_ASR_IBM

vsLanguage en-US


vsGrammarMediaType gsl (Possible: gsl, srgs_xml, builtin)

Nortel ICP VoiceXML 2.1 (IBM) [ ID = 166, Channel = Voice ]

vsDriver Nortel_HostedIVR _VXML_2_1

vsLanguage en-US



Nortel ICP VoiceXML 2.1 (Nuance) [ ID = 165, Channel = Voice ]

vsDriver Nortel_VXML_2_0_ICP_VXML_2_1_ASR_Nuance








VoiceObjects 11


Property Value


vsGrammarMediaType jsgf (Possible: jsgf, srgs_xml, regex, builtin)

Prosodie Voice Portal (Nuance) [ ID = 147, Channel = Voice ]

vsDriver Prosodie_Voice_Portal_VXML_2_1_ASR_Nuance

vsLanguage en-US



Rich Web Client XHTML 1.0 [ ID = 135, Channel = Web ]

vsDriver RichWeb_XHTML_1_0

vsLanguage en-US

vsEncoding UTF-8



SandCherry Voice Portal 3.2 (Nuance) [ ID = 127, Channel = Voice ]

vsDriver SandCherry_SVP_3_2_VXML_2_0_ASR_Nuance

vsLanguage en-US


vsGrammarMediaType gsl (Possible: gsl, srgs_xml, precompiled, builtin)

SandCherry Voice Portal 3.2/3.3 (Nuance OSR) [ ID = 128, Channel = Voice ]

vsDriver SandCherry_SVP_3_2_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US



SandCherry Voice Portal 3.3 (LumenVox) [ ID = 137, Channel = Voice ]

vsDriver SandCherry_SVP_3_3_VXML_2_1_ASR_LumenVox

vsLanguage en-US


vsGrammarMediaType gsl (Possible: gsl, srgs_xml, precompiled, builtin)

SandCherry Voice Portal 3.3 (Nuance) [ ID = 138, Channel = Voice ]

vsDriver SandCherry_SVP_3_3_VXML_2_1_ASR_Nuance

vsLanguage en-US






VoiceObjects 11


Property Value

Sicap USSD Menu Browser 3.2-4.2 [ ID = 102, Channel = Text ]

vsDriver Sicap_UMB_3_2

vsLanguage en-US

vsEncoding UTF-8



Tecnomen Telco Server 2.1 (Nuance OSR) [ ID = 161, Channel = Voice ]

vsDriver Tecnomen_TSS_2_1_VXML_2_1_ASR_SpeechWorks

vsLanguage en-US



Telenet MultiVoice (Nuance) [ ID = 21, Channel = Voice ]

vsDriver Telenet_MultiVoice_VXML_2_0_ASR_Nuance

vsLanguage de-DE




Tellme Studio [ ID = 1, Channel = Voice ]

vsDriver Tellme_Studio_VXML_2_0

vsLanguage en-US


vsGrammarMediaType gsl (Possible: gsl, builtin)

Comments • Input mode specific nomatch handler not supported

Unisys OSP 4.8 [ ID = 115, Channel = Voice ]

vsDriver Unisys_OSP_4_8_VXML_2_0_ASR_Nuance

vsLanguage en-US



Verascape VeraServ 2.2 [ ID = 30, Channel = Voice ]

vsDriver Verascape_VeraServ_2_2_VXML_2_0

vsLanguage en-US

vsEncoding UTF-8





VoiceObjects 11


Property Value


Verizon Business Hosted IVR (Nuance OSR) [ ID = 129, Channel = Voice ]

vsDriver VerizonBusiness_HostedIVR_VXML_2_1_ASR_SpeechWorks

vsLanguage en-US

vsEncoding UTF-8


Visibridge VXML Gateway [ ID = 36, Channel = Voice ]

vsDriver Visibridge_VG_1_23_VXML_2_0

vsLanguage en-US



Vocalocity Voice Browser 2.2 (Nuance OSR) [ ID = 41, Channel = Voice ]

vsDriver Vocalocity_VB_2_2_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US




Vocalocity Voice Browser 2.2 (Nuance) [ ID = 40, Channel = Voice ]

vsDriver Vocalocity_VB_2_2_VXML_2_0_ASR_Nuance

vsLanguage en-US




VoiceGenie 7 (IBM) [ ID = 81, Channel = Voice ]

vsDriver VoiceGenie_7_VXML_2_1_ASR_IBMvsLanguage en-US


vsGrammarMediaType srgs_xml (Possible: srgs_xml, abnf, precompiled, builtin)

Comments • If com.voicegenie.strictconformance is true (the defaultfor <vxml version=”2.1”>), slot values containing ‘#’characters will be cut down to all characters until the firstoccurrence of ‘#’. A slot value of only ‘#’ will be removedcompletely.Find more information athttp://developer.voicegenie.com/reference.php?ref=propertiesstrictconformance#Version.

http://developer.voicegenie.com/reference.php?ref=propertiesstrictconformance#Version







VoiceObjects 11


Property Value

VoiceGenie 7 (Nuance OSR) [ ID = 56, Channel = Voice ]

vsDriver VoiceGenie_7_VXML_2_1_ASR_SpeechWorks

vsLanguage en-US


vsGrammarMediaType srgs_xml (Possible: srgs_xml, precompiled, builtin)

Comments • If com.voicegenie.strictconformance is true (the defaultfor <vxml version=”2.1”>), slot values containing ‘#’characters will be cut down to all characters until the firstoccurrence of ‘#’. A slot value of only ‘#’ will be removedcompletely.Find more information at

http://developer.voicegenie.com/reference.php?ref=propertiesstrictconformance#Version.

VoiceGenie 7 (Nuance) [ ID = 55, Channel = Voice ]

vsDriver VoiceGenie_7_VXML_2_1_ASR_Nuance

vsLanguage en-US


vsGrammarMediaType gsl (Possible: abnf, gsl, srgs_xml, builtin)


VoiceGenie 7 (Telisma) [ ID = 82, Channel = Voice ]

vsDriver VoiceGenie_7_VXML_2_1_ASR_Telisma

vsLanguage en-US




VoiceGenie 7.1/7.2 (IBM) [ ID = 97, Channel = Voice ]

vsDriver VoiceGenie_7_1_VXML_2_1_ASR_IBM

vsLanguage en-US




















VoiceObjects 11


Property Value

key voName="SPSID" and <key voName="GCID"> andadjust them as follows:<key voName="SPSID">session.com.voicegenie.telephone.primarychan

</key>

<key voName="GCID">

session.telephone.callidref

</key>

• If com.voicegenie.strictconformance is true (the defaultfor <vxml version=”2.1”>), slot values containing ‘#’characters will be cut down to all characters until the firstoccurrence of ‘#’. A slot value of only ‘#’ will be removedcompletely.Find more information athttp://developer.voicegenie.com/reference.php?ref=propertie

sstrictconformance#Version.

VoiceGenie NeXusPoint 6.4 (Nuance OSR) [ ID = 39, Channel = Voice ]

vsDriver VoiceGenie_NP_6_4_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US



Comments • If com.voicegenie.strictconformance is true (the defaultfor <vxml version=”2.1”>), slot values containing ‘#’characters will be cut down to all characters until the first

occurrence of ‘#’. A slot value of only ‘#’ will be removedcompletely.Find more information athttp://developer.voicegenie.com/reference.php?ref=propertiesstrictconformance#Version.


VoiceGenie NeXusPoint 6.4 (Nuance) [ ID = 38, Channel = Voice ]

vsDriver VoiceGenie_NP_6_4_VXML_2_0_ASR_Nuance

vsLanguage en-US


vsGrammarMediaType srgs_xml (Possible: srgs_xml, gsl, abnf, builtin)



VoiceGenie NeXusPoint 6.4 (Telisma) [ ID = 48, Channel = Voice ]

vsDriver VoiceGenie_NP_6_4_VXML_2_0_ASR_Telisma

















VoiceObjects 11


Property Value

vsLanguage en-US





VoiceGenie VXML Gateway 5.9 (Nuance OSR) [ ID = 16, Channel = Voice ]

vsDriver VoiceGenie_VG_5_9_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US




VoiceGenie VXML Gateway 5.9 (Nuance) [ ID = 15, Channel = Voice ]

vsDriver VoiceGenie_VG_5_9_VXML_2_0_ASR_Nuance

vsLanguage en-US


vsGrammarMediaType gsl (Possible: gsl, abnf, builtin)


VoiceGenie VXML Gateway 6.1-6.3 (Nuance OSR) [ ID = 35, Channel = Voice ]

vsDriver VoiceGenie_VG_6_1_VXML_2_0_ASR_SpeechWorks

vsLanguage en-US




VoiceGenie VXML Gateway 6.1-6.3 (Nuance) [ ID = 34, Channel = Voice ]

vsDriver VoiceGenie_VG_6_1_VXML_2_0_ASR_Nuance

vsLanguage en-US


vsGrammarMediaType srgs_xml (Possible: srgs_xml, gsl, abnf, builtin)














VoiceObjects 11


Property Value

[Custom] [ ID = 8, Channel = Voice ]

vsDriver Custom

vsLanguage en-US




Voxeo IMified Platform [ ID = 173, Channel = Text ]

vsDriver Voxeo_IMified_Platform_TEXT

vsLanguage en-US vsEncoding ISO-8859-1

vsGrammarMediaType ---

Comments • Used internally together with IMified adapter

[Messaging Proxy] [ ID = 164, Channel = Text ]

vsDriver MessagingProxy

vsLanguage en-US



Comments • For internal use only

[Phone Simulator] [ ID = 136, Channel = Text ]

vsDriver PhoneSimulator

vsLanguage en-US



Comments • For internal use only



B – Control Center ReportsReport View

VoiceObjects 11


B – Control Center Reports

Based on data collected in the Infostore repository, VoiceObjects provides a set of pre-configuredreports that are deeply integrated into the Control Center to allow for easy access and convenientmonitoring of system performance on multiple levels.

Reports are available on the levels of servers, server instances, and services.

The data underlying the reports is retrieved from the server connected to in the Control Center usingthe Web Service Interface. No explicit connection to the Infostore repository is required.

Note: Infostore needs to be enabled in order to view reports since they rely on data captured

within the Infostore repository. Also, reports are only available when the server referenced in theControl Center connection uses <infostoreMode>Direct</infostoreMode>. For more information,refer to Configuring Infostore in the Administration Guide .

Caution: When using Control Center reports on live production servers, keep in mind thatrunning the corresponding SQL queries on the Infostore repository creates a certain load on thedatabase. Care should therefore be taken not e.g. to refresh the reports too frequently.

Report ViewControl Center reports are available from within the context menus for servers, serverinstances, and services as described in Chapter 3 – Managing Servers and Services .Selecting a report opens a new view called Report Chart (or brings it to the front if itwas already open).

Reports can be viewed for the current as well as the previous time period on the levelsof days, weeks, months, and years. By default, reports show data for today.

Time range can be selected from the first drop-down list offering Day , Week , Month ,and Year .

The second drop-down list adjusts accordingly to offer Today / Yesterday , Current week / Previous week , Current month / Previous month , or Current year / Previous year .

The report type itself can be switched using the third drop-down list; the choices

offered are the same as in the corresponding Control Center menu.

http://006-advancedconfiguration.htm/




B – Control Center ReportsServer Reports

VoiceObjects 11


To refresh the currently shown report, e.g. after additional calls have been made, click

the Refresh button .

The report can be saved as a PDF file by clicking the Save button .

Server ReportsServer reports provide information about all sessions processed on the server. In acluster setup, this spans the entire cluster with all its component server instances.

Number of Sessions

Shows the total number of sessions processed on the server during the selected timeperiod.

’

The specific type of chart (line chart or bar chart) is chosen automatically dependingon the time period.

Sessions by Instance

Shows the distribution of sessions processed on the server during the selected timeperiod split across server instance. In a cluster setup, this can be used to validate thatload is spread evenly across the component server instances.

Sessions by Service

Shows the distribution of sessions processed on the server during the selected timeperiod split across services. This can be used to monitor load distribution across thedifferent applications deployed on the server.



B – Control Center ReportsServer Instance Reports

VoiceObjects 11


Session Duration

Shows the average session duration during the selected time period split out byservice.

Session Status

Shows the distribution of session termination status for all sessions processed on theserver during the selected time period.

Server Instance ReportsServer instance reports provide information about all sessions processed on theserver instance. In a cluster setup, this allows for individual analysis of the variouscomponent server instances of the cluster.

Number of Sessions

Shows the total number of sessions processed on the server instance during theselected time period.



B – Control Center ReportsServer Instance Reports

VoiceObjects 11


Sessions by Service

Shows the distribution of sessions processed on the server instance during the

selected time period across services. This can be used to monitor load distributionacross the different applications deployed on the server instance.

Session Duration

Shows the average session duration during the selected time period split out byservice.

Session Status

Shows the distribution of session termination status for all sessions processed on theserver instance during the selected time period.

Memory Usage

Shows the memory usage on the server instance during the selected time period. Thisis important information to monitor the health of the server instance.



B – Control Center ReportsService Reports

VoiceObjects 11


Queue Usage

Shows the Infostore queue usage on the server instance during the selected time

period. This is important information to monitor the health of the server instance’sInfostore connection.

Cache Usage

Shows the in-memory cache usage on the server instance during the selected timeperiod. The in-memory cache represents the applications deployed on the serverinstance and is used when serving calls.This is important information to monitor the health of the server instance’s servicemanagement.

Service ReportsService reports provide information about all sessions processed on the service.

Number of Sessions

Shows the total number of sessions processed on the service during the selected timeperiod.

Session Duration

Shows the distribution of session durations during the selected time period.







C – Virtual Control CenterSetting up a Virtual Control Center

VoiceObjects 11


A sample configuration covering two clusters running on two server boxes each lookslike this:

<root>

<targets user="voadmin" pwd="manager">

<target host="cluster1-box1" port="8099">

<sidekick port="8098"/>

<sidekick host="cluster1-box2" port="8099"/>


</target>

<target host="cluster2-box1" port="8066">

<sidekick port="8065"/>



</target>

</targets>

<barrier>

<timeout>300000</timeout></barrier>

</root>

The configuration contains the following settings:

Element Description

<targets> Defines the list of targets, which corresponds to the listof clusters that are to be covered by the Virtual ControlCenter.

The <targets> element has the following attributes:

• user Defines the user ID to be used in communicationwith the server instances.To avoid user IDs in configuration files it is possibleto set the property vo.vcc.targets.user and use theoverwrite mechanism described in the sectionDynamic Property Retrieval in Chapter 1 – Advanced Configuration in the Administration Guide .

• pwd Defines the password to be used for the user.To avoid passwords in configuration files it ispossible to set the property vo.vcc.targets.pwd anduse the overwrite mechanism described in thesection Dynamic Property Retrieval in Chapter 1 – Advanced Configuration in the Administration Guide.







C – Virtual Control CenterSetting up a Virtual Control Center

VoiceObjects 11


Element Description

<target>

Defines an individual target, which corresponds to anindividual cluster; there can be any number of <target>elements within a <targets> parent element.

The <target> element itself defines the primary serverinstance in the cluster, which by default is contactedfirst. If it is not available, the other instances (defined in<sidekick> elements, see below) are contacted, so thechoice for the primary target instance is essentiallyarbitrary.

The <target> element has the following attributes:

• host [required]Defines the host on which the server instance runs.

• port [required]Defines the port on which the server instance runs.

• user Defines the user ID to be used in communicationwith the server instance. If not defined, the userdefined in the <targets> parent is used.

• pwd Defines the password to be used for the user. If notdefined, the password defined in the <targets>parent is used.

•

cert-url Specifies a certificate to be used for requests to thetarget. When specified, communication automaticallyuses HTTPS. Note that the server instances for thetarget need to be configured accordingly.The default is not to use a certificate.

• proxy-hostSpecifies a proxy host to be used for all requests tothe target.The default is not to use a proxy.

• proxy-portSpecifies a proxy port to be used for all requests to

the target.The default is not to use a proxy.



C – Virtual Control CenterUsing a Virtual Control Center

VoiceObjects 11


Element Description

<sidekick>

Defines additional server instances within the target;there can be any number of <sidekick> elements withina <target> parent element.

The <sidekick> element has the following attributes:

• host Defines the host on which the server instance runs.If not defined, the host defined in the <target> parentis used.

• port Defines the port on which the server instance runs.If not defined, the host defined in the <target> parentis used.

<response-timeout>

Defines the maximum time (in milliseconds) to wait forresponses from server instances. Default is 5 minutes.

<cycle-margin> Defines the maximum response time (in milliseconds)after which a reported error leads to cycling to the next<sidekick>. Default is 10 second.

Note: Changes to the VirtualCC.xml configuration file are applied dynamically without

the need to restart the Virtual Control Center process. In production setups you shouldtherefore be careful with changes made to this file.

Using a Virtual Control CenterTo monitor and manage multiple VoiceObjects clusters as an integrated unit, theVirtual Control Center stands in place of a “regular” VoiceObjects Server. So using theVirtual Control Center consists of two steps:

1. Setting up the Virtual Control Center process.

2. Configuring a Control Center connection pointing to it.

Virtual Control Center process

The Virtual Control Center process is configured using VirtualCC_Configuration.xml inthe WEB-INF/config subfolder of your VoiceObjects installation folder.

The only settings that normally need to be configured are <instanceIP> and<instancePort>, defining the host and port on which the Virtual Control Centerprocess is supposed to run. The default port if 7099.

To start the Virtual Control Center process, use the scripts start_VirtualCC.bat/.sh provided in the WEB-INF/bin subfolder of your VoiceObjects installation folder. Tostop the process on Linux, use the stop_VirtualCC.sh script. Starting or stopping theVirtual Control Center process does not in any way impact the clusters it monitors (asconfigured in VirtualCC.xml described above).

Note: Changes to the VirtualCC.xml configuration file are applied dynamically without

the need to restart the Virtual Control Center process. In production setups you should

therefore be careful with changes made to this file.



C – Virtual Control CenterUsing a Virtual Control Center

VoiceObjects 11

Control Center connection

As mentioned above, the Virtual Control Center process stands in place of the

“regular” VoiceObjects Server the Control Center would normally connect to. So theonly difference in configuring a connection to a Virtual Control Center is to use theserver address and port on which the Virtual Control Center runs.

Opening a Virtual Control Center connection initially can take some time depending onsize of clusters configured in VirtualCC.xml due to the connections that need to beestablished.

If all server instances for a target are unavailable when opening a Virtual ControlCenter connection, the respective target is skipped and also not considered inrefreshes. The connection needs to be closed and re-opened (from Desktop forEclipse or Desktop for Web) once at least one server instance of the target becomesavailable again.

Caution: When working with a Virtual Control Center do not use separate Control

Documents

VO Deployment