IBM WebSphere Voice Toolkit
V6.0 Preview
Readme

December 2004

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
  • Speech recognition test tool
  • Editors
  • Communication Flow Builder
  • VoiceXML testing and debugging
  • Natural Language Understanding (NLU) feature
  • Voice Toolkit documentation
  • Voice Portlet testing and debugging
  • SRGS XML Grammar Editor (Graphics page)
• Notices
• Trademarks

Introduction

This readme provides information on known problems and software limitations for the following features:

• VoiceXML Application Development and Debug
• Voice Portlet Application Development and Debug
• Natural Language Understanding (NLU) Development
• Voice Tools for MRCP Server

For installation information, see the IBM WebSphere Voice Toolkit V6.0 Installation Readme, located in the <rational_dir>\VoiceToolkit\Readme directory, where <rational_dir> is the full path to the IBM Rational(R) Software Development Platform (SDP). By default, the path to readme files is as follows:

Program Files\IBM\Rational\SDP\6.0\VoiceToolkit\Readme

Getting Started

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

For information on using the Voice Toolkit, refer to the online Help. From the Help menu, click Help Contents. When the Help window appears, select one of the following features included in the Contents list.

• VoiceXML developer information
• Voice Portlet developer information
• NLU developer information
• Voice Tools for MRCP Server

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 VoiceXML developer information 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 6.0, available at http://www.adobe.com. Click Get Adobe Reader and follow directions.

What's new

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

VoiceXML Application Development and Debug

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 or IBM Rational Web Developer (RWD) 6.0.

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, if you develop Voice Portlets using the WebSphere Voice Application Access (WVAA) Toolkit, the minimum requirement is RAD and its Portal Tools feature.

A free trial of Rational Application Developer V6.0 is available for download at:

http://www14.software.ibm.com/webapp/download/searchquery.jsp

VoiceXML browser

Supports VoiceXML 2.0 and Java 2 Enterprise Edition (J2EE) enablement.

CCXML interpreter

Supports markup currency (current CCXML draft) and J2EE enablement.

VoiceXML 2.1 support

Includes VoiceXML 2.1 support in the editors only. This allows you to create VXML 2.1-based applications.

SRGS XML Grammar Editor

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

Communication Flow Builder tool

Includes the following enhancements:

• A new, improved user interface
• An import feature, which supports the import of VoiceXML 2.0 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
• A dynamic set of Reusable Dialog Components (RDCs) — part of the IBM Open Source initiative
• A Prompt Configuration window, which allows you to create prompts based on a list of shorter, more manageable components

Natural Language Understanding (NLU) Development

Call Routing Designer tool

Extends the Communication Flow Builder as a base to provide communication flow designing capabilities to the design of a call router.

Enhancements:

• NLU Database and Project Wizard improvements
• Inline editing capability added to Sentence List views
• Action Classification and Language Model building from within the IBM Rational Software Development Plaform
  Includes toolbar updates for the NLU perspectiveas well as context menu items in the Filter Navigator view.
• Ability to use filters as an input source for model building
• Additional Find capabilities added to the Named Entity page of the Sentence Editor

Voice Tools for MRCP Server

MRCP Trace Viewer tool

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 (WVS) V5.1.

Known problems and software limitations

General

• If your program stops responding, close the IBM Rational Software Development Platform (SDP) 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 Voice Toolkit are saved in the workspace used by the SDP. If you uninstall the Voice Toolkit, the workspace remains on your system so that the files are still available.
   
• Files saved in the following directories are deleted when uninstalling the Voice Toolkit. If you create files in these directories, copy them to another folder before uninstalling the Voice Toolkit:
   

  •    <Rational_dir>\eclipse\plugins\com.ibm.voicetools.engines.wvs_6.0.0

  •    <Rational_dir>\eclipse\features\com.ibm.wpstools_6.0.0

  •    <Rational_dir>\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_6.0.0

  •    <rational_dir>\eclipse\logs
     

• When you change the Workbench or Workbench > Appearance preferences, the Restore Defaults button might not restore the original defaults. Close and restart the SDP for changes to take effect.
   
• If you receive an "Internal Error - Widget Disposed" error message, close and restart the SDP to recover from the error.
   
• 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.
   
• The Weather portlet sample is currently not working.

Language-specific considerations

• Voice Toolkit 6.0 does not support Lexicons for AP Languages. This is because a required feature, part-of-speech, is not supported by the WVS 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.0 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.
   
• The VoiceXML Programmer's Guide (pgmguide.pdf), packaged with the toolkit contains incorrect information about the alphabets supported in the phoneme tag for SSML. To view the guide, from the Help menu, click Help Contents and select VoiceXML developer information. In the Contents list, select Related documents. For updated information, see the IBM Text-to-Speech SSML Programming Guide (tts_ssml.pdf), also located under Related documents.
   
• 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." If you change the voice language in Voice Tools preferences, close the SDP for the changes to take effect.

Speech Recognition Test tool

• Do not save the script file in unicode format if you want to run the Speech recognition test tool. If you save the script file in unicode format, the Results dialog displays the message "Script Evaluation Error!" This happens whether you select or clear the Use unicode mode check box. To fix this problem, do not save your script file in unicode format, and select the Use unicode mode check box.
   
• If you use the Speech recognition test tool and your script file contains DBCS characters for the audio (.ulw) or grammar (.fsg) file name, you must select the Use unicode mode check box. If you do not select the Use unicode mode check box, the result does not display.
   
• If you run the Speech recognition test tool and the text phrase to be recognized has DBCS characters, select the Use unicode mode check box. If you do not select the check box, the result does not display.

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 SDP, terminate any javaw.exe and engine.exe processes, and restart the SDP. 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 SDP to hang. If this occurs, shut down your system and restart the SDP.
  
  Open the file with the Default Text Editor (File > Open With or Open With from the Context 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 and JSGF grammar editors, 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 context 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 XML validation still occurs.

SRGS XML Grammar Editor (Graphics page)

• Semantic (script) tags are not supported on the Graphics page.
• Comments are not supported on the Graphics page.
• Objects cannot be moved or rearranged after being placed on the canvas.
• Root rule can be specified only in the source.
• F1 Help is currently not implemented.
• Adding a group (embedded rule) as an option to an alternative, does not always generate all the source code expected.

  Workaround: If you require a complex piece of grammar, such as one of the objects in an alternative, use a rule reference and place the piece of grammar in a separate rule in the same file.

• Quoted tokens might not get updated or deleted in the source. For example:

  Quoted token:                    "Token Text"
  

  Workaround: Do not use quoted tokens. Instead, replace them in the source with one of the following forms:

  Tokens with tag:                  <token>Token Text</token>
  Tokens wrapped in item tag:       <item>Token Text</item>
  Free text tokens:                 Token Text
  

• 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.

• Property sheets for the last-selected object continue to display until another selection takes over the property sheet. This occurs even when the selection has changed to an object that does not provide a property sheet. When editing a left-over property sheet, changes usually do not take effect.

  Workaround: Do not edit the property sheet if the object for it is not selected.

• An empty Embedded Reference created on the Graphics page gets turned into an empty Text when switching back and forth between the editor pages. This is because the syntax: <item></item> is treated as empty text, but at the same time, an empty embedded reference generates the same syntax as long as nothing else is added to its sequence.

  Workaround: When creating an embedded reference on the source page, make sure to put something in its sequence before switching to the graphical side. If you switch by mistake, you can simply erase the empty token that is displayed on the Graphics page and create the embedded reference again.

• The Root rule appears on the Graphics page as either public or private according to the scope parameter it has in the source.

  Workaround: No known workaround. This problem does not cause functionality problems. The only impact is that you must view the source code to know which is the root rule.

• The Insert operation on the Graphics page moves the connectors out of position.

  Workaround: Toggle between the Graphics and SRGXML pages to put the connectors back in their current position. This does not cause a problem in the source.

• If you click in a connector to insert an object, objects to the right (or the inserted object) do not move to the right.

  Workaround: Toggle between the Graphics and SRGXML pages.

• Deleting objects might move the connectors out of position.

  Workaround: Toggle between the Graphics and SRGXML pages.

• When inserting a group (embedded rule) between two other objects, the subrule does not get created graphically. It gets created in the source only.

  Workaround: After inserting the group object, toggle between the Graphics and SRGXML pages.

• Deleting a group might not delete all its children inside its subrule graphically. This occurs when you delete a group that has other groups inside the group's subrule. Note that the delete does not delete the source.

  Workaround: After deleting the group, toggle between the Graphics and SRGXML pages.

• When deleting the last object of a set of alternative objects (the last remaining), the "<one-of>" tags are not deleted in the source.

  Workaround: Delete directly from the source.

• Deleting an object of an alternative on the Graphics page does not rearrange the remaining objects in the alternative. This does not cause any problem in the source.

  Workaround: Toggle between the Graphics and SRGXML pages. If objects are not rearranged, type or erase an item in the source editor to force the Multi-paged SRGS XML Grammar Editor to redraw the graphics.

• Non-self-closing ruleref elements with spaces, line breaks, or tabs between opening and closing tags are not supported. For example:

  <ruleref uri="#somerule">     </ruleref> 
  

  Workaround: Use self-closing tags or make sure there are no spaces, line breaks, or tabs between tags. For example:

  <ruleref uri="#somerule" /> 
  

• Nested "one-of" elements are not supported yet. For example:

  <rule id="r1">
   <one-of>  
    <item>
     <one-of>
      <item>Hi</item>
      <item>Hello</item>
     <one-of>
    </item>
    <item>Good morning</item>  
   </one-of>
  </rule>
  

  Workaround: Place the internal "one-of" in a separate rule and or a ruleref. For example:

  <rule id="r1">
   <one-of>  
    <item>
     <ruleref type="application/srgs+xml" uri="#r2" />
    </item>
    <item>Good morning</item>  
   </one-of>
  </rule>
  <rule id="r2">
   <one-of>  
    <item>Hi</item>
    <item>Hello</item>
   </one-of> 
  </rule>
  

Communication Flow Builder

• Communication Flow Builder files created with previous versions of this application do not display correctly because the appearance of 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 using CTTS to generate 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.
• This Preview does not support a group within a group.
• 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.

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.
   
• When using the Run menu, if the Run As submenu is missing use the Run toolbar icon to open the drop-down list.
   
• When debugging a VoiceXML application, double-clicking in the ruler bar does not add a breakpoint. To add a breakpoint, right-click in the ruler bar and select Add Breakpoint.

Natural Language Understanding (NLU) feature

• If you have problems running the model building tools, make sure you have followed the instructions provided in the Getting Started section of the NLU Developer Information. If you plan to use the NLU feature for parser model development, you must download and install the Tcl binary package before the model building tools run.
• Natural language call routers created in this Preview release do not automatically include certain JAR files used in the routing process. To properly validate and compile your call router, follow these steps:
  1. In the Navigator view, right click on the project, and on the context menu, click Properties.
  2. Select Java Build Path from the list on the left.
  3. From the Libraries tab, click the Add External JARs....
  4. Browse to the <rational_dir>\eclipse\plugins\com.ibm.nlutools.engines_6.0.0 directory and select the following files:
     • com.ibm.nlu.asm.jar
     • com.ibm.nlu.engines.jar
     • com.ibm.nlu.util.jar
  5. Click Open. The files are displayed in the Properties dialog box.
  6. Click OK to set the Java build path.
• If you create a new NLU database using the wizard, the database might not appear in the drop-down menu when creating a NLU project.

  To resolve this problem:

  1. Ensure that you are using the correct DB2 user ID and password.
   
  2. Increase the maximum number of concurrently active DB2 databases allowed. To do so, follow these steps:
     1. Open a DB2 command prompt.
     2. From your database server machine, type the following command:

        db2 get dbm cfg

     3. Locate the value associated with the maximum number of concurrently active databases. For example:

        Max number of concurrently active databases  (NUMDB) = 8

     4. To increase this database limit, use the DB2 update command. For example, to set this value to 20, type the following command:

        db2 update dbm cfg using numdb 20

Voice Toolkit documentation

• If you have Adobe Acrobat(R) 6.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.

Voice Portlet testing and debugging

• If you plan to debug and test voice portlets in the local test environment, your SDP must be installed with a short path name. Also, you must install additional programs. For details on software prerequisites needed for developing and testing voice portlets, see Getting started with developing voice portlet applications.

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.