1 Advanced Configuration of VoiceObjects

This chapter explains how to change the initial configuration, carried out during the installation of VoiceObjects with the VoiceObjects Installer.

i8 Note: Any changes in the configuration files mentioned in this chapter require a restart of VoiceObjects Server or VoiceObjects Desktop to become effective, except for the logging facilities described in the final section.

Prerequisites

In order to follow the instructions in this chapter you need an editor that is capable of editing ASCII and XML files. This can be a simple text editor like Notepad on Windows or vi on Linux (or any UNIX variety), or an advanced source code editor with specific XML editing features. You may also use your favorite editor for each platform. Instructions on how to use these editing tools and basic principles for editing XML files are not covered here. For information on this, consult the appropriate documentation of your operating system and/or editor and see the respective literature concerning the Extensible Markup Language (XML).

The configuration files addressed here are located in the WEB-INF/config, WEB-INF/bin and WEB-INF/etc/Jetty (or WEB-INF/etc/Tomcat) subfolders of your VoiceObjects installation folder. The WEB-INF/config and WEB-INF/bin folders contain the configuration files for the VoiceObjects platform itself, whereas the WEB-INF/etc folder contains the configuration files associated with the Servlet engine. The platform specific start scripts in the WEB-INF/bin folder contain some basic settings for the Java Virtual Machine. Navigate to these folders in order to change the settings described in this chapter.

When working with Desktop for Eclipse some settings are also made in the configuration file Eclipse_Configuration.xml in the com.voiceobjects.eclipseDesktop_9.1.0\config folder.

Reconfiguring Initial Settings

Change the license key

If your license key has expired, a larger number of ports is required, or you require additional features such as Infostore, you need to request a new license key from VoiceObjects. See Chapter 4 - Managing Licenses for instructions on how to update the license key within the VoiceObjects platform.

Change the character encoding

The VoiceObjects platform supports different character encodings, including ISO-8859-1 and UTF-8. The encoding is configured in the files VODesktop_Configuration.xml, VOServer_Configuration.xml and Eclipse_Configuration.xml (only relevant when using Desktop for Eclipse) using the <encoding> element:

The default encoding is ISO-8859-1. To change it, simply set it to UTF-8:

A full restart of VoiceObjects Desktop or VoiceObjects Server is required to activate the change. Refer to UTF-8 support below for more information on how to use UTF-8 as character encoding.

When running VoiceObjects Server in a clustered setup, make sure that all server instances in a cluster use the same encoding setting in their configuration files. Also, a VoiceObjects Desktop used to control the cluster must also use the same encoding.

Note that other components involved in the complete system setup (e.g. the media platform, back-end systems, Internet Explorer, etc.) must also be configured appropriately to ensure a consistent handling of character encoding.

Change a server instance name, address, and port

The name of a server instance is defined in the VOServer_Configuration.xml file. Locate the following section near the top of the file:

<instanceName>PrimaryInstance</instanceName>

<instanceName> defines a mnemonic name for the server instance. It can be set to any string (not including XML-restricted characters), or left empty. In the latter case, the combination of <instanceIP> and <instancePort> is used to identify the server instance.

<instanceIP> needs to be the IP address or host name (case-sensitive) of the machine on which this server instance runs.

<instancePort> needs to be the port on which this server instance listens for requests from the media platform. Make sure that this setting matches the one used in the corresponding Web application server configuration.

8 Caution: Make sure you use the same identifier throughout. Do not for example use localhost and 127.0.0.1 interchangeably, but always use the same address. Also, unless you run a single machine installation, use real IP addresses or machine names instead of the loopback address 127.0.0.1. This is particularly important on Linux/Unix installations.
Finally, when using host names in <instanceIP> make sure that they are identical to the actual host names used in the network, including case (e.g. server1, Server1, and SERVER1 are three different host names!).

The names of server instances must be unique within a cluster.

@8 Tip: If you are configuring a cluster, make sure to set <standalone> to network for all server instances involved in the cluster. Note, however, that since VoiceObjects 7.1 VoiceObjects Desktop is no longer part of the cluster, thus its <standalone> setting is set to singleton and should not be changed.

Media platform driver configuration

In order to change the default media platform driver and language you need to change the <defaultMPDriverID> and <defaultMPDriverLanguage> tags in the VOServer_Configuration.xml file respectively.

The value for the output driver is an ID that specifies the media platform driver settings to be used by VoiceObjects Server. See the MPDrivers.xml file for details on which ID belongs to a particular driver. Open this file in a text viewer or editor and search for XML elements like the following:

<channel>voice</channel>

<channelEngine>VoiceXML_VoiceVideo</channel>

<externalName>VoiceGenie 7 (Nuance)</externalName>

<internalName>ver_2_0.VoiceGenie.7</internalName>

<productName>VoiceGenie_7_VXML_2_1_ASR_Nuance</productName>

...

...

</languages>

</encodings>

...

</mp>

According to this example you need to use ID 55 for the <defaultMPDriverID> tag in order to specify the driver for VoiceGenie 7 with Nuance recognizer as the default.

Choose one of the languages supported by the selected driver as the default language (see the <languages> tag in the above example). Only the attribute values of the language keys (e.g. de-DE, en-US) are allowed as the value for the <defaultMPDriverLanguage> tag.

Choose one of the encodings supported by the selected driver as the default encoding (see the <encodings> tag in the above example). Only the attribute values of the encoding keys (e.g. ISO-8859-1, UTF-8) are allowed as the value for the <encoding> tag inside the <outputFormatting>.

OSDM configuration

When working with OpenSpeech DialogModules (OSDMs), it is necessary to make certain installation-specific adjustments in the file OSDMDrivers.xml located in the WEB-INF/config folder of the VoiceObjects installation.

In this file, locate the media platform you are using. Note that OSDMs are only available on a certain set of media platforms, and only work with the Nuance OSR recognition engine.

Within the configuration entry for the respective media platform, adjust the entry for the recognizer version, marked bold below:

<osdmParameter name="browser">speechgenie</osdmParameter>

<osdmParameter name="vxmlspec">v2.0-february2003</osdmParameter>

<osdmParameter name="recognizer">osr3.0</osdmParameter>

</osdmParameters>

</mp>

The default value depends on the media platform. Possible values are osr1.1, osr2.0 and osr3.0.

In addition, you need to configure the URL pointing to your OSDM installation in the server instance configuration file VOServer_Configuration.xml (in the same folder).

Locate the following element:

<osdmURL>http://localhost:8080/VoiceObjects/osdm</osdmURL>

and adjust the URL to point to the root of your OSDM installation. This URL is used when dynamically calling OSDMs during dialog processing.

For more information on OSDMs and their configuration, refer to the OSDM documentation.

Memory configuration

In order to increase or decrease the maximum amount of memory used by the Java Virtual Machine you need to change the values for the -Xmx and -Xms parameters in the start scripts within the bin folder. The folder contains one start script for VoiceObjects Desktop and one for VoiceObjects Server. Depending on your platform these files have the .bat (Windows) or .sh extension (Linux).

The -Xmx parameter specifies the maximum amount of memory used by the Java Virtual Machine whereas the -Xms parameter specifies the initial amount of memory that is allocated immediately after the start. It is recommended to use the same value for both parameters.

In order to change the memory limit for VoiceObjects Desktop on Windows to 1024 MB for example, you need to change the above-mentioned parameters in the start_VODesktop.bat file as follows:

-Xmx1024m –Xms1024m

8 Caution: Note that the memory that will be reserved in total for the corresponding JVM process might be up to 50% higher than the setting defined above, as Java claims this additional memory for internal data structures such as class stores or thread stacks.

i8 Note: The respective start scripts for Tomcat are available in the Tomcat subfolder.

Cache management

It is possible to define a maximum memory limit for VoiceObjects Service caches. VoiceObjects Server will then dynamically drop caches from memory on a least-recently-used basis when the total cache size exceeds the limit.

To define the limit, locate this section within the file components_VOServer.xml located in the WEB-INF/config folder of the VoiceObjects installation:

<component id="VOCacheManager" …

In this section, find the setting:

In it you can define the maximum memory size in the format XXmb (to specify megabytes) or YYgb (to specify gigabytes). The empty default setting indicates that no memory limit is used on caches.

Port configuration

VoiceObjects Desktop and VoiceObjects Server listen on specific network ports for incoming requests from the Web browser or the media platform. By default, VoiceObjects Desktop uses port 80 and VoiceObjects Server uses port 8099. In order to change the port numbers you need to edit the configuration files for the particular Servlet engine in the WEB-INF/etc folder. The port numbers must be modified separately for VoiceObjects Desktop and VoiceObjects Server.

For Jetty as a Servlet engine the following tag must be modified in the VOServer.xml and/or VODesktop.xml files in the Jetty folder:

</Set>

For Tomcat the tag looks like this:

i8 Note: The selected port must be available for use and you need to have the correct access rights. On Linux, for example, you need to have administrator rights to use port numbers below 1024.
Make sure to keep the port settings you make on the Web application server consistent with those configured in VODesktop_Configuration.xml and VOServer_Configuration.xml.

Thread pool configuration

VoiceObjects Server utilizes several thread pools, one of which may be adjusted in very specific usage scenarios such as high-load text/Web channel or mixed channel installations.

In addition, there is the thread pool used by the servlet engine or Web Application Server to manage incoming requests. We describe how to configure this for Jetty and Tomcat. For other application servers refer to the respective vendor documentation.

8 Caution: The VoiceObjects thread pool configurations should not normally be changed, since this may severely impact stability and performance of VoiceObjects Servers. Always consult with VoiceObjects Technical Support before making any changes, particularly in production environments.
Unauthorized changes may result in loss of support.

Thread pools grow dynamically from an initial size (initial-pool-size) to a given limit depending on load conditions. Beyond the configured maximum pool size (thread-limit), temporary threads are made available up to a hard limit (hardThreadLimit) beyond which requests must wait until threads become available again. Each thread pool serves a number of channels dedicated to specific tasks. These channels have their own limits on the maximum number of threads they consume at any given time (thread-limit). When adjusting limits, these dependencies need to be taken into account.

The first thread pool configuration is located within components.xml :

<thread-manager name="DynamicMultiplexer" initial-pool-size="5" thread-limit="120" sleep-time="1000" yield-delay="5" yield-retries="5" flexible="true" hardThreadLimit="300" shrinkAmount="5">

...

...

...

...

</thread-manager>

This pool deals with various aspects of dialog processing. The three channels DialogProcessor, DialogEndProcessing, and AsyncDialogProcessor should use the same thread-limit, which should coincide with the hardThreadLimit of the thread manager.

For very high load conditions, the thread-limit on the thread manager may be increased from its default value of 120 to e.g. 300; the hardThreadLimit then needs to be increased to e.g. 400. The thread-limit settings for the three processing channels mentioned above should then be adjusted to 400, too.

8 Caution: Do not change the configuration of InfostoreChannel, this may break the proper working of Infostore.

The second thread pool configuration is located within system-components.xml:

<thread-manager name="AsyncDispatcher" initial-pool-size="10" thread-limit="60" sleep-time="1000" yield-delay="5" yield-retries="5" flexible="true" hardThreadLimit="300" shrinkAmount="5">

...

...

...

...

...

...

...

</thread-manager>

This pool deals with administrative processes within VoiceObjects Server. They are not specifically load-related and therefore typically do not need to be adjusted even in very high load situations.

8 Caution: Do not change the configuration of NotificationChannel, this may break the proper working of notifications.

The initial limiting factor in high load situations is the thread pool of the servlet engine or Web Application Server since this is where external requests first enter and are routed through to VoiceObjects Server.

For Jetty the configuration is found in the VOServer.xml file in the Jetty folder:

<Arg>

</New>

</Arg>

</Call>

To accommodate high load situations, adjust MaxThreads to cover the anticipated maximum number of simultaneous incoming requests.

For Tomcat the configuration is found in the VOServer.xml file in the Tomcat folder:

<Connector port="8099" maxThreads="150" minSpareThreads="25"

maxSpareThreads="75" enableLookups="false"

acceptCount="100" debug="0" connectionTimeout="20000"

disableUploadTimeout="true"/>

To accommodate high load situations, adjust maxThreads to cover the anticipated maximum number of simultaneous incoming requests.

Notification configuration

VoiceObjects Server provides an SNMP (Simple Network Management Protocol) option as well as an e-mail notification option that allows you to receive notifications when specific situations (typically errors or other problems) occur.

For details on notifications, refer to Chapter 8 – Notifications in the Deployment Guide.

Disable Java connectors

In certain installations it is desirable to prevent the use of Java connectors since when used wrongly or maliciously, they may impact system stability.

This can be achieved by using the parameter

in components.xml. By default it is set to false, indicating that Java connectors may be used. When setting it to true, the processing of Java connectors will always fail and provoke an Error-Connector. The processing log file contains a corresponding message in this case.

IP filtering for ping command

VoiceObjects Server provides a “ping” functionality to test availability. This if useful e.g. when working with a load balancer. For more details, refer to Chapter 4 – Service Deployment in the Deployment Guide.

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

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

Configuration of the repository database connection

In order to start VoiceObjects Desktop and VoiceObjects Server you need to have a working database connection. This requires a valid JDBC driver configuration in the VOServer_Configuration.xml and VODesktop_Configuration.xml files. A valid JDBC driver configuration consists of the following parts:

Parameter	Function
<rdbms>	Defines the type of the RDBMS (Relational Database Management System). VoiceObjects 9 supports the following DBMS types: Oracle – Oracle 9.x and 10.x DB2UDB – IBM DB2 SQLServer – Microsoft SQL Server (2000 and 2005) PostgreSQL – PostgreSQL (8 or higher) MaxDB – MaxDB
<dburl>	Defines the database connection URL for the JDBC driver. The database URL is a composition of the following configurable elements: Driver to be used; Hostname or IP address of the machine on which the DBMS is installed; port number for JDBC connections; database name (not necessary for Microsoft SQL Server).
<user>	Defines the database user ID.
<password>	Defines the respective user password.

Since driver names and database URLs significantly differ between the database types, a sample configuration for each type is provided in the configuration file.

In these examples the default host is always localhost. If the database is installed on a different machine, or if you work in cluster environments, localhost needs to be replaced by the name or the IP address of this machine.

The port numbers represent the default ports for the respective RDBMS. Do not change the port numbers unless you have a non-standard installation of your database.

The database name depends on the initial configuration of the database and is usually specified by the database administrator. For more information on this see the Installation Guide or ask your database administrator.

i8 Note: You can only specify one database configuration in a configuration file. The other sample configurations must be deactivated or removed.

To prevent conflicts between the various JDBC drivers, the VoiceObjects Installer only copies the required JDBC driver package into the WEB-INF/lib folder. When switching from one RDBMS type to another or updating your database installation, you need to replace the respective JDBC driver in the WEB-INF/lib folder. The JDBC driver packages (jar-files) for the supported RDBMS types are located in the respective subfolders of the WEB-INF/drivers/db directory.

Using automatic Windows sign-on for SQL Server

When using Microsoft SQL Server as the database for the Metadata Repository, it is possible to use single sign-on based on the Windows account of the user running VoiceObjects Desktop or VoiceObjects Server. Note that this works only on Windows.

To enable automatic sign-on, do the following:

1. Copy the file ntlmauth.dll located in the folder <VOICEOBJECTS_HOME>\Platform\WEB-INF\driver\db\SQLServer\ntlmauth/<achitecture>/ of your VoiceObjects installation into the folder %WIN32%\system32\. Depending on your CPU and your operating system choose either the x86, x64, or IA64 variation.

2. <rdbms> must be SQLServer.

3. As <dburl> use jdbc:jtds:sqlserver://<server>:1433/<DB>;DOMAIN=<domain> where <server> is the server on which you run SQL Server, <DB> is the name of your database, and <domain> is the Windows login domain.

4. Leave both <user> and <password> empty.

Configuration of the System logging and Custom logging DB connection

The configuration of the System logging database connection and the Custom logging database connection is equivalent to the Configuration of the repository database connection (see above).

In order to configure these connections you need to select systemlogdb or customlogdb as connection name instead of repositorydb as shown in the examples below for the SQLServer database type.

Server name

During the installation of VoiceObjects with the VoiceObjects Installer, the name of the logical server is specified (set to VOServer by default). In order to change this setting you need to modify the value of the following tag:

<servername>VOServer</servername>

Keep in mind that the name defined here must match the name defined in the corresponding Server object created in the Metadata Repository. Also note that the Server object has to exist before the logical server can be started.

Connector URL

The Connector URL specifies the URL used by the media platform to access VoiceObjects Server. By default this is the standard URL of VoiceObjects Server. The standard URL consists of the machine name, the port number on which the Servlet engine is listening for requests, and the context path of the DialogMapping Servlet. Within the local network this URL is only valid if the machine is placed behind a firewall, or if NAT (Network Address Translation) is used. If the server running the media platform is not part of the local network, it will not be able to access the server by using the standard URL. In this case the value of the <connectorURL> tag must specify a URL that points to the server from outside. The server will then use this URL for the VoiceXML pages it generates instead of the standard URL.

By default the <connectorURL> tag is empty, which means that the standard URL is used. Any other value will replace the standard URL.

The connector URL can be defined separately for the text channel, the Web channel, and the voice / video channels. The latter is used as default if nothing else is defined.

</connectorURLs>

As an example, if you are running a server on a machine with IP address 172.22.23.59 on the standard port 8099, then the URL for the text channel would be:

<connectorURL type=”text”>
http://172.22.23.59:8099/VoiceObjects/DialogMapping
</connectorURL>

Secure connection to media platform

VoiceObjects Server can communicate with the media platform using an HTTPS connection instead of the default HTTP connection. This is a configuration of the Web application server being used, and is therefore not described here in detail.

When using a secure connection, you need to define the <connectorURL> (see above) with an https:// URL.

Transfer custom data from media platform

For the voice and video channels, VoiceObjects automatically retrieves information such as caller input, recognition confidence, etc. from the media platform. This information is assembled using JavaScript code that is referenced from within the VoiceXML pages.

Within the JavaScript files, which can be found in <VOICEOBJECTS_HOME>\Platform\Resources\System\Script there is an extension point function customCount(event). It can be modified to store custom information in the customShadow variable that is automatically transferred back to VoiceObjects Server and made available using the Expression function SESSION(customShadow).

Cluster mode

The <standalone> tag influences the start behavior of the server manager. If it is set to network VoiceObjects Server tries to join a server manager in the local network. If it is set to local (the default) only server managers running on the local machine are used. If it is set to singleton VoiceObjects Server does not try to contact any other server manager.

<standalone>local</standalone>

When configuring a cluster installation consisting of multiple machines running VoiceObjects Server processes, standalone mode must be set to network on all machines to ensure that cluster communication works correctly. Refer to Configuring a VoiceObjects Cluster below for more details on how to setup a cluster.

8 Caution: Setting this value to network only has an effect if your VoiceObjects Server license enables the clustering option.

i8 Note: The default setting for VoiceObjects Desktop is singleton and should not be changed.

Force state creation

If the <forceStateCreation> tag in the file components.xml is set to true the server can be forced to ignore existing caches for itself and all of its services and create new ones for them. This option might be useful if the existing caches are corrupted and require a hard replacement. If this option should be used in a cluster environment it is recommended to perform the following steps in the given order:

1. Shutdown all server instances of your cluster.

2. Set <forceStateCreation> to true for a single server instance in the cluster only.

3. Start this particular server instance.

4. Reset the option <forceStateCreation> to false.

5. Start all remaining server instances in the cluster.

i8 Note: Force state creation will not create new caches for services, which have set the option Retain caches on shutdown to true.

Cleanup repository

The <cleanupRepository> tag in the file components.xml can be set to disabled, local and global. If set to local all states for servers and services on the local machine will be deleted from the repository, if set to global all states for all servers and services from within the complete cluster will be deleted from the repository. If this option should be used in a cluster environment it is recommended to perform the following steps in the given order:

1. Shutdown all server instances of your cluster.

2. Set <cleanupRepository> to local or global for one server instance.

3. Start this particular server instance.

4. Reset the option <cleanupRepository> to disabled.

5. Start all remaining server instances in the cluster.

Password and login policies

VoiceObjects provides various configuration options regarding password and login policies. For details refer to Chapter 2 – User Management - Basic Topics.

Dynamic property retrieval

Configuration settings made in files such as VODesktop_Configuration.xml and VOServer_Configuration.xml can dynamically be overwritten e.g. to retrieve passwords from secure storage systems instead of specifying them in the configuration files. This is done by supplying custom code that is activated upon startup of VoiceObjects Desktop and VoiceObjects Server.

To enable dynamic configuration, set the following configuration property in the file vo.properties located in the <VoiceObjects_Platform>\Platform\WEB-INF\properties folder to identify the class to be used:

vo.contextmodifier=com.yourCompany.ContextModifierImplementation

Your class needs to implement com.voiceobjects.factory.container.ContextEntryModifier and overwrite the getEntriesToModify method as shown in the following sample code:

import com.voiceobjects.factory.container.ContextEntryModifier;

import java.util.HashMap;

import java.util.Iterator;

import java.util.Map;

public class TestContextModifier implements ContextEntryModifier

{

public Map<String,String> getEntriesToModify(

final Map<String,String> contextEntries )

{

if ( null != contextEntries )

{

System.out.println( "contextEntries=" +

contextEntries.size() );

for ( Map.Entry<String, String> entry :

contextEntries.entrySet() )

{

System.out.println( entry.getKey() + " = " +

entry.getValue() );

}

final Map<String,String> map = new HashMap<String,String>();

map.put( "dbconf.repositorydb.user", "voadmin" );

map.put( "dbconf.repositorydb.password", "manager" );

return map;

}

You can overwrite the following properties:

Property	Definition
dbconf.repositorydb.rdbms	Database vendor used for repository DB. One of DB2UDB, MaxDB, MySQL, Oracle, PostgreSQL, SQLServer.
dbconf.repositorydb.dburl	URL defining the connection to the repository DB.
dbconf.repositorydb.user	User name for the repository DB connection
dbconf.repositorydb.password	Password for the repository DB connection
dbconf.systemlogdb.@enabled	Indicates whether System DB Logging is enabled. Either true or false.
dbconf.systemlogdb.rdbms	Database vendor used for System Logging DB. One of DB2UDB, MaxDB, MySQL, Oracle, PostgreSQL, SQLServer.
dbconf.systemlogdb.dburl	URL defining the connection to the System Logging DB.
dbconf.systemlogdb.user	User name for the System Logging DB connection
dbconf.systemlogdb.password	Password for the System Logging DB connection
dbconf.customlogdb.@enabled	Indicates whether Custom DB Logging is enabled. Either true or false.
dbconf.customlogdb.rdbms	Database vendor used for Custom Logging DB. One of DB2UDB, MaxDB, MySQL, Oracle, PostgreSQL, SQLServer.
dbconf.customlogdb.dburl	URL defining the connection to the Custom Logging DB.
dbconf.customlogdb.user	User name for the Custom Logging DB connection
dbconf.customlogdb.password	Password for the Custom Logging DB connection

Change the path to the log folder

The path to the log folder that contains all log files being created by VoiceObjects can me moved to another location. By default the log folder is created below the <VoiceObjects_Platform>\Platform\WEB-INF folder of your VoiceObjects installation. In order to change this path you need to process the following steps:

1. Open the configuration files VODesktop_logSettings.xml and VOServer_logSettings.xml.

2. Replace all occurrences of the term ${ovapRoot} with the new absolute path (e.g. c:/<myFolder>). It is strongly recommended to not change the remaining subpath starting with /log …

3. Restart VoiceObjects Desktop and VoiceObjects Server.

i8 Note: When moving the log folder as described above you will lose the connection to the log files from within the Control Center.

Additional Configuration

In addition to the initial configuration settings for VoiceObjects Server and VoiceObjects Desktop there is one more setting influencing the runtime behavior of VoiceObjects Server, which is not covered by the VoiceObjects Installer.

Session tracking mode

The session tracking mode specifies the mechanism used to identify the current HTTP session during a call. You may use session tracking based on cookies generated by the Servlet engine, or a session tracking based on dialog IDs generated by VoiceObjects Server. The default mode is Custom session tracking using dialog IDs. If a cookie-based session tracking is preferred, the value of the <sessionTrackingMode> tag should be changed to Cookie.

<sessionTrackingMode>Custom</sessionTrackingMode>

Configuring a VoiceObjects Cluster

Configuring a cluster installation consists of three steps:

1. Determine the number of server machines and the number of server instances running on them, based on the sizing recommendations given by VoiceObjects. See Appendix A – Sizing and Configuration Recommendations for details.

2. Set up each required server machine with the desired number of server instances. Refer to the paragraph Configure multiple server instances per machine below for detailed information on how to do this for a single machine.

3. Define some cluster related settings as mentioned in the paragraph Cluster configuration settings.

8 Caution: Cluster configurations are only possible if the clustering option is supported by your license key.
The maximum supported number of instances per logical server is 16, which can be realized on between 4 and 16 machines. All machines involved in the cluster need to run the same number of server instances.
Also, clusters are only supported within the same local area network (LAN).

Configure multiple server instances per machine

In order to configure multiple server instances on the same machine, multiple instances of the hosting Web application server must be configured accordingly.

In a nutshell, you need to make sure that each server instance uses a different TCP port for listening to HTTP requests, and writes into separate log files.

The simplest approach is to install several copies of VoiceObjects Server into different system paths or to copy the folder [VoiceObjects]\Platform several times and rename it to Platform_2, Platform_3, etc. As an example, this approach is described below to configure two server instances for a configuration using Jetty 5 as Web application server on a Windows machine.

8 Caution: Take care to follow the complete instructions given below as otherwise your installation may not be manageable afterwards.

1. Install VoiceObjects by running the VoiceObjects Installer.

2. After successfully running the Installer, locate the VoiceObjects folder on your file system, create a copy of its Platform folder and rename it to Platform_2.
In the following the original platform folder is referred to as Platform_1, whereas the copied platform folder is referred to as Platform_2.

3. Open the folder Platform_2\WEB-INF\config and delete the file .ezlm20jk if it exists. This file is managing the license information for this server instance and cannot be copied, but will be generated from scratch once the corresponding server instance has started successfully.

Configure used Web server (here Jetty 5)

1. Open the files
[VoiceObjects]\Platform_1\WEB-INF\etc\Jetty5\VOServer.xml
(referred to as VOServer1.xml) and
[VoiceObjects]\Platform_2\WEB-INF\etc\Jetty5\VOServer.xml
(referred to as VOServer2.xml)
in a text editor. In these configuration files, unique settings for the TCP port and for the log file destination for each instance of Jetty must be provided.

2. First, locate the line
<SystemProperty name="jetty.port" default="8099"/>
and change the Jetty port to two different numbers, for example default="8101" for VOServer1.xml
and
default="8102" for VOServer2.xml.

3. Next, locate the text snippet
<Arg>[VoiceObjects]\Platform</Arg>
and change it to
<Arg>[VoiceObjects]\Platform_1</Arg> for VOServer1.xml and
<Arg>[VoiceObjects]\Platform_2</Arg> for VOServer2.xml

4. Last, locate the text snippets
/logs/yyyy_mm_dd.voserver.request.log
/logs/yyyy_mm_dd.voserver.jetty.log
and change them to
/logs/yyyy_mm_dd.voserver1.request.log
/logs/yyyy_mm_dd.voserver1.jetty.logfor VOServer1.xml and

/logs/yyyy_mm_dd.voserver2.request.log
/logs/yyyy_mm_dd.voserver2.jetty.log for VOServer2.xml

Configure VOServer_Configuration.xml

1. Open the files
[VoiceObjects]\Platform_1\WEB-INF\config\VOServer_Configuration.xml (referred to as VOServer_Configuration1.xml) and
[VoiceObjects]\Platform_2\WEB-INF\config\VOServer_Configuration.xml (referred to as VOServer_Configuration2.xml).

2. Adapt the setting <instancePort> to reflect the new HTTP ports as assigned in the previous step. In our examples, the ports need to be changed to 8101 for VOServer_Configuration1.xml and 8102 for VOServer_Configuration2.xml, respectively.

3. Also define a unique name for each server instance with the setting <instanceName> or leave it empty for both server instances. In this case VoiceObjects concatenates the setting <instanceIP> and <instancePort> in order to build a unique identifier. Refer to Change a server instance name above for more details.

4. Locate the tag <standalone> and set it to network to allow the server instances to join a cluster in the network.

5. If the <connectorURL> was explicitly defined during installation, you need to locate and change these settings accordingly.

Automatic start script

8 Caution: When creating a start script that starts the Jetty server instances automatically, make sure to include a delay between each start that is sufficiently long to allow each instance to fully start. This is required because the process of starting and registering a server instance on a cluster may take some time and if in the meantime an additional server instance has been started, this may lead to situations of misconfiguration.

Cluster configuration settings

8 Caution: Make sure that when configuring a cluster, each machine participating in the cluster has a statically assigned IP address. Do not use DHCP.
Also, on Windows make sure that you disable media sensing. For more information, refer to http://support.microsoft.com/default.aspx?scid=KB;en-us;q239924.

1. To define the general cluster settings open the file
[VoiceObjects]\Platform\WEB-INF\config\system-components.xml

2. First locate the following section near the top of the file
<communication-properties>
TCP(sock_conn_timeout=200;bind_addr=##ADDR##;start_port=7800;loopback=true):TCPPING(initial_hosts=##ADDR##[7800];port_range=4;

3. In the section TCPPING, augment the list of initial_hosts by the comma-separated list of the IP addresses of all machines involved in the cluster by replacing the placeholder ##ADDR##. Regardless of how many server instances you plan to run on each machine, only list it once. The entries you list here must match the <instanceIP> entries on the respective machines.
In the following example, the two machines 172.22.23.45 and 172.22.23.68 participate in a cluster
<communication-properties>
TCP(sock_conn_timeout=200;bind_addr=##ADDR##;start_port=7800;loopback=true):TCPPING(initial_hosts=172.22.23.45[7800],172.22.23.68[7800];port_range=4;

8 Caution: It is not allowed to enter any blanks in the comma-separated list of IP addresses.

i8 Note: The same system-components.xml file can be used for all machines involved in the cluster as well as for all server instances installed on them.

The parameter port_range defines the maximum number of server instances to be run on a single machine. The recommendation is not to run more than four instances per machine and to keep the number of server instances per machine balanced across the entire cluster. In order to achieve the best performance this parameter should always reflect the maximum of server instances running on a machine. For example, if your cluster contains three machines running two server instances each, the port_range parameter should be set to two for all of them.

The parameter sock_conn_timeout influences how individual server instances within the cluster find each other. Should you encounter problems with this (e.g. server instances not joining the cluster upon startup, or dropping out of the cluster intermittently), you may increase this parameter up to values around 1000.
Normally, the parameter should be left unchanged.

Whether to identify the cluster participants by their IP addresses or by their host names depends on your network configuration. If you are unsure which one to use, try using IP addresses first. If you encounter problems, switch to host names.

Note that the Metadata Repository connection must be textually identical in the VOServer_Configuration.xml files of all instances involved in the cluster. It is not sufficient to merely point to the same DB using different URLs (e.g. localhost for one instance and the machine name for a different instance).

When starting up a cluster, make sure that you start the separate server instances one after the other, waiting until each instance is fully operational before starting the next one. A server instance is fully operational once it has printed a line

[INFO] VoiceObjects Server [<version number>] STARTED SUCCESSFULLY

on the console.

8 Caution: For proper communication within the cluster it is important that the clocks on all machines involved in the cluster are synchronized. It is strongly recommended to use an NTP (Network Time Protocol) server.

Configuring the Logging Facilities

VoiceObjects uses an advanced logging mechanism based on the LogKit toolkit of the Apache Jakarta Project. Logging is a widely used functionality that simplifies the task of detecting errors and provides valuable operational data that allows administrators to diagnose problems when they arise.

One of the advantages of this logging toolkit is a fine-grained control over which logging statements are printed. In some instances you may wish to enable all logging statements. In others you may wish to disable debug messages. It was out of this need that the notion of priorities was invented. A priority describes the urgency of a log event. Below is a list of priorities that are usable within the VoiceObjects platform:

Priority	Definition
DEBUG	Developer-oriented messages, usually used during development of the application.
INFO	Useful information messages such as state changes, client connection, user login etc.
WARN	A problem or conflict has occurred, but it may be recoverable. Then again, it could be the start of the system failing.
ERROR	A problem has occurred, but it is not fatal. The system will still function.
FATAL_ERROR	Something caused the entire system to fail. This indicates that an administrator should restart the system and try to fix the problem that caused the failure.

Each logger instance is associated with a priority. This allows you to limit each logger so that it only displays messages with certain priority (or higher). So if a DEBUG event occurred and the logger's priority is WARN, the log message is suppressed.

In a complex environment with VoiceObjects it is not sufficient to suppress or enable log messages based on priorities. For instance you may wish to specify a log level for a whole group of loggers without defining it separately for each of them. To accomplish this the logging toolkit uses a concept called categories. Categories can be nested into one another to build up a tree-like hierarchy. Each embedded category inherits the priority of its parent if it has not been explicitly set. In addition to the priority, the child inherits the log target from its parent.

Log targets are the destination of log messages. Possible destinations for writing to include the console, a file, a database, a network connection etc. Currently only the file and the console targets are used.

The configuration of the various targets and loggers is accomplished by two configuration files, VOServer_logSettings.xml for VoiceObjects Server and VODesktop_logSettings.xml for VoiceObjects Desktop. Each file consists of three sections:

Section	Function
<factories>	The factories section defines the `target factories` that are used to create the required `log targets`.
<targets>	The targets section defines the individual `log targets`. The element name of a target definition corresponds to a type attribute of a <factory> element. A target definition may also specify properties such as output format and the file naming scheme.
<categories>	The categories section assembles everything together. The log-level attribute gives the logging priority to the `logger` of that category. <category> elements have <log-targets> children which define the `log target`s for a particular logging category.

By default, the log files of VoiceObjects Server and VoiceObjects Desktop are located in the WEB-INF/log/VOServer_log and WEB-INF/log/ VODesktop_log folders respectively. Log files referring to VoiceObjects Server have a SRV_ prefix while log files referring to VoiceObjects Desktop have an API_ prefix. In addition to these files, which typically contain all log messages, there is a log file called VoiceServer_Messages.log, which only contains the root causes. This file usually is the most important one for users. In addition, there are also two bootstrap files in the WEB-INF/log folder containing the log messages from the startup phase.

By default, the log level of nearly all loggers is set to WARN. In most cases this is adequate but during installation and application development it may be useful to change the log level of the URLLogger and the VXMLLogger in the VOServer_logSettings.xml file to DEBUG.

<log-target id-ref="VXMLLoggerTarget"/>

</category>

<log-target id-ref="URLLoggerTarget"/>

</category>

The URLLogger logs the URLs requested from the media platform whereas the VXMLLogger logs the VoiceXML pages generated in response to these requests.

Disable logging and tracing

Logging and tracing can be disabled completely using the following settings in WEB-INF/properties/vo.properties:

vo.log.disable=true

vo.tracing.disable=true

This can be relevant for environments dealing with highly sensitive data.

i8 Note: Keep in mind that disabling of logging impacts the ability to analyze potential problems and to provide efficient support. Therefore, this switch should be used with caution.

When logging is disabled, no log entries are written to files. This also includes Log objects with destination Log File.

When tracing is disabled, no trace files are created, independently of any settings made in VoiceObjects Desktop.

Writing into syslog

VoiceObjects also supports writing into the standard log daemon syslog. In order to activate this, open the configuration files VOServer_logSettings.xml and VODesktop_logSettings.xml in the folder WEB-INF/config/. For all log targets (in each of both files there are approximately 30 different log targets available) locate the following text snippet:

disabledTargets="EmbeddedSyslogTarget"

and adjust this to

disabledTargets=""

The syslog will be activated for this specific log target. As the syslog can be activated or deactivated for each log target separately, only some of the log targets may be configured to write into syslog, whereas others may remain unchanged and write to the standard log files.

The referenced EmbeddedSyslogTarget existing for each log target is similar to the following text snippet:

[{instanceName}] [%40.40{category}] :%{message}\n%{throwable}

</format>

</syslog>

The hostname and port values must correspond to the hostname and port number of the server machine running the syslog daemon. The facility attribute can be used to identify the log file to which the syslog daemon should write this particular information, typical values are USER or SYSTEM. Contact your syslog administrator for more information on the different log files supported by the corresponding syslog daemon in your environment.

Finally a restart of both VoiceObjects Desktop and Server is needed to activate the logging into the syslog.

Log file rotation

Log file rotation can be specified for each log target. When enabled, the log entries will be written to the respective log file until the specified size, date or time is reached. It is possible to combine multiple rotation conditions with logical “or” operations. Additional log entries will be written to a new file. The file naming strategy for file rotation is specified in the type attribute of the rotation tag. Possible values are unique and revolving.

Rotation type revolving

If the file naming strategy revolving is selected, the system will revolve over a certain number of files defined with the additional attribute max, which specifies the maximum number of rotations. If this limit is reached, the oldest log file will be overwritten. If for instance max is set to 5 this means that only 5 log files will be created, after the fifth log file the system will start again with the first log file and overwrite it. Optionally the start value for the revolving mechanism can be defined with the init attribute, e.g. if init is set to 101 and max is set to 103 this will result at the end in 3 log files of the kind [filename].101, [filename].102 and [filename].103.

i8 Note: The rotation option revolving should always be used if the available space on the file system is limited; together with using size as criteria for the rotation the maximum amount of space can easily be calculated.

Rotation type unique

If the naming strategy unique is selected, two additional attributes pattern, describing the file name , and suffix defining the file extension (e.g. .log), have to be specified. A table describing all letters that might be used within the pattern attribute can be found at the end of this chapter. Note that when using this option the amount of space occupied on the file system is permanently growing. In order to avoid that the hard disk is running out of space either delete or archive old log files, or use other criteria like the log level to decrease the level of log information written to the hard disk. The filename of the log files will be build by the following rule: [filename][pattern][suffix].

The examples listed below describe the settings that specify when the system should move over to the next file (either creating a new one or overwriting an existing one).

Rotate by size

If a rotation by size is desired, the size (in bytes) is specified as the criteria. The element size specifies the maximum size for each log file. When a file has reached this limit, the system will move over to the next file. Instead of specifying the size in bytes (e.g. 1000000 for 1 Million bytes) as short form 1m can be used to limit the size of each log file to 1 MB.

Example for rotation type revolving:

<or>

</or>

</rotation>

By setting these values, the maximum space that the log files will occupy on the hard disk can be calculated. In the example above, a maximum rotation of 249 will create 250 log files with 1 MB each, for each log file per server instance.

Example for rotation type unique:

<or>

</or>

</rotation>

In this example a growing number of log files each of size 1 MB will be created. As the filename is extended by the pattern and suffix attribute it will be build as follows: [filename][yyyy-MM-dd-hh-mm-ss][.log]

Rotate by time

Time-based rotation means that a rotation occurs at the time defined in the format HH:MM:SS. If for example the file is to be rotated every night at 1 AM, the configuration will be the following for rotation type unqiue:

<or>

</or>

</rotation>

If the rotation has to occur every day at midnight, and rotation type is revolving, the configuration looks as follows:

<or>

<date>yyyyMMdd</date>

</or>

</rotation>

Rotate by size and time

In the following case a new file will be started every day at 12:00 noon or if the file size is 10 MB:

<or>

</or>

</rotation>

Rotate by interval

If the rotation has to occur in a specific interval, e.g. every twelve hours, the interval can be specified as follows:

<or>

</or>

</rotation>

If you want to rotate a log file at the beginning of every new week (=every Monday) the rotation needs to be configured in the following way:

<or>

</or>

</rotation>

In the example above the time is formatted with the format string w that returns the week of the year, e.g. for July 29, 2004 it returns 31. The next log file will be started on Aug. 2, 2004 because this timestamp would be formatted as 32. The format strings that can be used to define the interval are the same as those that might be used within the pattern attribute to generate the filename. See the table below for a complete overview.

The decision whether to start a new log file is based on date comparisons that are done before writing the log message. Timestamps from the last and the current log message are compared, and if they are different a new log file will be created. All timestamps are formatted with the format string specified in the date element using the SimpleDateTime formatter (Java). The following pattern letters are defined:

Overview of abbreviations

Pattern letter	Date or time component	Example
G	Era designator	AD
y	Current year	1996 (=yyyy), 96 (=yy)
M	Current month in year	07 (=MM)
w	Week in current year	27 (=w)
W	Week in current month	2 (=W)
D	Day in current year	189 (=D)
d	Day in current month	10 (=d)
F	Day in current week	2 (=F)
E	Day of current week	Tuesday
a	AM/PM marker	PM
H	Hour of current day (0-23)	0
k	Hour of current day (1-24)	24
K	Hour in AM/PM (0-11)	0
h	Hour in AM/PM (1-12)	12
m	Minute of current hour	30
s	Second of current minute	55
S	Millisecond of current second	978
z	Abbreviation of current timezone	PST
Z	Difference of current timezone to GMT	-0800

UTF-8 Support

VoiceObjects provides full UTF-8 support in order to use locale specific characters throughout the complete product. This includes object property fields such as name and description, prompt texts in Audio objects, inline grammars as well as external grammar files and data retrieved or written by Connector and Log objects.
If you plan to use non-western European special characters in your applications it is recommended to configure VoiceObjects Desktop and VoiceObjects Server to UTF-8.

i8 Note: Although VoiceObjects Desktop correctly interprets all UTF-8 characters, Internet Explorer is restricted to a subset of characters. As Internet Explorer is the only supported browser for VoiceObjects Desktop for Web, these restrictions also apply when working with VoiceObjects Desktop for Web.

Length restriction

Some locale specific characters require up to 4 bytes when being stored. When using such characters in object names, descriptions or other property fields, note that the maximum length of these fields is interpreted in bytes rather than in characters; consequently, the maximum length of the respective fields may not be used entirely.

Example: For the Name field in an object editor, which has a maximum length of 256 1-Byte characters, you will be able to use up to 64 4-Byte characters.

i8 Note: You cannot use special characters in reference IDs, VoiceObjects Service Names (VSNs), and user IDs.

VoiceObjects configuration

In order to configure VoiceObjects to use UTF-8, you need to adjust the entry <encoding> in the files VOServer_Configuration.xml, VODesktop_Configuration.xml and Eclipse_Configuration.xml (only relevant when using Desktop for Eclipse):

i8Note: The encoding must be the same for all Server and Desktop instances throughout one installation.

Database configuration

Make sure that your database is correctly set up to support UTF-8. In addition you need to make sure to run the appropriate UTF-8 SQL scripts. These scripts are located in the corresponding subfolder of your database under WEB-INF/driver/db and are suffixed with UTF8 (e.g. LDCreateUTF8.sql).

For some databases not all scripts have a special UTF-8 version. In these cases running the standard scripts is sufficient for UTF-8 characters to work. VoiceObjects supports UTF-8 on all supported database platforms.

i8 Note: Upgrading from a non-UTF8 Metadata or Infostore Repository to a UTF-8 enabled version is not supported. If you want to enable a non-UTF-8 Metadata or Infostore Repository for UTF-8 contact VoiceObjects Professional Services.

Project Documentation

When generating PDF documentation for your project you need to configure a font capable of displaying UTF-8 characters. This is done in the Desktop configuration files Eclipse_Configuration.xml (for Desktop for Eclipse) and VODesktop_Configuration.xml (for Desktop for Web). For a description of how to do this, refer to Chapter 9 – Project Documentation and Storyboard Export in the Desktop for Eclipse Guide or to Chapter 7 – Basic Commands in the Desktop for Web Guide respectively.