IBM WebSphere Voice Toolkit
V6.0.1.1
Readme

March 2006

Note: Before using this information and the product it supports, read the general information under Notices in this document.

IBM(R) WebSphere(R) Voice Toolkit is the new name of the previously released software entitled Voice Toolkit for WebSphere Studio. Also, for users familiar with Voice Toolkit for WebSphere Studio software and documentation, the term call flow is now referred to as communication flow.

Contents

This document contains the following topics for the IBM WebSphere Voice Toolkit:

• Introduction
• Getting started
• What's new
• Known problems and software limitations
  • General
  • Language-specific considerations
  • Editors
  • Multi-paged SRGS-XML Grammar Editor
  • Grammar Conversions
  • Communication Flow Builder
  • Grammar Test Tool
  • VoiceXML testing and debugging
  • WebSphere Voice Toolkit documentation
• Notices
• Trademarks

Introduction

This readme provides information on known problems and software limitations for the WebSphere Voice Toolkit.

For installation information, see the IBM WebSphere Voice Toolkit V6.0.1.1 Installation Readme, located in the <IBM_Rational_dir>\VoiceToolkit\Readme directory, where <IBM_Rational_dir> is the full path to the IBM Rational(R) Software Development Platform.

Getting Started

To launch the WebSphere Voice Toolkit, click Start > All Programs > IBM Rational and select your base Rational product. For example, if you have Rational Application Developer (RAD) installed, click IBM Rational Application Developer > Rational Application Developer.

For information on using the toolkit, refer to the online Help. From the Help menu, click Help Contents. When the Help window appears, select Developing Voice applications from the list.

For additional information about the samples included with the toolkit, see the sample readme files that are located in each of the sample directories in <IBM_Rational_dir>\VoiceToolkit\Samples.

• Developing Voice applications

In addition to the toolkit help topics, this package contains related publications in PDF format. These documents are available from the Help > Help Contents pane. For example, click Developing Voice applications and expand the Related documents folder to open the Developing Java Applications publication.

To view or print PDF files, use Adobe Reader, Version 4.0.5 or later. For optimum viewing, use Adobe Reader, Version 7.0, available at http://www.adobe.com.

What's new

The following features and functions are new or updated in this release:

IBM Rational Software Development Platform base support

IBM WebSphere Voice Toolkit is now based on the IBM Rational Software Development Platform, which is installed with IBM Rational Application Developer (RAD) 6.0.1.1, IBM Rational Web Developer (RWD) 6.0.1.1, or IBM Rational Software Architect (RSA) 6.0.1.1.

The Rational product you choose is dependent on the application being developed. For example, if you develop applications for WebSphere Voice Server, the minimum product requirement is RWD. However, to take advantage of all of the functions of the Rational Software Development Platform we recommend using RAD.

A free trial of Rational Application Developer may be available for download at http://www.ibm.com/software. Select Trials and Bites and then search for Rational Application Developer.

VoiceXML 2.1 support

This allows you to create and test VXML 2.1-based applications.

Multi-paged SRGS-XML Grammar Editor

Includes a new graphical environment for creating command-and-control grammars and their associated rules.

Communication Flow Builder

Includes the following enhancements:

• A new, improved user interface.
• An import feature, which supports the import of VoiceXML files created by Call Flow Builder V5.0 or higher.
  This allows you to recreate the graphic for a communication flow from a previously-generated XML file.
• Navigation of .xml, .vxml, or .cfb files directly from the canvas.
• Added support for the use of Reusable Dialog Components (RDCs) in the application flow, as well as support for RDC development.
• A Prompt Configuration window, which allows you to create prompts based on a list of shorter, more manageable components.

Test Grammar on MRCP

Allows you to compare audio files (what is said) versus what is understood and provides a confidence score of what was recognized. This tool supports WebSphere Voice Server V5.1.

Voice Trace Analyzer

Displays information and statistics on the grammar recognition events that have been logged on a WebSphere Voice Server V5.1 server for analysis of recognition accuracy and tuning of the grammars and server settings.

Prompt Manager

Organizes the audio files in your project for easier generation of prompts, as well as exporting and importing of professionally recorded audio.

SIP-based VoiceXML Simulator

A VoiceXML interpreter and debugger that has SIP connectivity from a virtual "phone" in the toolkit, and uses MRCP to interface with the speech engines just like a real IVR.

Known problems and software limitations

General

• If after installation of the toolkit some functions do not appear or work as expected, please close your IBM Rational Software Development Platform and restart it using the –clean command line parameter. You can add this parameter by viewing the properties of the startup file and just adding –clean to the executable (example: rationalsdp.exe –clean). This increases the startup time slightly and needs to be done only once. After you have restarted you can remove the –clean parameter so that it is not executed again.
  NOTE:
  If you use this parameter more than once, the only thing that you notice is a longer start-up time for your Rational Software Development Platform.
   
• If you cannot start the IBM Voice Server, it might be related to a lengthy installation path.
  Workaround:
  It is recommended that the Rational Software Development Platform product be installed to a directory such as C:/rad6 or similar.
   
• If your program stops responding, close the Rational Software Development Platform and any javaw.exe processes. If this fails to resolve the problem, restart your computer.
   
• In some configurations, one or more javaw.exe processes might continue to run after you exit the toolkit, particularly after an abnormal termination of the program.
  Workaround:
  Use the Windows Task Manager to locate and end these processes.
   
• The projects and files that you create using the WebSphere Voice Toolkit are saved in the workspace used by the Rational Software Development Platform. If you uninstall the toolkit, the workspace remains on your system so that the files are still available.
  
 
• Your microphone can pick up output from your computer speakers and interpret it as words in a grammar. To avoid this, turn down the volume on your speakers or use a headset.
  
 
• If you deploy your grammars and lexicon files to a web server for testing, you might find that updates to those files are not being loaded by the Voice Server test environment in the VoiceXML Simulator or the Test Grammar on MRCP tool. This occurs because the server honors the caching policies of the web server to avoid having to retrieve the same document repeatedly. To circumvent this, you should set the caching policies for the web server such that the files are not cached, or assign an immediate expiration in the caching properties of your application documents when deploying them to your web server.
  
 
• If you create an audio file from a text file or input text field that contains a large amount of text, you might find the length incorrectly shows 0.0 seconds. The audio file is created correctly, however the initial display of the length data is incorrect. To display the correct length, press Play or close and re-open the audio file in the editor.
  
 
• If you experience JavaScript related errors, it might be due to the incorrect version of the Rhino JavaScript Interpreter. The Rational Software Development Platform ships with the Rhino JavaScript Interpreter v1.5 release 2, however this toolkit package has been optimized to work with Rhino JavaScript Interpreter v1.5 release 3. It is recommended that this version, Rhino JavaScript Interpreter v1.5 release 3, be downloaded from http://www.mozilla.org/rhino/download.html using the download link rhino15R3.zip.
  Important: Do not install any other version than v1.5 release 3, as this will cause error conditions with this product.

  To install the Rhino JavaScript Interpreter download the rhino15R3.zip, extract the file js.jar, and copy to the following directories:

  <IBM_Rational_dir>\eclipse\plugins\com.ibm.voicetools.es_6.0.1
  <IBM_Rational_dir>\runtimes\base_v51\InstalledApps\localhost\WVX5.1-localhost.ear
  

 
• Files saved in the following directories are deleted when uninstalling the WebSphere Voice Toolkit. If you create files in these directories, copy them to another folder before uninstalling the toolkit:
   
  • <IBM_Rational_dir>\eclipse\logs
  • <IBM_Rational_dir>\VoiceToolkit
     
• When you change the Workbench or Workbench > Appearance preferences, the Restore Defaults button might not restore the original defaults. Close and restart the Rational Software Development Platform for changes to take effect.
   
• If you receive an "Internal Error - Widget Disposed" error message, close and restart the Rational Software Development Platform to recover from the error.
   
• If you need to alter the tracing options for the Local Voice Server Environment, follow these steps.
  1. Start the server from Voice Perspective menu by clicking Run > Start Voice Server.
  2. Open your internet browser to: http://localhost:9091/admin.
  3. Then alter the tracing options.
   
• Use only alphanumeric characters and spaces for directory, folder, and file names. Names should not include non-alphanumeric characters. For example:

   ~!@#$%^&*) 

• To import or use files from a network resource, map a drive letter to that network resource and import from the network drive.
   
• You might experience a problem running VoiceXML applications when using personal firewall software on your computer. If you encounter an error message, such as "Host manager did not initialize properly," disable your firewall and run your VoiceXML applications again.
   

Language-specific considerations

• WebSphere Voice Toolkit 6.0.1.1 does not support Lexicons for AP Languages. This is because a required feature, part-of-speech, is not supported by the WebSphere Voice Server 5.1 MRCP server.
  
   
• If you choose to install non-IBM Text-to-Speech (TTS) languages for use on your voice application server, such as WebSphere Voice Server, you should consult the vendor's documentation for details on the vendor's implementation of VoiceXML 2.1 and Speech Synthesis Markup Language (SSML). In addition, if you use another vendor's languages, you should also use that vendor's tools for generating pronunciations. If you use IBM tools to produce SSML for TTS output, the resulting code might not run as expected in a deployment environment for that language.
   
• Do not create a project name using DBCS characters. If you do, you receive validation errors and XML files do not validate.
   
• When using the Unknown Pronunciation view, Cantonese words are flagged as "unknown." For correct Cantonese functionality of the tools, your Windows regional setting should be "Chinese-Taiwan", rather than "Chinese-HongKong."

   

  Editors

  • The Content Assist pop-up window in the CCXML and LXML editors does not list all valid content when typing a less than symbol (<) (as set by user preferences). It only proposes the appropriate closing tag.

    Workaround:
    To view the full list of valid tags, type a backspace. Selecting an item from the list also inserts the removed < symbol. Alternatively, press Ctrl + Space to open the Content Assist.

     
  • When you select text in large VoiceXML files, it might take a few seconds for the highlighting to appear.
     
  • If you have a file open in an editor, and you Undo all the changes you have made to the file since your last Save, the file is still considered to have changes pending.
     
  • In some configurations, you might experience some problems verifying pronunciations after you have run or debugged a VoiceXML application. If this occurs, close the Rational Software Development Platform, terminate any javaw.exe and engine.exe processes, and restart it. You can use the Windows Task Manager to find and end these processes.
     
  • To pass validation, a VoiceXML document must have at least one child of the VXML element.
     
  • You might experience a problem with long lines of text (such as lines that are thousands of characters in length) in either the VoiceXML editor or SRGS-XML grammar editor. Some conditions can cause the Rational Software Development Platform to hang. If this occurs, shut down your system and restart it.
    
    Open the file with the Default Text Editor (File > Open With or Open With from the pop-up menu) to split the long lines into smaller ones, then save it and re-open the file in the VoiceXML or SRGS-XML editor.
     
  • In the SRGS grammar editor, if a rule is defined but not used, no warning is generated.
     
  • If you see the syntax error, "An error that cannot be determined exists in the SISR of this grammar," with no line information, it might be due to using invalid SISR syntax in SRGS-XML or ABNF grammars. This error can occur in either the grammar or VoiceXML editor if you declare an SISR object, and then reference an undeclared child object of that object.
     
  • After closing an editor, there might be a delay before you can delete the file.
     
  • In working with the SRGS-XML grammar editor, two messages for the same error appear in the Tasks view. To turn off the XML parsing in the SRGS-XML editor, follow these steps:

  1. In the Navigator view, right click on the project, and on the pop-up menu, click Properties.
  2. On the Properties dialog, select Validation. Also select the Override validation preferences check box, and clear the SRGS-XML Form Validator check box.
  3. Click Apply, and then click OK.

  Note:
  This turns off the SRGS-XML editor validation, but the compiler 's XML validation still occurs.
  

   

  Multi-paged SRGS-XML Grammar Editor

  • The combo boxes in property sheets allow you to input non-valid values.

    Workaround:
    Do not type invalid values in these combo boxes. Set the grammar to a valid value.

   
  • Unless the type for a rule reference is set to "application/srgs," the # sign is added to the "url" attribute in the syntax. This yields an invalid grammar when attempting to create a reference to a rule in an external grxml file.

    Workaround:
    Manually remove the # sign in the source before closing your file.

   
  • Global tags are not supported in the graphics.
   
  • Global commands are not supported in the graphics.
   
  • Moving elements from one rule to another is not supported.
    

   

  Grammar Conversions

  • If you convert a grammar file more than once you may not see updates when using the SRGS-XML editor.

    Workaround:
    Have the target grammar file open in the SRGS-XML editor while the conversion is being done.

   

   

  Communication Flow Builder

  • Communication Flow Builder files created with previous versions of this application do not display correctly because the appearance of the CFB has been updated. To view older communication flow builder files, you must import the files into a new communication flow file. To do so, follow these steps:
    1. Ensure that you have a copy of the .xml file for the old .cfb file.
     
    2. Create a new .cfb file and remove the objects in the canvas.
     
    3. Right mouse click and select Import....  
    4. Import either the .cfb or .xml file.  
    5. After the file is imported, reposition the communication flow in the canvas.
  When generating a multi-sentence audio file, the audio file is created, but only the first sentence is used.

  Workaround:
  If you require a multi-sentence audio file, divide the prompt into multiple audio files—one for each sentence.

  Reusable Dialog Component (RDC) release notes:

  • If you receive a message stating that Windows cannot open the JSP file, click Window > Preferences > Workbench > Capabilities and clear the Web Developer (typical) check box. Next, generate the JSP file again.
   
  • If you use the group.rdg file, do not change the strategy and submit default values.
   
  • By default, the order of the RDCs in a group is determined by the ID of the RDC objects. To order objects differently, you must drag in a Start object and then use Connect objects to achieve the desired order.
   
  • In a Group Communication Flow Model, you can drag in only RDC files, not VoiceXML palette objects.
   
  • When you launch the Tomcat server from the Workbench, an HTTP Status 500 error is displayed in the Web browser.

    Workaround:

    1. Install J2SDK1.4.2, which is specified in the RUNNING.txt file in the Tomcat installation directory.
    2. Copy the tools.jar file from <J2SDK_install_dir>/lib to the <jakarta_tomcat_installation_dir>\common\lib.
    3. Restart the Tomcat server in the Workbench.

   

  Grammar Test Tool

  • If using an audio file in the Grammar Test Tool you may receive a No Match even if the phrase should have matched the grammar being tested.

    Workaround:
    Use the Analyze Audio function to verify that the audio file is valid.

   

  VoiceXML testing and debugging

  • If the VoiceXML browser loads a document that specifies an HTTP URI for its DTD, and the DTD cannot be fetched, (for example, if you are disconnected from the network or Internet), the VoiceXML application you are running or debugging ends.
     
  • The VoiceXML Simulation Environment utilizes the WebSphere Application Server v5.1 Test Environment exclusively. No other WebSphere Application Server v5.1 Test Environment usage is permitted while the Voice Server is running. It is recommended that the WebSphere Application Server v6.0 be utilized, if necessary.
     
  • When using the Run menu, if the Run As submenu is missing use the Run toolbar icon to open the drop-down list.
     
  • SSML tags in your VoiceXML prompts should be separated from the surrounding text by white space, or the text may not be read correctly by the Text-to-Speech engine. For example, "this is<break/>a test" should be written as "this is <break/> a test."
     
  • If you need to perform the run or debug simulation of a VoiceXML application and an internet connection is not available, then you must either comment out or remove the DOCTYPE line in the VoiceXML document.

    Below is an example of a DOCTYPE line and how to comment it out.

    Before:
    <!DOCTYPE vxml PUBLIC "-//W3C//DTD VOICEXML 2.1//EN" "http://www.w3.org/TR/voicexml21/vxml.dtd">

    After:
    <!--
<!DOCTYPE vxml PUBLIC "-//W3C//DTD VOICEXML 2.1//EN" "http://www.w3.org/TR/voicexml21/vxml.dtd">
-->

   
  • If during simulation or debugging of a VoiceXML application you see an "unsupported language" message in the console, you should verify that the language specified in your MRCP preferences matches what is running on the voice server.
    
    

   

  WebSphere Voice Toolkit documentation

  • If you have Adobe Acrobat(R) 7.0 installed on your system and you open a PDF file in the toolkit's Help window, the Help window might stop responding when you close the PDF file or change to another topic. If this occurs, use the Task Manager to end the Help application, and then reopen the Help window.

   

  ---

  Notices

  The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:

  INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

  This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and\or changes in the product(s) and\or the program(s) described in this publication at any time without notice.

  Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

  Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

  ---

  Trademarks

  The following terms are trademarks or registered trademarks of the International Business Machines Corporation in the United States, other countries, or both:

  IBM
  Rational
  WebSphere

  Intel and Pentium are trademarks or registered trademarks of Intel Corporation in the United States, other countries, or both.

  Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.

  Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

  Other company, product, and service names may be trademarks or service marks of others.