WebSphere Voice Response for AIX with DirectTalk Technology Developing Java Applications Version 4.2 GC34-6377-02
WebSphere Voice Response for AIX with DirectTalk
Technology
Developing Java Applications
Version 4.2
GC34-6377-02
���
Note
Before using this information and the product it supports, read the general information under “Notices” on
page 231.
Third edition (August 2008)
This edition applies to Version 4, Release 2 of IBM WebSphere Voice Response for AIX with DirectTalk Technology
(program number 5724-I07), and to all subsequent releases and modifications until otherwise indicated in new
editions. Make sure you are using the correct edition for the level of the product.
© Copyright International Business Machines Corporation 1998, 2008. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . ix
About This documentation . . . . . . . xi
Who should use this documentation . . . . xi
How to use this documentation . . . . . xi
Typographical conventions . . . . . . . xii
Where to find more information . . . . . xii
Getting help . . . . . . . . . . . . xiv
Accessibility . . . . . . . . . . . . xiv
Making comments on this book . . . . . xiv
Chapter 1. Introduction to WebSphere Voice
Response Java development . . . . . . 1
What tools are available for writing Java
applications? . . . . . . . . . . . . 1
How does the Java API relate to the supplied
WebSphere Voice Response JavaBeans? . . . 2
Modifying JavaBeans applications . . . . 2
Java applications . . . . . . . . . . . 2
How is an incoming call routed to a Java
application? . . . . . . . . . . . 3
What controls the sequence of events in a
Java application? . . . . . . . . . . 3
How does the caller interact with the Java
application? . . . . . . . . . . . 5
How do you specify what the Java
application says? . . . . . . . . . . 6
How do Java applications access
information? . . . . . . . . . . . 6
Creating reusable components . . . . . 8
Integration and interoperability of Java
applications . . . . . . . . . . . 8
The benefits of Java . . . . . . . . . 8
How to get voice data into applications . . . 9
How voice segments are stored and
identified . . . . . . . . . . . . 9
Making voice segments available to Java
applications . . . . . . . . . . . 11
What happens when you install a
language? . . . . . . . . . . . . 12
How languages are identified in VoiceXML
and Java . . . . . . . . . . . . . 12
Why locale is important . . . . . . . 12
Default locale . . . . . . . . . . 13
Internationalization . . . . . . . . 13
Defining your own locales . . . . . . 14
Language-only locales . . . . . . . . 14
How locale is used for speech recognition
and text-to-speech . . . . . . . . . 15
Speech technologies . . . . . . . . . 15
Where to get more information about
using speech technologies . . . . . . 15
Chapter 2. Using the WebSphere Voice
Response simulator provided with Voice
Toolkit for WebSphere Studio . . . . . 17
The WebSphere Voice Response simulator . . 17
System requirements for the Voice Response
simulator . . . . . . . . . . . . . 18
Setting up TCP/IP to use the Voice
Response simulator . . . . . . . . 18
Installing the Voice Response simulator . . . 19
Installation procedure . . . . . . . . 19
Starting the Voice Response simulator . . . 21
Voice Response simulator utilities . . . . . 22
Using the Voice Response simulator telephone 23
Testing an application that answers
incoming calls . . . . . . . . . . 23
Testing an application that makes outgoing
calls . . . . . . . . . . . . . . 24
Hiding the telephone window . . . . . 25
Displaying a hidden telephone window . . 25
Creating more telephones . . . . . . 25
Installing languages . . . . . . . . . 25
Getting the Voice Response simulator ready to
run your applications . . . . . . . . . 26
Adding number-to-application mappings
to the configuration database . . . . . 27
Setting simulator properties . . . . . . 27
Setting the CLASSPATH for an application 29
Importing voice segments . . . . . . 29
Setting up an application to start
automatically . . . . . . . . . . 30
Using text-to-speech and speech recognition
with the simulator . . . . . . . . . . 32
Monitoring the phone lines . . . . . . . 32
Simulating multiple callers . . . . . . 35
Switch configuration . . . . . . . . 35
© Copyright IBM Corp. 1998, 2008 iii
Monitoring the sessions . . . . . . . 36
Limitations of the Voice Response simulator 36
Differences between using the Voice Response
simulator and a real WebSphere Voice
Response system . . . . . . . . . . 36
Troubleshooting the Voice Response simulator 37
Starting the host manager (dtjshost) fails
with RMI server exception . . . . . . 38
Starting the host manager (dtjshost)
produces no output . . . . . . . . 38
Recording does not work . . . . . . 38
Poor performance, long pauses during
play . . . . . . . . . . . . . . 38
You can’t hear anything . . . . . . . 38
You start to use a second phone and the
first phone stops talking . . . . . . . 39
The recorded sound is faint . . . . . . 39
The recorded sound is distorted . . . . 39
DTMF sound effect works intermittently 39
The first few seconds of user input is not
recorded . . . . . . . . . . . . 39
Incoming call is not answered . . . . . 39
The application answered my call and
hung up immediately . . . . . . . . 40
Uninstalling the Voice Response simulator . . 40
Chapter 3. Using the WebSphere Voice
Response Java API classes . . . . . . 41
Installing the WebSphere Voice Response Java
API classes . . . . . . . . . . . . 41
Prerequisites . . . . . . . . . . . 41
Instructions . . . . . . . . . . . 42
Using the Java API with WebSphere Studio
Site Developer . . . . . . . . . . . 43
Registering the IBM Runtime Environment
in WebSphere Studio Site Developer . . . 43
Running an application . . . . . . . 44
Creating a new voice application in
WebSphere Studio Site Developer . . . . 44
Introduction to applications . . . . . . . 46
Managed and unmanaged applications . . 46
Exceptions . . . . . . . . . . . 47
Getting started: the WVRApplication class . . 48
Setting the application environment . . . 49
The ApplicationProperties class . . . . 51
Starting the call . . . . . . . . . . . 53
Examples: receiving and making calls . . 55
Looping round to handle another call . . . 56
Finishing with a call . . . . . . . . . 57
Chapter 4. Creating voice applications . . 59
Saying something to the caller . . . . . . 59
Specifying what is to be spoken using the
MediaType class . . . . . . . . . 60
The VoiceSegment class . . . . . . . 61
The DTMFSequence class . . . . . . 62
The AudioNumber class . . . . . . . 63
The AudioCurrency class . . . . . . . 64
The AudioDate class . . . . . . . . 65
The AudioTime class . . . . . . . . 66
The AudioString class . . . . . . . . 67
The TextToSpeech class . . . . . . . 68
Creating a media sequence . . . . . . 68
Voice enabling your data structures: the
Playable interface . . . . . . . . . 69
Playing output to the caller . . . . . . . 70
Getting input from the caller . . . . . . 70
The Call.playAndGetInput() method . . . 71
The PlayAttributes class . . . . . . . 72
The InputAttributes class . . . . . . 73
The MenuAttributes class . . . . . . 76
The DTMFAttributes class . . . . . . 80
The RecoAttributes class . . . . . . . 81
The Caller’s response . . . . . . . . . 82
Validating input . . . . . . . . . . . 84
Recording the caller’s voice input . . . . . 85
Obtaining information about the recording 86
Dealing with silence . . . . . . . . 86
Changing the pacing tone . . . . . . . 87
Internationalizing your applications . . . . 87
Setting the application locale . . . . . 87
Changing the application locale
dynamically . . . . . . . . . . . 88
Determining which locale the application
is using . . . . . . . . . . . . 88
Creating multilingual applications . . . 89
Speaking currency values . . . . . . 89
Related information . . . . . . . . 91
Using speech recognition for menus and data
entry . . . . . . . . . . . . . . 91
Specifying the technology to be used . . . 92
Telling the caller what to say . . . . . 93
Mixing key and voice input . . . . . . 93
Asking the recognizer for alternative
results . . . . . . . . . . . . . 93
Annotations and words spoken in menus 94
Using text-to-speech . . . . . . . . . 94
Specifying the technology to be used . . . 95
Using TextToSpeech . . . . . . . . 96
More about handling calls . . . . . . . 96
iv Developing Java Applications
Summary of methods used for
telephony-related functions . . . . . . 96
Handing a call to another application . . 97
Transferring a call to an agent . . . . 100
Getting called and calling numbers and
application call data . . . . . . . . . 106
Handling voice segments dynamically . . . 107
Deleting voice segments dynamically . . 107
Importing and exporting voice segments
dynamically . . . . . . . . . . . 107
Invoking a VoiceXML application from a
Java application . . . . . . . . . . 108
Invoking a state table . . . . . . . . 109
Obtaining information from state tables 110
Chapter 5. Managing your voice segments 113
Using dtjplex . . . . . . . . . . . 113
dtjplex control file . . . . . . . . . 114
Example . . . . . . . . . . . . 115
Chapter 6. Testing applications . . . . 117
Using the Voice Response simulator or a real
WebSphere Voice Response system? . . . . 117
Using message logs . . . . . . . . . 117
Running an application from WebSphere
Studio Site Developer . . . . . . . . 118
Getting help from IBM Support . . . . . 119
What do you need to send to IBM
Support to get problems resolved? . . . 119
Chapter 7. WebSphere Voice Response
Java Tutorials . . . . . . . . . . 121
Prerequisites for the tutorials . . . . . . 121
Voice segments for running the tutorial
applications . . . . . . . . . . . . 122
The language of the tutorial voice
segments . . . . . . . . . . . . 122
Importing the voice segments . . . . . 123
List of voice segments in the Tutorials
category . . . . . . . . . . . . 123
Tutorials . . . . . . . . . . . . . 126
Tutorial 1: Caller calls an application . . 128
Code for Tutorial 1 . . . . . . . . 132
Tutorial 2: Select an item from a menu 134
Code for Tutorial 2 . . . . . . . . 139
Tutorial 3: Caller exits from the
application (menu item 5) . . . . . . 142
Code for Tutorial 3 . . . . . . . . 144
Tutorial 4: Leave a message (menu item
1) . . . . . . . . . . . . . . 148
Code for Tutorial 4 . . . . . . . . 150
Tutorial 5: Application makes a call . . . 154
Code for Tutorial 5 . . . . . . . . 156
Tutorial 6: Key in a telephone number
(menu item 2) . . . . . . . . . . 158
Code for Tutorial 6 . . . . . . . . 162
Tutorial 7: Order an item from a catalog
(menu item 3) . . . . . . . . . . 167
Code for Tutorial 7 Catalog class . . . . 172
Code for Tutorial 7 InApp class . . . . 175
Tutorial 8: Credit card validation (menu
item 3 continued) . . . . . . . . . 181
Code for Tutorial 8 CardChecker class 185
Code for Tutorial 8 Catalog class . . . . 187
Tutorial 9: Order information (menu item
3 continued) . . . . . . . . . . 190
Code for Tutorial 9 OrderInfo class . . . 193
Code for Tutorial 9 Catalog class . . . . 195
Tutorial 10: Transfer to an agent (menu
item 4) . . . . . . . . . . . . 198
Code for Tutorial 10 . . . . . . . . 202
Tutorial 11: Using speech recognition and
text-to-speech . . . . . . . . . . 208
Code for Tutorial 11 . . . . . . . . 213
Appendix. Using speech recognition and
text-to-speech with the WebSphere Voice
Toolkit WebSphere Voice Response
simulator . . . . . . . . . . . . 221
Using grammars with Voice Response Java
applications . . . . . . . . . . . . 221
Problem word reporting . . . . . . 223
Speech technology engines . . . . . . . 223
Configuring speech technologies for the
Voice Response simulator . . . . . . . 224
Speech recognition (RecoService entry) 224
Text-to-speech (TTSService entry) . . . 227
Example configuration . . . . . . . . 229
RecoService example . . . . . . . . 229
TTSService example . . . . . . . . 229
Deploying applications developed with the
simulator . . . . . . . . . . . . 229
Notices . . . . . . . . . . . . . 231
Trademarks . . . . . . . . . . . . 233
Glossary . . . . . . . . . . . . 235
List of WebSphere Voice Response and
associated documentation . . . . . . 261
Contents v
WebSphere Voice Response software . . . 261
IBM hardware for use with WebSphere Voice
Response . . . . . . . . . . . . 262
Withdrawn from marketing but still
supported . . . . . . . . . . . 262
WebSphere Voice Response related products 262
WebSphere Voice Server for
Multiplatforms . . . . . . . . . . 262
Unified Messaging for WebSphere Voice
Response . . . . . . . . . . . 263
AIX and the IBM pSeries computer . . . 263
HACMP . . . . . . . . . . . . 263
SS7 . . . . . . . . . . . . . 263
Integrated Services Digital Network . . . 264
Bellcore Specifications for ADSI Telephones 265
Index . . . . . . . . . . . . . 267
vi Developing Java Applications
Figures
1. Overview of some of the more important
WebSphere Voice Response Java API
classes . . . . . . . . . . . . 5
2. E-business application model . . . . . 7
3. Adding voice to e-business . . . . . 8
4. Voice segment database . . . . . . . 9
5. Voice segments in the Java voice
segment space . . . . . . . . . 10
6. The Java voice segment space is divided
into locales, which are divided into
categories . . . . . . . . . . . 10
7. Alternative ways of making voice
segments available to your applications . 11
8. The Voice Response simulator . . . . 18
9. The window displayed when you start
the simulator voice response node . . . 22
10. The simulated telephone window 23
11. Dialing an application . . . . . . . 24
12. After the caller has exited from the
application, but before replacing the
handset . . . . . . . . . . . . 24
13. Example of control file for importing
voice segments into the simulator . . . 30
14. Defining different language versions of
the “menu” application . . . . . . 31
15. The DTsim Line Monitor window 33
16. The DTsim Line Monitor window
showing the logical phone numbers
defined . . . . . . . . . . . . 34
17. The DTsim Line Monitor window
showing the physical line numbers
defined . . . . . . . . . . . . 35
18. DTsim Session Monitor window . . . 36
19. Overview of WebSphere Voice Response
Java API exceptions . . . . . . . 47
20. Example of a control file . . . . . . 91
21. Handing a call over to another
application and waiting to get it back . 99
22. Handing a call over to another
application . . . . . . . . . . 100
23. Transferring the caller to an agent 102
24. Consultation with an agent while the
caller is on hold . . . . . . . . 104
25. Retrieving a call from an agent 105
26. Example of control file for Windows 115
27. Example NodeName entry with a
NumToApp mapping for the “app1”
application . . . . . . . . . . 199
28. Relationship between the components
involved . . . . . . . . . . . 222
© Copyright IBM Corp. 1998, 2008 vii
viii Developing Java Applications
Tables
1. Currency voice segments for XYZ
currency . . . . . . . . . . . 89
2. A value of 20000000 spoken with
different currency and locale property
values . . . . . . . . . . . . 90
3. Voice segments required . . . . . . 90
4. Call-related methods and corresponding
WebSphere Voice Response actions . . 96
5. Checklist for running an application
from WebSphere Studio Site Developer . 118
© Copyright IBM Corp. 1998, 2008 ix
x Developing Java Applications
About This documentation
This documentation provides information about developing Java™ applications
for WebSphere® Voice Response for AIX® Version 4, Release 2, using
WebSphere Studio Site Developer. It includes an introduction to the Java
Application Programming Interface (API), guidance for developing
applications using Java, and instructions for testing applications.
Note: In this documentation, anywhere that WebSphere Studio Site Developer
is mentioned, you can also use Websphere Studio Application
Developer.
Who should use this documentation
To use this documentation you must be a Java application programmer. You
should also know how to use WebSphere Studio Site Developer.
How to use this documentation
This documentation is in several sections and you may not need all of them.
If you want to print it from Adobe Acrobat, print the sections you need, by
selecting the page numbers.
v Start with Chapter 1, “Introduction to WebSphere Voice Response Java
development,” on page 1 to provide background information.
v Install the WebSphere Voice Response Simulator by following the
instructions in Chapter 2, “Using the WebSphere Voice Response simulator
provided with Voice Toolkit for WebSphere Studio,” on page 17.
v Then read Chapter 3, “Using the WebSphere Voice Response Java API
classes,” on page 41 and then follow the tutorials in Chapter 7, “WebSphere
Voice Response Java Tutorials,” on page 121.
v Use Chapter 4, “Creating voice applications,” on page 59 for information
about creating voice applications.
v Use Chapter 6, “Testing applications,” on page 117 for information about
testing applications.
v You may also need to refer to the information in “Using speech recognition
and text-to-speech with the WebSphere Voice Toolkit WebSphere Voice
Response simulator,” on page 221.
© Copyright IBM Corp. 1998, 2008 xi
Typographical conventions
This documentation uses the following typographical conventions:
This font
Identifies new terms that describe WebSphere Voice Response Java
and VoiceXML Environment components or concepts. These terms are
normally defined where you see this font, and they are also defined in
the glossary.
This font
Identifies:
v a programming keyword, such as a property name, class name, or
method name.
v an item in a window. The item could be a keyword, an action, a
field label, or a pushbutton. Whenever one of the steps in a
procedure includes a word in this font, look for an item in the
window that is labeled with that word.
This font
Is used for emphasis. Take extra care wherever you see this font!
This font
Identifies text you must type, filenames and directory names. Because
AIX® is case sensitive, if you are using AIX, make sure you type the
uppercase and lowercase characters exactly as shown.
Where to find more information
Here is a list of the documentation for WebSphere Voice Response for AIX.
PDF and HTML versions of the documentation are available from the IBM
Publications Center at http://www.ibm.com/shop/publications/order.
Hardcopy books, where available, can be ordered through your IBM
representative or at this Web site.
WebSphere Voice Response for AIX documentation can also be found by going
to the IBM Pervasive software Web site at http://www.ibm.com/software/pervasive, selecting the WebSphere Voice products link, and then selecting
the library link from the Websphere Voice Response page.
PDF and HTML versions of the WebSphere Voice Response for AIX
publications are available on the CD-ROM supplied with the product. In
addition, WebSphere Voice Response for AIX, WebSphere Voice Response for
Windows, Unified Messaging, and other WebSphere Voice publications are
available together in PDF and HTML formats on a separately-orderable
CD-ROM (order number SK2T-1787).
v WebSphere Voice Response for AIX: General Information and Planning,
GC34-6379
typographical conventions
xii Developing Java Applications
v WebSphere Voice Response for AIX: Installation, GC34-6380
v WebSphere Voice Response for AIX: User Interface Guide, SC34-6386
v WebSphere Voice Response for AIX: Configuring the System, SC34-6381
v WebSphere Voice Response for AIX: Managing and Monitoring the System,
SC34–6384
v WebSphere Voice Response for AIX: Designing and Managing State Table
Applications, SC34–6388
v WebSphere Voice Response for AIX: Application Development using State Tables,
SC34–6387
v WebSphere Voice Response for AIX: Developing Java applications, GC34-6377
v WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and Java
Applications, GC34–6378
v WebSphere Voice Response for AIX: Custom Servers, SC34–6389
v WebSphere Voice Response for AIX: 3270 Servers, SC34–6390
v WebSphere Voice Response for AIX: Problem Determination, GC34–6382
v WebSphere Voice Response for AIX: Fax using Brooktrout, GC34–6385
v WebSphere Voice Response for AIX: Cisco ICM Interface User’s Guide, SC34–6391
v WebSphere Voice Response for AIX: Programming for the ADSI Feature,
SC34–6392
v WebSphere Voice Response for AIX: Programming for the Signaling Interface,
SC34–6392
v WebSphere Voice Response for AIX: Voice over IP using Session Initiation
Protocol, GC34–6383
v WebSphere Voice Response for AIX: Using the CCXML Browser, GC34–6368
Note: To read PDF versions of books you need to have the Adobe Acrobat
Reader (it can also be installed as a plug-in to a Web browser). It is
available from Adobe Systems at http://www.adobe.com .
Also see the JavaDoc reference material (HTML format only), supplied with
IBM Voice Toolkit for WebSphere Studio. The JavaDoc can also be found on
the WebSphere Voice Response for AIX publications CD-ROMs.
Hardcopy books, where available, can be ordered through your IBM®
representative or through the IBM Publications Center at http://www.ibm.com/shop/publications/order. At this Web site you can also obtain PDF and
HTML versions of the documentation. WebSphere Voice Response for AIX
publications can also be found by going to the IBM Pervasive software Web
site at http://www.ibm.com/software/pervasive, selecting the products link,
and then selecting the library link from the WebSphere Voice Response page.
PDF and HTML versions of the WebSphere Voice Response for AIX
publications are available on the CD-ROM supplied with the product. In
where to find more information
About This documentation xiii
addition, WebSphere Voice Response for AIX, WebSphere Voice Response for
Windows®, and Message Center publications are available together in PDF
and HTML formats on a separate CD-ROM (order number SK2T-1787).
Note: To read PDF versions of documentation you need to have the Adobe
Acrobat Reader (it can also be installed as a plug-in to a Web browser).
It is available from Adobe Systems at http://www.adobe.com.
Getting help
If you have a problem with the Java and VoiceXML support in one of the
WebSphere Voice Response products, report it to IBM using your normal
support channel.
Accessibility
WebSphere Voice Response is a voice application enabler. The applications
that are developed to run on WebSphere Voice Response provide telephone
access to business data and services. In this way, WebSphere Voice Response
provides accessibility for people who cannot access the data and services by
using regular Web pages or traditional graphic interfaces. These telephone
user interfaces are fully accessible to people who are blind or have low vision
and, if speech recognition is used, to people with mobility impairments or
limited hand use. Speech recognition capability can be provided by products
such as IBM WebSphere Voice Server. In addition, support for users of
Telephony Devices for the Deaf (TDD) is provided as part of the WebSphere
Voice Response product.
With WebSphere Voice Response you can perform many system
administration tasks with line commands, which are accessible using a screen
reader product. Application development is done with Java or VoiceXML
development tools that are supplied by IBM or third parties.
You can also use a screen reader product to access the WebSphere Voice
Response publications in HTML format (for details of their availability refer to
“List of WebSphere Voice Response and associated documentation” on page
261.
Making comments on this book
If you especially like or dislike anything about this book, feel free to send us
your comments.
You can comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book. Please
limit your comments to the information that is in this book and to the way in
where to find more information
xiv Developing Java Applications
which the information is presented. Speak to your IBM representative if you
have suggestions about the product itself.
When you send us comments, you grant to IBM a nonexclusive right to use or
distribute the information in any way it believes appropriate without
incurring any obligation to you.
You can get your comments to us quickly by sending an e-mail to
[email protected]. Alternatively, you can mail your comments to:
User Technologies
IBM United Kingdom Laboratories,
Mail Point 095, Hursley Park,
Winchester, Hampshire, SO21 2JN, United Kingdom
Please ensure that you include the book title, order number, and edition date.
making comments on this book
About This documentation xv
making comments on this book
xvi Developing Java Applications
Chapter 1. Introduction to WebSphere Voice Response
Java development
This section describes the Java application programming environment
supported by WebSphere Voice Response, and then introduces some of the
concepts that are fundamental to using Java in your applications.
The WebSphere Voice Response Java application programming interface (Java
API) allows you to extend the capability of VoiceXML applications by
accessing back end systems or complex telephony function such as call
transfer. Applications developed using the Java API can be integrated with
VoiceXML dialogs, and with CCXML call control scripts to deliver a robust
complete solution. This can include host data accessed through Enterprise
JavaBeans™ (EJBs) and JavaServer Pages (JSPs), or specialized
computer-telephony integration (CTI) functions accessed through WebSphere
Voice Response state tables. It can also include legacy state tables that provide
standard dialogs or that invoke custom servers to access databases. You can
also use the API to develop voice applications entirely in Java.
TheWebSphere Voice Response for AIX: General Information and Planning manual
provides more background information about the kinds of application you can
create with Java, and shows how you can fit these applications into your
enterprise systems.
The following topics are covered in this section:
v “What tools are available for writing Java applications?”
v “How does the Java API relate to the supplied WebSphere Voice Response
JavaBeans?” on page 2
v “Java applications” on page 2
v “How to get voice data into applications” on page 9.
v “Speech technologies” on page 15
What tools are available for writing Java applications?
The product CDs contain jar files that you can import into a Java integrated
development environment such as WebSphere Studio Site Developer or
Websphere Studio Application Developer.
The product package includes complementary CDs for WebSphere Studio Site
Developer (single license) and Voice Toolkit for WebSphere Studio. You can
use these tools to create and test your applications. If your applications will
© Copyright IBM Corp. 1998, 2008 1
be using WebSphere Voice Server, you can use the speech recognition and
text-to-speech engines supplied with the WebSphere Voice Toolkit to test these
functions.
You can alternatively use a text editor to code Java applications, or another
Java integrated development environment.
How does the Java API relate to the supplied WebSphere Voice Response
JavaBeans?
The only support for Java applications in earlier releases of Version 3 of
WebSphere Voice Response for AIX was based on the supplied WebSphere
Voice Response JavaBeans. These applications will run unchanged on the
current release of WebSphere Voice Response. However, for all new
applications, it is recommended that you use the Java API. The Java API
provides all the functionality of the JavaBeans, but offers a cleaner interface
and improved reusability. The Java API also uses an exception model instead
of the event model used by the beans.
There is some additional functionality in the Java API that was not available
using JavaBeans:
v The Playable interface allows you to make any data item presentable to the
caller: for example, the name, date of birth, and salary retrieved from an
employee record in a database could be spoken as TextToSpeech,
AudioDate and AudioCurrency items respectively.
v You can specify the beep for recording or speech recognition, for example,
as a spoken instruction (″please start recording″).
v You can import and export voice segments at runtime.
Modifying JavaBeans applications
If you need to modify a JavaBeans application to use functionality included in
the supplied JavaBeans, you can do so as you have done in previous releases.
If you need to modify a JavaBeans application to use functionality available
only through the Java API, you will need to convert the JavaBeans
application.
Java applications
This section describes how Java applications work, how you implement them
and when you should consider Java rather than other programming models:
v “How is an incoming call routed to a Java application?” on page 3
v “What controls the sequence of events in a Java application?” on page 3
v “How does the caller interact with the Java application?” on page 5
2 Developing Java Applications
v “How do you specify what the Java application says?” on page 6
v “How do Java applications access information?” on page 6
v “Integration and interoperability of Java applications” on page 8
v “The benefits of Java” on page 8
How is an incoming call routed to a Java application?
For an incoming call to be routed to a Java application:
1. The call is routed to the Java environment.
2. Either:
v The configuration maps the called number to the application, or
v The CCXML document that handles the call will call the application.
Alternatively, a VoiceXML application can call a Java application.
The WVR class, which represents the WebSphere Voice Response system,
establishes telephone calls and enables communication with the WebSphere
Voice Response system. The WVR class can also be used to make outgoing
calls and to return the call at the end of the interaction.
The need for multiple application instances
Each instance of a Java application typically handles a single call at one time.
To deal with more than one call you need to have multiple instances of the
application waiting for calls: as many as you expect to handle during your
peak hour. If you have more than one application, you need a different set of
instances for each, or you can have a “top-level” Java application that greets
the caller, asks them what service they require, and calls other applications as
needed. The service application can be written in Java, VoiceXML, or it can be
a state table.
If you want to run a lot of different applications consider writing your
applications in VoiceXML rather than Java. This may improve system
performance as you only need a single VoiceXML browser per channel. Each
browser can interpret any required VoiceXML document and so can handle a
multitude of applications. For example, if you had 10 channels and 2 different
applications, you would need 20 Java applications running, but only 10
VoiceXML browsers.
What controls the sequence of events in a Java application?
In a Java application, the sequence of events is determined by the ordering of
statements in the program.
The WebSphere Voice Response Java API includes classes and methods
representing the WebSphere Voice Response system, and also the components
of a typical voice response application. Figure 1 on page 5 gives an overview
of some of the more important classes and methods in the Java API.
Java applications
Chapter 1. Introduction to WebSphere Voice Response Java development 3
v The WVR class and its methods represent the WebSphere Voice Response
system and its interactions.
v The Call class and its methods interact with and manipulate telephone calls
through actions such as playing audio (the play() method), recording the
caller (the record() method), getting input (the playAndGetInput() method)
and also by performing telephony functions, for example:
– the getCalledNumber() and getANI() methods, which provide called
and calling number information to the application
– the consult(), conference(), transfer(), blindConference(), and
blindTransfer() methods, which provide call transfer and conference call
facilities.v The PlayAttributes class specifies whether the caller can interrupt the
messages played as part of a voice or DTMF input.
v The MenuAttributes class defines a menu that the caller can select a choice
from. Each choice contains a label to identify the choice to the application, a
message to announce the choice to the caller, a DTMF selector key and a
selector word.
v The InputAttributes class specifies how a caller is to be guided through
giving an input, and how their input should be validated.
v The DTMFAttributes class specifies how a caller can use their telephone
keypad to give input.
v The RecoAttributes class specifies how a caller can speak to the application
to give input.
Java applications
4 Developing Java Applications
How does the caller interact with the Java application?
The caller can interact with the application in two ways:
v Free form key or voice input
v Structured menu input using key presses (DTMF), or speech recognition, or
both.
There are five attribute classes that are used in conjunction with the
Call.playAndGetInput() method to facilitate this: “The PlayAttributes class”
on page 72, “The InputAttributes class” on page 73, “The MenuAttributes
class” on page 76, “The DTMFAttributes class” on page 80 and “The
RecoAttributes class” on page 81.
To record the caller’s speech and store it as a voice segment, you use the
Call.record() method.
ApplicationProperties
CallCall
Call
record()
invokeStateTable()
playAndGetInput()
play()
MediaType
PlayAttributes
InputAttributes
MenuAttributes
DTMFAttributes
RecoAttributes
RecordingInfo
StateTableResult
InputResult
WVRmakeCall()waitForCall()
WVRApplication
Figure 1. Overview of some of the more important WebSphere Voice Response Java API classes
Java applications
Chapter 1. Introduction to WebSphere Voice Response Java development 5
For more information about speech recognition see the WebSphere Voice
Response General Information and Planning manual and the WebSphere Voice
Server Administrator’s Guide for your version of WebSphere Voice Response.
How do you specify what the Java application says?
You can use prerecorded speech or text-to-speech in a Java voice application
by using any of the following subclasses of MediaType. These media classes
specify the sounds that the caller hears:
v VoiceSegment specifies recorded voice data and is used both for output,
and for input recorded from the user.
v DTMFSequence specifies a number of dual-tone multifrequency signals to
be played.
v AudioCurrency specifies a currency amount to be spoken.
v AudioDate specifies a date to be spoken.
v AudioNumber specifies a number to be spoken.
v AudioString specifies a character string to be spoken.
v AudioTime specifies a time to be spoken.
v TextToSpeech specifies text from which speech is to be synthesized.
v MediaSequence is a composite of other MediaType objects.
You can also use arrays of MediaType objects to make a composite sequence
of any of the media elements. All the methods capable of playing a message
can accept arrays of MediaTypes. This allows your applications to play chains
of MediaType objects in one operation.
You can make any data item presentable to the caller using the Playable
interface. For example, the name, date of birth, and salary retrieved from an
employee record in a database could be spoken as TextToSpeech, AudioDate
and AudioCurrency items respectively.
How do Java applications access information?
Unlike the proprietary programming languages and interfaces supplied with
many interactive voice response systems (for example, WebSphere Voice
Response state tables), you can use the Java API together with other APIs and
classes from other sources to create your applications, for example, you can
use other Java classes for database access, including:
v IBM Host Application Connectivity Link (HACL)
v JDBC database access
v IBM Secureways (LDAP directory access)
Java applications
6 Developing Java Applications
Adding voice capability to existing business applications
Most importantly, you can add voice capability to existing business
applications, taking advantage of what’s already there without having to
change it.
For example, if you are an IBM e-business, you may already be using
Enterprise JavaBeans (EJBs) to write the server side components of your
business applications in Java. Your enterprise application model looks
something like the one shown in Figure 2.
This model is designed to deliver Web pages. You would probably use IBM
WebSphere Studio Site Developer to create the business logic and author the
Web pages. The applications would use connectors to access the data in tier-3.
It’s easy to add voice to this model. Let’s put it in terms of a real example.
Assume that one of the Java applications offered by the e-business shown in
Figure 2 accesses insurance policy data and returns it to the user’s Web
browser. The enterprise can add voice to the solution without changing the
business logic and tier-3 server delivering data to users. Using IBM
WebSphere Studio Site Developer and the Java API supplied with WebSphere
Voice Response they can implement a voice application that integrates with
the existing Web application at the Enterprise JavaBeans (EJB) level. The final
result provides user access to insurance data through fully integrated voice
and Web applications, as shown in Figure 3 on page 8.
Figure 2. E-business application model
Java applications
Chapter 1. Introduction to WebSphere Voice Response Java development 7
This is a simple example, but the same principles apply to complex e-business
environments in which WebSphere Voice Response might link with several
other IBM products to enable successful e-business across existing enterprises.
These products include not only WebSphere but others such as SecureWay®
(for directory access), WebSphere MQ (for messaging), CICS® (for transaction
processing), and DB2® (for database access).
Creating reusable components
The Java language is especially suited to modular programming. You can
design your applications as a set of classes, which you can reuse in other
applications, and which are easy to customize and maintain.
Integration and interoperability of Java applications
In addition to being able to access data, Java applications are also very easy to
integrate with other systems. For example, call control can either be handled
by the WebSphere Voice Response system or it can be fully integrated with a
telephony service.
The benefits of Java
Using Java provides the following benefits:
v While it is recommended that you create the dialogs using VoiceXML, Java
can be used to augment the capabilities of the VoiceXML specification with
functions such as outbound calling.
v Java provides a simple and friendly environment for the integration of
VoiceXML dialogs with lower-level functions and a wealth of other
capability.
v Platform independence—Java applications run either on an application
server or on the WebSphere Voice Response system.
WebSphere ApplicationServer
HTML/HTTP
EJBEJB
EJB
Data
JSP
Command
ConnectorConnector
ConnectorJSPJSP
Telephone
Web browser
Caller
TelephoneNetwork
Host System
Java and VoiceXMLEnvironment
WebSphere VoiceResponse system
Voice response node
JavaapplicationJava
applicationJava
application
Figure 3. Adding voice to e-business
Java applications
8 Developing Java Applications
How to get voice data into applications
Voice segments are the prerecorded sounds that callers hear when they listen
to a voice application. A VoiceSegment media object represents a voice
segment stored on the WebSphere Voice Response server. A voice segment has
a category and a name, these together with the locale uniquely identify the
voice segment stored on the telephony server.
An understanding of how voice segments are stored is fundamental to
understanding how Java voice applications work:
v “How voice segments are stored and identified.”
v “Making voice segments available to Java applications” on page 11.
v “What happens when you install a language?” on page 12.
How voice segments are stored and identified
Voice segments are stored in the voice segment database of the base
WebSphere Voice Response system on the voice response node.
However, any voice segments that are required by Java voice applications
must be located in a special Java voice segment space within the voice segment
database, as shown in Figure 5 on page 10. Utility commands are provided for
adding your voice segments to this space.
Host System
Voice response node
JavaapplicationJava
applicationJava
application
Voicesegmentdatabase
Java and VoiceXMLEnvironment
WebSphere VoiceResponse system
Figure 4. Voice segment database
how to get voice data into applications
Chapter 1. Introduction to WebSphere Voice Response Java development 9
This space is divided into locales, which are, in turn, divided into categories.
Figure 6 shows an example where there are three locales, English (en), U.K.
English (en_GB), and German (de_DE). There is a Menu and a System
category in both U.K. English and German, and a Tutorials category in
English.
Note: If a voice segment for a specific country or region is not found, the
search continues among voice segments for the language. So, the "en"
voice segments can be used by an application whose locale is either
en_GB or en_US, or any other locale whose language component is
"en".
Voice segmentsavailable to Java
applications
Java voicesegment space
VoicesegmentdatabaseVoice segment database
Base WebSphere VoiceResponse system
Figure 5. Voice segments in the Java voice segment space
Figure 6. The Java voice segment space is divided into locales, which are divided into categories
how to get voice data into applications
10 Developing Java Applications
Making voice segments available to Java applications
You can make voice segments available to your Java voice applications in any
of the following ways (as shown in Figure 7):
1. Record new voice segments in a studio or using a sound recorder utility,
and import them from your file system, either singly or “in batch”. See
Chapter 5, “Managing your voice segments,” on page 113.
2. Use voice segments that are already on your base WebSphere Voice
Response system, and add them to the Java voice segment space. See
Chapter 5, “Managing your voice segments,” on page 113.
3. Use the Call.record() method to record new voice segments in a Java voice
application. See “Recording the caller’s voice input” on page 85.
4. Transfer them from the database on one voice response node to the
database on another voice response node by exporting and then importing
them. See Chapter 5, “Managing your voice segments,” on page 113.
5. Use the WVR.importVoiceSegment() and WVR.exportVoiceSegment()
methods in a Java application to import and export voice segments from
or to a file or audio stream.
Note: These voice segments are used by Java applications only, not by
VoiceXML applications.
Voicesegmentdatabase
Record
dtjplex -actionexportVoiceHost
4. Transfer fromone voice response
node to another
5. Use the WVR.import Voice Segment() and WVR.export Voice Segment() methods in aJava application to import and export voice segments from or to a file or audio stream
dtjplex -actionimportVoiceHostFile
system
1. Record new voicesegments in a studio
or using a soundrecorder utility, and
import them “in batch”
2. Use voice segmentsfrom your base
Voice Response system3. Use the Call.record()method to record newvoice segments in a
Java application.dtjplex
-action addVS
FilesystemJava voice
segment space
VoicesegmentdatabaseVoice segment database
Figure 7. Alternative ways of making voice segments available to your applications
how to get voice data into applications
Chapter 1. Introduction to WebSphere Voice Response Java development 11
What happens when you install a language?
Whenever you install a language in the Java environment, new voice
segments are imported from the language zip file into the Java voice segment
space. All these voice segments are located in the System and Menu
categories.
How languages are identified in VoiceXML and Java
All of the base WebSphere Voice Response products use the concept of
“language”, and some languages are defined in terms of language and the
country or region in which it is spoken: for example, Canadian French as
opposed to French spoken in France. In Java, this is explicitly acknowledged,
by using the term locale to refer to both the language and the specific territory.
Each locale is identified by an ISO-defined code, which comprises a language
component and a country or region component: for example, fr_CA for
Canadian French and fr_FR for French in France.
Optionally, you can create your own locale identifiers, including an optional
user-defined variant. For example en_US_FRED. If you are using a locale to
create Java voice segments, there is a limit of 15 characters for the length of
the locale identifier, so the variant part can be up to 9 characters. For
portability across different versions of the JDK, ensure that the locale variant
(’US’ in the previous example) is specified in uppercase.
In VoiceXML, the locale of the application is identified by the xml:lang
attribute of the <vxml> tag.
This section tells you about
v “Why locale is important” on page 12.
v “Default locale” on page 13.
v “Internationalization” on page 13.
v “Defining your own locales” on page 14.
v “Language-only locales” on page 14.
v “How locale is used for speech recognition and text-to-speech” on page 15.
Why locale is important
Locale is used for:
v Identifying precisely what is to be spoken to the caller: the words, accent,
and phrasing used (by using the variant component of the locale identifier,
you can also specify any other characteristics you want). In other words,
locale is used to identify the voice segments to be used.
v Determining the technology to be used for text-to-speech and speech
recognition.
v Optionally, altering the logic of your application.
how to get voice data into applications
12 Developing Java Applications
In VoiceXML, the locale also determines the language of the built-in
grammars, error prompts, and other language-specific features used by the
browser to handle an incoming call.
Default locale
The concept of a default locale is an important one, whether you are designing
and writing applications or setting up and managing systems:
v Each voice response node has a default locale, defined in the NodeName
configuration entry (for more information see WebSphere Voice Response for
AIX: Deploying and Managing VoiceXML and Java Applications). This default
locale is used by Java applications. For VoiceXML 2.0 applications, the
default locale is the locale of the operating system. If the operating system
is running in an unsupported locale, the default will be en_US.
v Optionally, each application can have a default locale, overriding the node
default locale. This must be specified in the AppName entry.
Internationalization
Although applications can be written to run on any supported locale, there
are differences in the way that CCXML, VoiceXML, and Java applications are
internationalized.
VoiceXML
In VoiceXML, resources referenced by URIs are not subject to changes in the
current locale, but built-in resources (such as built-in grammars) are. You
should associate a locale with the document rather than with the execution
environment (by using the <vxml> xml:lang attribute) to ensure that the
correct built-in resources are used.
CCXML
In CCXML, resources referenced by URIs are not subject to changes in the
current locale. There is no mechanism for associating a locale with the
document rather than with the execution environment. CCXML can be written
in any supported code page. There is a charset attribute for the <script>
element that allows the CCXML script to indicate the code page of an ECMA
script to be fetched.
Java
Java applications can be completely language-independent if the locale is not
specified on any individual voice segment objects within the application. To
make the application speak a specific language, simply set the default locale
of the node to that language. You could have several voice response nodes,
each running the same applications in a different language. Provided that
voice segments for the locale are available they are played to the caller in that
language.
how languages are identified in VoiceXML and Java
Chapter 1. Introduction to WebSphere Voice Response Java development 13
Instead of using the node default locale, you could specify a default locale for
each application, and have applications speaking different languages running
in the same node. You can have several AppName configuration entries for
the same Java class, each specifying a different application name and a
different locale.
Thus, the current locale provides full internationalization for your Java
applications, provided that each language is installed on the voice response
node.
Defining your own locales
It is up to you how you use the user-defined variant component of the locale
identifier. You might record voice segments for an application using different
voices: male and female, for example. You would identify these voice
segments as, for example, en_US_MALE, en_US_FEMALE).
You might have a different greeting at the beginning of an application,
depending on which branch of your company the call is for, even though the
logic of the application is the same for all branches. To achieve this, invent a
locale identifier for each branch (for example, en_US_CHICAGO,
en_US_WASHINGTO, en_US_NEWYORK). Then name each greeting voice
segment using the appropriate locale identifier, and use different default
locales, in one of the ways described in “Internationalization” on page 13, to
run instances of the application for each branch. The other voice segments in
the application, common to all branches, should be in the base locale (en_US).
Whenever a voice segment for a specific variant cannot be found, a voice
segment for the country or region and language is searched for.
Specifying PREEURO support with existing 3–part locales
As a result of Euro support, five languages (French, Castilian Spanish,
Catalan, German, and Italian) default to saying Euro rather than the national
currency in both new and existing applications. In two–part locales (for
example, fr_FR), you can override this by specifying a variant of PREEURO
(for example, fr_FR_PREEURO) in the locale option of the AudioCurrency
object (see Developing Java applications). However, if you have defined your
own locales with three parts (for example, fr_FR_PARIS), and want to use
preeuro support, you can do this only by specifying dtj.preeuro.support =
true in the dtj.ini file.
Language-only locales
In some cases, you may want to use a language-only locale identifier, such as
“en” or “fr”. One example of this is the use of “en” as a locale identifier for
the voice segments supplied for the tutorial applications in Chapter 7,
“WebSphere Voice Response Java Tutorials,” on page 121. These voice
segments can be used when the current language of an application is any
how languages are identified in VoiceXML and Java
14 Developing Java Applications
derivative of the en locale: en_US, en_GB, en_AU, and so on. Whenever a
voice segment for a specific country or region cannot be found, a voice
segment for the generic language is searched for.
How locale is used for speech recognition and text-to-speech
Because some speech recognition and text-to-speech technologies are better at
some languages than others, you can use different technologies for processing
different languages. You specify one technology for “all locales” and then
override this for the exceptional languages. This can be specified on a per
node or per application basis. Specifying the technology for a new language
or switching between technologies for any language is done without altering
the application itself.
If you are using language-only locales, make sure you have speech plug-ins
configured for all locales or the single-part locale.
The current application locale is assumed for all speech recognition attempts,
and is used for text-to-speech unless specified within the application. The
current application locale for VoiceXML 2.0 applications is either the operating
system locale or the application default locale, if one has been specified. The
current application locale for Java applications is the node default locale or
the application default locale, if one has been specified.
Speech technologies
You can run interactive voice response applications featuring speech
recognition and text-to-speech on a WebSphere Voice Response system, or on
a PC running.
IBM WebSphere Voice Server can be used with WebSphere Voice Response to
perform speech recognition and text-to-speech. For more information, see
WebSphere Voice Response for AIX: General Information and Planning.
Where to get more information about using speech technologies
You can refer to the following related topics in this documentation:
v “Using speech recognition for menus and data entry” on page 91.
v “The TextToSpeech class” on page 68.
v “The RecoAttributes class” on page 81.
You can also refer to WebSphere Voice Response for AIX: Deploying and Managing
VoiceXML and Java Applications.
how languages are identified in VoiceXML and Java
Chapter 1. Introduction to WebSphere Voice Response Java development 15
speech technologies
16 Developing Java Applications
Chapter 2. Using the WebSphere Voice Response simulator
provided with Voice Toolkit for WebSphere Studio
This section tells you how to use the Voice Response simulator included with
Voice Toolkit for WebSphere Studio, which was introduced in WebSphere Voice
Response for AIX: Deploying and Managing VoiceXML and Java Applications.
v “The WebSphere Voice Response simulator.”
v “System requirements for the Voice Response simulator” on page 18.
v “Installing the Voice Response simulator” on page 19.
v “Starting the Voice Response simulator” on page 21.
v “Voice Response simulator utilities” on page 22.
v “Using the Voice Response simulator telephone” on page 23.
v “Installing languages” on page 25
v “Getting the Voice Response simulator ready to run your applications” on
page 26.
v “Using text-to-speech and speech recognition with the simulator” on page
32
v “Monitoring the phone lines” on page 32.
v “Limitations of the Voice Response simulator” on page 36.
v “Differences between using the Voice Response simulator and a real
WebSphere Voice Response system” on page 36.
v “Troubleshooting the Voice Response simulator” on page 37.
v “Uninstalling the Voice Response simulator” on page 40.
The WebSphere Voice Response simulator
The WebSphere Voice Response Simulator is part of Voice Toolkit for
WebSphere Studio. The Voice Response simulator runs in a Windows
environment on a PC and simulates telephones, phone lines, a telephone
switch, and a WebSphere Voice Response system complete with a WebSphere
Voice Response Java and VoiceXML Environment.
Figure 8 on page 18 shows how the simulator simulates phones, the switch,
WebSphere Voice Response system and WebSphere Voice Response Java and
VoiceXML Environment.
© Copyright IBM Corp. 1998, 2008 17
The only restrictions are that you cannot test call control functions such as call
transfer and conferencing, nor can you test AIX-specific components such as
state tables or custom servers as the Voice Response simulator can only be
used in a Windows environment.
System requirements for the Voice Response simulator
The Voice Response simulator has the following requirements in addition to
those that apply to Voice Toolkit for WebSphere Studio (for WebSphere Voice
Toolkit requirements see the readme file supplied with the product):
v TCP/IP installed and configured. You don’t need to have a static IP address
for your machine, nor is it necessary for the PC to be connected to a
network
v A full duplex sound card with speakers or headphones
v A microphone (if you want to record from your voice application)
Setting up TCP/IP to use the Voice Response simulator
TCP/IP must be installed and configured. It is not necessary to have a static
IP address for your machine, nor is it necessary for the PC to be connected to
a network.
Make sure that you have “localhost” defined in the TCP/IP
winnt\system32\drivers\etc\hosts file.
If your PC is not network-attached, it may be necessary to enable the TCP/IP
loopback device.
Javaapplication
Javaapplication
Javaapplication
Java and VoiceXMLenvironment
WebSphere VoiceResponse system
Switch
Voice response node
Configurationdatabase
WebSphere Voice Response Simulator
Figure 8. The Voice Response simulator
18 Developing Java Applications
Enabling the loopback device
On Windows 2000 the MS Loopback adapter can be installed by selecting
Control panel -> Add/Remove Hardware -> Add/Troubleshoot a device ->
Add a new device -> Select from list -> Network adapters -> Microsoft
Loopback adapter.
You must then ensure that the loopback adapter comes before your network
adapters in the network bindings (Control panel -> Network -> Advanced ->
Advanced settings ->. Move the loopback adapter to the top of the
connections list.)
Installing the Voice Response simulator
The Voice Response simulator is installed automatically when you install
Voice Toolkit for WebSphere Studio, included in the WebSphere Voice
Response for AIX package.
The WebSphere Voice Toolkit installation process does not affect any previous
installation of the Voice Response simulator. If you have a previous version of
the Voice Response simulator installed and you want to continue to use your
voice segments and configuration file you need to export them from your
existing installation, and import them into the new setup. However you
should be aware that the new configuration file contains some differences, see
“Installation procedure” for details.
Installation procedure
1. Export any voice segments or files you wish to keep from your existing
installation of the Voice Response simulator to a safe place (refer to
Chapter 5, “Managing your voice segments,” on page 113 for more details
on how to do this).
2. Install Voice Toolkit for WebSphere Studio according to the installation
instructions in the readme supplied with the product. When the
installation process is complete the Voice Response simulator files are
located in the following directory:
websphere_studio_install_path\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_x.y.z
where websphere_studio_install_path is the location of WebSphere Studio Site
Developer, and x.y.z is the version number of the WebSphere Voice Toolkit.
This directory is referred to as the WVRsim directory. All relative path
names referred to in this section (for example, dtj_logs\log.1.log) are
relative to the WVRsim directory.
3. Add the pathname of the WVRSim directory to the default PATH. To do
this on Windows 2000, open the control panel, click on the System icon,
and then click on the Environment tab. Edit the PATH variable.
If you have an existing Voice Response simulator installation directory in
your path, for example C:\DTSIM, remove it now.
system requirements for the Voice Response simulator
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 19
4. Open the PATH variable again for editing and add the pathname of the
IBM(R) 32-bit Runtime Environment for Windows(R), Java(TM) 2
Technology Edition, Version 1.4.1 included with the WebSphere Voice
Toolkit. The default pathname is:
websphere_studio_install_path\VoiceToolkit\jvm\jre\bin
Make sure this entry comes before any other JRE (Java Runtime
Environment) you may have installed on your system, in either the user or
system path variables. To find out what JRE your system is using, open an
MS-DOS window and enter the command
java -version
If your version is not 1.4.1, make sure that you have edited the PATH
variables (both system and user) correctly.
5. Before you can use the Voice Response simulator you need to import some
voice segments. To do this, follow the instructions in “Starting the Voice
Response simulator” on page 21 to start the simulator, then follow the
instructions in “Installing languages” on page 25 to import the voice
segments.
6. If you have exported voice segments from a previous installation of the
Voice Response simulator, import them into your new installation and
check that they work as expected.
Attention: The speech recognition and text-to-speech entries in the Voice
Response simulator have changed since previous versions. If you want to
use the configuration file from a previous version of the Voice Response
simulator you will have to incorporate these entries to run speech-enabled
applications.
Note also that the NodeDefLocale is set to en_US. You will need to change
the locale if you keep voice segments in another language.
You can now uninstall your previous version of the Voice Response
simulator as follows:
a. Stop the node and HostManager if they are running.
b. cd to the directory where the Voice Response simulator is installed
(default C:\DTSIM).
c. Enter the following command:
java -cp . uninstall
Your system is now ready for you to follow the Chapter 7, “WebSphere Voice
Response Java Tutorials,” on page 121 or for Chapter 4, “Creating voice
applications,” on page 59.
installing the Voice Response simulator
20 Developing Java Applications
Starting the Voice Response simulator
The Voice Response simulator is ready to use immediately after you have
installed Voice Toolkit for WebSphere Studio.
Follow these instructions to start up the Voice Response simulator and dial a
sample voice application.
1. To start the HostManager, open an MS-DOS window and enter the
following command:
dtjshost
The following messages are displayed in the window:
Starting the HostManager ...
...I DTJ3002 Creating a new HostManagerImpl for this machine.
...I DTJ3001 The HostManagerImpl for this machine was successfully created.
If you don’t see those messages, try the following troubleshooting
suggestions:
v “Starting the host manager (dtjshost) fails with RMI server exception”
on page 38.
v “Starting the host manager (dtjshost) produces no output” on page 38.2. To start the voice response node, enter the following command:
dtjstart
The following messages are displayed in the MS-DOS window:
...I DTJ3015 Starting voice response node Node1 at host host1.
...I DTJ3030 Starting applications at node Node1 at host host1.
...I DTJ3019 Application menu was started at node Node1 at host host1.
...I DTJ3016 Voice response node Node1 at host host1 has started.
The system then displays the WebSphere Voice Response window and a
simulated telephone window labeled 5000, as shown in Figure 9 on page
22.
3. You can close the window whose menu bar says “Finished”, if it doesn’t
close automatically.
4. Minimize the window in which the HostManager started.
starting the Voice Response simulator
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 21
5. To call the menu application, click on the handset to get the dial tone. If
you don’t hear anything, check that the sound is turned up on your
computer.
6. There are two sample applications, one written in Java and the other in
VoiceXML. Dial 1001 to call the Java application or 1002 to call the
VoiceXML application.
7. To shut down the simulator, select File --> Quiesce shutdown in the main
WebSphere Voice Response Simulator window. This waits for active calls
to end before shutting down, so there may be a slight delay before the
Voice Response simulator windows disappear.
8. When the Voice Response simulator windows have gone, stop the
HostManager by pressing Ctrl-C in the HostManager MS-DOS window.
Voice Response simulator utilities
When using the Voice Response simulator, you can use all the supplied
scripts, commands, or batch files. These utilities are explained in detail in
Deploying and managing VoiceXML and Java applications. However you don’t
need to use dtjstop or dtjterm: instead you can use the File menu in the main
Voice Response simulator window to select either Quiesce shutdown or
Immediate shutdown.
All the utilities are designed to be run from the WVRsim directory.
In addition, the simulator has a diag command, which is a simple utility that
prints out the Voice Response simulator environment and its configuration.
Whenever you contact us for help, run this command and include its output
in the e-mail you send to us.
Figure 9. The window displayed when you start the simulator voice response node
starting the Voice Response simulator
22 Developing Java Applications
Using the Voice Response simulator telephone
The Voice Response simulator provides a simulated telephone, which you can
use to dial voice response applications or to answer a call made by a voice
application, on the Windows desktop.
Testing an application that answers incoming calls
To test an application that answers incoming calls, use one of the simulated
telephones to dial the application:
1. To get the dial tone, click on the handset or press the Enter key. If you
don’t hear anything, check that the sound is turned up on your computer.
2. Dial the number associated with the application, from the telephone on the
screen. You can use the telephone as a pushbutton phone, by clicking on
the keys with the mouse pointer, or you can type the number. Either way,
the number appears in the display window. The status of the call is
displayed below the keypad.
Figure 10. The simulated telephone window
using the Voice Response simulator telephone
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 23
3. Press keys in response to your application. The keystrokes are recorded in
the window, as shown in Figure 12. Note that if you interrupt with a
keystroke, you won’t hear a beep until the next keystroke.
4. To hang up, click on the handset or press the Enter key.
Testing an application that makes outgoing calls
First make sure that the application includes an instance of the WVR class
that invokes a makeCall() method, specifying the number shown on the
simulated telephone you are using (in these pictures, “5000”). Run your
application. When the phone rings, click on the handset or press Enter. After
that, it’s just like “Testing an application that answers incoming calls” on page
23.
Figure 11. Dialing an application
Figure 12. After the caller has exited from the application, but before replacing the handset
using the Voice Response simulator telephone
24 Developing Java Applications
Hiding the telephone window
To hide the telephone window, select the Close button
or press the Esc
key. This does not change the state of the call.
Displaying a hidden telephone window
To display a hidden phone from the Voice Response simulator window, select
View --> SimPhone.
To display a hidden phone from the DTsim Line Monitor (explained later in
“Monitoring the phone lines” on page 32), right-click on the phone line and
select Show Phone.
Creating more telephones
When you install the Voice Response simulator, two telephones are created.
You can specify the number of telephones and their phone numbers in the
DTsim.properties file, see “Setting simulator properties” on page 27.
Installing languages
1. The WebSphere Voice Response Simulator includes a separate zip file for
each language that you chose to install audio segments for when you
installed Voice Toolkit for WebSphere Studio. The zip files are called
xx_yy.zip, where xx_yy is the language identifier. These files can be found
in the WVRsim directory.
2. Ensure that the Voice Response simulator is running (see “Starting the
Voice Response simulator” on page 21).
3. For each language you want to use, type the following command and
press Enter:
dtjnlsin xx_yy.zip
where xx_yy is the language identifier. If you are not in the same directory
as the zip files, you need to include the directory path before the filename,
for example:
dtjnlsin websphere_studio_install_path\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_x.y.z\fr_FR.zip
where websphere_studio_install_path is the location of WebSphere Studio Site
Developer, and x.y.z is the version number of the WebSphere Voice Toolkit.
4. You will see a large number of messages as the voice segments are
imported. Make sure you see the final message that says “The language
pack has been installed successfully.....”.
using the Voice Response simulator telephone
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 25
Getting the Voice Response simulator ready to run your applications
You can run your applications on the same system as the simulator or on a
different one, provided that it supports Java, and both systems are known to
the TCP/IP name server.
Configuring the simulator to run applications involves:
v “Adding number-to-application mappings to the configuration database” on
page 27.
v “Setting simulator properties” on page 27.
v “Setting the CLASSPATH for an application” on page 29.
v “Importing voice segments” on page 29.
getting the simulator ready to run your applications
26 Developing Java Applications
Adding number-to-application mappings to the configuration database
The configuration database, config.cfd, includes number-to-application
mappings for the menu application and the app1 application.
To enable the simulator to run applications with other names:
1. Edit the default.cff file
Note: Do not modify the toolkit.cff file, this contains the configuration
required for testing VoiceXML applications from the WebSphere
Voice Toolkit.
2. Find the NodeName=Node1 entry.
3. Add a NumToApp entry to specify the name of your application, in this
example, “myapp”:
NodeName=Node1
NodeDefAppName=noapp
NodeDefLocale=en_US
Enabled=yes
VRNode=yes
NumToApp=1000,app1
NumToApp=1001,menu
NumToApp=1003,VXMLBrowser
NumToApp=1009,myapp
Group=group1
;
4. Save the default.cff file and use the dtjconf command to update the
configuration database.
5. Shut down the main simulator window, and restart it again.
If you use numbers other than 1000 through 1099, see “Setting simulator
properties” on page 27.
That’s all you have to do if you’re going to run the application from
WebSphere Studio Site Developer. To make the application start automatically,
like the supplied “menu” application, you need to read the next section.
Setting simulator properties
DTsim.properties is a text file that defines properties used only by the Voice
Response simulator. Each line contains a property=value statement which
defines the value of a property. Property names are case-sensitive.
Every time you make a change to DTsim.properties, you must shut down and
restart the simulator, using the dtjstart script, for the changes to take effect. It
is not usually necessary to run dtjshost.
DTsim.properties includes the following properties:
getting the simulator ready to run your applications
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 27
BaseIVRNumber
A 4-digit number that specifies the number of the first phone line
associated with the simulated WebSphere Voice Response system. The
number is incremented by 1 for each subsequent line. (Initially set to
2000.)
MaxLines
The number of phone lines associated with the simulated WebSphere
Voice Response system: the maximum number of sessions that can be
used concurrently. Lines are numbered sequentially starting with the
value specified for the BaseIVRNumber property. (Initially set to 2.)
BasePhoneNumber
A 4-digit number that specifies the first telephone number. (Initially
set to 5000.)
MaxPhones
The number of telephones to use. Telephones are numbered
sequentially starting with the value specified for the
BasePhoneNumber property. (Initially set to 2.)
NumberPlan1, NumberPlan2... NumberPlann
Each NumberPlan specifies the mapping of a range of logical phone
numbers to a list of physical phone lines. The format is
aaaa-bbbb:cccc-dddd, where aaaa, bbbb, cccc, and dddd are 4-digit
strings. aaaa-bbbb defines the logical numbers of the hunt group in
the telephone switch; cccc-dddd defines the physical numbers of the
hunt group. Dialing a logical number connects to any one of the lines
in the hunt group; dialing a physical number connects to a specific
line.
For example, 1000-1099:2000-2009 defines ten lines, with physical
numbers 2000-2009. Each of these lines can be dialed directly using
their physical number, and also by dialing a logical number in the
range 1000-1099.
VoiceDir
The top-level directory, where voice segment files are located. By
default, the simulator installation locates the voice files in the
WVRsim\voice directory. Do not change the value of this property,
because some of the sample scripts won’t work if you do.
VoiceDataMapFile
The name of the file containing the voice segment definitions. This file
allows Java applications to find the voice segment files at runtime. Do
not change the value of this property, because some of the sample
scripts won’t work if you do.
SimPhoneSoundEffect
Set this property to 1 to generate tones when keys are pressed on the
getting the simulator ready to run your applications
28 Developing Java Applications
telephone. Set this property to 0 to suppress the tones, for example,
when you are recording voice segments and do not want to record the
tones as well.
MaxRecordTime
A numeric value that specifies, in seconds, the maximum time
allowed by the Call.record() method for recording voice.
Setting the CLASSPATH for an application
To enable the simulator to find your applications:
1. Edit the default.cff file.
2. Find the NodeName=Node1 entry.
3. Use the NodeClassPath keyword to specify the path of the jar file or
directory containing the application, for example:
NodeClassPath=/j/prod/MyApplications.jar
4. Save the default.cff file and use the dtjconf command to update the
configuration database.
Importing voice segments
Follow these instructions to import WAV files containing linear PCM encoded
data into the simulator.
1. cd to the directory where the WAV files are.
2. If the WAV files did not come with a control file, create a control file like
the one shown in Figure 13 on page 30. Substitute your voice segment
category name for “Pizzas”; your locale identifier for “en_US”; and your
own file names and segment names for “hello”, “goodbye”, and so on.
3. Enter the following command to import the segments:
dtjplex -action importVoiceHost -controlfile filename
For more detail about this task, see Chapter 5, “Managing your voice
segments,” on page 113.
getting the simulator ready to run your applications
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 29
Setting up an application to start automatically
This section explains how to set up your application to start automatically.
However, until you are familiar with the system, you will find it easier to test
your applications by running them manually instead of starting them
automatically when the Voice Response simulator starts.
Procedure
You must add an AppName entry for the application to the configuration, and
an Application keyword to the GroupName entry. Figure 14 on page 31 shows
how you can modify the supplied default.cff file to define different language
versions of the “menu” application.
1. Install the languages: see “Installing languages” on page 25. You now have
the necessary voice segments to try this out.
2. Edit the default.cff file.
3. Add an AppName entry for each language version of the application, as
shown in Figure 14 on page 31. Make sure you specify the Locale keyword
in each AppName entry. Specify the same AppClass for each language
version, but a different AppName to identify each.
4. Add an Application keyword for each language version to the
GroupName entry, as shown in Figure 14 on page 31. Specify the names
you specified for the AppName keywords.
5. Add a NumToApp keyword for each language version to the NodeName
entry, as shown in Figure 14 on page 31. Specify the names you specified
for the AppName keywords.
6. Save the default.cff file and use the dtjconf command to update the
configuration database.
7. Shut down the main simulator window, and start it again.
# Set overall parameter values:
# Source:
segment_category=Pizzas
segment_locale=en_US
# Destination:
import_hints=Q0S0
# Set parameter values for individual segments:
file_name=hello
segment_name=hello
;
file_name=goodbye
segment_name=goodbye
;
file_name=help
segment_name=help
;
Figure 13. Example of control file for importing voice segments into the simulator
getting the simulator ready to run your applications
30 Developing Java Applications
#
# Define the applications
#
# noapp is the default application - it runs when a call is made
# to a number for which the defined application is not running, or
# for which there is no NumToApp mapping in the voice response node
# configuration.
#
AppName=noapp
Enabled=yes
AppClass=sample.DefaultApp
;
#
# Menu is a sample application, in U.S. English
#
AppName=menu
Enabled=yes
Locale=en_US
AppClass=com.ibm.telephony.directtalk.samples.DTDemoV
;
Figure 14. Defining different language versions of the “menu” application (Part 1 of 3)
#
# This is the German version of menu
#
AppName=menu_de_DE
Enabled=yes
Locale=de_DE
AppClass=com.ibm.telephony.directtalk.samples.DTDemoV
;
#
# This is the French version of menu
#
AppName=menu_fr_FR
Enabled=yes
Locale=fr_FR
AppClass=com.ibm.telephony.directtalk.samples.DTDemoV
;
Figure 14. Defining different language versions of the “menu” application (Part 2 of 3)
getting the simulator ready to run your applications
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 31
Using text-to-speech and speech recognition with the simulator
For information on using text-to-speech and speech recognition with the
WebSphere Voice Response simulator, see “Using speech recognition and
text-to-speech with the WebSphere Voice Toolkit WebSphere Voice Response
simulator,” on page 221.
Monitoring the phone lines
The line monitor shows the configuration of the telephone switch and the
states of all the phone lines defined to the switch.
1. To display the Line Monitor from the Voice Response simulator window,
select View --> Line monitor.
#
# Start one copy of each of the applications, when the node starts
#
GroupName=group1
Enabled=yes
Application=menu
Application=menu_de_DE
Application=menu_fr_FR
;
# Define the mapping between number called and the application that is
# used to service the call
#
NodeName=Node1
NodeDefAppName=noapp
NodeDefLocale=en_US
Enabled=yes
VRNode=yes
NumToApp=1000,app1
NumToApp=1001,menu
NumToApp=1002,menu_de_DE
NumToApp=1003,menu_fr_FR
Group=group1
;
# Define the TCP/IP hostname and the WebSphere Voice Response node name
# for this host.
#
HostName=host1
Enabled=yes
IPName=localhost
Node=Node1
;
Figure 14. Defining different language versions of the “menu” application (Part 3 of 3)
getting the simulator ready to run your applications
32 Developing Java Applications
2. To display the logical numbers defined for the switch, double-click on the
Switch. 1000 through 1099 are the logical numbers in a hunt group.
Figure 15. The DTsim Line Monitor window
monitoring the phone lines
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 33
3. To display the physical numbers for this hunt group, double-click on the
1000-1099.
Figure 16. The DTsim Line Monitor window showing the logical phone numbers defined
monitoring the phone lines
34 Developing Java Applications
Simulating multiple callers
Every phone line in the switch has a unique physical number. Additionally, a
line may belong to a hunt group. Lines in a hunt group are accessible using
the logical numbers defined for the group. If you associate a voice application
with a physical number, only one caller can get through to the program at any
one time. Using a logical number several callers may call the number and be
serviced at the same time. In the Line Monitor window, the folders in the Line
column represent the hunt groups defined. The labels of the folders show the
logical numbers defined for the group. Double-click on a hunt group folder to
reveal the physical lines in the group. The hunt group folder labeled
Ungrouped contains physical lines that are not part of a hunt group. These
are typically lines associated with telephones.
Switch configuration
The configuration of the switch is held in the DTsim.properties file under the
NumberPlan properties. A physical line that has been defined in a number
plan but is not instantiated (that is, not associated with the VRU or a phone)
is marked as Unavailable in the monitor.
The Calling Number and Called Number columns show the phone number of
the caller and the number they dialed respectively. These are available for
Figure 17. The DTsim Line Monitor window showing the physical line numbers defined
monitoring the phone lines
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 35
inbound calls only and may be retrieved by a Java voice application using the
methods Call.getANI() and Call.getDNIS().
Monitoring the sessions
In the Voice Response simulator, a session is created when one is needed. It is
created when an application makes an outbound call or when an inbound call
arrives, but only when no free ones are available. An IDLE session is one
which is running an application but not performing a telephony action. An
OFF-LINE session is one which is not associated with a call and is available
for reuse.
To monitor the status of the sessions, from the Voice Response simulator
window, select View --> Session monitor.
Limitations of the Voice Response simulator
The Voice Response simulator can only be used to run voice applications
written using VoiceXML or the classes supplied with WebSphere Voice
Response. In addition:
v None of the functions that require advanced features of a telephone switch
are available. Your voice application cannot hold or transfer a call or use
conference or consult using the simulator.
v DTMF keys are only recognized when generated by a voice application or
from the supplied telephone simulation. DTMF tones in their audio form
are not recognized.
v ANI and DNIS are available for inbound calls only.
v Only 4-digit phone numbers are supported.
v The Call.invokeStateTable() method is not supported.
v There are no audio sound effects when playing DTMF in an application.
Differences between using the Voice Response simulator and a real WebSphere
Voice Response system
In addition to the “Limitations of the Voice Response simulator” on page 36,
there are some other differences:
Figure 18. DTsim Session Monitor window
monitoring the phone lines
36 Developing Java Applications
v The main difference between using WebSphere Voice Response and the
Voice Response simulator is in the call setup. In the real WebSphere Voice
Response environment, all incoming calls are answered by the base
WebSphere Voice Response system before control is passed to the
WebSphere Voice Response Java and VoiceXML Environment. In the
simulator environment, calls arrive at the voice response subsystem directly
without first being answered. On the Voice Response simulator, a call is
answered only if there is a Java voice application configured for the dialed
number. This allows you to distinguish the case where an application is
invoked and subsequently fails (call is answered and immediately hung
up), and when there is no application configured for the number (call is not
answered).
v The Voice Response simulator is a controlled and idealized environment.
For instance, a voice application always gets a positive far-end hang-up
notification from the simulator, whereas the same application running on a
real network is subject to the limitations of the signaling protocol used. You
should always test your applications on a real network before deploying
them in production.
v There is no concept of inbound-only or outbound-only lines. All lines can
handle both incoming and outgoing calls.
v When importing a voice segment, you can specify any of the valid values
for the segment_encoding parameter: The simulator automatically stores
the voice segment in the appropriate format.
Troubleshooting the Voice Response simulator
The following suggestions refer to the Windows install directory and the
WVRsim directory (the directory where the Voice Response simulator is
installed).
WVRsim and a real WebSphere Voice Response system
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 37
Starting the host manager (dtjshost) fails with RMI server exception
If you see the following messages:
... I DTJ3002 Creating a new HostManagerImpl for this machine.
java.rmi.ServerException: Server RemoteException; nested exception is:
java.rmi.AccessException: Registry.rebind
... E DTJ3003 The creation of the HostManagerImpl for this machine has failed.
make sure that TCP/IP is properly configured. To do this on Windows 2000:
v Make sure that the MS Loopback Adapter is installed (the IP address
assigned to it does not matter). You must then ensure that the loopback
adapter comes before the other network adapters in the network bindings
for the TCP/IP protocol.
v If you are using a desktop firewall product, you should disable it to make
sure it is not interfering with the RMI calls.
Starting the host manager (dtjshost) produces no output
You can only start one instance of the HostManager. Attempting to start it for
a second time causes the command to hang without any output.
Recording does not work
Check in the Windows audio mixer applet that you have:
v Enabled the microphone as a record source.
v Set the record volume to the maximum.
Poor performance, long pauses during play
Long pauses during the playback of voice can be caused by having the
Windows audio mixer applet running. Close the audio mixer application.
You can’t hear anything
Check that you have the sound turned up on your computer.
troubleshooting the Voice Response simulator
38 Developing Java Applications
You start to use a second phone and the first phone stops talking
To use more than one phone, the sound card must be able to support more
than one concurrent session. If the maximum number of sessions supported
by the sound card is exceeded, you may get completion code 505,
TELEPHONY_SERVER_ERROR when playing a media object. Use the
SoundcardTest.exe utility to find out how many concurrent sessions your
sound card supports.
The recorded sound is faint
Check the record setting on your Audio Mixer, making sure that the volume
control for microphone input is set to maximum. If the recorded sound is still
too soft, set the REC_AMP environment variable in the dtjenv.bat file to a
small positive integer. A value of 3 or 4 is usually sufficient. You may need to
experiment with the value to achieve the optimal result. The Node and the
HostManager must be shut down and restarted each time you change the
value of REC_AMP.
The recorded sound is distorted
Your record level is probably set too high. Unset the REC_AMP environment
variable in dtjenv.bat. Reduce the volume for microphone input in the audio
mixer as necessary.
DTMF sound effect works intermittently
Use the SoundcardTest.exe utility to find out how many concurrent sessions
your sound card supports. If SoundcardTest reports a value of 1, there is only
one session. This means that when you interrupt a voice prompt using a key,
there is no sound effect
The first few seconds of user input is not recorded
This is a limitation of the sound hardware. Some sound cards take a
noticeable time to switch from playback to record mode during which nothing
is recorded.
Incoming call is not answered
This is caused by not having an application defined and running for the
number you called. You must ensure that:
v Each phone number you plan to use is defined in a NumToApp statement
in default.cff, or you have a default application defined.
v The applications defined for the phone numbers are running. Whenever a
call is rejected, the event is logged in the WVRsim\dtj_logs\log.1.log file
(see “Using message logs” on page 117 for more information about using
log files). We recommend that you always have a default application
defined.
troubleshooting the Voice Response simulator
Chapter 2. Using the WebSphere Voice Response simulator provided with Voice Toolkit for WebSphere Studio 39
The application answered my call and hung up immediately
This is usually caused by a play failure. Check that you have all the voice
segments needed by your application. Use the diag utility to verify the
integrity of your voice data map, and use dtjplex -listVS to get a list of the
voice segments defined.
Uninstalling the Voice Response simulator
To uninstall the Voice Response simulator you must uninstall Voice Toolkit for
WebSphere Studio. To uninstall the WebSphere Voice Toolkit follow the
uninstall instructions provided in the WebSphere Voice Toolkit documentation.
troubleshooting the Voice Response simulator
40 Developing Java Applications
Chapter 3. Using the WebSphere Voice Response Java API
classes
Read this section after reading Chapter 1, “Introduction to WebSphere Voice
Response Java development,” on page 1. If this is your first reading, we
suggest that you have a quick look through this section , register the Java API
classes with WebSphere Studio Site Developer and then work through the
supplied tutorials (refer to the Chapter 7, “WebSphere Voice Response Java
Tutorials,” on page 121) to get some practical experience. You will find it
useful to refer to this chapter when you come to develop your own
applications. For more detailed information about each class, see the JavaDoc
Reference provided on the WebSphere Voice Pesponse for AIX Publications
CD.
This section includes the following topics:
v “Installing the WebSphere Voice Response Java API classes.”
v “Using the Java API with WebSphere Studio Site Developer” on page 43.
v “Introduction to applications” on page 46.
v “Starting the call” on page 53.
v “Looping round to handle another call” on page 56.
v “Finishing with a call” on page 57.
Related information can be found in the following sections:
v Chapter 4, “Creating voice applications,” on page 59.
Installing the WebSphere Voice Response Java API classes
Before you can develop a Java application, you need to install the WebSphere
Voice Response Java API classes, following the instructions in this section.
Prerequisites
v TCP/IP must be installed, configured, and running, and the hostname must
be resolvable by the voice response node (that is, it must have a DNS entry
in the nameserver). For more information, see “Setting up your TCP/IP
network” on page 42.
v The system must have IBM(R) 32-bit Runtime Environment for
Windows(R), Java(TM) 2 Technology Edition, Version 1.4.1 installed.
Note: A prerequisite of Voice Toolkit for WebSphere Studio is that you have
either WebSphere Studio Site Developer or Websphere Studio
Application Developer installed. In this documentation, anywhere that
© Copyright IBM Corp. 1998, 2008 41
WebSphere Studio Site Developer is mentioned, you can also use
Websphere Studio Application Developer. If you have the WebSphere
Voice Toolkit installed you can create your Java applications within it.
Setting up your TCP/IP network
TCP/IP must be installed, configured, and running, with DNS configured to
provide TCP/IP name resolution. This usually means that a static IP address
has been allocated to the machine. This is because the classes use remote
method invocation (RMI), which in turn uses TCP/IP. It is important to set up
your TCP/IP network correctly, otherwise your application will fail with
completion code 503.
Do not install your WebSphere Voice Response system with a dynamic IP
address.
A failure of dtjstart with the message DTJ3029 indicates that the TCP/IP
configuration might have been changed, perhaps because you have installed
some other software. Check the machine hostname and IP Address and ensure
that the name is resolvable, by trying to ping the name. Ensure the hostname
matches the IPName field in the default.cff file. (On Windows 2000, right-click
My Computer and select the Network Identification tab. On AIX, use the
hostname command.) After changing the default.cff file, run the dtjconf
script.
A failure of dtjstart with the message DTJ3021 indicates that Java RMI is not
working properly. For Java RMI to work, it is necessary for host resolution to
work correctly and access a working network interface. For host resolution,
you can either configure the machine to use a DNS server, or add the host
name (the TCP/IP fully qualified domain name) to the /etc/hosts file. You
must be able to ping the TCP/IP host name you have used in configuration
(default.cff). For a working network interface, you must have a network
adapter installed, configured, and running. Make sure ″localhost″ resolves to
the correct IP name.
Instructions
If you have installed Voice Toolkit for WebSphere Studio, the Java API classes
are already installed in the following directory:
websphere_studio_install_path\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_x.y.z
where websphere_studio_install_path is the location of WebSphere Studio Site
Developer, and x.y.z is the version number of the WebSphere Voice Toolkit.
The files in this directory required by the Java API are:
v ibmcctl.jar
v ibmdtext.jar
installing the WebSphere Voice Response classes
42 Developing Java Applications
v ibmdtext2.jar
v ibmdtalk.jar
v ibmwvrapi.jar
v js.jar
v vxi.jar
v vxiev.jar
v vxisrvc.jar
Using the Java API with WebSphere Studio Site Developer
The minimum level of IBM WebSphere Studio Site Developer required is
Version 5.0. These instructions apply to this level. Remember that you can also
use Websphere Studio Application Developer.
Registering the IBM Runtime Environment in WebSphere Studio Site
Developer
WebSphere Studio Site Developer version 5.0 uses IBM 32-bit Runtime
Environment for Windows, Java 2 Technology Edition, Version 1.3.1. The Java
API supplied with WebSphere Voice Response for AIX requires IBM Runtime
Environment version 1.4.1, which is included with Voice Toolkit for
WebSphere Studio. Before you can use the Java API with WebSphere Studio
Site Developer, you must configure WebSphere Studio Site Developer to use
IBM Runtime Environment 1.4.1, as follows:
1. Open WebSphere Studio Site Developer.
2. Select Window->Preferences.
3. In the Preferences window, expand the Java section and click on
Compiler. On the JDK Compliance tab, click on the drop down list next
to Compiler compliance level, and select 1.4.
4. In the Preferences window, under the expanded Java section, click on
Installed JREs.
5. Click Add to bring up the Add JRE window.
6. In the Add JRE window, uncheck the Use default system libraries box.
7. Enter a name for the JRE in the JRE name field.
8. Click in the JRE home directory field and then click the Browse button.
9. Navigate to the IBM Runtime Environment directory. If you have
installed Voice Toolkit for WebSphere Studio, the directory is
websphere_studio_install_path\VoiceToolkit\jvm\jre
10. Click the Add External JARs button. Navigate to the IBM Runtime
Environment \lib directory. If you have installed Voice Toolkit for
WebSphere Studio, this directory is
websphere_studio_install_path\VoiceToolkit\jvm\jre\lib
11. Select all the JAR files and click OK.
installing the WebSphere Voice Response classes
Chapter 3. Using the WebSphere Voice Response Java API classes 43
12. Make sure that core.jar is at the top of the list. To move a JAR file,
select the file and move it using the Up and Down buttons.
13. Click OK. WebSphere Studio Site Developer will now compile projects
using IBM Runtime Environment version 1.4.1.
Running an application
To run an application using the Java API:
1. Select Run->Run...
2. In the Launch Configurations window, select the application and click
New.
3. On the JRE tab, click on the drop-down list and select the IBM Runtime
Environment you added in “Registering the IBM Runtime Environment in
WebSphere Studio Site Developer” on page 43.
4. On the Arguments tab, enter the following in the VM arguments section:
-Ddtj.home="websphere_studio_install_path\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_x.y.z"
where websphere_studio_install_path is the location of WebSphere Studio Site
Developer , and x.y.z is the version number of the WebSphere Voice
Toolkit.
5. Click Run to run the application. Once you have created the launch
configuration for this application, you can re-run it by making sure the
application is selected and then selecting Run->Run As->Java
Application.
Creating a new voice application in WebSphere Studio Site Developer
You register the Java API classes in IBM WebSphere Studio Site Developer
when you create a new application.
Follow these instructions to create a new voice application:
1. Create a new project by selecting File->New->Project.
2. Select Java and Java Project. Click Next.
3. Give the project a name, for example if you are running the tutorials, use
“VRTutorials”. Click Next.
4. Click the Libraries tab. Click Add External JARs and navigate to the
Voice Response simulator install directory. For WebSphere Voice Response
for AIX users this is
websphere_studio_install_path\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_x.y.z
where websphere_studio_install_path is the location of WebSphere Studio
Site Developer, and x.y.z is the version number of the WebSphere Voice
Toolkit.
Open the following files:
v ibmcctl.jar
v ibmdtalk.jar
using the Java API with WebSphere Studio Site Developer
44 Developing Java Applications
v ibmdtext.jar
v ibmwvrapi.jar
v ibmdtext2.jar
v js.jar
v vxi.jar
v vxiev.jar
v vxisrvc.jar
Click Finish.
5. Create a new package for the WebSphere Voice Response Java and
VoiceXML Environment application by selecting File->New->Package.
6. Give the package a name, for example, if you are running the tutorials,
use “tut”. Click Finish.
7. Create the new class for the application by selecting File->New->Class.
8. Make sure the Source Folder and Package fields match the project and
package names you used in steps 3 and 6.
9. In the Name field, type a name for the class.
10. In the Superclass field, click Browse. Type WVRApplication, select the
WVRApplication class and click OK.
11. In the section labeled Which method stubs would you like to create?,
ensure that the check boxes for public static void main(String[] args) and
Inherited abstract methods are checked. Click Finish.
The new class is created in the package and project you specified, and the
corresponding application code is generated, for example:
package tut;
import com.ibm.telephony.wvr.WVRApplication;
import com.ibm.telephony.wvr.WVRException;
/**
* @author
*
* To change this generated comment edit the template variable "typecomment":
* Window>Preferences>Java>Templates.
* To enable and disable the creation of type comments go to
* Window>Preferences>Java>Code Generation.
*/
public class InApp extends WVRApplication {
/**
* @see com.ibm.telephony.wvr.WVRApplication#voiceMain()
*/
public void voiceMain() throws WVRException {
}
creating a new Voice appliction in WebSphere Studio Site Developer
Chapter 3. Using the WebSphere Voice Response Java API classes 45
public static void main(String[] args) {
}
}
Introduction to applications
All WebSphere Voice Response Java applications are extensions of the
WVRApplication class. This class contains methods which are used
automatically by the Java and VoiceXML environment when it manages your
application. The WVRApplication class also contains a voiceMain() method,
which will contain the main implementation of your application. Within this
voiceMain() method your code will include a WVR object, which represents
the base WebSphere Voice Response system, and at least one Call object,
which represents a single call. The WVR class is used to receive and make
telephone calls, handle voice segments and define application properties. The
Call class is used to interact with and manipulate telephone calls, for
example, by playing audio, transferring calls, getting input from callers and so
on.
Managed and unmanaged applications
WebSphere Voice Response Java applications can be:
Managed
When you deploy your application you will want it to be completely
managed by the Java and VoiceXML environment. In order for this to
happen you must define an AppName entry in the configuration file,
default.cff. For more information about the AppName entry see
WebSphere Voice Response for AIX: Deploying and Managing VoiceXML
and Java Applications. When you start the application, the Java and
VoiceXML environment automatically retrieves the settings for the
application environment, such as locale, from the configuration file.
When you tell the voice response node to start up the application, the
Java and VoiceXML environment automatically creates an instance of
your application and starts it running.
For more information about running applications managed (also
known as ″running applications in a node″), see WebSphere Voice
Response for AIX: Deploying and Managing VoiceXML and Java
Applications.
Unmanaged
When you are testing your application you will probably run it
unmanaged. This means that the application is not completely
managed by the Java and VoiceXML environment, and there is no
AppName entry in the configuration file for this application. There
are no environment settings for the application to retrieve so you
creating a new Voice appliction in WebSphere Studio Site Developer
46 Developing Java Applications
must define them yourself within the application. See “Setting the
application environment” on page 49.
Unmanaged applications also do not run automatically. You must
implement the standard Java main() method to enable the application
to be run from a command line. For more information, see “Getting
started: the WVRApplication class” on page 48
Exceptions
The WebSphere Voice Response Java API uses a fairly standard exception
model. Some exceptions are expected, like WVRRequestCancelledException
or WVRHungUpException, but most are thrown when the application
encounters an error condition. The exceptions are arranged into a hierarchy.
The hierarchy groups related exceptions together and allows you to catch a
whole group of exceptions in one go by catching the exception that is the base
class for the group. For instance all exceptions relating to the Call class are
either direct or indirect sub classes of WVRCallException. The base classes
are as follows:
These base class exceptions are never actually thrown themselves, they are
only used for catching groups of exceptions. You can also catch individual
exceptions. The most likely exception you would want to catch in this way
would probably be WVRHungUpException. For example:
WVRException
WVRCallException
WVRConnectionItemException
WVRExternalApplicationException
WVRPlayException
WVRStateTableException
WVRInputException
WVRMakeCallException
WVRVoiceSegmentException
WVRCTIException
WVRNodeException
Figure 19. Overview of WebSphere Voice Response Java API exceptions
creating a new Voice appliction in WebSphere Studio Site Developer
Chapter 3. Using the WebSphere Voice Response Java API classes 47
try {
// Execute some code
.
.
.
}
catch (WVRHungUpException ex) {
// Catches an individual exception - in this case the caller has hung up
}
catch (WVRCallException ex) {
// Catches all exceptions that inherit from WVRCallException that have
// not already been caught (in other words, not WVRHungUpException) -
// the application has encountered an error condition
}
catch (WVRException ex) {
// Catches all WVR exceptions not already caught - the application has
// encountered a further error
}
For more information and details of individual exceptions, see the JavaDoc
supplied with this documentation.
Multi-threading
We advise against writing multi-threaded apps using the WebSphere Voice
Response Java API. However, if your application does do multi-threading and
a thread tries to invoke a telephony method, such as Call.transfer(), on a Call
object at the same time as another thread, then a
java.lang.IllegalStateException will be thrown.
If your application is multi-threaded, try to avoid inter-thread interaction by
creating a different Call object for each thread.
Getting started: the WVRApplication class
The first step to creating a voice application using the WebSphere Voice
Response Java API is to create a class which extends the WVRApplication
class. Full instructions for using WebSphere Studio Site Developer to do this
are given in “Creating a new voice application in WebSphere Studio Site
Developer” on page 44. The WVRApplication class contains the following
methods:
getApplicationProperties()
Retrieves environment properties required to run the application. If
you are running your application unmanaged, this method will return
null. (See “Managed and unmanaged applications” on page 46 for
more information about managed and unmanaged applications). If
you are running your application managed, the application properties
are returned in the form of an ApplicationProperties object. See
creating a new Voice appliction in WebSphere Studio Site Developer
48 Developing Java Applications
“Setting the application environment” for more information about the
ApplicationProperties class.
setApplicationProperties()
Defines environment properties required to run the application. Your
application only needs to use this method if you are running it as an
unmanaged application. (See “Managed and unmanaged applications”
on page 46 for more information about managed and unmanaged
applications.) The only parameter is an ApplicationProperties object.
See “Setting the application environment” for more information about
the ApplicationProperties class, and the use of the
WVR.setApplicationProperties() method.
voiceMain()
This is the main entry point for the application. The main
implementation code for your application will be in this method.
run() Starts an instance of the application. This method is invoked
automatically by WebSphere Voice Response when a managed
application is started. If you are testing your application it is likely
that you will be running it unmanaged, in which case you will have
to write a main() method which creates an instance of your
application and invokes its run() method. For example:
public static void main(String[] args) {
// Create an instance of the MyVoiceApp class and invoke its run method
MyVoiceApp aVoiceApp = new MyVoiceApp();
aVoiceApp.run();
}
Also see “Tutorial 1: Caller calls an application” on page 128 for an
example of this code.
This method also provides error handling of uncaught exceptions and
returns a call when the caller hangs up (when the application receives
a WVRHungUpException).
voiceAppStop()
This method is invoked automatically when a node shuts down. Use
it to prepare your application for shut down, for example by stopping
pending methods such as Call.waitForCall().
Setting the application environment
The application environment is controlled by setting the application
properties. This is done automatically by the Java and VoiceXML environment
for managed applications . (See “Managed and unmanaged applications” on
page 46.) The Java and VoiceXML environment automatically retrieves the
settings for the application environment, such as locale, from the
configuration file. These application properties are returned in the form of an
ApplicationProperties object (see “The ApplicationProperties class” on page
51
getting started
Chapter 3. Using the WebSphere Voice Response Java API classes 49
51). The Java and VoiceXML environment then invokes the
WVRApplication.setAppplicationProperties() method to set the properties
within the application.
Your application code must access these application properties in order to
create a usable WVR object later on, to represent the base WebSphere Voice
Response system. To access the application properties, use the
WVRApplication.getApplicationProperties() method.
For example:
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
// Retrieve the application properties that have been loaded
// automatically from the configuration file
ApplicationProperties appProperties = this.getApplicationProperties();
// The application properties will be used later on to create the WVR
// object that makes or receives the telephone calls
.
.
.
}
.
.
.
}
For unmanaged applications, the application properties are not loaded
automatically. (See “Managed and unmanaged applications” on page 46.) In
this case, you must define them within your application. To do this, create an
ApplicationProperties object directly, with properties according to your
environment.
For example:
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
// Create the application properties object
ApplicationProperties appProperties = new ApplicationProperties();
// The application properties will be used later on to create the WVR
// object that makes or receives the telephone calls
.
.
.
}
getting started
50 Developing Java Applications
.
.
.
}
Note: If you create your own ApplicationProperties object, and then run the
application managed, your application properties will be overriden by
the AppName entry in the configuration file.
You can arrange your code so that your application can run managed or
unmanaged. This will help you move your application from a test
environment (where you will probably run it unmanaged) to a deployment
environment (where it will be managed). For example:
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
// Retrieve the application properties that have been loaded automatically
// from the configuration file
ApplicationProperties appProperties = this.getApplicationProperties();
// If the application properties are null (application is unmanaged), then
// set the properties manually
if (appProperties == null) {
// Create the application properties object
ApplicationProperties appProperties = new ApplicationProperties();
}
// The application properties will be used later on to create the WVR
// object that makes or receives the telephone calls.
.
.
.
}
.
.
.
}
The ApplicationProperties class
The ApplicationProperties class represents the properties of the environment
in which the application will be run, for example, locale. It is required to
create the WVR object which represents the base WebSphere Voice Response
system. The ApplicationProperties class contains the following properties,
each with get and set methods, as appropriate:
v applicationName: the application name by which the application will be
known in the configuration file (the name that is linked to the phone
number or line number for incoming calls). Default is an empty String.
getting started
Chapter 3. Using the WebSphere Voice Response Java API classes 51
v nodeName: the name of the voice response node, as specified in the
NodeName configuration entry in the configuration file. The default is
Node1.
v ipAddress: the name or address by which the voice response node is
known to the network. The default is 127.0.0.1 (the local system).
v rmiPortNumber: the port number that the voice response node uses for the
RMI registry. Make sure this matches the RMIPortNumber value in the
HostName configuration entry in the configuration file. The default is
26924.
v locale: the locale for the application, in the form of a java.util.Locale object.
Determines the default language and region of all voice segments in the
application. For more information about the application locale see “Setting
the application locale” on page 87.
v recoDefinitions: the speech recognition technology to use in this
application, if different from the RecoDefinitions set in the NodeName
configuration entry in the configuration file. For more information, see
“Specifying RecoDefinitions in ApplicationProperties” on page 92.
v ttsDefinitions: the Text-To-Speech technology to use in this application, if
different from the TTSDefinitions set in the NodeName configuration entry
in the configuration file. For more information, see “Specifying
TTSDefinitions in ApplicationProperties” on page 95.
v parameters: a Hashtable containing the application parameters. Application
parameters allow values to be passed to the application. The hashtable uses
the parameter name as the key. All parameter values must be strings.
You can create the ApplicationProperties object using the above properties as
parameters, in the order above. Alternatively, you can create the object with
default properties, and then set any properties you need to change according
to your particular environment. For example:
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
// Create the application properties object
ApplicationProperties appProperties = new ApplicationProperties();
// Change some of the properties to match this particular environment
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
.
.
.
}
.
.
.
}
getting started
52 Developing Java Applications
Note: If an application is to be run as a managed application , the
ApplicationProperties are set automatically according to the entries in
the configuration file default.cff, and made available by the
WVRApplication.getApplicationProperties() method.
See also “Setting the application environment” on page 49.
Starting the call
To make or receive telephone calls the voice application uses the WVR class,
which represents the base WebSphere Voice Response system. You can also
use this class to cancel a waitForCall() method or makeCall() method or to
delete, import or export single voice segments from within your application.
You generally only need one WVR object in your application. To create it, you
need to pass into the constructor method a reference to the application itself
as the first parameter, and an optional second parameter which consists of an
ApplicationProperties object. (See “Setting the application environment” on
page 49 and “The ApplicationProperties class” on page 51 for more
information about application properties.)
For example:
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
// Create the application properties object
ApplicationProperties appProperties = new ApplicationProperties();
// Use the application properties to create the WVR object. The this
// keyword registers the application as the owner of the WVR object
WVR wvr = new WVR(this, appProperties);
.
.
.
}
.
.
.
}
It is possible to create a WVR object without application properties, but you
must set the properties before you can use it. You can do this by invoking the
WVR.setApplicationProperties() method (not to be confused with the
WVRApplication.setApplicationProperties() method).
Once the WVR object has been created and the application properties set, you
can make or receive a call using the following methods, which should be
included in a try–catch block so that you can handle any error conditions:
getting started
Chapter 3. Using the WebSphere Voice Response Java API classes 53
makeCall(String label, String number)
Makes a call to the specified number and waits the number of seconds
specified by the ringTime property (see below) for an answer. If the
call is answered, makeCall returns a Call object. The call label is an
optional tag to enable the application to identify the call. You can use
labels to gather call statistics or to identify recordings of calls received.
Exceptions thrown:
v WVRException
v WVRRequestCancelled exception: if the call request has been
cancelled
v WVRMakeCallException: if the outbound call is either not
answered or answered by a machine. You can construct your
application so that depending on the apparatus detected, a voice or
fax message is played (for example a message left on the answering
machine).
waitForCall(String label)
Waits the number of seconds specified by the waitTime property (see
below) for an incoming call, and returns a Call object. The call label is
an optional tag to enable the application to identify the call. You can
use labels to gather call statistics or to identify recordings of calls
received.
Exceptions thrown:
v WVRException
v WVRRequestCancelledException: if the call request has been
cancelled
v WVRInvalidApplicationPropertiesException: if the application
properties are invalid
v WVRWaitForCallTimeoutException: if a call has not been received
in the specified time (see waitTime, below)
Both these methods return a Call object if successful. The Call object
represents a single telephone call. It is used by the voice application to play
prompts to the caller (or called party for an outbound call), get the caller’s
input, hand the call over to another application, transfer the call or return the
call when your application has finished with it. The Call class will be dealt
with in detail throughout the rest of this documentation.
The WVR class includes the following properties used when starting a call.
Each property has get and set methods as appropriate:
starting the call
54 Developing Java Applications
waitTime()
the maximum time in seconds that a voice application waits for a call
when using waitForCall() to receive an incoming telephone call. The
default is -1 (wait forever).
ringTime()
the maximum time in seconds that a voice application waits for an
answer when using makeCall() to make an outgoing telephone call.
The default is -1 (wait forever). Specify 0 to use the system default,
this is the Maximum Ring Time system parameter.
The WVR class has other properties and methods that will be covered later on
in the documentation, for example, dynamically deleting, importing and
exporting voice segments is covered in “Handling voice segments
dynamically” on page 107.
Examples: receiving and making calls
To receive an incoming call:
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
.
.
.
// Create the application properties object
ApplicationProperties appProperties = new ApplicationProperties();
appProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object. The this keyword registers the application
// as the owner of the WVR object
WVR wvr = new WVR(this, appProperties);
// Set the value of the WVR.waitTime property to the time in seconds that
// you want the application to wait for a call
wvr.setWaitTime(10);
try {
// Wait for a call
Call call = wvr.waitForCall("Call: " + callNumber);
// Handle the call
.
.
.
}
catch (WVRException e) {
// Error handling
.
.
starting the call
Chapter 3. Using the WebSphere Voice Response Java API classes 55
.
}
}
}
To make an outgoing call:
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
// Create the application properties object
ApplicationProperties appProperties = new ApplicationProperties();
appProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object. The this keyword registers the application
// as the owner of the WVR object
WVR wvr = new WVR(this, appProperties);
// Set the value of the WVR.ringTime property to the time in seconds that
// you want the application to wait for a call to be answered
wvr.setRingTime(20);
try {
// Make a call
Call call = wvr.makeCall();
// Handle the call
.
.
.
catch (WVRException e) {
// Error handling
}
}
}
Looping round to handle another call
To ensure that your application continues to wait for calls (unless an error
prevents the calls being dealt with correctly), simply structure your code so
that the WVR.waitForCall() or WVR.makeCall() method is within a loop. For
example, for waitForCall():
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
// Define a reference variable for a Call object, so we avoid
// creating multiple instances later on in the loop
Call call = null;
// Create the application properties object
ApplicationProperties appProperties = new ApplicationProperties();
starting the call
56 Developing Java Applications
appProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object
WVR wvr = new WVR(this, appProperties);
// Create a boolean to control the loop
private boolean keepTakingCalls = true;
// Create the loop
while (keepTakingCalls) {
try {
// Wait for a call
Call call = wvr.waitForCall("Call: " + callNumber);
// Handle the call
.
.
.
}
catch (WVRException e) {
// Error handling
.
.
.
}
}
}
}
You may want to add the loop when you have finished development and
testing the basic call handling functionality of your application, otherwise you
will explicitly have to stop and restart the application every time you make a
change to it.
Finishing with a call
To ensure that each telephone call is returned to the system when your voice
application has finished with it, and the line is freed, use the Call.returnCall()
method on the relevant Call object.
The following example makes use of the try–catch–finally structure to handle
the calls. Successful calls pass through the try block to the finally block. Calls
that receive a WVRHungUpException, indicating that the caller has hungup,
are passed straight to the finally block. Calls that encounter some other kind
of exception print out some debugging information and are also passed to the
finally block. In the finally block the call is returned by invoking the
Call.returnCall() method. This frees the resources used by the call.
starting the call
Chapter 3. Using the WebSphere Voice Response Java API classes 57
public class MyVoiceApp extends WVRApplication {
public void voiceMain() throws WVRException {
// Define a reference variable for a Call object, so we avoid
// creating multiple instances later on in the loop
Call call = null;
// Create the application properties object
ApplicationProperties appProperties = new ApplicationProperties();
appProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object
WVR wvr = new WVR(this, appProperties);
// Create a boolean to control the call-handling loop
private boolean keepTakingCalls = true;
// Create the loop
while (keepTakingCalls) {
try{
// Wait for a call
call = wvr.waitForCall();
// Handle successful calls
.
.
.
}
catch (WVRHungUpException e) {
// Caller has hung up - ignore exception, application will go to
// finally block
}
catch (WVRException e) {
// Print debugging information
e.printStackTrace();
}
finally {
// Return the call
call.returnCall();
}
}
}
}
finishing with a call
58 Developing Java Applications
Chapter 4. Creating voice applications
Chapter 1, “Introduction to WebSphere Voice Response Java development,” on
page 1 lists the WebSphere Voice Response Java API classes and describes
what you can do with them. Chapter 3, “Using the WebSphere Voice Response
Java API classes,” on page 41 introduces the basics of using the WebSphere
Voice Response Java API classes. Chapter 7, “WebSphere Voice Response Java
Tutorials,” on page 121 takes you step-by-step through some of these tasks.
This section goes into more detail about using the Java API to create
applications:
v “Saying something to the caller”
v “Playing output to the caller” on page 70
v “Getting input from the caller” on page 70
v “The Caller’s response” on page 82
v “Validating input” on page 84
v “Recording the caller’s voice input” on page 85
v “Changing the pacing tone” on page 87
v “Internationalizing your applications” on page 87
v “Using speech recognition for menus and data entry” on page 91
v “Using text-to-speech” on page 94
v “More about handling calls” on page 96
v “Getting called and calling numbers and application call data” on page 106
v “Handling voice segments dynamically” on page 107
v “Invoking a VoiceXML application from a Java application” on page 108
v “Invoking a state table” on page 109
Saying something to the caller
Once a call has been established between a voice application and a caller (or
called party), the remainder of the call consists of a dialog between the
application and the caller.
This section goes into more detail about the variety of information types that
your application can play to the caller.
v “Specifying what is to be spoken using the MediaType class” on page 60
v “The VoiceSegment class” on page 61
v “The DTMFSequence class” on page 62
v “The AudioNumber class” on page 63
© Copyright IBM Corp. 1998, 2008 59
v “The AudioCurrency class” on page 64
v “The AudioDate class” on page 65
v “The AudioTime class” on page 66
v “The AudioString class” on page 67
v “The TextToSpeech class” on page 68
v “Creating a media sequence” on page 68
v “Voice enabling your data structures: the Playable interface” on page 69
Specifying what is to be spoken using the MediaType class
You can use prerecorded speech or text-to-speech in a Java voice application
by using one of the following subclasses of MediaType. These media data
objects specify the sounds that the caller hears:
v VoiceSegment specifies recorded voice data and is used both for output,
and for input recorded from the user.
v DTMFSequence specifies a number of dual-tone multifrequency signals to
be played.
v AudioCurrency specifies a currency amount to be spoken.
v AudioDate specifies a date to be spoken.
v AudioNumber specifies a number to be spoken.
v AudioString specifies a character string to be spoken.
v AudioTime specifies a time to be spoken.
v TextToSpeech specifies text from which speech is to be synthesized.
v MediaSequence is a composite of other MediaType objects.
VoiceSegment and DTMFSequence are primitive audio types; they can be
played by the telephony server directly. All other media type objects are
decomposed by the system into a sequence of these two types, so that they
can be played to the user. For example, an AudioTime object representing a
time of 3:30 pm would be decomposed and played as three VoiceSegments:
’three’, ’thirty’, ’p m’.
The locale of each media type object can be individually altered using the
setLocale() method inherited from the MediaType superclass. This method is
useful for creating multilingual applications as it changes the language in
which an individual media type object is spoken. For example, if this method
was used to set the locale of the 3:30 pm AudioTime object to French, it
would be spoken as ’quinze’, ’heures’, ’trente’. If the locale is not specified
when the object is created, the default locale is used. The default locale is
taken from the application, or if you are running your application managed
(in a node), the node in which the application is running. The setLocale()
method takes a java.util.Locale object as a parameter. For example, to change
the locale of an AudioTime object called ’today’ to French:
saying something to the caller
60 Developing Java Applications
today.setLocale(new Locale("fr","FR"));
The MediaType class also has a style property that affects the way in which
the media object is spoken. For example, if the Full style is specified for an
AudioDate, the value 2000/1/26 is spoken as “Thursday, January twenty-six,
two thousand” while the same value is spoken as “Thursday” if DOW
(day-of-week) is specified. The style property only applies to AudioDate,
AudioTime, AudioNumber, AudioCurrency and AudioString — for other
media types the style property is ignored. For more information see the
individual section for the relevant MediaType.
Note: If you define your MediaType objects as ’static’, one copy is shared
between all instances of an application within a JVM, reducing overall
storage usage.
To play a voice segment or any other MediaType object in an application, use
one of the following Call methods:
play(MediaType message)
Used to play a simple uninterruptible message that requires no
response, using any kind of MediaType.
play(MediaType[] message)
Used to play a composite, uninterruptible message that requires no
response. The message can include one or more voice segments
together with other media objects such as AudioNumber,
AudioCurrency, AudioDate, AudioString, or AudioTime. The
MediaType objects in the array, which can be in any order, are played
in sequence.
You can use the Call.play(Playable message) method to play your
own mixed media objects.
playAndGetInput(PlayAttributes, InputAttributes, DTMFAttributes,
RecoAttributes)
Used to play an interruptible or non-interruptible free form message
that requires a response. The attribute objects are used to define what
to play, how to play it, and what to expect in return.
playAndGetInput(PlayAttributes, MenuAttributes, DTMFAttributes,
RecoAttributes)
Used to play within a menu structure an interruptible or
non-interruptible message that requires a response. The attribute
objects are used to define what to play, how to play it, and what to
expect in return.
The VoiceSegment class
The VoiceSegment class is used to represent a voice segment stored on the
WebSphere Voice Response server. This segment can contain pre-recorded
saying something to the caller
Chapter 4. Creating voice applications 61
speech to be used by the voice application, or it can be empty in preparation
for obtaining input from the caller. VoiceSegments can be deleted, imported
and exported dynamically, see “Handling voice segments dynamically” on
page 107.
To distinguish the voice segment from other segments on the server, each
VoiceSegment object has a name, a category and a locale.
The constructor methods for this class are:
VoiceSegment()
Constructs an voice segment object with default properties,
category=″″, locale=null and name=″″. You can set these properties
later using the methods setCategory(), setName() and setLocale()
(inherited from MediaType).
VoiceSegment(java.lang.String category, java.lang.String name)
Constructs a voice segment object with the specified category and
name, and default locale.
VoiceSegment(java.lang.String category, java.lang.String name,
java.util.Locale locale)
Constructs a voice segment object with the specified category, name
and locale.
Example:
public class InApp extends WVRApplication {
.
.
.
// Create the Welcome and Difficulties segment objects
public VoiceSegment vs_welcome = new VoiceSegment("App1Segments", "Welcome");
public VoiceSegment vs_difficulties = new VoiceSegment("App1Segments", "Difficulties");
.
.
.
}
To manage your voice segments, specify for each one a category defined in
your Voice Segment Database and a unique label identifying the voice
segment.
The DTMFSequence class
A DTMFSequence object represents a sequence of Dual Tone Multi Frequency
signals.
The constructor methods for this class are:
DTMFSequence()
Constructs an empty DTMF sequence object. You can set the sequence
later using the setKeySequence() method.
saying something to the caller
62 Developing Java Applications
DTMFSequence(java.lang.String sequence)
Constructs a DTMF sequence object with the specified sequence.
For example:
public class InApp extends WVRApplication {
// Create a DTMF sequence
public DTMFSequence telNo = new DTMFSequence("815443");
.
.
.
}
The AudioNumber class
An AudioNumber object represents a numeric value. To set the value
property, you must use a double.
The number can be read out in several different ways, according to the style
property inherited from the MediaType superclass. For the AudioNumber
class, the style property can have the following values (note that the locale
property of the MediaType class may also affect how the number is spoken):
v Integer: This is the default. Plays the number as an integer and in words.
For example, 305,004,042 is played in English as ″three hundred and five
million, four thousand and forty-two″. In most languages this will support
numbers up to 999,999,999. Any fractional part is ignored. Any number
greater than or equal to 1012 is played in the Digits style.
v Digits: Plays the number as a string of digits. For example, 305,004,042 is
played in English as ″three zero five zero zero four zero four two″. If the
number is negative, it is preceded by the word ″minus″.
v Counter: In most languages, plays the same as Integer, but some languages
treats numbers differently if they represent a count rather than some other
form of number.
v Phone: Only available for en_US and en_GB locales. Now deprecated: use
Digits in new applications.
v Real: Only available for en_US and en_GB locales. The value is spoken as a
real number, fractional up to two decimal places. Any number greater than
or equal to 1012 is played in the Phone style.
Note that 1 billion is used to mean 1 thousand million in both the en_US and
en_GB locales.
The constructor methods for this class are:
AudioNumber()
Constructs an audio number object with a value of zero and a style of
Integer. You can set these properties later using the methods
setValue() and setStyle().
saying something to the caller
Chapter 4. Creating voice applications 63
AudioNumber(double value)
Constructs an audio number object with the specified value and a
style of Integer.
AudioNumber(double value, java.lang.String style)
Constructs an audio number object with the specified value and style.
For example:
public class InApp extends WVRApplication {
// Create an audio number
public AudioNumber code = new AudioNumber(118257, "Digits");
.
.
.
}
The AudioCurrency class
Use the AudioCurrency class to represent a monetary value. The
AudioCurrency class is a subclass of AudioNumber, and so inherits the
setValue() and getValue() methods. In addition to the value property, which
represents the amount, an AudioCurrency object has a country property
which is used as an indirect representation of the monetary unit of the
currency. For example, if ’US’ is specified, the monetary units will be dollars
and cents. If not specified, the country property is obtained from the current
locale of the application at runtime.
The style property inherited from the superclass MediaType has only one
value for AudioCurrency. This default style takes a real number and speaks it
as follows: the first part of the number is spoken using the Integer style of the
AudioNumber class, followed by the major currency voice segment for the
locale. The second part of the real number, up to 2 decimal places, is then
spoken also using the Integer style, followed by the minor currency voice
segment for the locale. For example, 2.22 in the en_US locale is spoken as
″two dollars twenty two cents″.
In the following locales, currency amounts are spoken in euros and cents by
default: French, Castilian Spanish, Catalan, German and Italian. To revert to
the old national currency, specify PREEURO in the variant part of the locale
property of the AudioCurrency object. For example, to use the French franc in
place of the euro, specify fr_FR_PREEURO as the locale. Alternatively, you
can specify dtj.preeuro.support=true in the dtj.ini file to achieve the same
result.
Note that 1 billion is used to mean 1 thousand million in both the en_US and
en_GB locales.
The constructor methods for this class are:
saying something to the caller
64 Developing Java Applications
AudioCurrency()
Constructs an audio currency object with a value of zero and the
single default style. The country property is taken from the current
locale of the application at runtime. You can set these properties later
using the methods setValue() and setCountry().
AudioCurrency(double value)
Constructs an audio currency object with specified value and the
single default style. The monetary unit of this currency is taken from
the current locale of the application at runtime.
AudioCurrency(double value, Country currency)
Constructs an audio currency object with specified value and currency.
For example:
public class InApp extends WVRApplication {
// Create a Country object to represent the monetary units
Country unitedStates = new Country("US");
// Create an audio currency
public AudioCurrency orderCost = new AudioCurrency(86.32, unitedStates);
.
.
.
}
The AudioDate class
An AudioDate object represents a date to be ″spoken″ to the user. The
AudioDate class has a calendar property, in the form of a java.util.Calendar
object, which represents the date, and a timeZone property which represents
the time zone of the AudioDate object.
The style property inherited from the superclass MediaType has several
different values for an AudioDate object. Together with the locale property,
also inherited from MediaType, they affect the way the date is ″spoken″:
v MDY: Month, day-of-month and year, played in an order appropriate for
the locale. This is the default.
v Full: The day-of-week, month, day-of-month and year, played in an order
appropriate for the locale.
v DOW: The day of the week.
v DMD: Day-of-week, month and day-of-month, played in an order
appropriate for the locale.
v MD: Month and day-of-month, played in an order appropriate for the
locale.
v MY: Month and year, played in an order appropriate for the locale.
The constructor methods for this class are:
saying something to the caller
Chapter 4. Creating voice applications 65
AudioDate()
Constructs a ″current-time″ audio date object with a style of MDY.
The time zone is taken from the default time zone of the Java virtual
machine (JVM). You can set the properties of the AudioDate object
later using the methods setValue() and setTimeZone().
AudioDate(java.util.Calendar calendar)
Constructs an audio date object with a specified value and a style of
MDY. The time zone of the AudioDate object is set to the time zone
of the Calendar object.
AudioDate(java.util.Calendar calendar, java.lang.String style)
Constructs an audio date object with a specified value and style.
AudioDate(java.util.TimeZone tz)
Constructs a ″current-time″ audio date object with adjustment for a
specified time zone. For example, if the time at which the AudioDate
is spoken is 2300 hours universal time (UT) on February 17th, and the
time zone specified is UT+2, then the date value spoken will be
February 18th.
For example:
public class InApp extends WVRApplication {
// Create an audio date
public AudioDate today = new AudioDate(Calendar.getInstance(), "MD");
.
.
.
}
The AudioTime class
An AudioTime object represents a time to be ″spoken″ to the user. The
AudioTime class has a value property, in the form of a java.util.Calendar
object, which represents the time, and a timeZone property which represents
the time zone of the AudioTime object.
The style property, inherited from the superclass MediaType, has only one
value for an AudioTime object. This default value speaks the time in hours
and minutes, using the 12–hour or 24–hour clock depending on the locale
property (also inherited from MediaType).
The constructor methods for this class are:
AudioTime()
Constructs a ″current-time″ AudioTime object. The time zone is taken
from the default time zone of the Java virtual machine (JVM). You can
set the properties of the AudioTime class later using the methods
setValue() and setTimeZone().
saying something to the caller
66 Developing Java Applications
AudioTime(java.util.Calendar calendar)
Constructs an audio time using the specified Calendar object. The
time zone of the AudioTime object is set to the time zone of the
Calendar object.
AudioTime(java.util.TimeZone tz)
Constructs a ″current-time″ AudioTime object with adjustment for a
specified time zone. For example, if the time at which the AudioTime
is spoken is 2300 hours universal time (UT), and the time zone
specified is UT+2, then the time value spoken will be 0100 hours.
For example:
public class InApp extends WVRApplication {
// Create an audio time
public AudioTime now = new AudioTime(Calendar.getInstance());
.
.
.
}
The AudioString class
An AudioString object represents a string of characters to be spoken
individually. The style property inherited from the superclass MediaType has
only one value. This default style is to speak the characters one by one.
Blanks can be included in the string but are ignored. Uppercase and lowercase
characters are spoken in exactly the same way. You can specify any characters,
but there must be a voice segment on the WebSphere Voice Response server,
in the System category, for each one. The name of the voice segment must be
the character (for example, the name of the ″ampersand″ segment must be
″&″).
The constructor methods for this class are:
AudioString()
Constructs a zero-length audio string object with the single default
style. You can set the string later using the setString() method.
AudioString(java.lang.String string)
Constructs an audio string object with the specified string and the
single default style.
For example:
public class InApp extends WVRApplication {
// Create an audio string
public AudioString letters = new AudioString("ABCD");
.
.
.
}
saying something to the caller
Chapter 4. Creating voice applications 67
The TextToSpeech class
A TextToSpeech object represents a string which is to be spoken using
synthesized speech in a specific locale. You must have Text-To-Speech
technology configured on the telephony server in order to use this class. See
“Using text-to-speech” on page 94 for more information.
The string to be synthesized is represented by the ttsString property in the
form of a java.lang.String object.
The constructor methods for this class are:
TextToSpeech()
Constructs a text to speech object with an empty string and default
locale (the application locale or the node locale depending on how
you are running the application). You can set these properties later
using the methods setTtsString() and setLocale().
TextToSpeech(java.lang.String ttsString)
Constructs a text to speech object with specified text and default
locale.
TextToSpeech(java.lang.String ttsString, java.util.Locale locale)
Constructs a text to speech object with specified text and locale.
For example, a weather forecast application might ask a caller to input their
geographical location using speech recognition. Rather than repeat the
recorded input string to the caller to confirm their location, the application
could use text-to-speech to play the output string (townString) from the
recognizer. The following example shows how to declare the TextToSpeech
object:
public class InApp extends WVRApplication {
.
.
.
// Create the TextToSpeech object
public TextToSpeech ttsTown = new TextToSpeech(townString);
.
.
.
}
Creating a media sequence
You can use the MediaSequence subclass of MediaType to create a sequence
of other MediaType objects. This class has only one constructor method,
which takes no parameters and creates an empty sequence. You then add
MediaType objects to the sequence using the setNewMediaItem() method.
Each new MediaType object is added to the end of the sequence.
saying something to the caller
68 Developing Java Applications
Note: You must not add null objects to a MediaSequence, as this will cause a
NullPointerException.
Obviously creating a media sequence using the MediaSequence class could be
quite a lengthy procedure. A much quicker way to create a media sequence is
to use an array of MediaTypes. This array can be played by any method
which accepts MediaTypes as parameters.
For example, the following array of MediaTypes says “Today’s date is... and
the temperature is 32 degrees Celsius.”
public class InApp extends WVRApplication {
.
.
.
// Create a string to represent the voice segment category.
public String category = new String("TempTodaySegments");
// Create the Today, Temperature and Degrees voice segment objects
public VoiceSegment vs_today = new VoiceSegment(category, "Today");
public VoiceSegment vs_temperature = new VoiceSegment(category, "Temperature");
public VoiceSegment vs_degrees_c = new VoiceSegment(category, "Degrees");
// Create media objects to play the date and temperature
public AudioDate date = new AudioDate();
public AudioNumber temperature = new AudioNumber(32);
// Create a media sequence
public MediaType[] tempToday = { VS_TODAY, date, VS_TEMPERATURE, temperature, VS_DEGREES_C};
.
.
.
//Play the media sequence
call.play(tempToday);
.
.
.
}
The voice segments need to be recorded but the temperature is ‘spoken’ uses
voice segments supplied with WebSphere Voice Response. The date is created
dynamically at runtime based on the default timezone and is ‘spoken’ using
supplied voice segments.
Voice enabling your data structures: the Playable interface
Your application could have access to data structures that you want to present
to the caller over the telephone. For example, the application may lookup a
caller’s order information in a database and play the information back to the
caller. The Playable interface allows you to create a class which takes this
information and turns it into something which can be played by any method
which can play a MediaType object. The Playable interface defines one
method, toMedia(), which takes no parameters and returns an array of
MediaTypes. When the Playable object is passed into a method that plays
MediaTypes (for example, Call.play()), its toMedia() method is invoked to
return the array of MediaType objects to play to the caller.
saying something to the caller
Chapter 4. Creating voice applications 69
For an example of a class that implements the Playable interface, see “Tutorial
9: Order information (menu item 3 continued)” on page 190.
Playing output to the caller
The play() method of the Call class is used to play output to the caller
without expecting anything back. The voice prompt cannot be interrupted by
the caller. If the caller presses a key, the key is left in the buffer for the next
action method (a method which uses the underlying telephony, for example
Call.play()), which may or may not clear the buffer.
The media to be played can be any of the defined MediaType objects, an
array of MediaType objects, or a class which implements the Playable
interface.
For example:
public class InApp extends WVRApplication {
.
.
.
// Create a voice segment object for some information that you don’t want your callers to
// be able to interrupt.
public VoiceSegment importantInfo = new VoiceSegment("App1Segments", "ImportantInfo");
//Play the voice segment
call.play(importantInfo);
.
.
.
}
Getting input from the caller
Your application obtains input from the caller using the playAndGetInput()
method of the Call class. The caller can give either key input or voice
recognition input (see “Using speech recognition for menus and data entry”
on page 91 for more information about using speech recognition). The
Call.playAndGetInput() method is the equivalent of a data entry field in a
graphical user interface.
This section explains the Call.playAndGetInput() and its parameters in more
detail:
v “The Call.playAndGetInput() method” on page 71
v “The PlayAttributes class” on page 72
v “The InputAttributes class” on page 73
v “The MenuAttributes class” on page 76
v “The DTMFAttributes class” on page 80
v “The RecoAttributes class” on page 81
saying something to the caller
70 Developing Java Applications
The Call.playAndGetInput() method
The Call.playAndGetInput() method takes four ’attributes’ objects as
parameters. Each attributes object contains several attributes that specify such
things as prompts for the caller, timeouts and error messages.
The attributes objects that make up the four parameters of the
playAndGetInput() method are :
1. PlayAttributes - used to specify whether the caller can interrupt the
messages played as part of a voice or DTMF input.
2. Either
v InputAttributes - used to specify the voice segment or sequence of
voice segments to be played to the caller, the time to wait for a
response, and the validation that will be performed on the caller’s input.
Or
v MenuAttributes - an extension of class InputAttributes. Has all the
attributes of InputAttributes, plus additional attributes used to specify a
complete menu with voice segments, identification labels, DTMF
selector key responses and recognized selector word responses.3. DTMFAttributes - used to specify the maximum number of DTMF key
presses allowed in a caller response and also any keys to be used for
ending input. Replace with null if DTMF input is not required.
4. RecoAttributes - used to specify the settings for the speech recognition
used for this input. Replace with null if voice input is not required.
As shown above, the second parameter of the Call.playAndGetInput()
method varies. The attributes object you use as the second parameter depends
on whether you are obtaining data from the user, or are asking the user to
make a menu selection:
v Obtaining data from the caller
To obtain information such as a telephone number from the caller, use
Call.playAndGetInput(PlayAttributes playAttributes, InputAttributes
inputAttributes, DTMFAttributes dtmfAttributes, RecoAttributes
recoAttributes)
v Getting the caller to make a menu selection
To get a caller to choose from a list of menu choices, use
Call.playAndGetInput (PlayAttributes playAttributes, MenuAttributes
menuAttributes, DTMFAttributes dtmfAttributes, RecoAttributes
recoAttributes)
Storing the various attributes in four separate attributes objects means that
you can re-use them elsewhere in the application. For example, you may want
all your prompts to be interruptible by DTMF key, but you might want to
getting input from the caller
Chapter 4. Creating voice applications 71
change the number of DTMF key presses the caller is allowed to use. In this
case you could reuse your PlayAttributes object throughout the application,
and either create different DTMFAttributes objects according to the
requirements of each prompt, or create one DTMFAttributes object and alter
it for each prompt.
The Call.playAndGetInput() method returns an InputResult object that
represents the caller’s input. See “The Caller’s response” on page 82 for more
information about the InputResult class.
Example:
public class myVoiceApp extends WVRApplication {
.
.
.
// Create the attributes objects - use empty constructors so that attributes
// have default values
private PlayAttributes myPlayAtts = new PlayAttributes();
private InputAttributes myInputAtts = new InputAttributes();
private DTMFAttributes myDTMFAtts = new DTMFAttributes();
private RecoAttributes myRecoAtts = null;
// Enter the main application method
public void VoiceMain() throws WVRException {
// Create the application properties
ApplicationProperties appProperties = new ApplicationProperties();
appProperties.setApplicationName("myApplication");
applicationProperties.setLocale(Locale.US);
// Create the WVR object, using the application properties
WVR wvr = new wvr(this, appProperties);
// Create the Call object, using the WVR object
Call call = wvr.waitForCall();
// Get input from the caller, using the attribute objects created earlier
InputResult result = call.playAndGetInput(myPlayAtts, myInputAtts, myDTMFAtts, myRecoAtts);
.
.
.
}//VoiceMain
}
In the above example, null is used in place of a RecoAttributes object because
speech recognition is not used with this prompt.
The PlayAttributes class
The PlayAttributes class determines whether a caller can interrupt a prompt
played using the Call.playAndGetInput() method. The default is to allow a
message to be interrupted by DTMF key but not by voice. The class has two
properties, DTMFInterruptible and voiceInterruptible. Each property has two
values:
DTMFInterruptible
v PlayAttributes.NO_DTMF: the prompt cannot be interrupted by DTMF key
presses.
getting input from the caller
72 Developing Java Applications
v PlayAttributes.FIRST_DTMF: the first DTMF key pressed by the caller will
interrupt the prompt.
voiceInterruptible
v PlayAttributes.NO_VOICE: the prompt cannot be interrupted by voice.
v PlayAttributes.VOICE_ENERGY: the prompt will be interrupted as soon as
the caller starts to speak. If the caller interrupts by speaking, the utterance
is assumed to be voice input and is sent to the voice recognizer.
The constructor methods for this class are:
PlayAttributes()
Constructs a PlayAttributes object with default properties
DTMFInterruptible=PlayAttributes.FIRST_DTMF and
voiceInterruptible=PlayAttributes.NO_VOICE.
PlayAttributes(int dtmfInterruptible, int voiceInterruptible)
Constructs a PlayAttributes object with the specified properties.
For example:
public class myVoiceApp extends WVRApplication {
.
.
.
// Create the attributes object - use empty constructors so that attributes have
// default values
public PlayAttributes myPlayAtts = new PlayAttributes();
// Then change the attributes you need
myPlayAtts.setDTMFInterruptible(PlayAttributes.NO_DTMF);
myPlayAtts.setVoiceInterruptible(PlayAttributes.VOICE_ENERGY);
.
.
.
}
The InputAttributes class
The InputAttributes class contains properties which determine how the caller
is guided through giving input using the Call.playAndGetInput() method,
and how their response is validated. The properties defined in the
InputAttributes class are listed below; each property has set and get methods.
Message properties
v message: the prompt that is played to the caller before the application waits
for their response.
v invalidInputMessage: a message that is played when the caller has
provided input that is considered invalid by the application. For example, if
the application is expecting a telephone number that begins with a 2, and
getting input from the caller
Chapter 4. Creating voice applications 73
the caller has entered a number beginning with a 6, the application might
say ″That is not a valid phone number″.
v oneMoreRepeatMessage: a message that is played before the caller is
prompted for input for the last time. Use the numberOfRepeats property to
set the number of times the prompt will be played. For example, if the user
has not provided a valid telephone number so far, the application might
want to warn the user that they only have one more chance by saying ″You
have one more chance to enter a valid phone number″.
v noMoreRepeatsMessage: a message that is played after the last time the
prompt has been repeated. For example, if the caller has not provided any
valid input and the application will no longer repeat the prompt, the
application might say “Sorry, we cannot continue, as you have not entered
any valid input”.
v timeoutMessage: a message that is played when the caller has failed to
provide input before the timeout value is reached. For example, if the user
does not respond in time the application might inform them of this by
saying ″You did not provide any input. Please try again″.
Other properties
v numberOfRepeats: the number of times the application will play the
prompt if no valid input is received. (The total number of chances the caller
has is numberOfRepeats + 1.)
v validator: sets the validator object to be used for the input. The validator
object is an instance of a class that implements the InputValidator interface.
Each time the caller gives input the validate() method of the validator
object will be called to check the input. For example, if the application
needs to accept only telephone numbers beginning with a 2, you create a
class, implementing the InputValidator interface, to check this, and then set
an instance of your class as the validator object. For more information see
“Validating input” on page 84
v clearDTMFBuffer: specifies whether to clear the dual tone multifrequency
(DTMF) buffer before input takes place. Set this property to true to ignore
keys that have been pressed previously by the caller. This property also
applies when using speech recognition — setting the property to true will
clear the voice interrupted flag.
v timeout: the time in seconds to wait for the caller’s input. Specify -1 to wait
for ever. If you specify 0, the caller will not have a chance to provide input.
Note that the timeout is an ’interdigit timeout’: when the caller is pressing
keys, the timeout period is reset after each key is pressed.
For the message properties, the message object to be played can be a
MediaType object, an array of MediaType objects, or an instance of a class
that implements the Playable interface.
getting input from the caller
74 Developing Java Applications
The constructor methods for this class are:
InputAttributes()
Constructs an InputAttributes object with null for all messages and
the validator, and default properties of timeout=-1,
clearDTMFBuffer=false and numberOfRepeats=1.
InputAttributes(InputAttributes base)
Constructs an InputAttributes object with properties inherited from
the specified InputAttributes.
InputAttributes(MediaType[] message, int timeout)
Constructs an InputAttributes object with specified main message as
an array of MediaType objects, and specified timeout.
InputAttributes(MediaType message, int timeout)
Constructs an InputAttributes object with specified main message as
a single MediaType, and specified timeout.
InputAttributes(Playable message, int timeout)
Constructs an InputAttributes object with specified main message as
a Playable object, and specified timeout.
For example:
public class myVoiceApp extends WVRApplication {
.
.
.
// Create the voice segment objects that will be used for the prompt
public VoiceSegment vs_card_number = new VoiceSegment("OrderSegments", "CardNumber");
public VoiceSegment vs_not_enough_digits = new VoiceSegment("OrderSegments", "NotEnough");
public VoiceSegment vs_invalid = new VoiceSegment("OrderSegments", "Invalid");
// Create the attributes object - use empty constructors so that attributes have
// default values
public InputAttributes myInputAtts = new InputAttributes();
// Then change the attributes you need.
myInputAtts.setMessage(vs_card_number);
myInputAtts.setTimeoutMessage(vs_not_enough_digits);
myInputAtts.setInvalidInputMessage(vs_invalid);
myInputAtts.setTimeout(5);
myInputAtts.setNumberOfRepeats(3);
.
.
.
// Within the voiceMain() method, use the attributes object to get input from the caller
InputResult input = call.playAndGetInput(myPlayAtts, myInputAtts, myDTMFAtts, myRecoAtts);
}
Example interaction
You set the numberOfRepeats to 3. This gives the caller a total of four
chances to enter data.
getting input from the caller
Chapter 4. Creating voice applications 75
Iteration Property used by object Words spoken by application
Caller
response
1 message Enter your credit card number.
The number must be 16 digits.
Does not
press any
keys, or
presses fewer
than 16.
2 timeoutMessage You did not enter enough data. Presses #12#
*123 ###8
8888
(an invalid
number).
message Enter your credit card number.
The number must be 16 digits.
3 invalidInputMessage That is not a valid credit card
number.
Does not
press any
keys, or
presses fewer
than 16.
message Enter your credit card number.
The number must be 16 digits.
4 timeoutMessage You did not enter 16 digits. Presses #12#
*123 ###8
8888
(an invalid
number).
oneMoreRepeatMessage You have one more chance...
message Enter your credit card number.
The number must be 16 digits.
5 invalidInputMessage That is not a valid credit card
number.
noMoreRepeatsMessage Sorry, we cannot continue with
the transaction.
The MenuAttributes class
Using the MenuAttributes class in conjunction with the
Call.playAndGetInput() method enables you to allow the caller to make a
selection from a number of items in your voice application. It is the equivalent
of a menu or set of radio buttons in a graphical user interface. The
MenuAttributes class is an extension of InputAttributes. MenuAttributes
inherits all the properties of the InputAttributes class, and has additional
attributes that define the menu choices. You can use the same MenuAttributes
object in more than one invocation of Call.playAndGetInput(). This enables
you to create default menus for common menu operations and reuse these
within your application.
The caller is presented with a set of choices, and must select one of the items,
either by pressing the key or keys associated with the choice or by saying the
word or words associated with it. You can enable and disable menu choices as
required. A menu choice consists of:
getting input from the caller
76 Developing Java Applications
v A message that will be played to the caller.
v An identifying label used by the application.
v The input keys or words the caller will use to select their choice.
Validation of the caller’s input is based upon the specified selector keys and
words. If the grammar used for speech recognition contains annotations,
validation is performed on the annotation rather than the actual word spoken
by the caller. When the caller makes a valid choice the label for that choice is
set as the value property of the InputResult object returned by the
Call.playAndGetInput() method.
The properties contained in this class, additional to those inherited from
InputAttributes, are listed below.
Properties for the menu choices
v message: an array of the messages for the menu items. These messages can
be in the form of single MediaType objects, arrays of MediaType objects, or
instances of classes that implement the Playable interface.
v labels: an array of labels for the menu items, in the form of Strings.
v keys: an array of selector keys for the menu items, in the form of Strings.
v words: an array of selector words for the menu items, also in the form of
Strings.
These properties have get methods only and are set using a constructor
method (see below). The properties cannot be set individually because the
group of menu items is made up from all the property arrays combined — the
second menu item consists of the second message array item, the second
labels array item, the second keys array item and the second words array
item. The arrays must therefore be the same length. To change the order of the
menu items, simply rearrange the arrays. To use only one response mode (for
example DTMF keys but not speech recognition), the array for the unused
response mode can be replaced with null.
Other properties
v headerMessage: the message that is played before the the menu items are
listed.You could use this message to say, for example, ″What kind of
entertainment are you interested in...″.
v footerMessage: the message that is played after the menu items have been
listed; if the caller reaches the end of the menu without making a selection.
You could use this message to say, for example, ″Please press the key
corresponding to your choice″.
These properties have get and set methods. They are not included in any
constructor method, so must be set after the MenuAttributes object has been
created.
asking the caller to make a menu selection
Chapter 4. Creating voice applications 77
The constructor methods for this class are:
MenuAttributes()
Constructs an empty menu.
MenuAttributes(MediaType[] messages, java.lang.String[] labels,
java.lang.String[] selectorKeys, java.lang.String[] selectorWords)
Constructs a MenuAttributes object with the specified messages,
labels, selector keys and selector words. Use null for selectorWords if
your application does not use speech recognition. Use null for
selectorKeys if your application uses speech recognition only.
Note: The validator property inherited from the InputAttributes class cannot
be used with MenuAttributes. This is because the MenuAttributes
class generates its own InputValidator based on the contents of the
menu. This validator cannot be changed, therefore calling this method
will throw an exception.
For example:
public class myVoiceApp extends WVRApplication {
.
.
.
// Create the voice segment objects that will be used for the prompt
VoiceSegment vs_pizza_sizes = new VoiceSegment("PizzaSegments", "ChooseAPizzaSize");
VoiceSegment vs_not_enough_digits = new VoiceSegment("PizzaSegments", "NotEnough");
VoiceSegment vs_invalid = new VoiceSegment("PizzaSegments", "Invalid");
.
.
.
// Create the message array
MediaType[] Menu_Prompts = {
new VoiceSegment("myApp", "Small"),
new VoiceSegment("myApp", "Medium"),
new VoiceSegment("myApp", "Large")
};
// Define the menu item labels. These are defined outside of an array
// as the application will need to refer to them later on to see what choice the caller made.
String Item1_Small = "Small";
String Item2_Medium = "Medium";
String Item3_Large = "Large";
// Create the labels array
String[] MenuLabels={ Item1_Small, Item2_Medium, Item3_Large };
// Create the selector keys array
String[] Menu_Keys = { "1", "2", "3" };
// Create the selector words array
String[] Menu_Words = { "Small", "Medium", "Large" };
// Use the arrays to create the MenuAttributes object
MenuAttributes myMenuAtts = new MenuAttributes(Menu_Prompts, Menu_Labels, Menu_Keys, Menu_Words);
// Set any other attributes required
myMenuAtts.setHeaderMessage(vs_pizza_sizes);
myMenuAtts.setFooterMessage(vs_not_enough_digits);
myMenuAtts.setInvalidInputMessage(vs_invalid);
myMenuAtts.setTimeout(10);
myMenuAtts.setNumberOfRepeats(2);
.
.
.
asking the caller to make a menu selection
78 Developing Java Applications
// Get the caller’s input
InputResult pizza_size = call.playAndGetInput(myPlayAtts, myMenuAtts, myDTMFAtts, myRecoAtts);
String size = input.getValue();
}
Disabling a menu item
To temporarily disable a menu item, without removing it from the application,
use the MenuAttributes.setChoiceEnabled() method to change the value of
the enabled property for a specific menu choice from true to false. For
example, to disable the menu item with the label Operator for a menu
constructed using an instance of MenuAttributes named menuAtts:
menuAtts.setChoiceEnabled(Operator, 0);
Example interaction
You set the numberOfRepeats to 3. This gives the caller a total of 4 chances to
select a menu item. The PlayAttributes.DTMFInterruptible property is set to
PlayAttributes.FIRST_DTMF.
Iteration Property used by object Words spoken by application
Caller
response
1 headerMessage What do you want to do? Does not
press a key. MenuItem message Hear the class schedules... press
1
MenuItem message Register for a class... press 2
MenuItem message Talk to an administrator... press
3
footerMessage Please press the key
corresponding to your choice.
timeoutMessage You did not select an option...
2 headerMessage What do you want to do? Presses the 4
key before
the end.
MenuItem message Hear the class schedules... press
1
MenuItem message Register for a cla...
invalidInputMessage You did not press a valid key...
asking the caller to make a menu selection
Chapter 4. Creating voice applications 79
Iteration Property used by object Words spoken by application
Caller
response
3 headerMessage What do you want to do? Does not
press a key. MenuItem message Hear the class schedules... press
1
MenuItem message Register for a class... press 2
MenuItem message Talk to an administrator... press
3
footerMessage Please press the key
corresponding to your choice.
timeoutMessage You did not select an option...
4 oneMoreRepeatMessage You have one more chance... Presses the 4
key before
the end.
headerMessage What do you ...
invalidInputMessage You did not press a valid key...
5 noMoreRepeatsMessage Sorry, we cannot continue, as
you have not selected a valid
option.
The DTMFAttributes class
The DTMFAttributes class determines the number of dual tone
multi-frequency (DTMF) keys the application expects in response to a prompt
played using the Call.playAndGetInput() method, and also the keys the caller
can use to indicate that they have finished their input. The class contains two
properties, each with get and set methods:
v maximumKeys: the maximum number of DTMF keys that the caller can
enter. Specify -1 to indicate no limit.
v delimiterKeys: a list of DTMF keys that the caller can use to indicate that
they have finished entering data.
Note: If a delimiter key is specified, the maximum number of keys is ignored.
If the input should be fixed length (for example a six-digit product code), set
the maximumKeys property to the number of keys you expect. The caller
then simply has to key that number of digits.
If the input length can vary, set the maximumKeys property to -1, meaning
“any number of keys”. Specify one or more “enter” keys by setting the
delimiterKeys property to a string representing the keys that the caller can
press to indicate that they have finished. As soon as the caller presses one of
these keys, they are assumed to have finished. The “enter” key is not
considered to be part of the input, but its value is placed in the
asking the caller to make a menu selection
80 Developing Java Applications
terminationKey property of the InputResult class. To find out which key was
pressed, use the InputResult.getTerminationKey() method.
The constructor methods for this class are:
DTMFAttributes()
Constructs a DTMFAttributes object with default properties
maximumKeys=-1, delimiterKeys=″#″.
DTMFAttributes(int maximumKeys, java.lang.String delimiterKeys)
Constructs a DTMFAttributes object with the specified maximum
keys value and delimiter keys string.
For example:
public class myVoiceApp extends WVRApplication {
.
.
.
// Create the attributes object - use empty constructors so that attributes have
// default values
public DTMFAttributes myDTMFAtts = new DTMFAttributes();
// Then change the attributes you need
myDTMFAtts.setMaximumKeys(6);
myDTMFAtts.setDelimiterKeys("#");
.
.
.
}
The RecoAttributes class
The RecoAttributes class determines the speech recognition settings for a
prompt played using the Call.playAndGetInput() method. You must have
speech recognition technology configured on the telephony server in order to
use this class. If the application does not use speech recognition, use null in
place of RecoAttributes.
This class has three properties, each with set and get methods:
v context: a string to be passed to the speech recognition plug-in to indicate
what vocabulary or grammar should be used for the recognition attempt.
The precise meaning depends on the plug-in. The string is typically a short
identifier such as ″numbers″ or ″months″, which is used by the plug-in to
select a suitable grammar.
v nBest: the maximum number of possible recognition results to return from
the recognizer. For guidance, see “Asking the recognizer for alternative
results” on page 93
v beep: specifies whether or not a pacing tone is played after the prompt to
indicate to the caller when to start speaking. Speech recognition starts after
the tone.
asking the caller to make a menu selection
Chapter 4. Creating voice applications 81
Note: Beep and interruptible are mutually exclusive. Speech recognition
will fail if both options are set. If a starting beep is used, the
PlayAttributes.VOICE_INTERRUPTIBLE property must be set to
PlayAttributes.NO_VOICE.
The constructor methods for this class are:
RecoAttributes()
Constructs a RecoAttributes object with default properties context=″″,
nBest=1, beep=true.
RecoAttributes(java.lang.String context, int nBest, boolean beep)
Constructs a RecoAttributes object with the specified context, nBest
value and beep.
See “Using speech recognition for menus and data entry” on page 91 for more
information about using speech recognition in your application.
For example:
public class myVoiceApp extends WVRApplication {
.
.
.
// Create the attributes object - use empty constructors so that attributes have
// default values
public RecoAttributes myRecoAtts = new RecoAttributes();
// Then change the attributes you need
myRecoAtts.setContext("colors");
myRecoAtts.setNBest(3);
.
.
.
}
The Caller’s response
The Call.playAndGetInput() method returns an InputResult object that
represents the caller’s input. To process the input, use the
InputResult.getValue() method to extract the input information as a String.
For example:
public class MyVoiceApp extends WVRApplication {
.
.
.
// Get the caller’s input, using some previously defined attributes objects (not shown)
InputResult result = call.playAndGetInput(myPlayAtts, myInputAtts, myDTMFAtts, myRecoAtts);
// Extract the input information
String cardNumber = result.getValue();
.
.
.
}
}
asking the caller to make a menu selection
82 Developing Java Applications
When used with a simple input field (Call.playAndGetInput() using an
InputAttributes object, as in the above example), the InputResult.getValue()
method returns a String containing the DTMF keys pressed by the caller, the
recognized words spoken by them, or the annotations associated with the
recognized words if the grammar uses annotations. When used with a menu
(Call.playAndGetInput() using a MenuAttributes object), this method returns
the value of the label corresponding to the selected menu item. Your
application can then process the input accordingly.
The InputResult class also has the following properties, mostly to do with
speech recognition results. To extract the value of the property from the
InputResults object use the relevant get method:
v annotation: the annotation that corresponds to the word or words of
recognized input.
v nBestAnnotations: an array of the annotations returned by the speech
recognizer. The annotations correspond to the nBestValues of words
spoken. A single annotation may be obtained by calling the getAnnotation()
method with the words spoken.
v nBestScores: an array of the confidence scores returned by the speech
recognizer. The scores in are in the range 0 to 100, with 100 being the best
score and 0 the worst.
v nBestValues: an array of the results from the speech recognizer. This array
and the nbestScores array vary in length depending on the number of
results returned: they may be smaller than the number of results requested
if the recognizer returns fewer results. The results are ordered from most
likely to least likely. The first value in this list (the most likely response) is
also placed in the value property. You can set the number of results
required in the nbest property of the RecoAtrributes class. Recognizers can
return various pieces of information in a recognition result, including the
actual utterance recognized and tag words that are added based on the
provided grammar. To a large extent the information returned is
determined by the grammar used. See the documentation that comes with
your plug-in for more details. If annotations are returned, as well as the
actual words spoken, they are set in the annotations property.
v nthBestAnnotation: the annotation at the specified index.
v nthBestScore: the score of the specified nthBest value.
v nthBestValue: the specified nBest value.
v terminationKey: the actual key that was interpreted as the end of input
(the ″enter″ or ″delimiter″ key).
v type: the input type of the return value. Either
InputResult.KEY_INPUT_RECEIVED or
InputResult.VOICE_INPUT_RECEIVED.
v numberOfValues: the number of results returned by the speech recognizer.
asking the caller to make a menu selection
Chapter 4. Creating voice applications 83
Validating input
Your voice application will automatically do some validation of the caller’s
input using properties that you set in your attributes classes. For example, the
maximumKeys property of the DTMFAttributes class will ensure that the
caller enters the correct number of keys. To perform more complicate
validation you can create your own validation class. This class must
implement the InputValidator interface, which has one method, validate().
This method takes as a parameter the InputResult object returned by the
Call.playAndGetInput() method used to get the caller’s input. The validate()
method returns the validated input in the form of a String, or null if the
input is not valid. Your implementation of this method is where the validation
takes place.
Once you have created a new validation class you need to create an instance
of it in your application. You then set this instance as the validator property
of your InputAttributes object, using InputAttributes.setValidator(), or the
InputAttributes constructor method. When you use this InputAttributes
object as a parameter of the Call.playAndGetInput() method, your
implemented validate() method is called to perform its validation. For
example:
Creating the validator class
// Create an InputValidator class to validate the caller’s telephone number
public class PhoneNumChecker implements InputValidator {
public String validate(InputResult result) {
// Get the caller’s input from the InputResult object
String value = result.getValue();
// Process the input data
// If the caller’s number starts with a 2, it is valid
if (value.substring(0, 1).equals("2")) return value;
// Otherwise the number is invalid, so return null
return null;
}//validate
}
Using the validator class within your application
public class myVoiceApp extends WVRApplication {
.
.
.
// Create an instance of the new validation class
private PhoneNumChecker phoneNumChecker = new PhoneNumChecker();
// Set the validator in InputAttributes
telNoInputAtts.setValidator(PhoneNumChecker);
// Use the InputAttributes object with the playAndGetInput() method.
asking the caller to make a menu selection
84 Developing Java Applications
// The caller’s response will automatically be checked to see if it begins
// with a 2
call.playAndGetInput(telNoPlayAtts, telNoInputAtts, telNoDTMFAtts, null);
.
.
.
}
Recording the caller’s voice input
The Call.record() method provides an opportunity for the caller to record
some spoken input. Think of it as a voice input field, or even a voice text
area. The recorded voice is stored in a voice segment that you specify. The
method takes two required parameters and optionally, two additional
parameters:
v voiceSegment: the name of the VoiceSegment object to be used for the
recording. The VoiceSegment object must be defined before you use it.
v duration: the duration of the recording in seconds. This is the maximum
time, in seconds, allowed for the voice input. Specify −1 for a period
limited only by the base WebSphere Voice Response system limit on
recording time. Your application can later obtain the actual duration of the
recording by using the RecordingInfo.getLengthRecorded() method (see
“Obtaining information about the recording” on page 86).
v beep: whether or not a beep is to be played before recording. (Optional)
v stopOnKey: whether or not to stop recording when a DTMF key is pressed.
(Optional).
For example, to define a voice segment with the label CallerMsg in the
RECORDING category:
public class InApp extends WVRApplication {
.
.
.
// Create the segment object for recording a message to a voice segment in the
// Recordings category
VoiceSegment vs_caller_message = new VoiceSegment("Recordings", "CallerMessage");
.
.
.
}
To record, after a beep, a message of up to 180 seconds in duration from a
caller to the vs_caller_message voice segment, and enable the caller to stop
the recording by pressing a DTMF key, you would invoke the Call.record()
method within voiceMain() in the following way:
call.record(vs_caller_message, 180, true, true);
asking the caller to make a menu selection
Chapter 4. Creating voice applications 85
To record without a starting beep, a message of maximum duration to the
same voice segment, that could be stopped by pressing a DTMF key, you
would invoke the Call.record() method in the following way:
call.record(vs_caller_message, -1, false, true);
Once recorded, the VoiceSegment can be used in the same way as any other
VoiceSegment object.
Obtaining information about the recording
The RecordingInfo class contains information about a recording made using
the Call.record() method, for example the length of the recording. A
RecordingInfo object is returned when the Call.record() method is invoked.
The class has the following properties, which can be extracted from the
RecordingInfo object using the appropriate get method:
v keyPressed: the key that the caller pressed to indicate that they had
finished recording their message.
v lengthRecorded: the duration of the recording in seconds.
v terminationReason: how the recording was terminated. Possible values are:
– RecordingInfo.MAX_SILENCE: no voice was detected
– RecordingInfo.KEY_PRESSED: the caller pressed a DTMF key
– RecordingInfo.MAX_RECORD_LENGTH: the recording exceeded the
specified maximum length
For example:
public class InApp extends WVRApplication {
.
.
.
// Create the segment object for recording a message to a voice segment in the
// Recordings category
VoiceSegment vs_caller_message = new VoiceSegment("Recordings", "CallerMessage");
.
.
.
// Record the message using the maximum time limit
RecordingInfo input = call.record(vs_caller_message, -1, false, true);
// If the user terminated the recording by pressing a key, find out which key they used
if (input.getTerminationReason() == RecordingInfo.KEY_PRESSED) {
Character key = input.getKeyPressed();
}
.
.
.
}
Dealing with silence
WebSphere Voice Response for AIX can detect an extended period of silence
and terminate the recording. It starts silence detection only after the caller has
recording the caller’s voice input
86 Developing Java Applications
started speaking, and does not terminate the recording until the time specified
by the maximumLength property has elapsed.
Changing the pacing tone
When asking for the caller’s input using speech recognition, or when
recording a message from the caller, you can choose to have a pacing tone
(beep) played when the application is ready to receive input. See “The
RecoAttributes class” on page 81 and “Recording the caller’s voice input” on
page 85 for more information about playing pacing tones.
You can replace the system tone with any VoiceSegment object using the
Call.setBeep() method, which takes one VoiceSegment as a parameter. Once
set, this pacing tone will apply throughout the rest of the application. To reset
to the system tone, invoke the Call.setBeep() method again, using null as a
parameter.
To access the pacing tone currently set in the application, use the
Call.getBeep() method.
Internationalizing your applications
The book WebSphere Voice Response for AIX: Deploying and Managing VoiceXML
and Java Applications introduces the concepts of locale, default locale, and
current locale, and how you can use these to make the same application speak
different languages, without altering the application itself in any way. This
section tells you how to do this:
v “Setting the application locale”
v “Changing the application locale dynamically” on page 88
v “Determining which locale the application is using” on page 88
Setting the application locale
The application locale property allows an application to have a default locale
that is different from the default locale of the voice response node. For
example, you might want to run an English version, a French version, and a
Spanish version of an application on the same voice response node. The
application locale for each version determines the default language and
country or region (and optionally a user-defined variant) of all voice segments
in the application.
To specify the application locale, use the ApplicationProperties.setLocale()
method. For example, to set the locale of an application to United States
include the following within voiceMain():
public void voiceMain() throws WVRException {
.
.
recording the caller’s voice input
Chapter 4. Creating voice applications 87
.
// Create the application properties object
ApplicationProperties applicationProperties = new ApplicationProperties();
// Set the application locale
applicationProperties.setLocale(Locale.US);
.
.
.
}
Changing the application locale dynamically
The book WebSphere Voice Response for AIX: Deploying and Managing VoiceXML
and Java Applications introduces the concept of current locale, and suggests
how you might design an application that changes the current locale
dynamically. This section tells you how to do it.
Setting the locale
You can set the locale to be used while the application is running, either on
the basis of the calling number or some other criteria (for example, a menu
that asks the caller which language they want).
The WVR class has a currentLocale property. When WVR.makeCall() or
WVR.waitForCall() is invoked, the currentLocale property is set to the default
locale (see WebSphere Voice Response for AIX: Deploying and Managing VoiceXML
and Java Applications). To change the locale used by the application, during the
application, use the WVR.setCurrentLocale() method within voiceMain().
Setting the current locale in this way does not change the value of the locale
in the ApplicationProperties object. The current locale does not affect any
MediaType objects that have locale individually specified.
When an application finishes with the call and starts to handle a new call, the
default locale is used again, rather than a locale that the application has
switched to during the previous call.
Resetting the current locale to the default locale
To reset the locale back to the default locale during a call, set the value of the
currentLocale property of the WVR object to null.
Determining which locale the application is using
To determine what locale the application is currently using use the
WVR.getCurrentLocale() method. You can change the behavior of the
application, if necessary, depending on this value.
internationalizing your applications
88 Developing Java Applications
Creating multilingual applications
Not all applications are completely language-independent. You might want to
mix the languages spoken by a single application. In this case, rather than
changing the current locale, use the locale property of individual MediaType
objects to override the current locale.
Using the locale property of the media objects
Normally, the MediaType.locale property is not set, so that the default locale
is used at runtime. This makes it very easy to develop an international
application that automatically adapts itself to the local requirements (for
example, in France, users hear French voice segments and in Britain, users
hear UK English voice segments). However, you can override the default
locale by specifying a locale for the media objects, for example, to develop a
multilingual message.
Speaking currency values
The supplied voice segments for each locale include one set of four voice
segments for currency names, as shown in Table 1. Because locale includes
country or region as well as language, these names are the names of the main
local currency. Normally, the AudioCurrency object speaks the currency
names for this currency. For example, if the locale is en_US, the value 2.25 is
spoken as “two dollars and twenty-five cents”.
Table 1. Currency voice segments for XYZ currency
Voice segments for XYZ currency Example
XYZ_majorcur (major currency name, singular) “dollar”
XYZ_majorcurs (major currency name, plural) “dollars”
XYZ_minorcur (minor currency name, singular) “cent”
XYZ_minorcurs (minor currency name, plural) “cents”
Using the currency property of the AudioCurrency object
The currency property of the AudioCurrency object allows you to speak a
value as an amount in a currency that isn’t the local currency. For example,
you might want to talk about British currency in France, or you might want to
talk about Euros anywhere in Europe. Table 2 on page 90 shows an example
of this, and Table 3 on page 90 shows what voice segments you would need.
Speaking euro amounts
In the following locales, currency amounts are spoken in euros and cents by
default: French, Castilian Spanish, Catalan, German and Italian. To revert to
the old national currency, specify PREEURO in the variant part of the locale
property. Alternatively, you can specify dtj.preeuro.support=true in the
dtj.ini file to achieve the same result. To speak a numeric value as a euro
amount in a locale which doesn’t default to euro, you need to:
internationalizing your applications
Chapter 4. Creating voice applications 89
1. Record major and minor currency names (“euro” “euros”, “cent”, and
“cents”) in the languages in which you intend to speak euro amounts (for
example, you might want them pronounced differently in French, English,
and so on). The names must be prefixed with the characters “EUR”, for
example, EUR_majorcur, EUR_majorcurs, EUR_minorcur, EUR_minorcurs.
2. Before you can import the voice segments that you have recorded, you
need to create your own control file, an example of which is shown in
Figure 20 on page 91.
3. Import the voice segments that you have recorded using the following
command:
dtjplex -action importVoiceAll -controlfile <path>\impexpeuro.cfv
4. Specify EUR in the currency property of the AudioCurrency object.
Table 2. A value of 20000000 spoken with different currency and locale property
values
locale GBP currency FRF currency EUR currency
en_GB “twenty million pounds” “twenty million
francs”
“twenty million
euros”
fr_FR “vingt millions de livres
sterling”
“vingt millions
francs”
“vingt millions
euros”
Table 3. Voice segments required
locale Voice segments required
en_GB GBP_majorcur FRF_majorcur EUR_majorcur
GBP_majorcurs FRF_majorcurs EUR_majorcurs
GBP_minorcur FRF_minorcur EUR_minorcur
GBP_minorcurs FRF_minorcurs EUR_minorcurs
fr_FR GBP_majorcur FRF_majorcur EUR_majorcur
GBP_majorcurs FRF_majorcurs EUR_majorcurs
GBP_minorcur FRF_minorcur EUR_minorcur
GBP_minorcurs FRF_minorcurs EUR_minorcurs
internationalizing your applications
90 Developing Java Applications
Related information
v How languages are identified in Java. See WebSphere Voice Response for AIX:
Deploying and Managing VoiceXML and Java Applications.
v “Which locale is used when an application is invoked?” on page 98
Using speech recognition for menus and data entry
If you have speech recognition installed on your base WebSphere Voice
Response system, you can use the Call.playAndGetInput() method to ask for
voice input. Basically, getting voice input using this method is the same as
getting key input, as described in “Getting input from the caller” on page 70.
This section adds to those sections, telling you what you have to do in
addition, to get voice input from the caller.
To recognize voice input, you need to install a speech recognition product on
your base WebSphere Voice Response system, and install a plug-in program to
allow Java applications to use it. For details see ″Adding speech recognition
capability″ in WebSphere Voice Response for AIX: Deploying and Managing
VoiceXML and Java Applications. The capability of the speech recognition
product, or technology, determines what you can do with speech recognition in
Java applications. However, if the technologies are equivalent, you can switch
from one to another without changing the application itself, because the
character_encoding = Cp1252
#export :
segment_locale = fr_FR
export_type = raw
#import :
import_hints = Q0S0
file_encoding = wav
segment_name = EUR_majorcur
segment_category = System
file_name = euro.wav
;
segment_name = EUR_majorcurs
segment_category = System
file_name = euros.wav
;
segment_name = EUR_minorcur
segment_category = System
file_name = cent.wav
;
segment_name = EUR_minorcurs
segment_category = System
file_name = cents.wav
;
Figure 20. Example of a control file
internationalizing your applications
Chapter 4. Creating voice applications 91
technology is not specified inside the application. In addition, you can use
different technologies for different languages, without modification to the
application itself.
Specifying the technology to be used
The technology (or technologies) to be used by all applications can be
specified in the NodeName configuration entry of the voice response node
(for more information see WebSphere Voice Response for AIX: Deploying and
Managing VoiceXML and Java Applications). This is the simplest method.
If the technology you want to use does not have a RecoDefinition in the
NodeName configuration entry, you can specify it in the
ApplicationProperties. This might be necessary if you have other applications
using another technology. When you put your application into production,
you need to add the definition to the configuration; see WebSphere Voice
Response for AIX: Deploying and Managing VoiceXML and Java Applications for
more information.
Specifying RecoDefinitions in ApplicationProperties
If you don’t know the name of your speech recognition technology, look at the
RecoService entries in the configuration file (default.cff). The name must
match the RecoType keyword.
To specify the RecoDefinitions for an application in ApplicationProperties,
within voiceMain():
v Create a new RecoDefinition object for the application that is to use the
other technology or language. For example, to specify that an application
use the speech recognition technology associated with the RecoType
Recoen_US in the US locale:
RecoDefinition recoDef= new RecoDefinition("en_US","Recoen_US");
v Create a new RecoDefinitions object:
RecoDefinitions recoDefs= new RecoDefinitions();
v Add the new definition to the RecoDefinitions:
recoDefs.addRecoDefinition(recoDef);
v Specify that your application use the new definition by setting the
RecoDefinitions with the ApplicationProperties.setRecoDefinitions()
method:
ApplicationProperties.setRecoDefinitions(recoDefs);
The default behavior is for a technology to apply to any language.
You can use different RecoTypes (technologies) for different languages. First
decide what the “default” technology is, and add that without specifying a
locale. Then add the “exceptions”.
using speech recognition for menus and data entry
92 Developing Java Applications
See also ″Adding speech recognition capability″, in WebSphere Voice Response
for AIX: Deploying and Managing VoiceXML and Java Applications.
Telling the caller what to say
To use speech recognition in your application, you will need to create at least
one RecoAttributes object, to be used with the Call.playAndGetInput()
method. See “The RecoAttributes class” on page 81 for more information. For
speech recognition in menus, you will also need to specify the words that the
caller can use to select their menu choice. See “The MenuAttributes class” on
page 76 for more information.
Mixing key and voice input
Although it is possible, we do not recommend allowing key and voice input
in the same interaction, or even in the same application. It is likely to make
your program very complicated, and is not usually expected or exploited by
callers. But there may be applications where it would make sense.
When using WebSphere Voice Response for Windows with speech recognition,
if you have created a PlayAttributes object with properties of
PlayAttributes.FIRST_DTMF and PlayAttributes.VOICE_ENERGY, and the user
presses a key, the key tone may be treated as noise and passed to the
recognizer.
Asking the recognizer for alternative results
Many speech recognition technologies return multiple recognition results
when uncertain what the speaker said. Multiple recognition results are
referred to as n-best results. Not all technologies support n-best results, but if
you want to make use of them, use the nbest property of the RecoAttributes
object to specify the maximum number of results your program is prepared to
handle.
Speech recognition on AIX only returns the first three matches from the
recognition event. Specifying an nbest value greater than this has no effect.
The number you specify depends on your application, but is unlikely to be
very large. Bear in mind that what you are interested in is the one thing that
the caller actually said. If the recognizer was not confident, then you need to
ask the caller to help you establish what they did say. One way of doing this
is to repeat back the result with the highest score to the caller, and ask the
caller a Yes/No question to clarify what they said. If they say “No”, repeat
the original question, or ask the question in a different way. The exact way
you handle the interaction is up to you and the needs of your callers.
You can request n-best even if your current speech recognition technology
only returns a single result.
using speech recognition for menus and data entry
Chapter 4. Creating voice applications 93
The various results are returned simultaneously in an array of String objects
in the nbestValues property of the InputResult object obtained when a caller
gives input. The number of entries in the array is never greater than the
number of results you specify in the RecoAttributes.nbest property, but it can
be smaller. The more entries, the more uncertain the recognizer was. The
results are in the order of most likely to least likely.
You can see the score that the recognizer determined for each result by
invoking the InputResult.getNbestScores() method. You can also get an
individual score for a specific position in the array by using the
InputResult.getNthBestScore() method. The value of each score is in the
range 0 through 100, with 0 being the least confident, and 100 being the most
confident. AIX uses only the first three results returned from the recognizer.
These are given confidence scores of 100, 50 and 0.
There are also similar methods to retrieve an individual recognition result at a
particular level, or all recognition results.
Annotations and words spoken in menus
When you use MenuAttributes() with voice input, if an annotation is
returned, the system uses this as the input value in preference to the words
spoken. The system compares the value with the selector word values of the
menu items and if it finds a match, the corresponding menu item is assumed
to be selected. If an annotation is not returned, the system uses the words
spoken as the input value instead.
There are several methods for retrieving annotation information:
v InputResult.getNbestAnnotations() which returns an array of the n-best
annotation results.
v InputResult.getNthbestAnnotation() which takes an integer index
parameter and returns the corresponding n-best annotation result.
v InputResult.getAnnotation() which returns the speech recognition
annotation for the one or more specified word of recognised input
Using text-to-speech
If your application is designed to provide callers with information that
changes frequently, or which is very lengthy or infrequently accessed,
text-to-speech may be more suitable than recorded voice segments: good
examples are news articles and e-mail messages. Using text-to-speech, your
application can output synthesized speech, supported by any text-to-speech
technology installed on the base WebSphere Voice Response system.
To use text-to-speech, you need to install a text-to-speech product on your
base WebSphere Voice Response system, and install a plug-in program to
using speech recognition for menus and data entry
94 Developing Java Applications
allow Java applications to use it. For details see WebSphere Voice Response for
AIX: Deploying and Managing VoiceXML and Java Applications. The capability of
the text-to-speech technology installed determines what you can do with
text-to-speech in Java applications. However, if the technologies are
equivalent, you can switch from one technology to another without changing
the application itself, because the technology is not specified inside the
application.
If you are using a streaming technology, there is a minimal delay because the
utterance is returned for playback as soon as the first segment is completed. If
you are not using streaming technology, the completed segment is returned
when generated. If the segment is large, there could be some delay.
Specifying the technology to be used
The technology (or technologies) to be used by all applications can be
specified in the NodeName configuration entry of the voice response node.
This is the simplest method. For more information see WebSphere Voice
Response for AIX: Deploying and Managing VoiceXML and Java Applications.
If the technology you want to use does not have a TTSDefinition in the
NodeName configuration entry, you can specify it in the
ApplicationProperties. This might be necessary if you have other applications
using another technology. When you put your application into production,
you need to add the definition to the configuration; see WebSphere Voice
Response for AIX: Deploying and Managing VoiceXML and Java Applications for
more information.
Specifying TTSDefinitions in ApplicationProperties
If you don’t know the name of your speech synthesis technology, look at the
TTSService entries in the configuration file (default.cff). The name must
match the TTSType keyword.
To specify the TTSDefinitions for an application in ApplicationProperties,
within voiceMain():
v Create a new TTSDefinition object for the application that is to use the
other technology or language. For example, to specify that an application
use the speech synthesis technology associated with the TTSType TTSen_US
in the US locale:
TTSDefinition TTSDef= new TTSDefinition("en_US","TTSen_US");
v Create a new TTSDefinitions object:
TTSDefinitions TTSDefs= new TTSDefinitions();
v Add the new definition to the TTSDefinitions:
TTSDefs.addTTSDefinition(TTSDef);
using text-to-speech
Chapter 4. Creating voice applications 95
v Specify that your application use the new definition by setting the
TTSDefinitions with the ApplicationProperties.setTTSDefinitions()
method:
ApplicationProperties.setTTSDefinitions(TTSDefs);
The default behavior is for a technology to apply to any language.
You can use different TTSTypes (technologies) for different languages. First
decide what the “default” technology is, and add that without specifying a
locale. Then add the “exceptions”.
See also ″Adding text-to-speech capability″, in WebSphere Voice Response for
AIX: Deploying and Managing VoiceXML and Java Applications.
Using TextToSpeech
The TextToSpeech class is a subclass of MediaType and can be used in the
same way as all the other MediaType subclasses, such as VoiceSegment, as
described in “Specifying what is to be spoken using the MediaType class” on
page 60 and “The TextToSpeech class” on page 68. The speech is synthesized
dynamically from text specified using the ttsString property of the
TextToSpeech class. As with other media objects, the language of the
individual Text-To-Speech string can be specified using the locale property of
the TextToSpeech class.
Text-to-speech support is intended for reading passages of text that is either
lengthy or frequently changed, or for repeating back callers’ input,
particularly when using speech recognition. It is not intended to replace the
use of recorded voice segments for the regular prompts in an application.
However, where appropriate in an application, you can use text-to-speech
instead of a voice segment, for example, as a prompt or in the
headerMessage, and footerMessage of a menu.
More about handling calls
This section covers topics that you may want to skip on a first reading:
v “Summary of methods used for telephony-related functions”
v “Handing a call to another application” on page 97
v “Transferring a call to an agent” on page 100
Summary of methods used for telephony-related functions
Table 4. Call-related methods and corresponding WebSphere Voice Response actions
Corresponding action
WVR.waitForCall() AnswerCall
using text-to-speech
96 Developing Java Applications
Table 4. Call-related methods and corresponding WebSphere Voice Response
actions (continued)
Corresponding action
WVR.cancelWait() None.
WVR.makeCall() MakeCall
Call.returnCall() TerminateCall
Call.invokeApplication method() InvokeStateTable
Call.consult() TransferCall
Call.retrieve()
1 ReconnectCall
Call.hold() None.
Call.unhold() ReconnectCall
Call.transfer() TerminateCall
Call.blindTransfer() TransferCall and then
immediately TerminateCall
Call.conference() None.
Call.blindConference() None.
1. There is little difference between retrieve() and unhold() on most switches.
Handing a call to another application
The Call.invokeApplication() method allows one application to pass the
telephone call to another voice application. The application to be invoked
does not need a number-to-application mapping in the configuration database.
Before being invoked, the application must be started and must issue a
WVR.waitForCall(), so that it is waiting for a call, as shown in Figure 21 on
page 99.
An invoked application can invoke another application: the nesting of
applications is not limited by the architecture.
To pass the telephone call to another application use the
Call.invokeApplication() method. The parameters of this method are:
applicationName
If you are running the application in a node, the applicationName
should match the application name as described in the AppName
configuration entry.
applicationData
This is an optional property which may be set to contain a serializable
Java object that is to be passed to the invoked application. Note that
parameters passed into the invoking application are not automatically
more about handling calls
Chapter 4. Creating voice applications 97
passed to the invoked application, and that the Java object must be
accessible in the classpath for the voice response node in addition to
the application node in which the application is running.
waitForReturn
To make the invoking application wait for the invoked application to
return, set waitForReturn to true, as shown in Figure 21 on page 99. If
the invoking application has finished with the phone call, set
waitForReturn to false, as shown in Figure 22 on page 100. The Call
object of the invoking application becomes invalid.
For example:
try {
// Make a call to another application, transfer data, and wait
Call call = wvr.waitforcall();
Object javaObject = new Object();
call.invokeApplication("OtherApp", javaObject, true);
}
Which locale is used when an application is invoked?
When you use the Call.invokeApplication() method to invoke another
application, the locale specified in the ApplicationProperties or the AppName
entry for the invoked application is used; if no locale is specified for the
invoked application, the current locale of the calling application is used. If the
call is passed back to the invoking application, the locale is whatever the
invoked application was using when it returned the call.
What text-to-speech and speech recognition definitions are used when an
application is invoked?
When you use the Call.invokeApplication() method to invoke another
application, any text-to-speech and speech recognition definitions that were
configured for the invoking application do not apply to the invoked
application. If the invoked application returns to the invoking application, the
text-to-speech and speech recognition definitions of the invoking application
are reinstated.
handing a call to another application
98 Developing Java Applications
WVR.waitForCall()Call.invokeApplication()
Application “B”Application “A”
Call.returnCall()Call.returnCall()
Call.play()
Specify in theproperty.
truewaitForReturn
Specify in the
property.
BapplicationName
Application Bcan nowinteract withthe caller.
When application Bfinishes with the call, itreturns to application A.
speechspeech
Figure 21. Handing a call over to another application and waiting to get it back
handing a call to another application
Chapter 4. Creating voice applications 99
Transferring a call to an agent
Many voice applications give the caller the option of speaking to a real
person. Your application can either transfer blind (without checking that an
agent is available) or it can check before transferring the call.
Blind Transfer
To transfer the caller to an agent without first checking that an agent is
available, use the Call.blindTransfer() method. This method calls a specified
number and transfers the caller to the ringing call. The first call becomes
inactive. If an agent is not available, the caller is left to hang up. If an agent is
available, the call is dealt with by them and if necessary the caller can be
transferred to another instance of the original application (or to another
application) by the agent.
Note: To transfer a call and for consulting and conferencing functions, the
application uses the methods in the Call class. The call transfer can be
done either by a telephony service or by the base WebSphere Voice
WVR.waitForCall()
Call.invokeApplication()
Application “B”Application “A”
Call.returnCall()
Call.play()
Specify in theproperty.
falsewaitForReturn
Specify in the
property.
BapplicationName
Application Bcan nowinteract withthe caller.
Application A can continueprocessing, but it cannotcontinue to interact with thecaller.
speechspeech
When application Bfinishes with the call, itreturns to the system.
Figure 22. Handing a call over to another application
transferring a call to an agent
100 Developing Java Applications
Response system (if the switch has the capability). The application
program is exactly the same in both cases. To use a telephony service,
follow the instructions in ″Adding Telephony Capability″, in WebSphere
Voice Response for AIX: Deploying and Managing VoiceXML and Java
Applications. Otherwise, make sure your base WebSphere Voice
Response system is configured for the function you require and, if you
have WebSphere Voice Response for Windows, set the
ConsultCommand, ConferenceCommand, HoldCommand, and
RetrieveCommand keywords in the NodeName configuration entry to
the correct values for the switch being used (for more information see
WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and
Java Applications). Note that the base WebSphere Voice Response for AIX
system does not support call conference.
To transfer the caller to an agent simply invoke the Call.blindTransfer()
method with the telephone number of the agent. For example:
.
.
.
// Tell the caller they are being transferred to an agent by playing a
// voice segment
call.play(VS_Being_Transferred);
// Transfer caller to agent
call.blindTransfer("7001");
// No further action required. The call object is now invalid, and any
// methods called on it will throw an exception
.
.
.
To set up a blind conference call, the process is similar to that shown in
Figure 23 on page 102.
transferring a call to an agent
Chapter 4. Creating voice applications 101
Consulting with an agent while keeping the caller on hold
In this scenario, the voice application puts the caller on hold while it consults
an agent. The application uses the Call.consult() method to check that the
agent is there, as shown in Figure 24 on page 104. The application places the
current call on hold, then uses the same line to call the specified number. If
the agent is there, the voice application uses Call.transfer() to transfer the
caller to the agent. If the agent is not there, the application uses Call.retrieve()
to return to the original caller.
To transfer the caller to an agent invoke the Call.consult() method. This
method returns a Call object representing the new call between the
application and the agent — the original caller is now on hold. You can use
this Call object to play messages to the agent before transferring the caller
using the Call.transfer() method. If the agent is not available, or the transfer
fails for some other reason, use the Call.retrieve() method as shown in
Call.play() AgentCall.blindTransfer()
Call.play()
succeedtry
C
B
A
“Please hold whilewe transfer you toan agent”
“How can Ihelp you?”
“Sorry, theagent isunavailable atthe moment”
catc
hspeechspeech
speechspeech
speechspeech
On hold
Connected
Caller
Application
Agent
A B C Key
Figure 23. Transferring the caller to an agent
consulting with an agent while keeping the caller on hold
102 Developing Java Applications
Figure 24 on page 104 to retrieve the original call from its held state. The
transfer call is now inactive. For example:
.
.
.
try {
// Make another call to the agent on telephone number "7001".
// The caller is now on hold
Call transferCall = originalCall.consult("7001");
// Tell the agent they have a caller by playing a voice segment
transferCall.play(VS_Caller_For_You);
// Transfer the caller to the agent
originalCall.transfer();
// No further action required on the original call
}
catch (WVRException e) {
// In the event of an exception, get the original caller back
originalCall.retrieve();
// Tell the caller that an agent was not available
originalCall.play(VS_Agent_Not_Avail);
// Continue with call
.
.
.
}//try
.
.
.
Note: ISDN trunks have a dedicated signaling channel, so the caller is not put
on hold while the application establishes a connection to the agent. If
the agent is not available the application does not need to use the
Call.Retrieve() method to reconnect to the caller, as the connection was
not interrupted.
consulting with an agent while keeping the caller on hold
Chapter 4. Creating voice applications 103
Call.play() Call.consult()
Call.transfer()
The
activ
ecall
The held call
Call.returnCall()
Call.play()
Call.play()
succeedtry
C
B
A
“Please hold whilewe transfer you toan agent”
“We aretransferring acaller to you”
“Sorry, theagent isunavailable atthe moment”
catc
hspeechspeech
speechspeech
speechspeech
On hold
Connected
Caller
Application
Agent
KeyA B C D E
D
E
Figure 24. Consultation with an agent while the caller is on hold
consulting with an agent while keeping the caller on hold
104 Developing Java Applications
To set up a conference call, use the Call.conference() method once the
Call.consult() method has established the new call. If the conference is
successful any further actions such as play and record will occur on both calls.
Note: The base WebSphere Voice Response for AIX system does not support
call conference. To use the Call.conference() method on AIX you must
have a telephony service.
Call.play()
Call.play()
Call.consult()
Call.retrieve()
The
activ
ecall
The held call
Call.play()
Call.play()
succeedtry
C
D
E
B
A
“Please hold fora few moments”
“We need tocheck the details
of caller...”
“Sorry, we areunable to checkyour details atthis time”
catc
hspeechspeech
speechspeech
speechspeech
speechspeech
On hold
Connected
Caller
Application
Agent
KeyA B C D E
Figure 25. Retrieving a call from an agent
consulting with an agent while keeping the caller on hold
Chapter 4. Creating voice applications 105
Getting called and calling numbers and application call data
To get called and calling numbers and application call data into your voice
application, use the following Call class methods:
getDNIS()
Return type: java.lang.String
For an inbound call, this method returns the number that was called
to get to this phone line (the called number).
Note: This information is only available if the connection to the
telephony network provides this information, for example if a
telephony service is being used or the line protocol supports
DNIS. If the DNIS is not available from elsewhere, then this
method returns the number configured for this phone line in
the base WebSphere Voice Response system instead.
getANI()
Return type: java.lang.String
For an inbound call, this method returns the number of the party that
made the call (the calling number). This information is only available
if a telephony service is in use, or if the protocol on the connection to
the telephone network can provide it (for example, Feature Group D).
getApplicationCallData()
Return type: java.lang.Object
This method returns application call data. This is application defined
data that has been attached to the call before the call was transferred
to WebSphere Voice Response.
Note: To pass on application data from this application to another
Java voice application, use the Call.invokeApplication()
method and specify the application data as a java.lang.Object
in the second parameter of the method.
getCTIKeys()
Return type: java.lang.String
Returns the CTI keys for this call
getting called and calling numbers and application call data
106 Developing Java Applications
Handling voice segments dynamically
This section explains how to delete, import, and export voice segments during
application runtime.
v “Deleting voice segments dynamically”
v “Importing and exporting voice segments dynamically”
Deleting voice segments dynamically
Sometimes you need to delete a voice segment from within an application,
typically when a voice segment has been recorded during the application and
is not required after the application has finished. It is possible to delete the
segment during a call, before the call starts or after the call has finished.
If the voice segment does not exist, you will receive an exception.
To delete a voice segment, use the WVR.deleteVoiceSegment() method, which
takes one parameter, the name of the VoiceSegment to be deleted.
For example, to define a voice segment named CallerMessage in the
RECORDING category, record to it and then delete it:
public class InApp extends WVRApplication {
.
.
.
// Create the voice segment object for recording the message
VoiceSegment vs_caller_message = new VoiceSegment(RECORDING, "CallerMessage");
.
.
.
// Record the message
call.record(VS_Caller_Message, -1, false, true);
.
.
.
// During the call handling, the voice segment is no longer required and can be deleted
wvr.deleteVoiceSegment(VS_CALLER_MSG);
.
.
.
}
You can delete the voice segment at any time during the application, as long
as there is a WVR object to invoke the method on.
Importing and exporting voice segments dynamically
You might want to import or export a voice segment from within your
application while it is running, for example, if your application announces
status updates which change throughout the day. To do this, use the
WVR.importVoiceSegment() and WVR.exportVoiceSegment() methods.
getting called and calling numbers and application call data
Chapter 4. Creating voice applications 107
There are two versions of each method, one uses a file and the other uses a
data stream. The parameters are as follows:
v segment: the name of the VoiceSegment to be imported or exported. If the
voice segment does not exist, the method will throw an exception.
v Either
– file: the name of the file to import or export from
Or
– in or out: a java.io.InputStream or java.io.OutputStream object, as
appropriate.v type: the type of the audio data. Possible values are
– WVR.AUDIO_TYPE_WAVE: the audio is in wave format.
– WVR.AUDIO_TYPE_ALAW: the audio is in A-Law format.
– WVR.AUDIO_TYPE_ULAW: the audio is in U-Law format.
– null: the audio type will be automatically determined.
For example, to import a voice segment called ’status’, by reading a file called
’hour1’ recorded in A-Law format, using a WVR object called ’wvr’:
wvr.importVoiceSegment(status, hour1, WVR.AUDIO_TYPE_ALAW);
To export the ’status’ voice segment to an OutputStream called ’out’, with the
audio type automatically determined:
wvr.exportVoiceSegment(status, out, null);
Invoking a VoiceXML application from a Java application
The Call.invokeVoiceXML2() method allows you to invoke a VoiceXML 2.0
application from a Java application.
It is easy to create a dialog with the caller using VoiceXML, but there are
currently some things you cannot do from VoiceXML because the VoiceXML
specification does not support them. For example, you can’t make an
outbound call from a VoiceXML dialog. To augment the capabilities of
VoiceXML, you can create a Java application that makes the outbound call and
then invokes the Call.invokeVoiceXML2() method to transfer control to a
VoiceXML application dialog. At the end of the dialog, you return control to
the Java application.
1. To invoke a VoiceXML 2.0 application from a Java application, use the
Call.invokeVoiceXML2() method. In the first parameter, which is the URI
property, specify the URI of the VoiceXML application.
2. Optionally, to pass data to the VoiceXML application, specify a second
parameter, which is the applicationData property, the name of a
serializable Java object. The data is put into a session variable called
deleting a voice segment dynamically
108 Developing Java Applications
session.ibm.application_data, which the VoiceXML application can access. To
pass data back to the Java application, use the expr= attribute on the
VoiceXML <exit>tag. In this example, response is a VoiceXML variable
that contains a value indicating the called party’s response to a question
they have been asked, which you want to return to the Java application:
<exit expr=”response” />
The value passed using the expr= attribute is returned by the
Call.invokeVoiceXML2() method as an object when the method has
finished executing.
To pass the telephone call to a VoiceXML 2.0 application, create an instance of
the Call object and within the try– catch block dealing with the call handling,
use the Call.invokeVoiceXML2() method. For example:
try {
// Invoke a VoiceXML application and transfer data
Object appData = new Object();
call.invokeVoiceXML2("\\http:\mydir\myapp.vxml",appData);
}
This gives you the start of a generic outbound calling solution where the Web
or application server not only delivers the VoiceXML pages to the browser but
controls the outbound dialing numbers. You can then extend this further to
deal with errors such as no answer, fax or answering machine detection, and
so on.
For performance reasons you should always run Java applications that invoke
VoiceXML applications within a node: in other words, you must define the
Java application in an AppName entry in the default.cff configuration file.
Invoking a state table
Use the Call.invokeStateTable() method to invoke a WebSphere Voice
Response for AIX state table. You can only pass string parameters to the state
table, so if your state table requires numeric parameters, you need to invoke it
from another state table that can accept strings from the Java voice
application.
Let’s look at an example. The state table you want to invoke, DBlookup,
retrieves a value from a database. It has three parameters:
v Database name, in this example, a constant
v Customer number, a variable obtained from the caller using
Call.playAndGetInput()
v Account balance, returned by the state table and spoken to the caller using
an AudioString MediaType object.
deleting a voice segment dynamically
Chapter 4. Creating voice applications 109
1. To invoke a State Table application from a Java application, use the
Call.invokeStateTable() method.
2. In the first parameter, which is the name property, specify the name of the
state table (DBlookup).
3. In the second parameter, which is the entryPoint property specify the state
table entry point.
4. In the third parameter, which is the parameters property, specify in the
form of a String array the list of parameters to pass to the State Table
application. You can only pass String parameters to the state table. You
must include the number of parameters that the state table expects, even if
you are not interested in some of the values.
Example:
public void voiceMain() throws WVRException {
.
.
.
// Invoke the state table
StateTableResult result = call.invokeStateTable(DBlookup, entryPoint, [customerNumber, accountNumber]);
.
.
.
}
Obtaining information from state tables
The Call.invokeStateTable() method passes back a StateTableResult object
containing a list of parameters in the form of a String array. You can only
pass back String parameters from a state table. To retrieve application data
from the StateTableResult object you use the following methods...
getParameters(String[] parameters)
Return type: java.lang.String[]
Retrieves the list of parameters returned by the state table. This
method takes a String array as a parameter. The array is then updated
with the parameters from the StateTableResult object, and returned.
The size of the array must be at least equal to the number of
parameters returned by the state table, otherwise an exception will be
thrown. Passing an array into this method increases efficiency as you
can reuse the array. Use null as a parameter to create a new array
automatically.
numberOfParameters()
Return type: int
Returns the number of parameters in the parameter list.
getParameter(int index)
Return type: java.lang.String
invoking a state table
110 Developing Java Applications
Retrieves the value of the parameter at the position in the array
specified byindex.
parametersHaveChanged()
Return type: boolean
Returns true or false, depending on whether the parameters passed
back from the state have changed from the values passed in.
getReturnCode
Return type: int
Retrieves the return code passed back from the state table.
For example, to retrieve the account balance for the Customer number from
the DBlookup state table mentioned above:
public void voiceMain() throws WVRException {
.
.
.
// Invoke the state table
StateTableResult result = call.invokeStateTable(DBlookup, entryPoint, [customerNumber, accountNumber]);
String[] balance= result.getParameters()
.
.
.// Process the input, according to the value of balance
}
invoking a state table
Chapter 4. Creating voice applications 111
invoking a state table
112 Developing Java Applications
Chapter 5. Managing your voice segments
“Making voice segments available to Java applications” on page 11 introduced
the concept of the Java voice segment space. This section provides more detail
about the dtjplex utility command, which you use to manage the voice
segments in the Java voice segment space.
Using dtjplex
Within the Java and VoiceXML environment use the dtjplex script, command,
or batch file to make voice segments available to Java voice applications. To
use dtjplex, the HostManager must be running and, for many of the actions,
the voice response node and base WebSphere Voice Response system must
also be running. The actions take effect immediately.
Here is a summary of the dtjplex actions:
Import voice segments listed in a control file
v dtjplex -action importVoiceHost -controlfile filename
Add voice segments from the base WebSphere Voice Response system to the
Java segment space
v dtjplex -action addVS -controlfile filename
Export voice segments from the Java segment space to the file system
v dtjplex -action exportVoiceHost -controlfile filename
You can also list the voice segments currently in the Java segment space
v dtjplex -action listVS -voicesegmentfile filename
Copy or rename them
v dtjplex -action copyVS -controlfile filename
And delete them
v dtjplex -action deleteVS -controlfile filename
Full reference information is given in WebSphere Voice Response for AIX:
Deploying and Managing VoiceXML and Java Applications.
© Copyright IBM Corp. 1998, 2008 113
dtjplex control file
To use many of the dtjplex actions (addVS, copyVS, deleteVS,
exportVoiceHost, importVoiceHost, importVoiceAll), you also need a dtjplex
control file to specify the names and other relevant attributes of the voice
segments you want to operate on. Specify the control file using the
-controlfile parameter. For example, dtjplex -action addVS -controlfile
pizzavsegs.txt.
Syntax
The control file contains one or more entries each of which is ended by a line
containing only a semicolon (;). The action is performed for each entry.
Each entry contains one or more lines. If the first nonblank character on a line
is a pound or hash symbol (#), the remainder of the line is ignored (treated as
a comment). Otherwise, the line must contain one, and only one,
“parameter=value” pair. The parameters are not case sensitive but the values
are. The parameters and their values are listed in detail, in WebSphere Voice
Response for AIX: Deploying and Managing VoiceXML and Java Applications.
For each entry, parameter values are gathered from top to bottom and then
the action is performed: if you do not specify a mandatory parameter in an
entry, the value last specified for it in a previous entry is used.
To unset a parameter value, set it to null (“parameter=”): in this case, the
default value is used.
Voice segments with names that use national characters
You can use the character_encoding keyword in the control file to specify the
encoding of the content of control file: see individual action information in
WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and Java
Applications.
The dtjplex command displays messages which you should check to be sure
you have operated on the correct voice segments. If you are using national
characters (8-bit ASCII or DBCS encoding), the messages may display the
“wrong” characters. If you are worried that, for example, you have not added
the correct voice segments to the Java voice segment space, use the dtjplex
listVS command to list the voice segments.
You can use the -encoding parameter to specify the character encoding used
by the listvs action to list the voice segments.
Syntax errors in the control file
If there is a syntax error in the control file an error message is displayed and
processing stops. Entries in the control file are processed up to the syntax
using dtjplex
114 Developing Java Applications
error, but no further entries are processed. If the action fails on the target host
for an entry, an error message is displayed, and processing continues to the
next entry in the control file.
Example
Figure 26 on page 115 shows a dtjplex control file that could be used to add
three voice segments from the Pizzas voice segment database to the Pizzas
category in the Java voice segment space. After this, three voice segments are
added from the Sandwiches voice segment database to the Sandwiches
category. The purpose of this example is to show how parameter values are
used repeatedly until a new value is specified.
# Example of control file for adding base voice segments
# from two voice databases to the Java voice segment space
#
# Set overall parameter values for Italian Pizza voice segments:
base_segment_database=Pizzas
segment_category=Pizzas
segment_locale=it_IT
# Set parameter values for individual segments:
base_segment_name=1
segment_name=1
;
base_segment_name=2
segment_name=2
;
base_segment_name=3
segment_name=3
;
# Set overall parameter values for American Sandwich voice segments:
base_segment_database=Sandwiches
segment_category=Sandwiches
segment_locale=en_US
# Set parameter values for individual segments:
base_segment_name=1
segment_name=1
;
base_segment_name=2
segment_name=2
;
Figure 26. Example of control file for Windows
using dtjplex
Chapter 5. Managing your voice segments 115
using dtjplex
116 Developing Java Applications
Chapter 6. Testing applications
In this section, we build on the background information in Chapter 1,
“Introduction to WebSphere Voice Response Java development,” on page 1:
v “Using the Voice Response simulator or a real WebSphere Voice Response
system?” on page 117
v “Using message logs”
v “Running an application from WebSphere Studio Site Developer” on page
118
v “Getting help from IBM Support” on page 119
Using the Voice Response simulator or a real WebSphere Voice Response
system?
You can use the Voice Response simulator to test many applications without
using a real WebSphere Voice Response system. You can run applications,
either locally on the same PC as the simulator, or on another system. You can
either run the application from WebSphere Studio Site Developer or the java
command, or you can define it in the configuration file and run it in the Voice
Response simulator’s voice response node. For more information, see
Chapter 2, “Using the WebSphere Voice Response simulator provided with
Voice Toolkit for WebSphere Studio,” on page 17.
Because you can’t test everything with the simulator, it is important that you
test using a real telephone, switch, and a voice response node that has one of
the base WebSphere Voice Response systems running on it, before deploying
your application on a production system. For instructions on how to do this,
see WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and
Java Applications.
Using message logs
Message log files contain the messages displayed on stdout, runtime errors
and application logging, if it exists. The following log files are created in the
websphere_voice_response_simulator_install_path\dtj_logs directory:
v log.n.log, created on each machine running the Java and VoiceXML
environment, where n is a number between 1 and 10 (by default). This file
contains a binary representation of runtime errors.
v <nodename>.out, created by each node. This file catches messages not caught
by the log.n.log file. It contains messages that are sent to stdout, for
example, Java application messages printed using System.out.println(). It
is a standard text file that does not need to be formatted for viewing.
© Copyright IBM Corp. 1998, 2008 117
The log.n.log file is a cyclic file. Logging will initially be output to
log.1.log. When this file reaches a size of 5000 Kb (by default), logging will
be output to log.2.log, and so on. When this process has continued until
log.10.log is full, the first log file will be overwritten and the cycle continues.
You can change the size and number of the log files by editing the following
properties in the dtj.ini file located in the WebSphere Voice Response
Simulator install directory, default:
websphere_studio_install_path\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_x.y.z
where websphere_studio_install_path is the location of WebSphere Studio Site
Developer, and x.y.z is the version number of the WebSphere Voice Toolkit):
v log.filesize
v log.numberoflogs
Note that the log.filesize property is stored in kilobytes, so to increase the
value to 10000 Kb from the default value of 5000, you would edit the entry to:
log.filesize=10000
Use the dtjflog command to format the log.n.log file so that you can read it.
See Deploying and managing VoiceXML and Java applications for details. For
example, to format log.2.log to a file called log2.out:
dtjflog -o log2.out log.2.log
Note: The <nodename>.out file is backed up to <nodename>.out.bak when the
node starts. This applies to application nodes and voice response nodes
when started. If <nodename>.out already exists, it is renamed to
<nodename>.out.bak before the new file is created.
Running an application from WebSphere Studio Site Developer
You can run applications from WebSphere Studio Site Developer using the
Voice Response simulator. You do not need to have the WebSphere Voice
Response Java and VoiceXML Environment installed on your development
system: you can use any system that has the Voice Response simulator
installed on it. For a checklist of what you do need, see Table 5.
Table 5. Checklist for running an application from WebSphere Studio Site Developer
1. Make sure that the ApplicationProperties in the application are set up
correctly to identify the IP address and nodename of the Voice Response
simulator’s voice response node.
2. The application must have a NumToApp definition in the default.cff file,
as described in ″Mapping your application to a phone number″ in the
book WebSphere Voice Response for AIX: Deploying and Managing VoiceXML
and Java Applications.
118 Developing Java Applications
Table 5. Checklist for running an application from WebSphere Studio Site
Developer (continued)
3. If you change the default.cff file, you must run dtjconf to update the
configuration database.
4. Make sure the voice response node is running.
5. In WebSphere Studio Site Developer, select the application, then select
Run->Run As->Java Application. If you have WebSphere Voice Response
for AIX, make sure you have created a new launch configuration first,
according to the instructions in “Running an application” on page 44.
Getting help from IBM Support
If you have a problem with the Java support in the WebSphere Voice
Response simulator, report it to IBM using your normal support channel.
What do you need to send to IBM Support to get problems resolved?
It makes it much easier to help you with problems if you give us precise
information, for example:
v The version number of WebSphere Voice Response Java and VoiceXML
Environment (use the dtjver command to get this)
v The exact command you issued
v The exact message you saw (DTJnnnn)
v The exact exception condition
v What the CLASSPATH is set to
v The name of the directory where the WebSphere Voice Response simulator
is installed
v The operating system where you are running the application
v The operating system where the WebSphere Voice Response simulator is
running
It can also be useful if you send:
v A copy of your default.cff file
v A copy of your dtsim.properties file
v The output of the diag command.
Providing a simple test case for the problem will aid problem determination
greatly.
Chapter 6. Testing applications 119
getting help from IBM Support
120 Developing Java Applications
Chapter 7. WebSphere Voice Response Java Tutorials
The following tutorials will introduce you to voice application programming
using the Java programming language and the IBM Java and VoiceXML
environment. In the course of these tutorials you will write a basic voice
application which receives an incoming call and lets the caller choose from a
menu offering different functions. In “Tutorial 5: Application makes a call” on
page 154 you will also write a simple application that makes an outgoing call,
which you will use to verify some of the function of the main application. The
main application builds up gradually with each tutorial, so you should follow
the tutorials in order.
You can use any IDE that supports Java, or the Java programming language
and a text editor, to create the applications.
This section includes the following:
v “Prerequisites for the tutorials.”
v “Voice segments for running the tutorial applications” on page 122.
v “Tutorial 1: Caller calls an application” on page 128.
v “Tutorial 2: Select an item from a menu” on page 134.
v “Tutorial 3: Caller exits from the application (menu item 5)” on page 142.
v “Tutorial 4: Leave a message (menu item 1)” on page 148.
v “Tutorial 5: Application makes a call” on page 154.
v “Tutorial 6: Key in a telephone number (menu item 2)” on page 158.
v “Tutorial 7: Order an item from a catalog (menu item 3)” on page 167.
v “Tutorial 8: Credit card validation (menu item 3 continued)” on page 181.
v “Tutorial 9: Order information (menu item 3 continued)” on page 190.
v “Tutorial 10: Transfer to an agent (menu item 4)” on page 198.
v “Tutorial 11: Using speech recognition and text-to-speech” on page 208.
Prerequisites for the tutorials
To complete the tutorials, you must:
1. Have a basic knowledge of the Java programming language.
2. Install the WebSphere Voice Response Simulator, by installing Voice Toolkit
for WebSphere Studio. See Chapter 2, “Using the WebSphere Voice
Response simulator provided with Voice Toolkit for WebSphere Studio,”
on page 17
© Copyright IBM Corp. 1998, 2008 121
3. Know the Node name and the IP address of the voice response node, as
this information is required by the application. For the Voice Response
simulator on your local system, these are Node1 and 127.0.0.1.
4. Start the Voice Response simulator, if it is not already running. You will
not be able to test the call transfer tutorial (“Tutorial 10: Transfer to an
agent (menu item 4)” on page 198), as the Voice Response simulator does
not support call transfer. To test this tutorial you need WebSphere Voice
Response and a switch that supports call transfer.
5. Make sure you have the voice segments needed by the tutorials: follow the
instructions in “Voice segments for running the tutorial applications.”
Voice segments for running the tutorial applications
Before you can test the applications you write in the tutorials, you need some
voice segments.
When you install Voice Toolkit for WebSphere Studio a zip file called
dtjtvseg.zip is installed into the
com.ibm.voicetools.java.develop.doc_x.y.z folder (where x.y.z is the
version number) in your websphere_studio_install_path\eclipse\plugins
directory. This zip file contains sample voice segments and a control file
(impexp.cfv) for importing them.
You can of course record your own segments; as long as you use the same
names as the sample segments, you can use the same control file to import
them.
v “The language of the tutorial voice segments.”
v “Importing the voice segments” on page 123.
v “List of voice segments in the Tutorials category” on page 123.
The language of the tutorial voice segments
The voice segments are in English. The locale is “en”, which means that these
segments can be used by any application whose current locale has a language
component of “en”, for example en_US or en_GB. In the tutorials, the
applications use the locale set in the default.cff file (located in the WVRSim
directory). Within default.cff the locale is defined in the NodeName entry,
using the NodeDefLocale keyword. If your NodeDefLocale is not set to an “en”
locale, then you must change the segment_locale in the control file included
with the voice segments (impexp.cfv) to match it. For example:
In the default.cff file: NodeDefLocale=fr_CA
In the impexp.cfv file: segment_locale=fr_CA
122 Developing Java Applications
When you have imported the voice segments the tutorial applications will
work in your locale, but they will actually be speaking English. To make the
applications speak in a different language you must record your own voice
segments.
Now import the segments, following the instructions in “Importing the voice
segments”
Importing the voice segments
Importing the voice segments into the WebSphere Voice Response
Simulator
1. Make sure the Voice Response simulator is running (from the command
line dtjshost followed by dtjstart).
2. In the Voice Response simulator install directory, create a new directory
and unzip dtjtvseg.zip into it (see “Voice segments for running the
tutorial applications” on page 122 for the location of this file). This file
contains .wav files and a control file called impexp.cfv.
3. Open a DOS command window, cd to the new directory and enter the
following command:
dtjplex -action importVoiceHost
The system will display messages containing the words Successfully
imported as the voice segments are imported into the voice segment
database.
If you see the message ’dtjplex’ is not recognised as an internal or
external command, operable program or batch file, it could be that you
have not added the Voice Response simulator install directory to your
path. Follow the instructions in Chapter 2, “Using the WebSphere Voice
Response simulator provided with Voice Toolkit for WebSphere Studio,”
on page 17 to add the directory to the path.
List of voice segments in the Tutorials category
This table lists all the voice segments provided in the Tutorials category, and
the tutorials which use them.
Tutorial
Voice Segment
Name Text
“Tutorial 1: Caller calls an
application” on page 128
Welcome Welcome to our sample application.
“Tutorial 1: Caller calls an
application” on page 128
Difficulties We seem to be experiencing technical
difficulties. Please call again later.
Chapter 7. WebSphere Voice Response Java Tutorials 123
Tutorial
Voice Segment
Name Text
“Tutorial 2: Select an item from a
menu” on page 134
MenuHeader What would you like to do?
“Tutorial 2: Select an item from a
menu” on page 134
Message To leave a message for us... press 1.
“Tutorial 2: Select an item from a
menu” on page 134
Number To leave a telephone number so that we
can call you... press 2.
“Tutorial 2: Select an item from a
menu” on page 134
Order To order an item from our catalog... press
3.
“Tutorial 2: Select an item from a
menu” on page 134
Operator To talk to one of our agents... press 4.
“Tutorial 2: Select an item from a
menu” on page 134
Hangup To disconnect... press 5.
“Tutorial 2: Select an item from a
menu” on page 134
MenuFooter Please press the key corresponding to
your choice.
“Tutorial 2: Select an item from a
menu” on page 134
InvalidKey You pressed an invalid key.
“Tutorial 2: Select an item from a
menu” on page 134
OneMore You have one more chance.
“Tutorial 2: Select an item from a
menu” on page 134
Error Sorry, you have not selected a valid
option, so we are hanging up now.
“Tutorial 3: Caller exits from the
application (menu item 5)” on page
142
ThankCalling Thank you for calling.
“Tutorial 4: Leave a message (menu
item 1)” on page 148
Record To record your message, start speaking
after the tone.
“Tutorial 4: Leave a message (menu
item 1)” on page 148
PressKey When you have finished, press the
pound key.
“Tutorial 4: Leave a message (menu
item 1)” on page 148
Respond We will respond to your message soon.
“Tutorial 5: Application makes a
call” on page 154
FollowingMessage The following message has been left for
you...
124 Developing Java Applications
Tutorial
Voice Segment
Name Text
“Tutorial 6: Key in a telephone
number (menu item 2)” on page 158
TelNo Please key in the telephone number.
“Tutorial 6: Key in a telephone
number (menu item 2)” on page 158
ThankYou Thank you.
“Tutorial 6: Key in a telephone
number (menu item 2)” on page 158
OneMoreTime You have one more chance to key in a
six-digit number.
“Tutorial 6: Key in a telephone
number (menu item 2)” on page 158
NoValidInput You have not entered a valid number.
“Tutorial 6: Key in a telephone
number (menu item 2)” on page 158
NumberInvalid That is not a valid number.
“Tutorial 6: Key in a telephone
number (menu item 2)” on page 158
NotEnough You did not key enough digits.
“Tutorial 6: Key in a telephone
number (menu item 2)” on page 158
CallBack We will call you back.
“Tutorial 7: Order an item from a
catalog (menu item 3)” on page 167
ProductNumber To order a product, key in its four-digit
product number now.
“Tutorial 7: Order an item from a
catalog (menu item 3)” on page 167
Quantity Please key in the quantity you require,
followed by the pound key.
“Tutorial 7: Order an item from a
catalog (menu item 3)” on page 167
YouOrdered You have ordered...
“Tutorial 7: Order an item from a
catalog (menu item 3)” on page 167
Items ...items of product number...
“Tutorial 7: Order an item from a
catalog (menu item 3)” on page 167
IsThisOK Is this OK?
“Tutorial 7: Order an item from a
catalog (menu item 3)” on page 167
ForYesPress1 For yes, press 1.
“Tutorial 7: Order an item from a
catalog (menu item 3)” on page 167
ForNoPress2 For no, press 2.
“Tutorial 7: Order an item from a
catalog (menu item 3)” on page 167
MailOrder We will mail your order to you
immediately.
Chapter 7. WebSphere Voice Response Java Tutorials 125
Tutorial
Voice Segment
Name Text
“Tutorial 8: Credit card validation
(menu item 3 continued)” on page
181
CardNumber Please key in a sixteen-digit credit card
number.
“Tutorial 8: Credit card validation
(menu item 3 continued)” on page
181
ExpiryDate Please key in the expiration date.
“Tutorial 8: Credit card validation
(menu item 3 continued)” on page
181
DateFormat The expiry date is four digits, month
month, year year.
“Tutorial 8: Credit card validation
(menu item 3 continued)” on page
181
InvalidCard Sorry, these credit card details are not
valid.
“Tutorial 8: Credit card validation
(menu item 3 continued)” on page
181
Sorry Sorry, we could not complete the
transaction.
“Tutorial 9: Order information (menu
item 3 continued)” on page 190
OrderCost Your order will cost...
“Tutorial 9: Order information (menu
item 3 continued)” on page 190
OrderDate ...and will be delivered on...
“Tutorial 9: Order information (menu
item 3 continued)” on page 190
OrderRef Please note your customer reference is...
“Tutorial 10: Transfer to an agent
(menu item 4)” on page 198
PleaseHold Please hold.
“Tutorial 10: Transfer to an agent
(menu item 4)” on page 198
CallerForYou We have a caller for you.
“Tutorial 10: Transfer to an agent
(menu item 4)” on page 198
AgentNotAvailable Sorry, all our agents are busy.
Tutorials
These tutorials will take you through the steps required to create a simple
voice application. Read each instruction and then try and create your own
code before checking it against the tutorials, or copy and paste the code for
convenience.
v “Tutorial 1: Caller calls an application” on page 128.
v “Tutorial 2: Select an item from a menu” on page 134.
v “Tutorial 3: Caller exits from the application (menu item 5)” on page 142.
126 Developing Java Applications
v “Tutorial 4: Leave a message (menu item 1)” on page 148.
v “Tutorial 5: Application makes a call” on page 154.
v “Tutorial 6: Key in a telephone number (menu item 2)” on page 158.
v “Tutorial 7: Order an item from a catalog (menu item 3)” on page 167.
v “Tutorial 8: Credit card validation (menu item 3 continued)” on page 181.
v “Tutorial 9: Order information (menu item 3 continued)” on page 190.
v “Tutorial 10: Transfer to an agent (menu item 4)” on page 198.
v “Tutorial 11: Using speech recognition and text-to-speech” on page 208.
Chapter 7. WebSphere Voice Response Java Tutorials 127
Tutorial 1: Caller calls an application
In this tutorial you will create an application that can receive an incoming call
and play voice segments to the caller. This application introduces the use of
the WVR and Call classes to receive an incoming call and then play
information to the caller.
Attention: Make sure you have read the following before you start the
tutorials:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122. 1. Follow the instructions in “Creating a new voice application in
WebSphere Studio Site Developer” on page 44 to create the initial InApp
application.
2. Add import statements at the top of the class, for the following external
classes that will be required by the application
2
:
v java.util.Locale
v com.ibm.telephony.beans.directtalk.ApplicationProperties
v com.ibm.telephony.beans.media.*
v com.ibm.telephony.wvr.*. If you created a class according to the
instructions in “Creating a new voice application in WebSphere Studio
Site Developer” on page 44, you will already have import statements
for com.ibm.telephony.wvr.WVRApplication and
com.ibm.telephony.wvr.WVRException. You will require more
com.ibm.telephony.wvr classes, so replace the previous two statements
with com.ibm.telephony.wvr.*. 3. After the class definition line, create a String to represent the category for
the tutorial voice segments. The category throughout the tutorials is
Tutorials
3
.
4. Create VoiceSegment objects to represent the following tutorial voice
segments
4
:
v Welcome
v Difficulties – you will need this voice segment later on in the tutorials
The constructor for the VoiceSegment object takes two String parameters
– the category, which you defined in step 3, and the name of the voice
segment, which must match that defined in the Java voice segment space.
See Chapter 5, “Managing your voice segments,” on page 113 for more
information about voice segments and the Java voice segment space.
128 Developing Java Applications
There are alternative constructor methods in which you can also specify a
locale and organization for the voice segment, however we will not be
using them in these tutorials.
Creating the voice segment objects as ’static’ means that one copy is
shared between all instances of the application within a JVM, reducing
the amount of storage required.
5. The voiceMain() method is the entry point for the application. It is
invoked by the run() method which you will use later. The voiceMain()
method for the tutorial application will control the basic flow of the calls.
Within the voiceMain() method, create a reference variable for a Call
object and assign to it a value of null
5
. The Call object will be used
throughout the application to represent the call itself. You have defined
the call reference variable as null since the call does not exist yet.
6. In order to receive or make a call the application must have a WVR
object to represent the base WebSphere Voice Response system. To create
the WVR object we first need to create an ApplicationProperties object
to store application-related information. Create the ApplicationProperties
object using the default constructor method, which takes no parameters.
Use the setApplicationName() method of the ApplicationProperties
object to set the application name to app1, and the setLocale() method to
set the locale to match NodeDefLocale in your default.cff file (if you are
using the simulator the default is en_US)
6
.
By default, the ApplicationProperties object will also have an IP address
of 127.0.0.1 (the local system), a node name of Node1 (the default for the
Voice Response simulator), and an RMI port number of 25924 (also the
default for the Voice Response simulator). If you are not using the Voice
Response simulator, you may need to change these default properties. If
you do not know what values to set, see “Prerequisites for the tutorials”
on page 121.
Note: You need to set the application properties as you will be running
the tutorial application unmanaged (that is, you will run it from an
IDE or from the Java command). If an application is run managed
(that is, within a Node managed by the Java and VoiceXML
environment; see “Managed and unmanaged applications” on page
46 for more information), the application properties will be set
automatically according to the entries in the configuration file,
default.cff. To access these properties within a managed
application, invoke the getApplicationProperties() method, which
will return an ApplicationProperties object containing the relevant
properties.
7. Now create a WVR object using the this keyword and the
ApplicationProperties object you created in step 6 as parameters
7
.
The WVR object represents the base WebSphere Voice Response system,
Chapter 7. WebSphere Voice Response Java Tutorials 129
and will be used by the application to receive the incoming call. The this
keyword tells the WVR object that the current application, InApp, is the
owner of the WVR object.
8. Use the setWaitTime() method of the WVR object to set the amount of
time, in seconds, the application will wait for a call
8
. Use a waitTime
of –1 to tell the application to wait indefinitely.
9. Create a try–catch block to catch any exceptions that might be thrown by
the application
9
. WVRException is the superclass for all WebSphere
Voice Response related exceptions.
10. Within the try block, invoke the waitForCall() method of the WVR object
and assign the result to the Call object you created earlier
10
. The
application will wait for the amount of time specified in step 8 for an
incoming call.
11. To greet the caller, invoke the play() method of the Call object, using the
Welcome prompt as the parameter
11
.
12. Use the returnCall() method of the Call object to return the call back to
the system
12
. The system will now hang up once the Welcome prompt
has been played.
13. In the catch block add a line to print out a stack trace for debugging
13
.
14. In the main() method, at the end of the class, create an instance of InApp
and invoke its run() method so that the application will run when you
start it from WebSphere Studio Site Developer
14
.
Note: If you run the application managed you will not need a main()
method and you will not need to invoke the run() method – this
will be done automatically by WebSphere Voice Response.
15. Save the application. Run the application according to the following
instructions:
v Make sure the Voice Response simulator is running.
v Switch to the Debug perspective in WebSphere Studio Site Developer
and select Run->Run...
v In the Launch Configurations window, select the application and click
New.
v On the JRE tab, click on the drop-down list and select the IBM
Runtime Environment you added in Chapter 3, “Using the WebSphere
Voice Response Java API classes,” on page 41.
v On the Arguments tab, enter the following in the VM arguments
section:
-Ddtj.home="websphere_studio_install_path\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_x.y.z"
130 Developing Java Applications
where websphere_studio_install_path is the location of WebSphere Studio
Site Developer, and x.y.z is the version number of the WebSphere Voice
Toolkit.
v Click Run to run the application. Once you have created the launch
configuration for this application, you can re-run it by making sure the
application is selected and then selecting Run->Run As->Java
Application.16. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
v Listen for the ″Welcome to our sample application″ announcement.
Make sure that the application disconnects.
v Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding
in “Tutorial 2: Select an item from a menu” on page 134.
If the Console window in WebSphere Studio Site Developer displays the
following message when you try to run an application:
com.ibm.telephony.wvr.WVRUnableToContactVrNodeException: Unable to contact the
WebSphere Voice Response node. Code 534
... check that the application properties have been set correctly. If the
application properties are all correct and the problem is still happening there
may be a TCP/IP set up problem. See “Setting up your TCP/IP network” on
page 42.
Chapter 7. WebSphere Voice Response Java Tutorials 131
Code for Tutorial 1
package tut;
2
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* InApp - a simple WVR application which lets the caller choose from a menu offering different functions
*/
public class InApp extends WVRApplication {
3
// Define the category for all the voice segments in this application.
private static final String CATEGORY = "Tutorials";
4
// Define a number of Voice Segment objects that are shared amongst all instances of this
// application within the JVM.
// Define the Welcome and Difficulties segments (tutorial 1)
private static final VoiceSegment VS_WELCOME = new VoiceSegment(CATEGORY, "Welcome");
private static final VoiceSegment VS_DIFFICULTIES = new VoiceSegment(CATEGORY, "Difficulties");
/**
* voiceMain() - this is the entry point for the application
*/
public void voiceMain() throws WVRException {
5
// Define the Call object reference variable
Call call = null;
6
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
7
// Create the WVR object and set the wait time
WVR wvr = new WVR(this, applicationProperties);
8
wvr.setWaitTime(-1);
9
try {
10
// Wait for a call
call = wvr.waitForCall();
11
// Play welcome message
call.play(VS_WELCOME);
12
// End call
call.returnCall();
}
catch (WVRException e) {
13
// Print debugging information
e.printStackTrace();
}//try
}//voiceMain()
public static void main(String[] args) {
132 Developing Java Applications
14 // Create an instance of the class and invoke the run method
InApp aInApp = new InApp();
aInApp.run();
}//main()
}//InApp
Chapter 7. WebSphere Voice Response Java Tutorials 133
Tutorial 2: Select an item from a menu
In “Tutorial 1: Caller calls an application” on page 128 you created a basic
voice application which just accepted an incoming call and played a Welcome
message to the caller. In this tutorial you will expand your application to
include a menu with five different choices. You will add functionality to each
menu choice in later tutorials. This tutorial introduces the use of attributes
objects to play a menu to the caller.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed Tutorial 1 as the code from that tutorial is
used as a base for this tutorial.
General overview of creating and playing a menu
Creating and playing a menu involves four steps, which will be covered in
more detail later on in this tutorial:
1. Create the properties required for the menu items. Each menu item
consists of a label which is used to reference it, a DTMF key, or keys,
which the caller can use to select it, a voice segment that the system will
play for the item, and a word, or words, that the caller can say to select it.
2. Create attribute objects (containers for attributes), using the menu item
properties from step 1, to tell the application how to play the information
and what to expect in reply.
3. Set any required attributes of the attribute objects, for example time-outs.
4. Play the menu, using the attribute objects from step 2.
Tutorial
1. The application menu will have five options:
v Message – allows the caller to leave a voice message
v Number – asks the caller to enter a six-digit telephone number
v Order – takes an order from the caller
v Operator – transfers the caller to an agent
v Hangup – allows the caller to end the call gracefully
Create String labels to represent each option in the menu. You will use
these later on to check what choice the caller made
1
.
134 Developing Java Applications
2. Create an array of Strings to store the menu item labels, and populate it
with the labels that you created in step 1
2
.
3. Create an array of Strings and populate it with Strings of digits to
represent the DTMF selector keys that the caller will use to select the
menu items
3
.
4. Create an array of MediaTypes and populate it with VoiceSegment
objects for each menu item.
4
. The system will play the segments in
the order in which they appear in the array.
MediaType is the superclass for all the audio classes, such as
VoiceSegment and AudioNumber, which you will use in “Tutorial 7:
Order an item from a catalog (menu item 3)” on page 167.
You do not need to create an array of selector words as you will not be
using speech recognition.
5. Create the following VoiceSegment objects for additional menu
messages, such as the header message and invalid key message
5
:
v Invalid Key
v Error
v OneMore
v MenuHeader
v MenuFooter
These additional messages are attributes of the menu which you will set
later.
6. You now need to create four attributes objects to tell the application how
to play your information to the caller and what to expect in reply
6
:
v PlayAttributes – this class specifies how the caller can interrupt the
prompt. Create this object using the default constructor, which takes no
parameters and specifies that the prompt is interruptible by DTMF, but
not interruptible by voice input.
v MenuAttributes – this class is an extension of InputAttributes.
InputAttributes is used to get caller information without using a
menu, by specifying various attributes such as messages, time-outs,
repeats and validator classes. MenuAttributes contains extra attributes
to do with menu items. Create the MenuAttributes object using the
voice segments, menu item labels and DTMF selector keys that you
defined for the menu in steps 2 through 4, plus a null value for the
selector words, as you will not be using speech recognition.
v DTMFAttributes – this class specifies the number DTMF keys the
caller can enter, and which keys they can press to terminate their
input. Create the DTMFAttributes object using the default constructor,
which takes no parameters. You will set the required parameters later.
Chapter 7. WebSphere Voice Response Java Tutorials 135
v RecoAttributes – this class contains attributes relating to speech
recognition . Create a RecoAttributes reference variable and assign to
it a value of null, so that the application will not attempt to use speech
recognition. The use of speech recognition will be covered in “Tutorial
11: Using speech recognition and text-to-speech” on page 208. 7. Create a boolean flag called keepTakingCalls which will be used later to
control the main application loop where calls are received
7
.
8. Write a constructor method for the InApp class. The constructor method
will set various attributes of the menu when an instance of the class is
created. Set the attributes according to the following table, using the
VoiceSegments you created in step 5
8
.
Attribute
object
Attribute Value Result
menuAtts HeaderMessage VS_MENU_HEADER The caller will hear ″What
would you like to do?″, before
the menu choices are listed
menuAtts FooterMessage VS_MENU_FOOTER The caller will hear ″Please press
the key corresponding to your
choice″, after the menu choices
are listed
menuAtts InvalidInputMessage VS_MENU_INVALID The caller will hear ″You pressed
an invalid key″ if they pressed a
key the application is not
expecting
menuAtts OneMoreRepeatMessage VS_MENU_ONEMORE The caller will hear ″You have
one more chance″, when they are
asked for input for the last time
menuAtts NoMoreRepeatsMessage VS_MENU_ERROR The caller will hear ″Sorry, you
have not selected a valid option,
so we are hanging up now″,
when they have given non-valid
input every time the menu was
repeated
menuAtts Timeout 10 The caller will have 10 seconds
to press a key
menuAtts NumberOfRepeats 2 The caller will have three
chances to press a valid key (in
other words, repeat the menu
twice after the first time if the
caller presses an non-valid key)
menuDTMFAtts MaximumKeys 1 The application will accept one
key press only.
136 Developing Java Applications
Attribute
object
Attribute Value Result
menuDTMFAtts DelimiterKeys ″″ (empty string) The caller does not need to use a
delimiter key as the application
is only expecting one key press
9. In the voiceMain() method, create a variable called callNumber to keep
track of the number of calls. Set the initial value of the variable to zero9
.
10. In the try block, create a while loop around the lines call.waitForCall(),
call.play() and call.returnCall(). Use the variable keepTakingCalls, which
you created in step 7, as the loop condition
10
.
11. Add a line immediately inside the while loop to increment the
callNumber variable, so that each call will have a unique number
11
.
12. Modify the waitForCall() statement to use the alternative
waitForCall(java.lang.String label) method, and use callNumber as the
parameter so that the unique call number is assigned to the call as a label12
. Labels allow the application to uniquely identify each call. You can
use labels to gather call statistics or to identify recordings of calls
received.
13. After the waitForCall() statement create a boolean variable called
callInProgress to indicate whether the call is in progress. Set the value of
callInProgressto true
13
.
14. Create another try block around the call.play() statement, to catch
exceptions that may occur while the call is in progress. Create three catch
blocks to go with the try block, the first to catch a
WVRHungUpException, the second to catch a
WVRInvalidInputException and the third to catch any other
WVRExceptions
14
.
15. In the try block, after the play() statement, create another while loop, this
time using callInProgress
15
. This loop will contain code to play the
menu to the caller and retrieve their input, for as long as the call is in
progress.
16. Use the playAndGetInput() method of the Call object, with the attributes
objects that you created for the menu earlier as parameters, to play the
menu to the caller. The playAndGetInput() method returns an
InputResult object. Invoke the getValue() method on the InputResult
object to extract the caller’s response
16
.
17. Don’t add any code to the first two catch blocks – these just catch the
exceptions thrown when the caller hangs up or repeatedly enters invalid
input. In the second catch block, add an if statement that invokes the
Chapter 7. WebSphere Voice Response Java Tutorials 137
isActive() method of the Call object to check that the call is still active. If
the call is still active use the play() method of the Call object to play the
Difficulties message, to tell the caller that some technical difficulties
were encountered. You need to check that the Call object is active
because because invoking the play() method on an inactive call throws an
exception. After the if block print out a stack trace as before
17
.
18. Create a finally block around the line call.returnCall(). This code will be
executed after any processing done by the try or catch blocks.
18
.
By using the finally block in this way we cover all eventualities – if the
while loop is exited, if the caller hangs up, or if an exception is thrown,
the call will be returned.
19. After the voiceMain() method, create a voiceAppStop() method, which
will override the voiceAppStop() method defined in the API. This
method is automatically invoked when the node is shut down, and is
used for cleaning up. In your voiceAppStop() method, set the
keepTakingCalls variable to false, so that the application will no longer
wait for a call
19
.
20. Save the application and run it.
21. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
v Listen for the text of the menu. Do you hear the header (″What would
you like to do?″) and all five choices, followed by the footer (″Please
press the key corresponding to your choice″)?
v None of the keys will do anything yet, but you could try one of keys 6
through 9, 0, # or *, to see what happens when you press an non-valid
key. You should try three non-valid keys to hear the messages,
InvalidKey, OneMore, and Error. Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding
in “Tutorial 3: Caller exits from the application (menu item 5)” on page
142.
138 Developing Java Applications
Code for Tutorial 2
package tut;
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* A simple WVR application
*/
public class InApp extends WVRApplication {
// Define the category for all the voice segments in this application.
private static final String CATEGORY = "Tutorials";
1
// Define the menu items
private static final String ITEM1_MSG = "Message";
private static final String ITEM2_NUMBER = "Number";
private static final String ITEM3_ORDER = "Order";
private static final String ITEM4_OPERATOR = "Operator";
private static final String ITEM5_HANGUP = "Hangup";
2
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_MSG, ITEM2_NUMBER, ITEM3_ORDER,
ITEM4_OPERATOR, ITEM5_HANGUP };
3
// Create an array to represent the keys that will be used to select the menu items
private static final String[] MENU_KEYS = { "1", "2", "3", "4", "5" };
// Create a number of Voice Segment objects that are shared amongst all instances of this
// application within the JVM.
// Create the Welcome and Difficulties segment objects
private static final VoiceSegment VS_WELCOME = new VoiceSegment(CATEGORY, "Welcome");
private static final VoiceSegment VS_DIFFICULTIES = new VoiceSegment(CATEGORY, "Difficulties");
4
// Create the segment objects for the menu choices, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "Message"),
new VoiceSegment(CATEGORY, "Number"),
new VoiceSegment(CATEGORY, "Order"),
new VoiceSegment(CATEGORY, "Operator"),
new VoiceSegment(CATEGORY, "Hangup")
};
5
// Create the segment objects required for the menu properties
private static final VoiceSegment VS_MENU_INVALID = new VoiceSegment(CATEGORY, "InvalidKey");
private static final VoiceSegment VS_MENU_ERROR = new VoiceSegment(CATEGORY, "Error");
private static final VoiceSegment VS_MENU_ONEMORE = new VoiceSegment(CATEGORY, "OneMore");
private static final VoiceSegment VS_MENU_HEADER = new VoiceSegment(CATEGORY, "MenuHeader");
private static final VoiceSegment VS_MENU_FOOTER = new VoiceSegment(CATEGORY, "MenuFooter");
6
// Create some attribute objects for the menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, null);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
Chapter 7. WebSphere Voice Response Java Tutorials 139
7 // Create a flag to control whether we continue to loop around in the voiceMain() method taking calls
private boolean keepTakingCalls = true;
8
// Create a constructor method to set up the attributes
public InApp() {
// Set the input attributes of the menu
menuAtts.setHeaderMessage(VS_MENU_HEADER);
menuAtts.setFooterMessage(VS_MENU_FOOTER);
menuAtts.setInvalidInputMessage(VS_MENU_INVALID);
menuAtts.setNoMoreRepeatsMessage(VS_MENU_ERROR);
menuAtts.setOneMoreRepeatMessage(VS_MENU_ONEMORE);
menuAtts.setTimeout(10);
menuAtts.setNumberOfRepeats(2);
// Set the DTMF attributes of the menu
menuDTMFAtts.setDelimiterKeys("");
menuDTMFAtts.setMaximumKeys(1);
}//InApp
/**
* @see com.ibm.telephony.wvr.WVRApplication#voiceMain()
*/
public void voiceMain() throws WVRException {
// Define the Call object
Call call = null;
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object and set the wait time
WVR wvr = new WVR(this, applicationProperties);
wvr.setWaitTime(-1);
9
// Create a variable that will be used to give each call a unique number
int callNumber = 0;
try {
10
while (keepTakingCalls) {
11
// Increment callNumber
callNumber++;
// Wait for a call
12
call = wvr.waitForCall("Call: " + callNumber);
13
// Create a flag to indicate whether the call is in progress
boolean callInProgress = true;
14
try {
// Play welcome message
call.play(VS_WELCOME);
15
while (callInProgress) {
140 Developing Java Applications
16 // Play the menu and get the caller’s response.
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String choice = input.getValue();
// Print out the caller’s choice.
System.out.println("Caller chose option" + choice);
}//while
}
catch (WVRHungUpException e) {
// Caller has hung up - ignore exception, program will go to finally block
}
catch (WVRInvalidInputException e) {
// Caller has entered invalid input - ignore exception, application will go to finally block
}
catch (WVRException e) {
17
// Check if Call object has been created. If yes, play the Difficulties message.
if (call.isActive()) call.play(VS_DIFFICULTIES);
// Print debugging information
e.printStackTrace();
}
finally {
18
// Return the call
call.returnCall();
}//try
}//while
}
catch (WVRException e) {
// Print debugging information
e.printStackTrace();
}//try
}//voiceMain()
19
// Tell the application to stop taking calls when the node shuts down
public void voiceAppStop() { keepTakingCalls = false; }
public static void main(String[] args) {
// Create an instance of the class and invoke the run method
InApp aInApp = new InApp();
aInApp.run();
}//main()
}//InApp
Chapter 7. WebSphere Voice Response Java Tutorials 141
Tutorial 3: Caller exits from the application (menu item 5)
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. In this tutorial you will add
functionality to the last menu item so that the caller can choose to end the
call.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed Tutorials 1 and 2 as the code from these
tutorials is used as a base for this tutorial.
1. In the section of code where you have been creating voice segments, create
a new VoiceSegment object for the ThankCalling segment which will be
played to the caller before the system ends the call
1
.
2. Inside the inner while loop, after the caller’s choice has been obtained,
add an if statement to determine what to do with the choice. In the if
statement, check to see if the caller chose the Hangup menu item (menu
item 5). If they did, invoke a hangUp() method, which you will write later,
and pass the call to it. Assign the result to the callInProgress variable. This
variable determines whether the call should continue. Add an else
statement around the line that prints out the caller’s choice, so that if the
caller presses another key the application will display it
2
.
3. Write the hangUp() method after the voiceMain() method
3
:
a. The method should take a Call object as a parameter, and return a
boolean. It should also throw a WVRException
a
.
b. Invoke the play() method of the Call object to play the ThankCalling
segment
b
.
c. Return false. This will indicate to the application that the call should
end
c
.4. Save and run the application.
5. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
v Listen for the text of the menu. While the menu is playing, press the 5
key on the telephone. Do you hear ″Thank you for calling″? Does the
application hang up?
142 Developing Java Applications
v Hang up.
v Dial the application again, to make sure that the application has
returned to waiting for a call.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding in
“Tutorial 4: Leave a message (menu item 1)” on page 148.
Chapter 7. WebSphere Voice Response Java Tutorials 143
Code for Tutorial 3
package tut;
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* A simple WVR application
*/
public class InApp extends WVRApplication {
// Define the category for all the voice segments in this application.
private static final String CATEGORY = "Tutorials";
// Define the menu items
private static final String ITEM1_MSG = "Message";
private static final String ITEM2_NUMBER = "Number";
private static final String ITEM3_ORDER = "Order";
private static final String ITEM4_OPERATOR = "Operator";
private static final String ITEM5_HANGUP = "Hangup";
// Create an array to store the menu choices
private static final String[] MENU_ITEMS = { ITEM1_MSG, ITEM2_NUMBER, ITEM3_ORDER,
ITEM4_OPERATOR, ITEM5_HANGUP };
// Create an array to represent the keys that will be used to select the menu items
private static final String[] MENU_KEYS = { "1", "2", "3", "4", "5" };
// Create a number of Voice Segment objects that are shared amongst all instances of this
// application within the JVM.
// Create the Welcome and Difficulties segment objects
private static final VoiceSegment VS_WELCOME = new VoiceSegment(CATEGORY, "Welcome");
private static final VoiceSegment VS_DIFFICULTIES = new VoiceSegment(CATEGORY, "Difficulties");
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "Message"),
new VoiceSegment(CATEGORY, "Number"),
new VoiceSegment(CATEGORY, "Order"),
new VoiceSegment(CATEGORY, "Operator"),
new VoiceSegment(CATEGORY, "Hangup")
};
// Create the segment objects required for the menu properties
private static final VoiceSegment VS_MENU_INVALID = new VoiceSegment(CATEGORY, "InvalidKey");
private static final VoiceSegment VS_MENU_ERROR = new VoiceSegment(CATEGORY, "Error");
private static final VoiceSegment VS_MENU_ONEMORE = new VoiceSegment(CATEGORY, "OneMore");
private static final VoiceSegment VS_MENU_HEADER = new VoiceSegment(CATEGORY, "MenuHeader");
private static final VoiceSegment VS_MENU_FOOTER = new VoiceSegment(CATEGORY, "MenuFooter");
144 Developing Java Applications
1 // Create the segment objects for the hangup menu item
private static final VoiceSegment VS_THANKCALLING = new VoiceSegment(CATEGORY, "ThankCalling");
// Create some attribute objects for the menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, null);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
// Create a flag to control whether we continue to loop around in the voiceMain() method taking calls
private boolean keepTakingCalls = true;
// Create a constructor method to set up the attributes
public InApp() {
// Set the input attributes of the menu
menuAtts.setHeaderMessage(VS_MENU_HEADER);
menuAtts.setFooterMessage(VS_MENU_FOOTER);
menuAtts.setInvalidInputMessage(VS_MENU_INVALID);
menuAtts.setNoMoreRepeatsMessage(VS_MENU_ERROR);
menuAtts.setOneMoreRepeatMessage(VS_MENU_ONEMORE);
menuAtts.setTimeout(10);
menuAtts.setNumberOfRepeats(2);
// Set the DTMF attributes of the menu
menuDTMFAtts.setDelimiterKeys("");
menuDTMFAtts.setMaximumKeys(1);
}//InApp
/**
* @see com.ibm.telephony.wvr.WVRApplication#voiceMain()
*/
public void voiceMain() throws WVRException {
// Define the Call object
Call call = null;
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object and set the wait time
WVR wvr = new WVR(this, applicationProperties);
wvr.setWaitTime(-1);
// Create a variable that will be used to give each call a unique number
int callNumber = 0;
try {
while (keepTakingCalls) {
// Increment callNumber
callNumber++;
// Wait for a call
call = wvr.waitForCall("Call: " + callNumber);
// Create a flag to indicate whether the call is in progress
boolean callInProgress = true;
Chapter 7. WebSphere Voice Response Java Tutorials 145
try {
// Play welcome message
call.play(VS_WELCOME);
while (callInProgress) {
// Play the menu and get the caller’s response.
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String choice = input.getValue();
2
// Check which menu option has been selected and take
// the appropriate action. Each action returns a boolean
// stating whether the call should continue or not
if (choice.equals(ITEM5_HANGUP)) {
callInProgress = hangUp(call);
}
else {
// Print out the caller’s choice.
System.out.println("Caller chose option " + choice);
}//if
}//while
}
catch (WVRHungUpException e) {
// Caller has hung up - ignore exception, program will go to finally block
}
catch (WVRInvalidInputException e) {
// Caller has entered invalid input - ignore exception, application will go to finally block
}
catch (WVRException e) {
// Check if Call object has been created. If yes, play the Difficulties message.
if (call.isActive()) call.play(VS_DIFFICULTIES);
// Print debugging information
e.printStackTrace();
}
finally {
// Return the call
call.returnCall();
}//try
}//while
}
catch (WVRException e) {
// Print debugging information
e.printStackTrace();
}//try
}//voiceMain()
3
/**
* Method hangUp.
* @param call
* @return boolean
*/
a
private boolean hangUp(Call call) throws WVRException {
b
// Thank the user for calling
call.play(VS_THANKCALLING);
146 Developing Java Applications
c return false;
}//hangUp()
// Tell the application to stop taking calls when the node shuts down
public void voiceAppStop() { keepTakingCalls = false; }
public static void main(String[] args) {
// Create an instance of the class and invoke the run method
InApp aInApp = new InApp();
aInApp.run();
}//main()
}//InApp
Chapter 7. WebSphere Voice Response Java Tutorials 147
Tutorial 4: Leave a message (menu item 1)
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. The only menu item that
had functionality was the last menu item – the Hangup option. In this tutorial
you will add functionality to the first menu item so that the caller can leave a
message. This tutorial introduces the use of the Call object to record voice
input.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed Tutorials 1 through 3 as the code from these
tutorials is used as a base for this tutorial.
1. In the section of code where you have been creating voice segments, create
four new VoiceSegment objects for this menu item
1
:
v Record
v PressKey
v Respond
v CallerMsg – this segment will be used to store the caller’s message. It is
created in the same way as the other segment objects.2. In the inner while loop of the application, change the if statement to an
else if statement, then add a new if statement before it. Make this new if
statement check to see if the caller chose the Message item (menu item 1),
and if so, call a new method called recordMessage()
2
.
3. Write the recordMessage() method after the voiceMain() method
3
:
a. The method should take a Call object as a parameter, and return a
boolean. It should also throw a WVRException
a
.
b. Use the play() method of the Call object to play the Record and
PressKey segments – these will give the caller instructions on how to
record their message
b
.
c. Use the record() method of the Call object to make the recording. This
method takes two parameters – the name of the VoiceSegment object
that you created in step 1 to store the message, and a duration. Use a
duration of 180 (the units are seconds) to give the caller plenty of time
to leave a message
c
. There is an alternative record() method which
148 Developing Java Applications
also allows you to specify that a beep should be played to the caller
before recording, and that the caller can stop the recording by pressing
any DTMF key.
d. Use the play() method of the Call object to play the Respond message
to let the caller know the message has been recorded
d
.
e. Make sure the method returns true, so that the call will continue
e
.4. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
v Listen for the text of the menu. While the menu is playing, press the 1
key on the telephone. Do you hear ″To record your message, start
speaking after the tone″? Do you hear a tone?
v If so, say something. (You’ll be able to test whether the message has
been recorded in “Tutorial 5: Application makes a call” on page 154,
when you’ll create another application that plays back the
CallerMessage.
v Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding in
“Tutorial 5: Application makes a call” on page 154.
Chapter 7. WebSphere Voice Response Java Tutorials 149
Code for Tutorial 4
package tut;
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* A simple WVR application
*/
public class InApp extends WVRApplication {
// Define the category for all the voice segments in this application.
private static final String CATEGORY = "Tutorials";
// Define the menu items
private static final String ITEM1_MSG = "Message";
private static final String ITEM2_NUMBER = "Number";
private static final String ITEM3_ORDER = "Order";
private static final String ITEM4_OPERATOR = "Operator";
private static final String ITEM5_HANGUP = "Hangup";
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_MSG, ITEM2_NUMBER, ITEM3_ORDER,
ITEM4_OPERATOR, ITEM5_HANGUP };
// Create an array to represent the keys that will be used to select the menu items
private static final String[] MENU_KEYS = { "1", "2", "3", "4", "5" };
// Create a number of Voice Segment objects that are shared amongst all instances of this
// application within the JVM.
// Create the Welcome and Difficulties segment objects
private static final VoiceSegment VS_WELCOME = new VoiceSegment(CATEGORY, "Welcome");
private static final VoiceSegment VS_DIFFICULTIES = new VoiceSegment(CATEGORY, "Difficulties");
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "Message"),
new VoiceSegment(CATEGORY, "Number"),
new VoiceSegment(CATEGORY, "Order"),
new VoiceSegment(CATEGORY, "Operator"),
new VoiceSegment(CATEGORY, "Hangup")
};
// Create the segment objects required for the menu properties
private static final VoiceSegment VS_MENU_INVALID = new VoiceSegment(CATEGORY, "InvalidKey");
private static final VoiceSegment VS_MENU_ERROR = new VoiceSegment(CATEGORY, "Error");
private static final VoiceSegment VS_MENU_ONEMORE = new VoiceSegment(CATEGORY, "OneMore");
private static final VoiceSegment VS_MENU_HEADER = new VoiceSegment(CATEGORY, "MenuHeader");
private static final VoiceSegment VS_MENU_FOOTER = new VoiceSegment(CATEGORY, "MenuFooter");
// Create the segment objects for the hangup menu item
private static final VoiceSegment VS_THANKCALLING = new VoiceSegment(CATEGORY, "ThankCalling");
150 Developing Java Applications
1 // Create the segment objects for the record a message menu item
private static final VoiceSegment VS_RECORD = new VoiceSegment(CATEGORY, "Record");
private static final VoiceSegment VS_PRESS_KEY = new VoiceSegment(CATEGORY, "PressKey");
private static final VoiceSegment VS_CALLER_MSG = new VoiceSegment(CATEGORY, "CallerMsg");
private static final VoiceSegment VS_RESPOND = new VoiceSegment(CATEGORY, "Respond");
// Create some attribute objects for the menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, null);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
// Create a flag to control whether we continue to loop around in the voiceMain() method taking calls
private boolean keepTakingCalls = true;
// Create a constructor method to set up the attributes
public InApp() {
// Set the input attributes of the menu
menuAtts.setHeaderMessage(VS_MENU_HEADER);
menuAtts.setFooterMessage(VS_MENU_FOOTER);
menuAtts.setInvalidInputMessage(VS_MENU_INVALID);
menuAtts.setNoMoreRepeatsMessage(VS_MENU_ERROR);
menuAtts.setOneMoreRepeatMessage(VS_MENU_ONEMORE);
menuAtts.setTimeout(10);
menuAtts.setNumberOfRepeats(2);
// Set the DTMF attributes of the menu
menuDTMFAtts.setDelimiterKeys("");
menuDTMFAtts.setMaximumKeys(1);
}//InApp
/**
* @see com.ibm.telephony.wvr.WVRApplication#voiceMain()
*/
public void voiceMain() throws WVRException {
// Define the Call object
Call call = null;
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object and set the wait time
WVR wvr = new WVR(this, applicationProperties);
wvr.setWaitTime(-1);
// Create a variable that will be used to give each call a unique number
int callNumber = 0;
try {
while (keepTakingCalls) {
// Increment callNumber
callNumber++;
// Wait for a call
call = wvr.waitForCall("Call: " + callNumber);
// Create a flag to indicate whether the call is in progress
boolean callInProgress = true;
Chapter 7. WebSphere Voice Response Java Tutorials 151
try {
// Play welcome message
call.play(VS_WELCOME);
while (callInProgress) {
// Play the menu and get the caller’s response.
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String choice = input.getValue();
// Check which menu option has been selected and take
// the appropriate action. Each action returns a boolean
// stating whether the call should continue or not
2
if (choice.equals(ITEM1_MSG)) {
callInProgress = recordMessage(call);
}
else if (choice.equals(ITEM5_HANGUP)) {
callInProgress = hangUp(call);
}
else {
// Print out the caller’s choice.
System.out.println("Caller chose option " + choice);
}//if
}//while
}
catch (WVRHungUpException e) {
// Caller has hung up - ignore exception, program will go to finally block
}
catch (WVRInvalidInputException e) {
// Caller has entered invalid input - ignore exception, application will go to finally block
}
catch (WVRException e) {
// Check if Call object has been created. If yes, play the Difficulties message.
if (call.isActive()) call.play(VS_DIFFICULTIES);
// Print debugging information
e.printStackTrace();
}
finally {
// Return the call
call.returnCall();
}//try
}//while
}
catch (WVRException e) {
// Check if Call object has been created. If yes, play the Difficulties message.
// Print debugging information
e.printStackTrace();
}//try
}//voiceMain()
3
/**
* Method recordMessage.
* @param call
* @return boolean
*/
a
private boolean recordMessage(Call call) throws WVRException {
152 Developing Java Applications
b // Play segments to instruct the caller on how to record their message
call.play(VS_RECORD);
call.play(VS_PRESS_KEY);
c
// Record the message
call.record(VS_CALLER_MSG, 180);
d
// Play a message to acknowledge the recording
call.play(VS_RESPOND);
e
return true;
}//recordMessage()
/**
* Method hangUp.
* @param call
* @return boolean
*/
private boolean hangUp(Call call) throws WVRException {
// Thank the user for calling
call.play(VS_THANKCALLING);
return false;
}//hangUp()
// Tell the application to stop taking calls when the node shuts down
public void voiceAppStop() { keepTakingCalls = false; }
public static void main(String[] args) {
// Create an instance of the class and invoke the run method
InApp aInApp = new InApp();
aInApp.run();
}//main()
}//InApp
Chapter 7. WebSphere Voice Response Java Tutorials 153
Tutorial 5: Application makes a call
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. You then wrote functionality
for two of the menu items, so that the caller could either hang up or leave a
message. In this tutorial you will create a new, simple application which will
make an outgoing call and play the message that you recorded in “Tutorial 4:
Leave a message (menu item 1)” on page 148. This will enable you to test that
the message you left earlier has been recorded correctly. This tutorial
introduces the use of the WVR object to make an outgoing call.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed Tutorials 1 through 4, and recorded a
message as part of the testing of the code for Tutorial 4.
1. Create a new class called OutApp, in the same package as InApp. Make
sure the class extends WVRApplication. For instructions on how to do
this see step 7 onwards of “Creating a new voice application in
WebSphere Studio Site Developer” on page 44.
2. Add import statements at the top of the class, for the following external
classes that will be required by the application
2
:
v java.util.Locale
v com.ibm.telephony.beans.directtalk.ApplicationProperties
v com.ibm.telephony.beans.media.*
v com.ibm.telephony.wvr.*
3. After the class definition line, create a String to represent the category for
the tutorial voice segments (″Tutorials″)
3
.
4. Create VoiceSegment objects for the FollowingMessage segment and the
caller’s message that was recorded in Tutorial 4
4
.
5. In the voiceMain() method, define a null reference variable for a Call
object
5
.
6. Create an ApplicationProperties object and set its application properties6
. See step 6 of “Tutorial 1: Caller calls an application” on page 128 for
instructions on setting application properties.
154 Developing Java Applications
Note: There is no need to create a NumToApp entry in the configuration
file, default.cff, for this application, because it does not wait for
a call.
7. Create a WVR object to handle the call
7
.
8. Use the setWaitTime() method of the WVR object to set the amount of
time, in seconds, the application will wait for a line to become available.
Set waitTime to –1 (wait for ever)
8
.
9. Create a try–catch block. In the try block, invoke the makeCall() method
of the WVR object. This takes one String parameter, the telephone
number to dial. If you are using the Voice Response simulator specify
5000 as the number to call
9
. If you want to give the call a label, use
the alternative makeCall() method which takes two String parameters,
the label and the telephone number.
10. Use the Call object to play an introductory voice segment (″The following
message has been left for you...″) followed by the voice segment that you
recorded in “Tutorial 4: Leave a message (menu item 1)” on page 148 10
.
11. Print out stack information in the catch block
11
.
12. Add a finally block after the catch block. In this block, use an if
statement to check that the call is not null. If the Call object satisfies this
condition, invoke the returnCall() method to end the call
12
.
13. Modify the main() method, at the end of the class, to create an instance
of the class and run the application, as you did in “Tutorial 1: Caller calls
an application” on page 128
13
.
14. Test the application:
v Run the application. As this is a new application you will need to add
a launch configuration for it, as described at the end of “Tutorial 1:
Caller calls an application” on page 128.
v When the phone rings, pick it up. Listen for the message ″The
following message has been left for you...″ followed by the message
you recorded when you ran the InApp class in “Tutorial 4: Leave a
message (menu item 1)” on page 148.
v After this, make sure that the application disconnects.
v Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding
in “Tutorial 6: Key in a telephone number (menu item 2)” on page 158.
Chapter 7. WebSphere Voice Response Java Tutorials 155
Code for Tutorial 5
package tut;
2
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* OutApp - makes an ougoing call and plays back a previously recorded message.
*/
public class OutApp extends WVRApplication {
3
// Define a category for the voice segment objects
private static final String CATEGORY = "Tutorials";
4
// Create the voice segment objects
private static final VoiceSegment VS_FOLLOWING_MESSAGE = new VoiceSegment(CATEGORY, "FollowingMessage");
private static final VoiceSegment VS_CALLER_MSG = new VoiceSegment(CATEGORY, "CallerMsg");
/**
* voiceMain() - this is the entry point for the application
*/
public void voiceMain() throws WVRException {
5
// Define the call object reference variable
Call call = null;
6
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
7
// Create the WVR object
WVR wvr = new WVR(this, applicationProperties);
8
wvr.setWaitTime(-1);
9
try {
// Make an outgoing call
call = wvr.makeCall("5000");
10
// Play an introduction, followed by the caller’s message that was recorded by InApp
call.play(VS_FOLLOWING_MESSAGE);
call.play(VS_CALLER_MSG);
}
11
catch (WVRException e) {
// Print debugging information
e.printStackTrace();
}
156 Developing Java Applications
12 finally {
// If the call exists, return it
if (call != null) call.returnCall();
} //try
}//voiceMain()
public static void main(String[] args) {
13
// Create an instance of the class and invoke the run method
OutApp aOutApp = new OutApp();
aOutApp.run();
}//main
}//OutApp
Chapter 7. WebSphere Voice Response Java Tutorials 157
Tutorial 6: Key in a telephone number (menu item 2)
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. In this tutorial you will add
functionality to the second menu item so that the caller can key in a six digit
telephone number that must begin with a 2. The tutorial introduces the use of
the Call object to get a sequence of DTMFs from the caller, and the use of the
InputValidator interface to validate the caller’s input.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed all the previous tutorials, apart from Tutorial
5 which involves a separate application, as the code from these tutorials is
used as a base for this tutorial.
1. Return to the InApp class.
2. In the section of code where you have been creating voice segments, create
the following VoiceSegment objects that will be required for this menu
item
2
:
v TelNo
v ThankYou
v OneMoreTime
v NoValidInput
v NumberInvalid
v NotEnough
v CallBack
3. We will do some validation on the telephone number that we will request
from the caller, using a class which implements the InputValidator
interface. If the telephone number does not begin with a 2, we will deem it
non-valid. After the voice segments, create an instance of a class which
implements the InputValidator interface. This InputValidator object will
be used as an attribute when we get the caller’s number later on. As our
InputValidator is very simple, we will define it as an inline class.
Classes which implement the InputValidator interface must implement the
interface’s validate() method. The validate() method takes an InputResult
object containing the unvalidated input and returns either a String
representing the validated input, or null if the input is not valid. Within
158 Developing Java Applications
the validate() method, add lines to extract the value from the InputResult
object, determine if it begins with a 2, and return it if it does, otherwise
return null
3
.
4. In earlier tutorials we asked the caller for input using a menu. Now we
want to ask the caller for input using an ’input field’; this will obtain one
piece of information rather than asking the caller to make a choice. To do
this create four more attributes objects after the attributes objects you
created earlier for the menu. The only difference between the two sets of
objects is that for an input field you need to create an InputAttributes
object rather than a MenuAttributes object. The MenuAttributes class is a
subclass of InputAttributes, containing extra menu-specific fields and
methods that do not apply to input fields
4
.
5. In the constructor method, set the attributes for the input field as follows5
:
Attribute
object
Attribute Value Result
telNoInputAtts Message VS_TEL_NO The caller will hear ″Please
key in the telephone
number″ then the
application waits for input
telNoInputAtts InvalidInputMessage VS_NUMBER_INVALID The caller will hear ″That is
not a valid number″ when
they enter a number that the
InputValidator determines to
be non-valid
telNoInputAtts OneMoreRepeatMessage VS_ONE_MORE_TIME The caller will hear ″You
have one more chance to key
in a six-digit number″, when
they are asked for input for
the last time
telNoInputAtts NoMoreRepeatsMessage VS_NO_VALID_INPUT The caller will hear ″You
have not entered a valid
number″, when they have
given non-valid input every
time the input field was
repeated
telNoInputAtts Timeout 10 The caller will have 10
seconds to press a key
Chapter 7. WebSphere Voice Response Java Tutorials 159
Attribute
object
Attribute Value Result
telNoInputAtts NumberOfRepeats 2 The caller will have three
chances to enter the full six
digits (in other words, repeat
the input field twice after
the first time if the caller
presses an non-valid key)
telNoInputAtts Validator PHONE_NUM_CHECKER The input will be checked by
the InputValidator to see if it
begins with a 2
telNoDTMFAtts MaximumKeys 6 The application will only
accept a sequence of 6 key
presses
telNoDTMFAtts DelimiterKeys ″″ (empty string) The caller does not need to
use a delimiter key as the
application is expecting 6
digits
6. Within the inner while loop, add another if–else statement to check to see
if the caller chose the Telephone Number item (menu item 2). If they did,
invoke a new method called leavePhoneNumber()
6
.
7. Write the new leavePhoneNumber() method after the recordMessage()
method
7
:
a. The method should take a Call object as a parameter, and return a
boolean. It should also throw a WVRException
a
.
b. Create a try–catch block to catch any WVRInvalidInputExceptions
b
. A WVRInvalidInputException is thrown when the caller has repeatedly entered non-valid input, exceeding the number of attempts
specified in the NumberOfRepeats property of the InputAttributes
object.
c. In the try block, use the playAndGetInput() method of the Call object,
with the attribute objects you created in step 4, to get a string of digits
from the caller
c
. The InputValidator that you set as an attribute of
the InputAttributes object will check the input to see if it begins with a
2.
d. In the catch block, return a value of true to indicate to the application
that the call should continue
d
. The caller will now be returned to
the menu if they haven’t entered a valid number after three tries.
Note: In a real application you would deal with non-valid input
exceptions every time the caller was asked for input.
160 Developing Java Applications
e. After the catch block, at the end of the method, play the ThankYou
message followed by the CallBack message, to acknowledge that a
valid telephone number has been received
e
.8. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
v Listen for the text of the menu. While the menu is playing, press the 2
key on the telephone. Do you hear ″Please key in the telephone
number″?
v If so, key in a telephone number beginning with 2. Do you hear ″Thank
you. We will call you back″?
v Hang up.
v Repeat, this time keying in a number beginning with a digit other than
2. Do you hear ″That is not a valid number?″
v Repeat, this time keying fewer than six digits. Do you hear ″You did not
key enough digits″?
v Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding in
“Tutorial 7: Order an item from a catalog (menu item 3)” on page 167.
Chapter 7. WebSphere Voice Response Java Tutorials 161
Code for Tutorial 6
package tut;
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* A simple WVR application
*/
public class InApp extends WVRApplication {
// Define the category for all the voice segments in this application.
private static final String CATEGORY = "Tutorials";
// Define the menu items
private static final String ITEM1_MSG = "Message";
private static final String ITEM2_NUMBER = "Number";
private static final String ITEM3_ORDER = "Order";
private static final String ITEM4_OPERATOR = "Operator";
private static final String ITEM5_HANGUP = "Hangup";
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_MSG, ITEM2_NUMBER, ITEM3_ORDER,
ITEM4_OPERATOR, ITEM5_HANGUP };
// Create an array to represent the keys that will be used to select the menu items
private static final String[] MENU_KEYS = { "1", "2", "3", "4", "5" };
// Create a number of Voice Segment objects that are shared amongst all instances of this
// application within the JVM.
// Create the Welcome and Difficulties segment objects
private static final VoiceSegment VS_WELCOME = new VoiceSegment(CATEGORY, "Welcome");
private static final VoiceSegment VS_DIFFICULTIES = new VoiceSegment(CATEGORY, "Difficulties");
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "Message"),
new VoiceSegment(CATEGORY, "Number"),
new VoiceSegment(CATEGORY, "Order"),
new VoiceSegment(CATEGORY, "Operator"),
new VoiceSegment(CATEGORY, "Hangup")
};
// Create the segment objects required for the menu properties
private static final VoiceSegment VS_MENU_INVALID = new VoiceSegment(CATEGORY, "InvalidKey");
private static final VoiceSegment VS_MENU_ERROR = new VoiceSegment(CATEGORY, "Error");
private static final VoiceSegment VS_MENU_ONEMORE = new VoiceSegment(CATEGORY, "OneMore");
private static final VoiceSegment VS_MENU_HEADER = new VoiceSegment(CATEGORY, "MenuHeader");
private static final VoiceSegment VS_MENU_FOOTER = new VoiceSegment(CATEGORY, "MenuFooter");
// Create the segment objects for the hangup menu item
private static final VoiceSegment VS_THANKCALLING = new VoiceSegment(CATEGORY, "ThankCalling");
// Create the segment objects for the record a message menu item
private static final VoiceSegment VS_RECORD = new VoiceSegment(CATEGORY, "Record");
private static final VoiceSegment VS_PRESS_KEY = new VoiceSegment(CATEGORY, "PressKey");
private static final VoiceSegment VS_CALLER_MSG = new VoiceSegment(CATEGORY, "CallerMsg");
private static final VoiceSegment VS_RESPOND = new VoiceSegment(CATEGORY, "Respond");
162 Developing Java Applications
2 // Create the segment objects for the key in a telephone number menu item
private static final VoiceSegment VS_TEL_NO = new VoiceSegment(CATEGORY, "TelNo");
private static final VoiceSegment VS_THANK_YOU = new VoiceSegment(CATEGORY, "ThankYou");
private static final VoiceSegment VS_ONE_MORE_TIME = new VoiceSegment(CATEGORY, "OneMoreTime");
private static final VoiceSegment VS_NO_VALID_INPUT = new VoiceSegment(CATEGORY, "NoValidInput");
private static final VoiceSegment VS_NUMBER_INVALID = new VoiceSegment(CATEGORY, "NumberInvalid");
private static final VoiceSegment VS_NOT_ENOUGH = new VoiceSegment(CATEGORY, "NotEnough");
private static final VoiceSegment VS_CALL_BACK = new VoiceSegment(CATEGORY, "CallBack");
3
// Create an InputValidator to validate the caller’s telephone number
private static final InputValidator PHONE_NUM_CHECKER = new InputValidator() {
public String validate(InputResult result) {
String value = result.getValue();
if (value.substring(0, 1).equals("2")) return value;
return null;
}
};
// Create some attribute objects for the menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, null);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
4
// Create some attribute objects for getting the caller’s telephone number
private PlayAttributes telNoPlayAtts = new PlayAttributes();
private InputAttributes telNoInputAtts = new InputAttributes();
private DTMFAttributes telNoDTMFAtts = new DTMFAttributes();
private RecoAttributes telNoRecoAtts = null;
// Create a flag to control whether we continue to loop around in the voiceMain() method taking calls
private boolean keepTakingCalls = true;
// Create a constructor method to set up the attributes
public InApp() {
// Set the input attributes of the menu
menuAtts.setHeaderMessage(VS_MENU_HEADER);
menuAtts.setFooterMessage(VS_MENU_FOOTER);
menuAtts.setInvalidInputMessage(VS_MENU_INVALID);
menuAtts.setOneMoreRepeatMessage(VS_MENU_ONEMORE);
menuAtts.setNoMoreRepeatsMessage(VS_MENU_ERROR);
menuAtts.setTimeout(10);
menuAtts.setNumberOfRepeats(2);
// Set the DTMF attributes of the menu
menuDTMFAtts.setDelimiterKeys("");
menuDTMFAtts.setMaximumKeys(1);
Chapter 7. WebSphere Voice Response Java Tutorials 163
5 // Set the input attributes for getting the telephone number
telNoInputAtts.setMessage(VS_TEL_NO);
telNoInputAtts.setTimeoutMessage(VS_NOT_ENOUGH);
telNoInputAtts.setInvalidInputMessage(VS_NUMBER_INVALID);
telNoInputAtts.setOneMoreRepeatMessage(VS_ONE_MORE_TIME);
telNoInputAtts.setNoMoreRepeatsMessage(VS_NO_VALID_INPUT);
telNoInputAtts.setTimeout(10);
telNoInputAtts.setNumberOfRepeats(2);
telNoInputAtts.setValidator(PHONE_NUM_CHECKER);
// Set the DTMF attributes for getting the telephone number
telNoDTMFAtts.setDelimiterKeys("");
telNoDTMFAtts.setMaximumKeys(6);
}//InApp
/**
* @see com.ibm.telephony.wvr.WVRApplication#voiceMain()
*/
public void voiceMain() throws WVRException {
// Define the Call object
Call call = null;
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object and set the wait time
WVR wvr = new WVR(this, applicationProperties);
wvr.setWaitTime(-1);
// Create a variable which will be used to give each call a unique number
int callNumber = 0;
try {
while (keepTakingCalls) {
// Increment callNumber
callNumber++;
// Wait for a call
call = wvr.waitForCall("Call: " + callNumber);
// Create a flag to indicate whether the call is in progress
boolean callInProgress = true;
try {
// Play welcome message
call.play(VS_WELCOME);
while (callInProgress) {
// Play the menu and get the caller’s response.
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String choice = input.getValue();
// Check which menu option has been selected and take
// the appropriate action. Each action returns a boolean
// stating whether the call should continue or not
if (choice.equals(ITEM1_MSG)) {
// Menu item 1 - record a message
callInProgress = recordMessage(call);
}
164 Developing Java Applications
6 else if (choice.equals(ITEM2_NUMBER)) {
// Menu item 2 - leave a telephone number
callInProgress = leavePhoneNumber(call);
}
else if (choice.equals(ITEM5_HANGUP)) {
// Menu item 5 - hang up
callInProgress = hangUp(call);
}
else {
// Print out the caller’s choice.
System.out.println("Caller chose option " + choice);
}//if
}//while
}
catch (WVRHungUpException e) {
// Caller has hung up - ignore exception, program will go to finally block
}
catch (WVRInvalidInputException e) {
// Caller has entered invalid input - ignore exception, application will go to finally block
}
catch (WVRException e) {
// Check if Call object has been created. If yes, play the Difficulties message.
if (call.isActive()) call.play(VS_DIFFICULTIES);
// Print debugging information
e.printStackTrace();
}
finally {
// Return the call
call.returnCall();
}//try
}//while
}
catch (WVRException e) {
// Print debugging information
e.printStackTrace();
}//try
}//voiceMain()
/**
* Method recordMessage.
* @param call
* @return boolean
*/
private boolean recordMessage(Call call) throws WVRException {
// Play segments to instruct the caller on how to record their message
call.play(VS_RECORD);
call.play(VS_PRESS_KEY);
// Record the message
call.record(VS_CALLER_MSG, 180);
// Play a message to acknowledge the recording
call.play(VS_RESPOND);
return true;
}//recordMessage()
Chapter 7. WebSphere Voice Response Java Tutorials 165
7 /**
* Method leavePhoneNumber.
* @param call
* @return boolean
*/
a
private boolean leavePhoneNumber(Call call) throws WVRException {
b
try {
c
// Get the caller’s input - the Input Validator class created earlier will check to make sure the
// number begins with a 2
InputResult result = call.playAndGetInput(telNoPlayAtts, telNoInputAtts, telNoDTMFAtts, telNoRecoAtts);
}
catch (WVRInvalidInputException e) {
d
return true;
}//try
e
// Play the ThankYou message to acknowledge a valid number
call.play(VS_THANK_YOU);
call.play(VS_CALL_BACK);
return true;
}//leavePhoneNumber()
/**
* Method hangUp.
* @param call
* @return boolean
*/
private boolean hangUp(Call call) throws WVRException {
// Thank the user for calling
call.play(VS_THANKCALLING);
return false;
}//hangUp()
// Tell the application to stop taking calls when the node shuts down
public void voiceAppStop() { keepTakingCalls = false; }
public static void main(String[] args) {
// Create an instance of the class and invoke the run method
InApp aInApp = new InApp();
aInApp.run();
}//main()
}//InApp
166 Developing Java Applications
Tutorial 7: Order an item from a catalog (menu item 3)
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. In this tutorial you will add
functionality to the third menu item so that the caller can order an item from
a catalog. The tutorial introduces the technique of creating separate classes
and using them in the main application. This makes your main application
less cluttered and allows easy reuse of functionality. The tutorial also
introduces the AudioNumber class and the use of arrays to play media
sequences.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed all the previous tutorials, apart from Tutorial
5 which involves a separate application, as the code from these tutorials is
used as a base for this tutorial.
1. Create a new class called Catalog, in the same package as InApp. Accept
java.lang.Object as the superclass. Do not check the public static void
main(String[] args) check box. This new class will do the work of getting
the order information from the caller.
2. Add import statements at the top of the class, for the following external
classes that will be required by the Catalog class
2
:
v com.ibm.telephony.beans.media.*
v com.ibm.telephony.wvr.*
3. In the Catalog class, create a String to represent the category for the
voice segments you will use later (″Tutorials″)
3
.
4. Create String labels to represent two menu options, Yes and No, and
store them in an array
4
.
5. Create an array of Strings to represent the DTMF selector keys that will
be used to select each menu item
5
.
6. Create an array of MediaTypes and populate it with the following
VoiceSegment objects that will be played in turn for the menu items
6
:
v ForYesPress1
v ForNoPress2
7. Create the following VoiceSegment objects
7
:
Chapter 7. WebSphere Voice Response Java Tutorials 167
Segments for getting the caller’s order:
v ProductNumber
v Quantity
Segments for playing the caller’s order back to them:
v YouOrdered
v Items
Segments for asking the caller to confirm the order:
v IsThisOK
Segments for confirming to the caller that their order has gone through:
v MailOrder
8. Create two AudioNumber objects to represent the quantity and item
number of the items in the caller’s order
8
. Use the default constructor,
which takes no parameters.
9. Create an array of MediaTypes and populate it with the YouOrdered
voice segment, followed by the quantity AudioNumber object, the Items
voice segment and the product number AudioNumber object
9
. The
array will be played as a media sequence that represents the caller’s
order. The caller will hear ″You have ordered ... <quantity> ... items of
product number ... <product number>″.
10. Create three sets of attribute objects
10
:
v A set including InputAttributes, for the input field that will get the
product number from the caller.
v A set including InputAttributes, for the input field that will get the
quantity from the caller.
v A set including MenuAttributes, for the menu, which asks the caller to
confirm their order.
11. Create a constructor method to set up various attributes
11
.
12. In the constructor method, set the style of the product number
AudioNumber object to Digits (note that the style String is case
sensitive)
12
. This will ensure that the number will be read out as a
string of separate digits, rather than words. For example, ″1234″ will be
read out as ″one two three four″ rather than ″one thousand two-hundred
and thirty four″.
13. Still in the constructor method, set up the attributes of the attribute
objects as follows
13
:
168 Developing Java Applications
Attribute object Attribute Value Result
prodNumInputAtts Message VS_PRODUCT_NUMBER The caller will hear ″To order a
product, key in its four-digit
product number now″ then the
application waits for input
prodNumInputAtts Timeout 10 The caller will have 10 seconds to
enter the number
prodNumDTMFAtts MaximumKeys 4 The application will only accept a
sequence of 4 key presses
prodNumDTMFAtts DelimiterKeys ″″ (empty string) The caller does not need to use a
delimiter key as the application is
expecting 4 digits
quantityInputAtts Message VS_QUANTITY The caller will hear ″Please key in
the quantity you require,
followed by the pound key″ then
the application waits for input
quantityInputAtts Timeout 10 The caller will have 10 seconds to
enter the quantity
menuAtts HeaderMessage VS_IS_THIS_OK The caller will hear ″Is this OK?″,
before the menu choices are listed
menuAtts Timeout 10 The caller will have 10 seconds to
enter their choice
menuDTMFAtts MaximumKeys 1 The application will only accept 1
key press
menuDTMFAtts DelimiterKeys ″″ (empty string) The caller does not need to use a
delimiter key as the application is
expecting 1 digit
14. After the constructor method create a void method called takeOrder().
The method should take a Call object as a parameter, and throw a
WVRException
14
. This method will take the call from the main
application (InApp) and then get the caller’s input.
15. Inside the takeOrder() method, create two double variables to store the
product number and quantity of the caller’s order
15
.
16. Create an infinite while loop. Inside the loop, use the playAndGetInput()
method of the Call object, with the attribute objects you created for the
product number input field in step 10, to get the product number from
the caller. Extract the product number String from the InputResult object
using the getValue() method and then convert it into a double. Store the
product number in the product number variable you created in step 15.
Assign the product number to the corresponding AudioNumber object
using the setValue() method
16
.
Chapter 7. WebSphere Voice Response Java Tutorials 169
17. Repeat step 16 (excluding the creation of the loop) for the quantity
17
.
18. Use the play() method of the Call object to play the caller’s order back to
them, using the media sequence you created in step 9
18
.
19. Use the playAndGetInput() method of the Call object, with the attribute
objects you created for the menu in step 10, to confirm the order with the
caller
19
.
20. Add a line to break out of the while loop if the caller confirms their
order
20
. If the caller does not confirm, the application will loop round,
asking the caller again for their order details.
21. After the while loop, play a message to the caller to acknowledge receipt
of their order
21
.
22. Now that you have created the Catalog class, you need to create an
instance of it in the main application. Back in the InApp class, after the
creation of the keepTakingCalls flag, create an instance of the Catalog
class
22
.
23. In the inner loop of the voiceMain() method, add another if–else
statement to check to see if the caller chose the Order item (menu item 3).
If they did, invoke a new method called order()
23
.
24. Write the order() method after the leavePhoneNumber() method
24
:
a. The method should take a Call object as a parameter, and return a
boolean. It should also throw a WVRException
a
.
b. Invoke the takeOrder() method of the Catalog class, using the
instance that you created in step 22, and passing the current Call
object
b
.
c. Return a value of true to the voiceMain() method, indicating that the
call should continue
c
.25. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
v Listen for the text of the menu. While the menu is playing, press the 3
key on the telephone. Do you hear ″To order a product, key in its
four-digit product number now″?
v If so, key in a four-digit number.
v After that you should hear ″Please key in the quantity you require,
followed by the pound key″.
v Key in any number of digits, followed by the pound key.
170 Developing Java Applications
v You should then hear ″You have ordered ...<quantity> ... items of
product number ... <product number>. Is this OK?″ Are the <quantity>
and <product number> values correct?
v Try pressing the 2 key (for ″no″). Do you hear the fields again?
v Try pressing the 1 key (for ″yes″). Do you hear ″We will mail your
order to you immediately″?
v Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding
in “Tutorial 8: Credit card validation (menu item 3 continued)” on page
181.When you have tested that the code works, stop the application
before proceeding to :
Chapter 7. WebSphere Voice Response Java Tutorials 171
Code for Tutorial 7 Catalog class
package tut;
2
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
* Subcomponent that allows the caller to order an item from a catalog
*/
class Catalog {
3
//Define the category for all the voice segments in this class.
private static final String CATEGORY = "Tutorials";
4
// Define the menu items
private static final String ITEM1_YES = "Yes";
private static final String ITEM2_NO = "No";
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_YES, ITEM2_NO };
5
// Define the keys used to make the menu selections, and store them in an array
private static final String[] MENU_KEYS = { "1", "2" };
// Create a number of Voice Segment objects
6
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "ForYesPress1"),
new VoiceSegment(CATEGORY, "ForNoPress2")
};
7
// Create the segment objects for taking the order
private static final VoiceSegment VS_PRODUCT_NUMBER = new VoiceSegment(CATEGORY, "ProductNumber");
private static final VoiceSegment VS_QUANTITY = new VoiceSegment(CATEGORY, "Quantity");
private static final VoiceSegment VS_YOU_ORDERED = new VoiceSegment(CATEGORY, "YouOrdered");
private static final VoiceSegment VS_ITEMS = new VoiceSegment(CATEGORY, "Items");
// Create the segment object for the verifying the order menu
private static final VoiceSegment VS_IS_THIS_OK = new VoiceSegment(CATEGORY, "IsThisOK");
// Create the segment object for the result
private static final VoiceSegment VS_MAIL_ORDER = new VoiceSegment(CATEGORY, "MailOrder");
8
// Create AudioNumber objects to play the caller’s order back to them
private AudioNumber prodNumValue = new AudioNumber();
private AudioNumber quantityValue = new AudioNumber();
9
// Create a media sequence of the caller’s order
private MediaType[] order = { VS_YOU_ORDERED, quantityValue, VS_ITEMS, prodNumValue };
172 Developing Java Applications
10 // Create some attribute objects for getting the product number from the caller
private PlayAttributes prodNumPlayAtts = new PlayAttributes();
private InputAttributes prodNumInputAtts = new InputAttributes();
private DTMFAttributes prodNumDTMFAtts = new DTMFAttributes();
private RecoAttributes prodNumRecoAtts = null;
// Create some attribute objects for getting the quantity from the caller
private PlayAttributes quantityPlayAtts = new PlayAttributes();
private InputAttributes quantityInputAtts = new InputAttributes();
private DTMFAttributes quantityDTMFAtts = new DTMFAttributes();
private RecoAttributes quantityRecoAtts = null;
// Create some attribute objects for the verify order menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, null);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
11
// Create a constructor method to set up various attributes
public Catalog() {
12
// Set the style of the product number AudioNumber object to digits
prodNumValue.setStyle("Digits");
13
// Set the attributes for getting the product number
prodNumInputAtts.setMessage(VS_PRODUCT_NUMBER);
prodNumInputAtts.setTimeout(10);
prodNumDTMFAtts.setMaximumKeys(4);
prodNumDTMFAtts.setDelimiterKeys("");
// Set the attributes for getting the quantity
quantityInputAtts.setMessage(VS_QUANTITY);
quantityInputAtts.setTimeout(10);
// Set the attributes for the verify order menu
menuAtts.setHeaderMessage(VS_IS_THIS_OK);
menuAtts.setTimeout(10);
menuDTMFAtts.setMaximumKeys(1);
menuDTMFAtts.setDelimiterKeys("");
}//Catalog()
14
public void takeOrder(Call call) throws WVRException {
15
// Create variables to store the product number and quantity of the order.
double prodNum = 0;
double quantity = 0;
16
while (true) {
// Get the product number from the caller
InputResult prodNumResult = call.playAndGetInput(prodNumPlayAtts, prodNumInputAtts,
prodNumDTMFAtts, prodNumRecoAtts);
prodNum = Double.parseDouble(prodNumResult.getValue());
prodNumValue.setValue(prodNum);
17
// Get the quantity from the caller
InputResult quantityResult = call.playAndGetInput(quantityPlayAtts, quantityInputAtts,
quantityDTMFAtts, quantityRecoAtts);
quantity = Double.parseDouble(quantityResult.getValue());
quantityValue.setValue(quantity);
18
// Play the order back to the caller
call.play(order);
Chapter 7. WebSphere Voice Response Java Tutorials 173
19 // Verifies with the caller that the choice is correct, if yes, breaks out of loop
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
20
String answer = input.getValue();
if (answer.equals(ITEM1_YES)) break;
}//while
21
// Confirm to the caller that their order has gone through
call.play(VS_MAIL_ORDER);
}//takeOrder()
}
174 Developing Java Applications
Code for Tutorial 7 InApp class
package tut;
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* A simple WVR application
*/
public class InApp extends WVRApplication {
// Define the category for all the voice segments in this application.
private static final String CATEGORY = "Tutorials";
// Define the menu items
private static final String ITEM1_MSG = "Message";
private static final String ITEM2_NUMBER = "Number";
private static final String ITEM3_ORDER = "Order";
private static final String ITEM4_OPERATOR = "Operator";
private static final String ITEM5_HANGUP = "Hangup";
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_MSG, ITEM2_NUMBER, ITEM3_ORDER,
ITEM4_OPERATOR, ITEM5_HANGUP };
// Create an array to represent the keys that will be used to select the menu items
private static final String[] MENU_KEYS = { "1", "2", "3", "4", "5" };
// Create a number of Voice Segment objects that are shared amongst all instances of this
// application within the JVM.
// Create the Welcome and Difficulties segment objects
private static final VoiceSegment VS_WELCOME = new VoiceSegment(CATEGORY, "Welcome");
private static final VoiceSegment VS_DIFFICULTIES = new VoiceSegment(CATEGORY, "Difficulties");
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "Message"),
new VoiceSegment(CATEGORY, "Number"),
new VoiceSegment(CATEGORY, "Order"),
new VoiceSegment(CATEGORY, "Operator"),
new VoiceSegment(CATEGORY, "Hangup")
};
// Create the segment objects required for the menu properties
private static final VoiceSegment VS_MENU_INVALID = new VoiceSegment(CATEGORY, "InvalidKey");
private static final VoiceSegment VS_MENU_ERROR = new VoiceSegment(CATEGORY, "Error");
private static final VoiceSegment VS_MENU_ONEMORE = new VoiceSegment(CATEGORY, "OneMore");
private static final VoiceSegment VS_MENU_HEADER = new VoiceSegment(CATEGORY, "MenuHeader");
private static final VoiceSegment VS_MENU_FOOTER = new VoiceSegment(CATEGORY, "MenuFooter");
// Create the segment objects for the hangup menu item
private static final VoiceSegment VS_THANKCALLING = new VoiceSegment(CATEGORY, "ThankCalling");
// Create the segment objects for the record a message menu item
private static final VoiceSegment VS_RECORD = new VoiceSegment(CATEGORY, "Record");
private static final VoiceSegment VS_PRESS_KEY = new VoiceSegment(CATEGORY, "PressKey");
private static final VoiceSegment VS_CALLER_MSG = new VoiceSegment(CATEGORY, "CallerMsg");
private static final VoiceSegment VS_RESPOND = new VoiceSegment(CATEGORY, "Respond");
Chapter 7. WebSphere Voice Response Java Tutorials 175
// Create the segment objects for the key in a telephone number menu item
private static final VoiceSegment VS_TEL_NO = new VoiceSegment(CATEGORY, "TelNo");
private static final VoiceSegment VS_THANK_YOU = new VoiceSegment(CATEGORY, "ThankYou");
private static final VoiceSegment VS_ONE_MORE_TIME = new VoiceSegment(CATEGORY, "OneMoreTime");
private static final VoiceSegment VS_NO_VALID_INPUT = new VoiceSegment(CATEGORY, "NoValidInput");
private static final VoiceSegment VS_NUMBER_INVALID = new VoiceSegment(CATEGORY, "NumberInvalid");
private static final VoiceSegment VS_NOT_ENOUGH = new VoiceSegment(CATEGORY, "NotEnough");
private static final VoiceSegment VS_CALL_BACK = new VoiceSegment(CATEGORY, "CallBack");
// Create an InputValidator to validate the caller’s telephone number
private static final InputValidator PHONE_NUM_CHECKER = new InputValidator() {
public String validate(InputResult result) {
String value = result.getValue();
if (value.substring(0, 1).equals("2")) return value;
return null;
}
};
// Create some attribute objects for the menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, null);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
// Create some attribute objects for getting the caller’s telephone number
private PlayAttributes telNoPlayAtts = new PlayAttributes();
private InputAttributes telNoInputAtts = new InputAttributes();
private DTMFAttributes telNoDTMFAtts = new DTMFAttributes();
private RecoAttributes telNoRecoAtts = null;
// Create a flag to control whether we continue to loop around in the voiceMain() method taking calls
private boolean keepTakingCalls = true;
176 Developing Java Applications
22 // Create an instance of the Catalog class
private Catalog catalog = new Catalog();
// Create a constructor method to set up the attributes
public InApp() {
// Set the input attributes of the menu
menuAtts.setHeaderMessage(VS_MENU_HEADER);
menuAtts.setFooterMessage(VS_MENU_FOOTER);
menuAtts.setInvalidInputMessage(VS_MENU_INVALID);
menuAtts.setOneMoreRepeatMessage(VS_MENU_ONEMORE);
menuAtts.setNoMoreRepeatsMessage(VS_MENU_ERROR);
menuAtts.setTimeout(10);
menuAtts.setNumberOfRepeats(2);
// Set the DTMF attributes of the menu
menuDTMFAtts.setDelimiterKeys("");
menuDTMFAtts.setMaximumKeys(1);
// Set the input attributes for getting the telephone number
telNoInputAtts.setMessage(VS_TEL_NO);
telNoInputAtts.setTimeoutMessage(VS_NOT_ENOUGH);
telNoInputAtts.setInvalidInputMessage(VS_NUMBER_INVALID);
telNoInputAtts.setOneMoreRepeatMessage(VS_ONE_MORE_TIME);
telNoInputAtts.setNoMoreRepeatsMessage(VS_NO_VALID_INPUT);
telNoInputAtts.setTimeout(10);
telNoInputAtts.setNumberOfRepeats(2);
telNoInputAtts.setValidator(PHONE_NUM_CHECKER);
// Set the DTMF attributes for getting the telephone number
telNoDTMFAtts.setDelimiterKeys("");
telNoDTMFAtts.setMaximumKeys(6);
}//InApp
/**
* @see com.ibm.telephony.wvr.WVRApplication#voiceMain()
*/
public void voiceMain() throws WVRException {
// Define the Call object
Call call = null;
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object and set the wait time
WVR wvr = new WVR(this, applicationProperties);
wvr.setWaitTime(-1);
// Create a variable that will be used to give each call a unique number
int callNumber = 0;
try {
while (keepTakingCalls) {
// Increment callNumber
callNumber++;
// Wait for a call
call = wvr.waitForCall("Call: " + callNumber);
// Create a flag to indicate whether the call is in progress
boolean callInProgress = true;
Chapter 7. WebSphere Voice Response Java Tutorials 177
try {
// Play welcome message
call.play(VS_WELCOME);
while (callInProgress) {
// Play the menu and get the caller’s response.
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String choice = input.getValue();
// Check which menu option has been selected and take
// the appropriate action. Each action returns a boolean
// stating whether the call should continue or not
if (choice.equals(ITEM1_MSG)) {
// Menu item 1 - record a message
callInProgress = recordMessage(call);
}
else if (choice.equals(ITEM2_NUMBER)) {
// Menu item 2 - leave a telephone number
callInProgress = leavePhoneNumber(call);
}
23
else if (choice.equals(ITEM3_ORDER)) {
// Menu item 3 - place an order
callInProgress = order(call);
}
else if (choice.equals(ITEM5_HANGUP)) {
// Menu item 5 - hang up
callInProgress = hangUp(call);
}
else {
// Print out the caller’s choice.
System.out.println("Caller chose option " + choice);
}//if
}//while
}
catch (WVRHungUpException e) {
// Caller has hung up - ignore exception, program will go to finally block
}
catch (WVRInvalidInputException e) {
// Caller has entered invalid input - ignore exception, application will go to finally block
}
catch (WVRException e) {
// Check if Call object has been created. If yes, play the Difficulties message.
if (call.isActive()) call.play(VS_DIFFICULTIES);
// Print debugging information
e.printStackTrace();
}
finally {
// Return the call
call.returnCall();
}//try
}//while
}
catch (WVRException e) {
// Print debugging information
e.printStackTrace();
}//try
}//voiceMain
178 Developing Java Applications
/**
* Method recordMessage.
* @param call
* @return boolean
*/
private boolean recordMessage(Call call) throws WVRException {
// Play segments to instruct the caller on how to record their message
call.play(VS_RECORD);
call.play(VS_PRESS_KEY);
// Record the message
call.record(VS_CALLER_MSG, 180);
// Play a message to acknowledge the recording
call.play(VS_RESPOND);
call.play(VS_CALL_BACK);
return true;
}
/**
* Method leavePhoneNumber.
* @param call
* @return boolean
*/
private boolean leavePhoneNumber(Call call) throws WVRException {
try {
// Get the caller’s input - the Input Validator class created earlier will check to make sure the
// number begins with a 2
InputResult result = call.playAndGetInput(telNoPlayAtts, telNoInputAtts, telNoDTMFAtts, telNoRecoAtts);
}
catch (WVRInvalidInputException e) {
return true;
}//try
// Play the ThankYou message to acknowledge a valid number
call.play(VS_THANK_YOU);
return true;
}
24
/**
* Method order.
* @param call
* @return boolean
*/
a
private boolean order(Call call) throws WVRException {
b
// Invoke the takeOrder method of the Catalog class to get the caller’s order
catalog.takeOrder(call);
Chapter 7. WebSphere Voice Response Java Tutorials 179
c return true;
}//order
/**
* Method hangUp.
* @param call
* @return boolean
*/
private boolean hangUp(Call call) throws WVRException {
// Thank the user for calling
call.play(VS_THANKCALLING);
return false;
}
// Tell the application to stop taking calls when the node shuts down
public void voiceAppStop() { keepTakingCalls = false; }
public static void main(String[] args) {
// Create an instance of the class and invoke the run method
InApp aInApp = new InApp();
aInApp.run();
}//main
}//InApp
180 Developing Java Applications
Tutorial 8: Credit card validation (menu item 3 continued)
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. You wrote a separate Java
class for the third menu item, which allowed the caller to order an item from
a catalog. In this tutorial you will create another class which you will use to
obtain and validate credit card information from the caller. This tutorial gives
you more practice at using separate classes in your main application, and
shows you how you can validate input without using an InputValidator.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed all the previous tutorials, apart from Tutorial
5 which involves a separate application, as the code from these tutorials is
used as a base for this tutorial.
1. Create a new class called CardChecker, in the same package as InApp.
Accept java.lang.Object as the superclass. Do not check the public static
void main(String[] args) check box. This class will get credit card details
from the caller and check their validity.
2. Add import statements at the top of the class, for the following external
classes that will be required by the CardChecker class
2
:
v com.ibm.telephony.beans.media.*
v com.ibm.telephony.wvr.*
3. In the CardChecker class, create a String to represent the category for the
voice segments you will use later (″Tutorials″)
3
.
4. Create the following VoiceSegment objects that will be used to get the
caller’s card details:
v InvalidCard
v CardNumber
v ExpriyDate
v DateFormat
4
.
5. Create an array of MediaTypes. Store the ExpiryDate and DateFormat
voice segments in this array, so that they can be played as a media
sequence
5
.
Chapter 7. WebSphere Voice Response Java Tutorials 181
6. Create two sets of attribute objects for obtaining the caller’s card number
and expiry date. These are both input fields rather than menus, so use
the InputAttributes object rather than the MenuAttributes object
6
.
7. Create a constructor method to set up various attributes as follows
7
:
Attribute object Attribute Value Result
cardNumInputAtts Message VS_CARD_NUMBER The caller will hear ″Please key in a
sixteen-digit credit card number″
then the application waits for input
cardNumInputAtts Timeout 20 The caller will have 20 seconds to
enter the number
cardNumDTMFAtts MaximumKeys 16 The application will only accept a
sequence of 16 key presses.
cardNumDTMFAtts DelimiterKeys ″″ (empty string) The caller does not need to use a
delimiter key as the application is
expecting 16 digits
expiryInputAtts Message VS_EXPIRY (the
media sequence
formed from
VS_EXPIRY_DATE
and
VS_DATE_FORMAT)
The caller will hear ″Please key in
the expiration date. The expiry date
is four digits, month month, year
year″ then the application waits for
input
expiryInputAtts Timeout 10 The caller will have 10 seconds to
enter the quantity
expiryDTMFAtts MaximumKeys 4 The application will only accept 4
key presses. Assume the date will be
in the format mmyy.
expiryDTMFAtts DelimiterKeys ″″ (empty string) The caller does not need to use a
delimiter key as the application is
expecting 4 digits
8. After the constructor method create a method called takeCardDetails().
The method should take a Call object as a parameter, return a boolean
and throw a WVRException
8
. This method will take the call from the
Catalog class and then get the caller’s input.
9. Inside the takeCardDetails() method, create some variables which we
will use to validate the caller’s data
9
:
v Create two Strings to represent the caller’s cardNumber and expiry
date.
v Create two ints to represent the year of the expiry date and the first
digit of the caller’s card number.
182 Developing Java Applications
10. Create a variable called numberOfTries which will keep track of the
number of times the caller has attempted to enter valid card details. Then
create a while loop that loops until numberOfTries equals three
10
.
11. Use the playAndGetInput() method of the Call object, and the getValue()
method of the resulting InputResult object to obtain the caller’s card
number and expiry date. Assign the results to the Strings you created in
step 8
11
.
12. To obtain the year of the expiry date and the first digit of the card
number, extract the last two characters of the expiry date string, and the
first character of the card number String. Then convert them into ints
12
. 13. Add an if statement to check for a valid card. The card will be declared
non-valid if the year is not 03, 04 or 05, and also if the first digit of the
card number does not match the year. For example, if the year is 03 the
card number must begin with 3 for the card to be valid. If the card is
valid, return a value of true, otherwise play the InvalidCard message to
inform the caller that the card failed validation
13
.
14. After the while loop, return false, to indicate that the card was not valid14
.
15. Now that you have created the CardChecker class, you can use it from
within the Catalog class. In the Catalog class, add a new VoiceSegment
object for the Sorry voice segment, which tells the caller that their order
could not be processed
15
.
16. Still in the Catalog class, after the attribute object declarations, create an
instance of the CardChecker class
16
.
17. Near the end of the Catalog class, add an if block around the line
call.play(VS_MAIL_ORDER);
The if statement should invoke the CardChecker’s takeCardDetails()
method using the current Call object, and then check to see if the result
was true. Inside the if block the card is valid, so use the play() method of
the Call object to play a voice segment to the caller to confirm receipt of
the order
17
.
18. Add an else statement to play the Sorry voice segment to the caller if
the card was not valid
18
.
19. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
Chapter 7. WebSphere Voice Response Java Tutorials 183
v Listen for the text of the menu. While the menu is playing, press the 3
key on the telephone.
v Key in a four-digit number.
v Key in a quantity, followed by the pound key.
v Press 1 to confirm the order. Do you hear ″Please key in a sixteen digit
credit-card number″?
v If so, try entering an non-valid combination of card number and expiry
date. For example, a card number that begins with 9 and an expiry
date ending in 04. Do you hear the message ″Sorry, these credit card
details are not valid″?
v When you enter a valid combination (for example a card number
beginning with 3 and an expiry date ending in 03), do you hear the
message ″We will mail your order to you immediately″?
v Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding
in “Tutorial 9: Order information (menu item 3 continued)” on page 190.
184 Developing Java Applications
Code for Tutorial 8 CardChecker class
package tut;
2
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
* Subcomponent that allows the caller to enter their credit card
* details and validates them
*/
class CardChecker {
3
//Define the category for all the voice segments in this class
private static final String CATEGORY = "Tutorials";
4
// Create the Voice Segment objects
private static final VoiceSegment VS_INVALID_CARD = new VoiceSegment(CATEGORY, "InvalidCard");
private static final VoiceSegment VS_CARD_NUMBER = new VoiceSegment(CATEGORY, "CardNumber");
private static final VoiceSegment VS_EXPIRY_DATE = new VoiceSegment(CATEGORY, "ExpiryDate");
private static final VoiceSegment VS_DATE_FORMAT = new VoiceSegment(CATEGORY, "DateFormat");
5
// Create an array to store two of the voice segments so they can be played in sequence
private static final MediaType[] VS_EXPIRY = { VS_EXPIRY_DATE, VS_DATE_FORMAT };
6
// Create attribute objects for getting the cardnumber from the caller
private PlayAttributes cardNumPlayAtts = new PlayAttributes();
private InputAttributes cardNumInputAtts = new InputAttributes();
private DTMFAttributes cardNumDTMFAtts = new DTMFAttributes();
private RecoAttributes cardNumRecoAtts = null;
// Create attribute objects for getting the expiry date from the caller
private PlayAttributes expiryPlayAtts = new PlayAttributes();
private InputAttributes expiryInputAtts = new InputAttributes();
private DTMFAttributes expiryDTMFAtts = new DTMFAttributes();
private RecoAttributes expiryRecoAtts = null;
7
// Create a constructor method to set up various attributes
public CardChecker() {
// Set the attributes for getting the credit card number
cardNumInputAtts.setMessage(VS_CARD_NUMBER);
cardNumInputAtts.setTimeout(20);
cardNumDTMFAtts.setMaximumKeys(16);
cardNumDTMFAtts.setDelimiterKeys("");
// Set the attributes for getting the expiry date
expiryInputAtts.setMessage(VS_EXPIRY);
expiryInputAtts.setTimeout(10);
expiryDTMFAtts.setMaximumKeys(4);
expiryDTMFAtts.setDelimiterKeys("");
} //CardChecker()
8
// Validate the caller’s credit card details
public boolean takeCardDetails(Call call) throws WVRException {
9
String cardNumber = null;
String expiryDate = null;
int year = 0;
int firstNumber = 0;
Chapter 7. WebSphere Voice Response Java Tutorials 185
10 int numberOfTries = 0;
while(numberOfTries < 3) {
numberOfTries++;
11
// Get the card number
InputResult result = call.playAndGetInput(cardNumPlayAtts, cardNumInputAtts,
cardNumDTMFAtts, cardNumRecoAtts);
cardNumber = result.getValue();
// Get the expiry date
result = call.playAndGetInput(expiryPlayAtts, expiryInputAtts, expiryDTMFAtts, expiryRecoAtts);
expiryDate = result.getValue();
12
// Extract the year and the first digit of the card number
year = Integer.parseInt(expiryDate.substring(2, 4));
firstNumber = Integer.parseInt(cardNumber.substring(0, 1));
13
// Validate the card number
if (year >= 3 && year <= 5 && year == firstNumber) {
return true; // Returns that the card number was valid
} else {
call.play(VS_INVALID_CARD);
} //if
}//while
14
return false; // Returns that the card number was not valid
}//takeCardDetails()
}//CardChecker
186 Developing Java Applications
Code for Tutorial 8 Catalog class
package tut;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
* Subcomponent that allows the caller to order an item from a catalog
*/
class Catalog {
//Define the category for all the voice segments in this class.
private static final String CATEGORY = "Tutorials";
// Define the menu items
private static final String ITEM1_YES = "Yes";
private static final String ITEM2_NO = "No";
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_YES, ITEM2_NO };
// Define the keys used to make the menu selections, and store them in an array
private static final String[] MENU_KEYS = { "1", "2" };
// Create a number of Voice Segment objects
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "ForYesPress1"),
new VoiceSegment(CATEGORY, "ForNoPress2")
};
// Create the segment objects for taking the order
private static final VoiceSegment VS_PRODUCT_NUMBER = new VoiceSegment(CATEGORY, "ProductNumber");
private static final VoiceSegment VS_QUANTITY = new VoiceSegment(CATEGORY, "Quantity");
private static final VoiceSegment VS_YOU_ORDERED = new VoiceSegment(CATEGORY, "YouOrdered");
private static final VoiceSegment VS_ITEMS = new VoiceSegment(CATEGORY, "Items");
// Create the segment objects for the verifying the order menu
private static final VoiceSegment VS_IS_THIS_OK = new VoiceSegment(CATEGORY, "IsThisOK");
// Create the segment objects for the result
private static final VoiceSegment VS_MAIL_ORDER = new VoiceSegment(CATEGORY, "MailOrder");
Chapter 7. WebSphere Voice Response Java Tutorials 187
15 private static final VoiceSegment VS_SORRY = new VoiceSegment(CATEGORY, "Sorry");
// Create AudioNumber objects to play the caller’s order back to them
private AudioNumber prodNumValue = new AudioNumber();
private AudioNumber quantityValue = new AudioNumber();
// Create a media sequence of the caller’s order
private MediaType[] order = { VS_YOU_ORDERED, quantityValue, VS_ITEMS, prodNumValue };
// Create some attribute objects for getting the product number from the caller
private PlayAttributes prodNumPlayAtts = new PlayAttributes();
private InputAttributes prodNumInputAtts = new InputAttributes();
private DTMFAttributes prodNumDTMFAtts = new DTMFAttributes();
private RecoAttributes prodNumRecoAtts = null;
// Create some attribute objects for getting the quantity from the caller
private PlayAttributes quantityPlayAtts = new PlayAttributes();
private InputAttributes quantityInputAtts = new InputAttributes();
private DTMFAttributes quantityDTMFAtts = new DTMFAttributes();
private RecoAttributes quantityRecoAtts = null;
// Create some attribute objects for the verify order menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, null);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
188 Developing Java Applications
16 private CardChecker cardChecker = new CardChecker();
// Create a constructor method to set up various attributes
public Catalog() {
// Set the style of the product number AudioNumber object to digits
prodNumValue.setStyle("Digits");
// Set the attributes for getting the product number
prodNumInputAtts.setMessage(VS_PRODUCT_NUMBER);
prodNumInputAtts.setTimeout(10);
prodNumDTMFAtts.setMaximumKeys(4);
prodNumDTMFAtts.setDelimiterKeys("");
// Set the attributes for getting the quantity
quantityInputAtts.setMessage(VS_QUANTITY);
quantityInputAtts.setTimeout(10);
// Set the attributes for the verify order menu
menuAtts.setHeaderMessage(VS_IS_THIS_OK);
menuAtts.setTimeout(10);
menuDTMFAtts.setMaximumKeys(1);
menuDTMFAtts.setDelimiterKeys("");
}//Catalog()
public void takeOrder(Call call) throws WVRException {
// Create variables to store the product number and quantity of the order.
double prodNum = 0;
double quantity = 0;
while (true) {
// Get the product number from the caller
InputResult prodNumResult = call.playAndGetInput(prodNumPlayAtts, prodNumInputAtts,
prodNumDTMFAtts, prodNumRecoAtts);
prodNum = Double.parseDouble(prodNumResult.getValue());
prodNumValue.setValue(prodNum);
// Get the quantity from the caller
InputResult quantityResult = call.playAndGetInput(quantityPlayAtts, quantityInputAtts,
quantityDTMFAtts, quantityRecoAtts);
quantity = Double.parseDouble(quantityResult.getValue());
quantityValue.setValue(quantity);
// Play the order back to the caller
call.play(order);
// Verifies with the caller that the choice is correct, if yes, breaks out of loop
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String answer = input.getValue();
if (answer.equals(ITEM1_YES)) break;
}//while
17
if (cardChecker.takeCardDetails(call)) {
// Confirm to the caller that their order has gone through
call.play(VS_MAIL_ORDER);
}
else {
18
call.play(VS_SORRY);
} //if
}//takeOrder()
}
Chapter 7. WebSphere Voice Response Java Tutorials 189
Tutorial 9: Order information (menu item 3 continued)
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. You wrote functionality for
the third menu item that allowed the caller to order an item from a catalog. In
this tutorial you will create another class which will represent information
extracted from a database, in a form that can be played to the caller. This
tutorial introduces the Playable interface, and the AudioCurrency and
AudioDate media objects.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed all the previous tutorials, apart from Tutorial
5 which involves a separate application, as the code from these tutorials is
used as a base for this tutorial.
1. The Playable interface is used to create classes that represent information
that cannot be represented by an existing MediaType object such as
VoiceSegment or AudioNumber. A Playable object can be used in the
same way as any MediaType object. In the InApp application the caller
can place an order and the system confirms that the order has gone
through. In a real application, when the caller places an order the
application might extract relevant information, such as the order cost,
from a database. We can create a separate class which extracts the
information and stores it as a sequence of MediaType objects that will be
played to the caller when the Playable class is used as a parameter in a
play() or playAndGetInput() method. To do this we need to use the
Playable interface. For simplicity we will not involve a real database in
this tutorial.
Create a new class called OrderInfo, in the same package as InApp,
using java.lang.Object as the superclass. You don’t need to include a
public static void main(String[] args) method. The class should
implement the Playable interface.
2. Add import statements for the following external classes that will be
required by the Playable class
2
:
v java.util.Calendar
v com.ibm.telephony.beans.media.*
v com.ibm.telephony.wvr.Playable
3. After the class definition line, create a String to represent the category for
the tutorial voice segments (″Tutorials″)
3
.
190 Developing Java Applications
4. Create VoiceSegment objects for the the following voice segments that
will be required to play the order information to the caller
4
:
v OrderCost
v OrderDate
v OrderRef
5. Create the following MediaType objects to represent the order
information itself
5
:
v An AudioCurrency object, to represent the cost of the order.
v An AudioDate object, to represent the delivery date.
v An AudioString object, to represent the caller’s reference number.
Use the default constructor method, which takes no parameters, for each
object.
6. Create an array of MediaTypes to represent the order information, and
populate it with the MediaType objects that you have just created
6
.
The order should be OrderCost voice segment followed by the cost
AudioCurrency object, the OrderDate voice segment followed by the
delivery date AudioDate object, and the OrderRef voice segment
followed by the customer reference AudioString object.
The array will be played as a media sequence that represents the order
information. The caller will hear ″Your order will cost ... <cost> ... and
will be delivered on ... <delivery date>. Please note your customer
reference is ... <customer reference>″.
7. Create a Calendar object to represent today’s date
7
.
8. Write a constructor method for the OrderInfo class. The constructor
method should take two double parameters, for the quantity of items in
the order and the product number
8
. In a real voice application, this
method would use these parameters to extract the relevant information
from a database, however in this tutorial we will just assign the
information ourselves.
9. Use the setValue() method of the AudioCurrency object to set the order
cost
9
. You can simply multiply the quantity by a value of your
choice.
10. Choose a number of days to allow for delivery, then modify the Calendar
object to represent the delivery date. Use the setValue() method of the
AudioDate object, with the Calendar object as the parameter, to set the
delivery date. Use the setStyle() method of the AudioDate object to
″MD″, so that the date will be read out as the month and the
day-of-month, in an order appropriate to the locale of the application 10
.
Chapter 7. WebSphere Voice Response Java Tutorials 191
11. Use the setString() method of the AudioString object to set the string to
be read out as the caller’s reference
11
. The string will be read out as a
sequence of characters.
12. After the constructor method create a method called toMedia(). This
method is defined in the Playable interface, and therefore must be
included in any class that implements that interface. Inside the toMedia()
method return the media sequence that you created in step 6
12
.
13. Now that you have created the OrderInfo class, you can use it from
within the main application. Open the InApp class and find the line that
plays the MailOrder voice segment. Replace the VoiceSegment object
with an instance of the OrderInfo class, using the quantity and product
number variables created in “Tutorial 7: Order an item from a catalog
(menu item 3)” on page 167, as parameters
13
. You can now delete the
MailOrder VoiceSegment object, since it is no longer used.
14. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
v Listen for the text of the menu. While the menu is playing, press the 3
key on the telephone.
v Key in a four-digit number.
v Key in a quantity, followed by the pound key.
v Press 1 to confirm the order.
v Enter a valid credit card number and date.
v Do you hear ″Your order will cost ... <cost> ... and will be delivered on
... <delivery date>. Please note your customer reference is ... <customer
reference>″?
v Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application. Then switch back to the Java perspective to continue coding
in “Tutorial 10: Transfer to an agent (menu item 4)” on page 198.
192 Developing Java Applications
Code for Tutorial 9 OrderInfo class
package tut;
2
import java.util.Calendar;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.Playable;
/**
*
* OrderInfo - a class that represents information returned from a database, in a form
* that can be played as voice segments.
*/
public class OrderInfo implements Playable {
3
// Define the category for the voice segments in this class
private static final String CATEGORY = "Tutorials";
4
// Create VoicesSegment objects to play the order information
private static final VoiceSegment VS_ORDER_COST = new VoiceSegment(CATEGORY, "OrderCost");
private static final VoiceSegment VS_ORDER_DATE = new VoiceSegment(CATEGORY, "OrderDate");
private static final VoiceSegment VS_ORDER_REF = new VoiceSegment(CATEGORY, "OrderRef");
5
// Create MediaType objects to represent the order information
AudioCurrency cost = new AudioCurrency();
AudioDate deliveryDate = new AudioDate();
AudioString callerRef = new AudioString();
6
// Create a media sequence that represents the caller’s order
MediaType[] orderInfo = {VS_ORDER_COST, cost, VS_ORDER_DATE, deliveryDate, VS_ORDER_REF, callerRef};
7
// Create a Calendar object for today’s date
Calendar today = Calendar.getInstance();
8
// Constructor method
public OrderInfo(double quantity, double prodNum) {
9
// Set the order information - in a real application this would involve
// extracting information from a database using the quantity and prodNum variables
cost.setValue(2.75 * quantity);
10
today.add(Calendar.DATE, 5);
deliveryDate.setValue(today);
deliveryDate.setStyle("MD");
11
callerRef.setString("AH1B2");
}
Chapter 7. WebSphere Voice Response Java Tutorials 193
12 // Return the order information
public MediaType[] toMedia() {
return orderInfo;
}
}
194 Developing Java Applications
Code for Tutorial 9 Catalog class
package tut;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
* Subcomponent that allows the caller to order an item from a catalog
*/
class Catalog {
//Define the category for all the voice segments in this class.
private static final String CATEGORY = "Tutorials";
// Define the menu items
private static final String ITEM1_YES = "Yes";
private static final String ITEM2_NO = "No";
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_YES, ITEM2_NO };
// Define the keys used to make the menu selections, and store them in an array
private static final String[] MENU_KEYS = { "1", "2" };
// Create a number of Voice Segment objects
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "ForYesPress1"),
new VoiceSegment(CATEGORY, "ForNoPress2")
};
// Create the segment objects for taking the order
private static final VoiceSegment VS_PRODUCT_NUMBER = new VoiceSegment(CATEGORY, "ProductNumber");
private static final VoiceSegment VS_QUANTITY = new VoiceSegment(CATEGORY, "Quantity");
private static final VoiceSegment VS_YOU_ORDERED = new VoiceSegment(CATEGORY, "YouOrdered");
private static final VoiceSegment VS_ITEMS = new VoiceSegment(CATEGORY, "Items");
// Create the segment objects for the verifying the order menu
private static final VoiceSegment VS_IS_THIS_OK = new VoiceSegment(CATEGORY, "IsThisOK");
// Create the segment object for the result
private static final VoiceSegment VS_SORRY = new VoiceSegment(CATEGORY, "Sorry");
// Create AudioNumber objects to play the caller’s order back to them
private AudioNumber prodNumValue = new AudioNumber();
private AudioNumber quantityValue = new AudioNumber();
// Create a media sequence of the caller’s order
private MediaType[] order = { VS_YOU_ORDERED, quantityValue, VS_ITEMS, prodNumValue };
// Create some attribute objects for getting the product number from the caller
private PlayAttributes prodNumPlayAtts = new PlayAttributes();
private InputAttributes prodNumInputAtts = new InputAttributes();
private DTMFAttributes prodNumDTMFAtts = new DTMFAttributes();
private RecoAttributes prodNumRecoAtts = null;
// Create some attribute objects for getting the quantity from the caller
private PlayAttributes quantityPlayAtts = new PlayAttributes();
private InputAttributes quantityInputAtts = new InputAttributes();
private DTMFAttributes quantityDTMFAtts = new DTMFAttributes();
private RecoAttributes quantityRecoAtts = null;
Chapter 7. WebSphere Voice Response Java Tutorials 195
// Create some attribute objects for the verify order menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, MENU_ITEMS);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
private CardChecker cardChecker = new CardChecker();
// Create a constructor method to set up various attributes
public Catalog() {
// Set the style of the product number AudioNumber object to digits
prodNumValue.setStyle("Digits");
// Set the attributes for getting the product number
prodNumInputAtts.setMessage(VS_PRODUCT_NUMBER);
prodNumInputAtts.setTimeout(10);
prodNumDTMFAtts.setMaximumKeys(4);
prodNumDTMFAtts.setDelimiterKeys("");
// Set the attributes for getting the quantity
quantityInputAtts.setMessage(VS_QUANTITY);
quantityInputAtts.setTimeout(10);
// Set the attributes for the verify order menu
menuAtts.setHeaderMessage(VS_IS_THIS_OK);
menuAtts.setTimeout(10);
menuDTMFAtts.setMaximumKeys(1);
menuDTMFAtts.setDelimiterKeys("");
}//Catalog()
public void takeOrder(Call call) throws WVRException {
// Create variables to store the product number and quantity of the order.
double prodNum = 0;
double quantity = 0;
while (true) {
// Get the product number from the caller
InputResult prodNumResult = call.playAndGetInput(prodNumPlayAtts, prodNumInputAtts,
prodNumDTMFAtts, prodNumRecoAtts);
prodNum = Double.parseDouble(prodNumResult.getValue());
prodNumValue.setValue(prodNum);
// Get the quantity from the caller
InputResult quantityResult = call.playAndGetInput(quantityPlayAtts, quantityInputAtts,
quantityDTMFAtts, quantityRecoAtts);
quantity = Double.parseDouble(quantityResult.getValue());
quantityValue.setValue(quantity);
// Play the order back to the caller
call.play(order);
// Verifies with the caller that the choice is correct, if yes, breaks out of loop
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String answer = input.getValue();
if (answer.equals(ITEM1_YES)) break;
}//while
if (cardChecker.takeCardDetails(call)) {
// Confirm to the caller that their order has gone through
196 Developing Java Applications
13 call.play(new OrderInfo(quantity, prodNum));
}
else {
call.play(VS_SORRY);
} //if
}//takeOrder()
}
Chapter 7. WebSphere Voice Response Java Tutorials 197
Tutorial 10: Transfer to an agent (menu item 4)
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. In this tutorial you will add
call transfer functionality to the fourth menu item. This tutorial introduces the
use of the Call class to perform a call transfer.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed all the previous tutorials, apart from Tutorial
5 which involves a separate application, as the code from these tutorials is
used as a base for this tutorial.
Preparation
Note:
The Voice Response simulator does not support call transfer, so to test
this you need to have a WebSphere Voice Response node with the Java
and VoiceXML environment installed. You also need a switch and
telephony protocol that support call transfer, and two phones.
If you have not yet installed the Java and VoiceXML environment on a
WebSphere Voice Response node, leave this tutorial for later. If you
have installed the Java and VoiceXML environment on a WebSphere
Voice Response node, but have been using the Voice Response
simulator for the tutorials up till now, you can change the
ApplicationProperties object to point to the WebSphere Voice Response
node.
To test an application on a real WebSphere Voice Response system you must
also:
1. Open the configuration file, default.cff, for the voice response node. The
configuration file is in /var/dirTalk/DTBE/native/aix. Under the NodeName
entry, add a
NumToApp=
mapping from a telephone number you can use for incoming calls to an
application named “app1”. Figure 1 shows how the NodeName entry should
look. Substitute your own numbers for 7003 and 7004. You must then run
the dtjconf utility, and restart the Node if it is running (using the
198 Developing Java Applications
commands dtjstop and dtjstart), to make the change take effect.
See an introduction to the configuration database in WebSphere Voice
Response for AIX: Deploying and Managing VoiceXML and Java Applications
for more information about default.cff.
2. Make sure that the base WebSphere Voice Response system has the
telephone number defined correctly. (For guidance, see the Installation
Guide for your version of WebSphere Voice Response).
3. Import the tutorial voice segments into the WebSphere Voice Response
system as follows:
a. Copy dtjtvseg.zip to the WebSphere Voice Response machine. See
“Voice segments for running the tutorial applications” on page 122 for
details of where to find this file.
b. Make sure that the base WebSphere Voice Response system is running,
and that you have run dtjshost and dtjstart.
c. Unpack the zip file into a temporary directory.
d. cd to the temporary directory and enter the following command:
dtjplex -action importVoiceHost
Note: Do not import the .wav files using the WebSphere Voice Response
for AIX Voice Segments window Development Work Area, because
this will not make them available for use by Java voice applications.
Tutorial
Menu item 4 lets the caller transfer to an agent. First, the application makes
sure the agent is available and, if they are, tells them there is a caller for them.
If the agent is not available, the caller is told, and is then returned to the
menu.
1. In the section of the InApp class where you have been creating voice
segments, create the following VoiceSegment objects that will be required
for this menu item
1
:
v PleaseHold
v CallerForYou
v AgentNotAvail
NodeName=Node1
NodeDefLocale=en_US
Group=group1
NumToApp=7003,menu
NumToApp=7004,app1
;
Figure 27. Example NodeName entry with a NumToApp mapping for the “app1” application
Chapter 7. WebSphere Voice Response Java Tutorials 199
2. In the inner while loop of the voiceMain() method, add another if–else
statement to see if the caller chose the Transfer item (menu item 4). If they
did, invoke a new method called operator()
2
.
3. Write the new operator() method after the order() method
3
:
a. The method should take a Call object as a parameter, and return a
boolean. It should also throw a WVRException
a
.
b. Use the play() method of the Call object to play a voice segment to the
caller asking them to hold
b
.
c. Create a try–catch block. In the try block, create a reference variable for
a new Call and assign to it the result of invoking the consult() method
of the current Call object. Use the the number you wish to dial as a
parameter for the consult() method
c
. The application puts the
current call on hold, then uses the same line to dial the specified
number, creating a new call with the agent.
d. Use the play() method of the new Call object to play a voice segment
to tell the agent that they have a caller
d
.
e. Use the transfer() method of the original Call object to transfer the
caller on the original call to the agent on the consult call
e
.
f. Once the caller has been transferred the original and consult call objects
become inactive and the line is now free to receive a new call. There is
no further involvement for the application, so return a value of false to
indicate that the original call should end
f
.
g. In the catch block, use the retrieve() method of the original Call object
to end the consult call and retrieve the original call from a holding
state, if the transfer was not successful
g
.
h. Use the play() method of the original call to play a voice segment to
tell the caller that an agent was not available
h
.
i. Return a value of true to indicate that the call should continue
i
.4. To run your application on a WebSphere Voice Response system create a
directory called tut on the WebSphere Voice Response machine and export
the Java class file for the application into it. If you are using WebSphere
Voice Response for AIX make sure that the class file is owned by the
WebSphere Voice Response user (the default is dtuser).
5.
v Run the application from the directory above tut, according to your
platform:
Enter the following command:
java -cp .:$CLASSPATH tut.InApp
200 Developing Java Applications
v Dial the number you associated with app1 in the configuration file
(default.cff).
v Listen for the text of the menu. While the menu is playing, press the 4
key on the telephone.
v Do you hear ″Please hold″?
v When the agent’s telephone rings, pick it up. Do you hear ″We have a
caller for you″? Does the application hang up on the original caller?
v Hang up.
v Try again, this time don’t pick up the agent’s phone. Do you (the
original caller) hear ″Sorry, all our agents are busy″?
v Hang up.
When you have tested that the code works, return to WebSphere Studio
Site Developer to continue coding in “Tutorial 11: Using speech recognition
and text-to-speech” on page 208.
Chapter 7. WebSphere Voice Response Java Tutorials 201
Code for Tutorial 10
package tut;
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* InApp - a simple WVR application which lets the caller choose from a menu offering different functions
*/
public class InApp extends WVRApplication {
// Define the category for all the voice segments in this application.
private static final String CATEGORY = "Tutorials";
// Define the menu items
private static final String ITEM1_MSG = "Message";
private static final String ITEM2_NUMBER = "Number";
private static final String ITEM3_ORDER = "Order";
private static final String ITEM4_OPERATOR = "Operator";
private static final String ITEM5_HANGUP = "Hangup";
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_MSG, ITEM2_NUMBER, ITEM3_ORDER,
ITEM4_OPERATOR, ITEM5_HANGUP };
// Create an array to represent the keys that will be used to select the menu items
private static final String[] MENU_KEYS = { "1", "2", "3", "4", "5" };
// Create a number of Voice Segment objects that are shared amongst all instances of this
// application within the JVM...
// Create the Welcome and Difficulties segment objects
private static final VoiceSegment VS_WELCOME = new VoiceSegment(CATEGORY, "Welcome");
private static final VoiceSegment VS_DIFFICULTIES = new VoiceSegment(CATEGORY, "Difficulties");
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new VoiceSegment(CATEGORY, "Message"),
new VoiceSegment(CATEGORY, "Number"),
new VoiceSegment(CATEGORY, "Order"),
new VoiceSegment(CATEGORY, "Operator"),
new VoiceSegment(CATEGORY, "Hangup")
};
// Create the segment objects required for the menu properties
private static final VoiceSegment VS_MENU_HEADER = new VoiceSegment(CATEGORY, "MenuHeader");
private static final VoiceSegment VS_MENU_FOOTER = new VoiceSegment(CATEGORY, "MenuFooter");
private static final VoiceSegment VS_MENU_INVALID = new VoiceSegment(CATEGORY, "InvalidKey");
private static final VoiceSegment VS_MENU_ERROR = new VoiceSegment(CATEGORY, "Error");
private static final VoiceSegment VS_MENU_ONEMORE = new VoiceSegment(CATEGORY, "OneMore");
// Create the segment objects for the hangup menu item
private static final VoiceSegment VS_THANKCALLING = new VoiceSegment(CATEGORY, "ThankCalling");
// Create the segment objects for the record a message menu item
private static final VoiceSegment VS_RECORD = new VoiceSegment(CATEGORY, "Record");
private static final VoiceSegment VS_PRESS_KEY = new VoiceSegment(CATEGORY, "PressKey");
private static final VoiceSegment VS_CALLER_MSG = new VoiceSegment(CATEGORY, "CallerMsg");
private static final VoiceSegment VS_RESPOND = new VoiceSegment(CATEGORY, "Respond");
202 Developing Java Applications
// Create the segment objects for the key in a telephone number menu item
private static final VoiceSegment VS_TEL_NO = new VoiceSegment(CATEGORY, "TelNo");
private static final VoiceSegment VS_THANK_YOU = new VoiceSegment(CATEGORY, "ThankYou");
private static final VoiceSegment VS_ONE_MORE_TIME = new VoiceSegment(CATEGORY, "OneMoreTime");
private static final VoiceSegment VS_NO_VALID_INPUT = new VoiceSegment(CATEGORY, "NoValidInput");
private static final VoiceSegment VS_NUMBER_INVALID = new VoiceSegment(CATEGORY, "NumberInvalid");
private static final VoiceSegment VS_NOT_ENOUGH = new VoiceSegment(CATEGORY, "NotEnough");
private static final VoiceSegment VS_CALL_BACK = new VoiceSegment(CATEGORY, "CallBack");
1
// Create the segment objects for the call transfer menu item
private static final VoiceSegment VS_PLEASE_HOLD = new VoiceSegment(CATEGORY, "PleaseHold");
private static final VoiceSegment VS_CALLER_FOR_YOU = new VoiceSegment(CATEGORY, "CallerForYou");
private static final VoiceSegment VS_AGENT_NOT_AVAIL = new VoiceSegment(CATEGORY, "AgentNotAvail");
// Create an InputValidator to validate the caller’s telephone number
private static final InputValidator PHONE_NUM_CHECKER = new InputValidator() {
public String validate(InputResult result) {
// Get the caller’s input from the InputResult object
String value = result.getValue();
// If the caller’s number starts with a 2, it is valid
if (value.substring(0, 1).equals("2")) return value;
// Otherwise the number is invalid, so return null
return null;
}//validate
};
// Create some attribute objects for the menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, null);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = null;
// Create some attribute objects for getting the caller’s telephone number
private PlayAttributes telNoPlayAtts = new PlayAttributes();
private InputAttributes telNoInputAtts = new InputAttributes();
private DTMFAttributes telNoDTMFAtts = new DTMFAttributes();
private RecoAttributes telNoRecoAtts = null;
// Create a flag to control whether we continue to loop around in the voiceMain() method taking calls
private boolean keepTakingCalls = true;
// Create an instance of the Catalog class
private Catalog catalog = new Catalog();
// Create a constructor method to set up the attributes
public InApp() {
// Set the input attributes of the menu
menuAtts.setHeaderMessage(VS_MENU_HEADER);
menuAtts.setFooterMessage(VS_MENU_FOOTER);
menuAtts.setInvalidInputMessage(VS_MENU_INVALID);
menuAtts.setOneMoreRepeatMessage(VS_MENU_ONEMORE);
menuAtts.setNoMoreRepeatsMessage(VS_MENU_ERROR);
menuAtts.setTimeout(10);
menuAtts.setNumberOfRepeats(2);
// Set the DTMF attributes of the menu
menuDTMFAtts.setDelimiterKeys("");
menuDTMFAtts.setMaximumKeys(1);
Chapter 7. WebSphere Voice Response Java Tutorials 203
// Set the input attributes for getting the telephone number
telNoInputAtts.setMessage(VS_TEL_NO);
telNoInputAtts.setTimeoutMessage(VS_NOT_ENOUGH);
telNoInputAtts.setInvalidInputMessage(VS_NUMBER_INVALID);
telNoInputAtts.setOneMoreRepeatMessage(VS_ONE_MORE_TIME);
telNoInputAtts.setNoMoreRepeatsMessage(VS_NO_VALID_INPUT);
telNoInputAtts.setTimeout(10);
telNoInputAtts.setNumberOfRepeats(2);
telNoInputAtts.setValidator(PHONE_NUM_CHECKER);
// Set the DTMF attributes for getting the telephone number
telNoDTMFAtts.setDelimiterKeys("");
telNoDTMFAtts.setMaximumKeys(6);
}//InApp
/**
* voiceMain() - this is the entry point for the application
*/
public void voiceMain() throws WVRException {
// Define the Call object
Call call = null;
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object and set the wait time
WVR wvr = new WVR(this, applicationProperties);
wvr.setWaitTime(-1);
// Create a variable that will be used to give each call a unique number
int callNumber = 0;
try {
while (keepTakingCalls) {
// Increment callNumber
callNumber++;
// Wait for a call
call = wvr.waitForCall("Call: " + callNumber);
// Create a flag to indicate whether the call is in progress
boolean callInProgress = true;
try {
// Play welcome message
call.play(VS_WELCOME);
while (callInProgress) {
// Play the menu and get the caller’s response.
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String choice = input.getValue();
// Check which menu option has been selected and take
// the appropriate action. Each action returns a boolean
// stating whether the call should continue or not
if (choice.equals(ITEM1_MSG)) {
// Menu item 1 - record a message
callInProgress = recordMessage(call);
}
204 Developing Java Applications
else if (choice.equals(ITEM2_NUMBER)) {
// Menu item 2 - leave a telephone number
callInProgress = leavePhoneNumber(call);
}
else if (choice.equals(ITEM3_ORDER)) {
// Menu item 3 - place an order
callInProgress = order(call);
}
2
else if (choice.equals(ITEM4_OPERATOR)) {
// Menu item 4 - transfer to an agent
callInProgress = operator(call);
}
else if (choice.equals(ITEM5_HANGUP)) {
// Menu item 5 - hang up
callInProgress = hangUp(call);
}
else {
// Print out the caller’s choice.
System.out.println("Caller chose option " + choice);
}//if
}//while
}
catch (WVRHungUpException e) {
// Caller has hung up - ignore exception, application will go to finally block
}
catch (WVRInvalidInputException e) {
// Caller has entered invalid input - ignore exception, application will go to finally block
}
catch (WVRException e) {
// Check if Call object has been created. If yes, play the Difficulties message.
if (call.isActive()) call.play(VS_DIFFICULTIES);
// Print debugging information
e.printStackTrace();
}
finally {
// Return the call
call.returnCall();
}//try
}//while
}
catch (WVRException e) {
// Print debugging information
e.printStackTrace();
}//try
}//voiceMain
/**
* Method recordMessage.
* @param call
* @return boolean
*/
private boolean recordMessage(Call call) throws WVRException {
// Play segments to instruct the caller how to record their message
call.play(VS_RECORD);
call.play(VS_PRESS_KEY);
Chapter 7. WebSphere Voice Response Java Tutorials 205
// Record the message
call.record(VS_CALLER_MSG, 180);
// Play a message to acknowledge the recording
call.play(VS_RESPOND);
return true;
}//recordMessage
/**
* Method leavePhoneNumber.
* @param call
* @return boolean
*/
private boolean leavePhoneNumber(Call call) throws WVRException {
try {
// Get the caller’s input - the Input Validator class created earlier will check to make sure the
// number begins with a 2
InputResult result = call.playAndGetInput(telNoPlayAtts, telNoInputAtts, telNoDTMFAtts, telNoRecoAtts);
}
catch (WVRInvalidInputException e) {
return true;
}//try
// Acknowledge a valid number
call.play(VS_THANK_YOU);
call.play(VS_CALL_BACK);
return true;
}//leavePhoneNumber
/**
* Method order.
* @param call
* @return boolean
*/
private boolean order(Call call) throws WVRException {
// Invoke the takeOrder method of the Catalog class to get the caller’s order
catalog.takeOrder(call);
return true;
}//order
3
/**
* Method operator.
* @param call
* @return boolean
*/
a
private boolean operator(Call call) throws WVRException {
b
// Ask the caller to hold
call.play(VS_PLEASE_HOLD);
c
try {
// Make another call
Call consultee = call.consult("7001");
d
// Tell the agent they have a caller
consultee.play(VS_CALLER_FOR_YOU);
e
// Transfer the agent to the caller
consultee.transfer();
206 Developing Java Applications
f // No further action required, so indicate that call can end
return false;
}
catch (WVRException e) {
g
// Get the original caller back
call.retrieve();
h
// Tell the caller that an agent was not available
call.play(VS_AGENT_NOT_AVAIL);
i
// Continue with call
return true;
}//try
}//operator
/**
* Method hangUp.
* @param call
* @return boolean
*/
private boolean hangUp(Call call) throws WVRException {
// Thank the user for calling
call.play(VS_THANKCALLING);
return false;
}//hangUp
// Tell the application to stop taking calls when the node shuts down
public void voiceAppStop() { keepTakingCalls = false; }
public static void main(String[] args) {
// Create an instance of the InApp class and invoke the run method
InApp aInApp = new InApp();
aInApp.run();
}//main
}//InApp
Chapter 7. WebSphere Voice Response Java Tutorials 207
Tutorial 11: Using speech recognition and text-to-speech
In the previous tutorials you created an application which received an
incoming call and presented a menu to the caller. The caller selected menu
items using DTMF keys and heard prerecorded voice segments played by the
system. In this tutorial you will modify your application to play the menu
using text-to-speech, and then allow the caller to select menu items using
voice input as well as DTMF keys. This tutorial introduces the use of the
RecoAttributes class to enable speech recognition, and the TextToSpeech class
to play text-to-speech.
Attention: Make sure you have read the following before you start this
tutorial:
v Chapter 3, “Using the WebSphere Voice Response Java API classes,” on
page 41.
v “Prerequisites for the tutorials” on page 121.
v “Voice segments for running the tutorial applications” on page 122.
You also need to have completed all the previous tutorials, apart from Tutorial
5 which involves a separate application, as the code from these tutorials is
used as a base for this tutorial.
1. In order to use speech recognition your system must have a grammar file
which tells it which words to expect from the caller. Create a file called
menu.bnf, and copy the following lines into it:
<<menuchoice>> = Message : "ch1" |
Number : "ch2" |
Order : "ch3" |
Operator : "ch4" |
Hang up : "ch5" .
You can create the grammar file using any text editor, or Voice Toolkit for
WebSphere Studio, which is included in the WebSphere Voice Response for
AIX package. See IBM WebSphere Voice Server: Application Development with
State Tables for more information about grammars.
Note: WebSphere Voice Toolkit Versions 4.2 and above support the
standard of Semantic Interpretation for Speech Recognition (SISR) in
grammars, which was not available in Version 3.1 of WebSphere
Voice Server. If you are using Version 3.1 of WebSphere Voice Server
you must use an earlier version of the WebSphere Voice Toolkit,
such as Version 4.1.1, to compile your grammar file.
Create a new directory called grammars under the WebSphere Voice
Response Simulator install directory and put the grammar file into it. The
default Voice Response simulator install directories are:
v For the WebSphere Voice Toolkit:
websphere_studio_install_path\eclipse\plugins\com.ibm.voicetools.browser.wvrsim_x.y.z
208 Developing Java Applications
where websphere_studio_install_path is the location of WebSphere Studio
Site Developer, and x.y.z is the version number of the WebSphere Voice
Toolkit.2. You must now configure your system to use speech recognition and
text-to-speech.The configuration file for the Voice Response simulator,
default.cff, includes sample RecoService entries. You need to create a
similar entry for your InApp application. Your RecoService entry should
look like this:
RecoService=DTSim_inapp_reco_en_us
Enabled=Yes
InitSessionString=Language=en_us,MaxInitialSilence=10000,grammar=grammars\\menu.bnf
PlugInClass=com.ibm.telephony.directtalk.dtsim.smapi.SRPlugIn
RecoType=inapp-reco-en
;
If necessary, modify the locale to suit your application.
The configuration file supplied with the Voice Response simulator also
contains TTSService entries that look like this:
TTSService=DTSim_tts_en_us
Enabled=yes
InitSessionString=Locale=en_US,ProductName=!
PlugInClass=com.ibm.telephony.directtalk.dtsim.eci.TTSECIPlugin
TTSType=tts-en
;
The TTSService entries are not application-specific so you do not have to
create a new one, just make sure there is one for your locale.
Modify the NodeName entry in the configuration file to include your
RecoService and TTSService definitions. Your NodeName entry should look
similar to this (you may have extra NumToApp mappings, however these
will not affect your application):
NodeName=Node1
NodeDefAppName=noapp
NodeDefLocale=en_US
Enabled=yes
VRNode=yes
NumToApp=1000,app1
Group=group1
TTSService=VXML
TTSDefinition=vo_IC_EXML,VXMLTTS
RecoService=DTSim_inapp_reco_en_us
TTSService=DTSim_tts_en_us
RecoDefinition=en,inapp-reco-en
TTSDefinition=en,tts-en
;
Chapter 7. WebSphere Voice Response Java Tutorials 209
For more information about RecoService and TTSService, see WebSphere
Voice Response for AIX: Deploying and Managing VoiceXML and Java
Applications.
Run the dtjconf utility, and restart the Node if it is running (using the
commands dtjstop and dtjstart), to make the change take effect. Your
system should now be configured for speech recognition and
text-to-speech.
3. Now you can modify your application to use recognition and
text-to-speech. Using text-to-speech is very simple: create a TextToSpeech
object using the String you want to synthesize into speech. Once you have
created the TextToSpeech object you can play it in the same way as a
VoiceSegment or any other MediaType object.
In “Tutorial 2: Select an item from a menu” on page 134 you created an
array of VoiceSegment objects for the menu items, to tell the caller which
DTMF key to press. Rewrite these segments as TextToSpeech objects
which will tell the caller which DTMF key to press and also which word
to say
3
:
Segment
name
Prerecorded segment speech Text-to-speech string
Message To leave a message for us...
press 1.
″To leave a message for us, press 1, or
say Message.″
Number To leave a telephone number
so that we can call you...
press 2.
″To leave a telephone number so that we
can call you, press 2, or say Number.″
Order To order an item from our
catalog... press 3.
″To order an item from our catalog,
press 3, or say Order.″
Operator To talk to one of our agents...
press 4.
″To talk to one of our agents, press 4, or
say Operator.″
Hangup To disconnect... press 5. ″To disconnect, press 5, or say Hang
up.″
For example, where the code says...
new VoiceSegment(CATEGORY, "Message")
... change this to:
new TextToSpeech("To leave a message for us, press 1, or say Message.")
Note: In a real voice application text-to-speech would be more suited to
prompts that are dynamic in nature, lengthy, or infrequently
accessed.
210 Developing Java Applications
4. Rewrite the MenuFooter VoiceSegment as a TextToSpeech object that will
synthesize the string ″Please press the key, or say the word, corresponding
to your choice.″
4
5. Now you need to modify the menu to accept voice input. In “Tutorial 2:
Select an item from a menu” on page 134 you created arrays of menu item
labels and DTMF selector keys for the menu. Now create another String
array, this time containing the words that the caller will use to select the
menu items; these are the same words that you put into the grammar file
in step 1
5
.
6. In “Tutorial 2: Select an item from a menu” on page 134 you created a
MenuAttributes object for the main menu, using a null value for the
selector words as the application did not use speech recognition. Now
replace the null value with the array of selector words you created in step
5. You also created a null reference variable for a RecoAttributes object.
Now modify this line to create a RecoAttributes object using the default
constructor, which takes no parameters
6
.
7. In the constructor method of the InApp class, after setting the DTMF
attributes of the menu, set the following attributes
7
:
Attribute
object
Attribute Value Result
menuPlayAtts VoiceInterruptible PlayAttributes.VOICE_ENERGY The menu can be interrupted by
voice input (the default for this
attribute is NO_VOICE).
menuRecoAtts Context menuchoice Sets the context to ″menuchoice″.
The context specifies the
grammars to use for speech
recognition.
menuRecoAtts Beep false The application will not play a
beep at the end of the prompt. If
you try to play a beep at the end
of a voice-interruptible prompt,
an exception will be thrown.
Now when the playAndGetInput() method is invoked to get the caller’s
choice, the application will accept voice input using the menu grammar
you created in step 1, as well as DTMF keys.
8. Test the application:
v Dial the number you associated with app1 in the configuration file
(default.cff). If you are using the Voice Response simulator, the
number associated with app1 is 1000.
v Listen for the text of the menu. Do you hear the text that you wrote for
the menu in the application?
Chapter 7. WebSphere Voice Response Java Tutorials 211
v Say one of the five keywords. Do you hear the same result as before,
when you used DTMF keys?
v Try the other keywords. You could also try DTMF keys to make sure the
original functionality is still the same.
v Hang up.
When you have tested that the code works, right click on the application
in the Debug window and click Terminate and Remove to stop the
application.
212 Developing Java Applications
Code for Tutorial 11
package tut;
import java.util.Locale;
import com.ibm.telephony.beans.directtalk.ApplicationProperties;
import com.ibm.telephony.beans.media.*;
import com.ibm.telephony.wvr.*;
/**
*
* InApp - a simple WVR application which lets the caller choose from a menu offering different functions
*/
public class InApp extends WVRApplication {
// Define the category for all the voice segments in this application.
private static final String CATEGORY = "Tutorials";
// Define the menu items
private static final String ITEM1_MSG = "Message";
private static final String ITEM2_NUMBER = "Number";
private static final String ITEM3_ORDER = "Order";
private static final String ITEM4_OPERATOR = "Operator";
private static final String ITEM5_HANGUP = "Hangup";
// Create an array to store the menu items
private static final String[] MENU_ITEMS = { ITEM1_MSG, ITEM2_NUMBER, ITEM3_ORDER,
ITEM4_OPERATOR, ITEM5_HANGUP };
// Create an array to represent the keys that will be used to select the menu items
private static final String[] MENU_KEYS = { "1", "2", "3", "4", "5" };
5
// Create an array to represent the words that will be used to select the menu items
private static final String[] MENU_WORDS = { "Message", "Number", "Order", "Operator", "Hang up" };
// Create a number of Voice Segment objects that are shared amongst all instances of this
// application within the JVM...
// Create the Welcome and Difficulties segment objects
private static final VoiceSegment VS_WELCOME = new VoiceSegment(CATEGORY, "Welcome");
private static final VoiceSegment VS_DIFFICULTIES = new VoiceSegment(CATEGORY, "Difficulties");
3
// Create the segment objects for the menu items, and store them in an array
private static final MediaType[] MENU_PROMPTS = {
new TextToSpeech("To leave a message for us, press 1, or say Message."),
new TextToSpeech("To leave a telephone number so that we can call you, press 2, or say Number."),
new TextToSpeech("To order an item from our catalog, press 3, or say Order."),
new TextToSpeech("To talk to one of our agents, press 4, or say Operator."),
new TextToSpeech("To disconnect, press 5, or say Hang up.")
};
// Create the segment objects required for the menu properties
private static final VoiceSegment VS_MENU_HEADER = new VoiceSegment(CATEGORY, "MenuHeader");
Chapter 7. WebSphere Voice Response Java Tutorials 213
4 private static final TextToSpeech VS_MENU_FOOTER = new TextToSpeech("Please press the key, or say the word,
corresponding to your choice.");
private static final VoiceSegment VS_MENU_INVALID = new VoiceSegment(CATEGORY, "InvalidKey");
private static final VoiceSegment VS_MENU_ERROR = new VoiceSegment(CATEGORY, "Error");
private static final VoiceSegment VS_MENU_ONEMORE = new VoiceSegment(CATEGORY, "OneMore");
// Create the segment objects for the hangup menu item
private static final VoiceSegment VS_THANKCALLING = new VoiceSegment(CATEGORY, "ThankCalling");
// Create the segment objects for the record a message menu item
private static final VoiceSegment VS_RECORD = new VoiceSegment(CATEGORY, "Record");
private static final VoiceSegment VS_PRESS_KEY = new VoiceSegment(CATEGORY, "PressKey");
private static final VoiceSegment VS_CALLER_MSG = new VoiceSegment(CATEGORY, "CallerMsg");
private static final VoiceSegment VS_RESPOND = new VoiceSegment(CATEGORY, "Respond");
// Create the segment objects for the key in a telephone number menu item
private static final VoiceSegment VS_TEL_NO = new VoiceSegment(CATEGORY, "TelNo");
private static final VoiceSegment VS_THANK_YOU = new VoiceSegment(CATEGORY, "ThankYou");
private static final VoiceSegment VS_ONE_MORE_TIME = new VoiceSegment(CATEGORY, "OneMoreTime");
private static final VoiceSegment VS_NO_VALID_INPUT = new VoiceSegment(CATEGORY, "NoValidInput");
private static final VoiceSegment VS_NUMBER_INVALID = new VoiceSegment(CATEGORY, "NumberInvalid");
private static final VoiceSegment VS_NOT_ENOUGH = new VoiceSegment(CATEGORY, "NotEnough");
private static final VoiceSegment VS_CALL_BACK = new VoiceSegment(CATEGORY, "CallBack");
// Create the segment objects for the call transfer menu item
private static final VoiceSegment VS_PLEASE_HOLD = new VoiceSegment(CATEGORY, "PleaseHold");
private static final VoiceSegment VS_CALLER_FOR_YOU = new VoiceSegment(CATEGORY, "CallerForYou");
private static final VoiceSegment VS_AGENT_NOT_AVAIL = new VoiceSegment(CATEGORY, "AgentNotAvail");
// Create an InputValidator to validate the caller’s telephone number
private static final InputValidator PHONE_NUM_CHECKER = new InputValidator() {
public String validate(InputResult result) {
// Get the caller’s input from the InputResult object
String value = result.getValue();
// If the caller’s number starts with a 2, it is valid
if (value.substring(0, 1).equals("2")) return value;
// Otherwise the number is invalid, so return null
return null;
}//validate
};
// Create some attribute objects for the menu
private PlayAttributes menuPlayAtts = new PlayAttributes();
214 Developing Java Applications
6 private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, MENU_WORDS);
private DTMFAttributes menuDTMFAtts = new DTMFAttributes();
private RecoAttributes menuRecoAtts = new RecoAttributes();
// Create some attribute objects for getting the caller’s telephone number
private PlayAttributes telNoPlayAtts = new PlayAttributes();
private InputAttributes telNoInputAtts = new InputAttributes();
private DTMFAttributes telNoDTMFAtts = new DTMFAttributes();
private RecoAttributes telNoRecoAtts = null;
// Create a flag to control whether we continue to loop around in the voiceMain() method taking calls
private boolean keepTakingCalls = true;
// Create an instance of the Catalog class
private Catalog catalog = new Catalog();
// Create a constructor method to set up the attributes
public InApp() {
// Set the input attributes of the menu
menuAtts.setHeaderMessage(VS_MENU_HEADER);
menuAtts.setFooterMessage(VS_MENU_FOOTER);
menuAtts.setInvalidInputMessage(VS_MENU_INVALID);
menuAtts.setOneMoreRepeatMessage(VS_MENU_ONEMORE);
menuAtts.setNoMoreRepeatsMessage(VS_MENU_ERROR);
menuAtts.setTimeout(10);
menuAtts.setNumberOfRepeats(2);
// Set the DTMF attributes of the menu
menuDTMFAtts.setDelimiterKeys("");
menuDTMFAtts.setMaximumKeys(1);
Chapter 7. WebSphere Voice Response Java Tutorials 215
7 // Set the Play attributes of the menu
menuPlayAtts.setVoiceInterruptible(PlayAttributes.VOICE_ENERGY);
// Set the Reco attributes of the menu
menuRecoAtts.setContext("menuchoice");
menuRecoAtts.setBeep(false);
// Set the input attributes for getting the telephone number
telNoInputAtts.setMessage(VS_TEL_NO);
telNoInputAtts.setTimeoutMessage(VS_NOT_ENOUGH);
telNoInputAtts.setInvalidInputMessage(VS_NUMBER_INVALID);
telNoInputAtts.setOneMoreRepeatMessage(VS_ONE_MORE_TIME);
telNoInputAtts.setNoMoreRepeatsMessage(VS_NO_VALID_INPUT);
telNoInputAtts.setTimeout(10);
telNoInputAtts.setNumberOfRepeats(2);
telNoInputAtts.setValidator(PHONE_NUM_CHECKER);
// Set the DTMF attributes for getting the telephone number
telNoDTMFAtts.setDelimiterKeys("");
telNoDTMFAtts.setMaximumKeys(6);
}//InApp
/**
* voiceMain() - this is the entry point for the application
*/
public void voiceMain() throws WVRException {
// Define the Call object
Call call = null;
// Set the application properties
ApplicationProperties applicationProperties = new ApplicationProperties();
applicationProperties.setApplicationName("app1");
applicationProperties.setLocale(Locale.US);
// Create the WVR object and set the wait time
WVR wvr = new WVR(this, applicationProperties);
wvr.setWaitTime(-1);
// Create a variable that will be used to give each call a unique number
int callNumber = 0;
try {
while (keepTakingCalls) {
// Increment callNumber
callNumber++;
// Wait for a call
call = wvr.waitForCall("Call: " + callNumber);
// Create a flag to indicate whether the call is in progress
boolean callInProgress = true;
try {
// Play welcome message
call.play(VS_WELCOME);
while (callInProgress) {
// Play the menu and get the caller’s response.
InputResult input = call.playAndGetInput(menuPlayAtts, menuAtts, menuDTMFAtts, menuRecoAtts);
String choice = input.getValue();
216 Developing Java Applications
// Check which menu option has been selected and take
// the appropriate action. Each action returns a boolean
// stating whether the call should continue or not
if (choice.equals(ITEM1_MSG)) {
// Menu item 1 - record a message
callInProgress = recordMessage(call);
}
else if (choice.equals(ITEM2_NUMBER)) {
// Menu item 2 - leave a telephone number
callInProgress = leavePhoneNumber(call);
}
else if (choice.equals(ITEM3_ORDER)) {
// Menu item 3 - place an order
callInProgress = order(call);
}
else if (choice.equals(ITEM4_OPERATOR)) {
// Menu item 4 - transfer to an agent
callInProgress = operator(call);
}
else if (choice.equals(ITEM5_HANGUP)) {
// Menu item 5 - hang up
callInProgress = hangUp(call);
}
else {
// Print out the caller’s choice.
System.out.println("Caller chose option " + choice);
}//if
}//while
}
catch (WVRHungUpException e) {
// Caller has hung up - ignore exception, application will go to finally block
}
catch (WVRInvalidInputException e) {
// Caller has entered invalid input - ignore exception, application will go to finally block
}
catch (WVRException e) {
// Check if Call object has been created. If yes, play the Difficulties message.
if (call.isActive()) call.play(VS_DIFFICULTIES);
// Print debugging information
e.printStackTrace();
}
finally {
// Return the call
call.returnCall();
}//try
}//while
}
catch (WVRException e) {
// Print debugging information
e.printStackTrace();
}//try
}//voiceMain
Chapter 7. WebSphere Voice Response Java Tutorials 217
/**
* Method recordMessage.
* @param call
* @return boolean
*/
private boolean recordMessage(Call call) throws WVRException {
// Play segments to instruct the caller how to record their message
call.play(VS_RECORD);
call.play(VS_PRESS_KEY);
// Record the message
call.record(VS_CALLER_MSG, 180);
// Play a message to acknowledge the recording
call.play(VS_RESPOND);
return true;
}//recordMessage
/**
* Method leavePhoneNumber.
* @param call
* @return boolean
*/
private boolean leavePhoneNumber(Call call) throws WVRException {
try {
// Get the caller’s input - the Input Validator class created earlier will check to make sure the
// number begins with a 2
InputResult result = call.playAndGetInput(telNoPlayAtts, telNoInputAtts, telNoDTMFAtts, telNoRecoAtts);
}
catch (WVRInvalidInputException e) {
return true;
}//try
// Acknowledge a valid number
call.play(VS_THANK_YOU);
call.play(VS_CALL_BACK);
return true;
}//leavePhoneNumber
/**
* Method order.
* @param call
* @return boolean
*/
private boolean order(Call call) throws WVRException {
// Invoke the takeOrder method of the Catalog class to get the caller’s order
catalog.takeOrder(call);
return true;
}//order
218 Developing Java Applications
/**
* Method operator.
* @param call
* @return boolean
*/
private boolean operator(Call call) throws WVRException {
// Ask the caller to hold
call.play(VS_PLEASE_HOLD);
try {
// Make another call
Call consultee = call.consult("7001");
// Tell the agent they have a caller
consultee.play(VS_CALLER_FOR_YOU);
// Transfer the agent to the caller
consultee.transfer();
// No further action required, so indicate that call can end
return false;
}
catch (WVRException e) {
// Get the original caller back
call.retrieve();
// Tell the caller that an agent was not available
call.play(VS_AGENT_NOT_AVAIL);
// Continue with call
return true;
}//try
}//operator
/**
* Method hangUp.
* @param call
* @return boolean
*/
private boolean hangUp(Call call) throws WVRException {
// Thank the user for calling
call.play(VS_THANKCALLING);
return false;
}//hangUp
// Tell the application to stop taking calls when the node shuts down
public void voiceAppStop() { keepTakingCalls = false; }
public static void main(String[] args) {
// Create an instance of the InApp class and invoke the run method
InApp aInApp = new InApp();
aInApp.run();
}//main
}//InApp
Chapter 7. WebSphere Voice Response Java Tutorials 219
220 Developing Java Applications
Appendix. Using speech recognition and text-to-speech
with the WebSphere Voice Toolkit WebSphere Voice
Response simulator
Read this section if you want to develop and test Java speech-enabled
applications for WebSphere Voice Response for AIX.
The WebSphere Voice Response simulator included with Voice Toolkit for
WebSphere Studio allows you to test IVR (interactive voice response)
applications before deploying them in a production environment. The
WebSphere Voice Toolkit includes speech recognition and text-to-speech
engines that allow you to develop and test speech aware Java applications on
the simulator. The simulator accesses the speech engines via speech
technology plug-ins. Two plug-ins are provided: one for speech recognition
and one for text-to-speech. The plug-ins are automatically installed when you
install the WebSphere Voice Toolkit but they do require configuring before
use.
For information on installing the WebSphere Voice Response Simulator, see
“Installing the Voice Response simulator” on page 19.
v “Using grammars with Voice Response Java applications”
v “Speech technology engines” on page 223
v “Configuring speech technologies for the Voice Response simulator” on
page 224
v “Example configuration” on page 229
v “Deploying applications developed with the simulator” on page 229
Using grammars with Voice Response Java applications
This section describes the use of grammars with WebSphere Voice Response
Java applications, and also the reporting of problem words.
The grammars allow you to tell the speech engines what to expect from the
caller. Different speech engines use different grammar formats. The engines
included with Voice Toolkit for WebSphere Studio use the BNF grammar
format.
Each BNF grammar file contains one or more rules. Some rules are public -
these are the one that you can reference in your application, load and unload
independently. Public rules are enclosed in double angle brackets <<rule
name>>. Non-public rules are rules used by other rules and cannot be
© Copyright IBM Corp. 1998, 2008 221
independently enabled or disabled. For more information about writing
grammars, see the WebSphere Voice Toolkit documentation. You specify the
BNF file you wish to use in the RecoService for your application in the
default.cff file.
A BNF grammar file must be compiled before it can be loaded into the speech
recognition engines. The WebSphere Voice Response Simulator supports
just-in-time compilation, so you do not have to pre-compile your BNF files
before you use them. Each public rule in the BNF file results in a finite state
grammar (FSG) file, when compiled.
An alternative to specifying a BNF file in the RecoService is to specify a
directory containing pre-compiled FSG files. This allows you to use compiled
grammar files for which you do not have the source. Figure 28 on page 222
shows the relationship between the different components.
Whether you specify a BNF file or a directory of FSG files in the
configuration, it is the compiled FSG files that are loaded by the engines at
runtime. An application selects which FSG files to load by specifying the FSG
names as the contexts to use in the RecoAttributes object. For instance, your
BNF file may contain two public rules, time and date. When this file is
compiled, two FSG files are created, time.fsg and date.fsg. To use the time
rule in a recognition operation, specify a context of time. To use both the time
and date rules, specify time,date in the context.
Configuration
RecoService
Either
Or
Application
BNF Rule 1
Context.fsg
Context 1
Directory
Figure 28. Relationship between the components involved
222 Developing Java Applications
Note that the content of a BNF file is case-sensitive, whereas the Windows file
system is not. Do not specify rules such as time and Time within the same
BNF because the Windows file system treats Time.fsg and time.fsg as the
same file.
The WebSphere Voice Response Simulator does not support external lists or
flat grammar files.
For more information about developing and compiling grammars, see the
documentation for the WebSphere Voice Toolkit. Also, see WebSphere Voice
Server for AIX: Application Development with State Tables.
Problem word reporting
Problem words are the unknown words (which are not in the baseform pool),
for which the recognition engine is unable to create baseforms automatically.
The reporting of problem words is permanently enabled in the WebSphere
Voice Response simulator. Any problem words in a grammar are written out
to the following file:
websphere_voice_response_install_directory\dtj_logs\ProblemWords.txt
This file is in UTF-8 encoding.
Each time a problem word is encountered, it is appended to the end of the
file. When the information is no longer required, you should prune the file so
that it does not become too large.
Problem words occur only in DBCS languages (Chinese and Japanese),
because by default the engine does not create baseforms for unknown words
automatically. You need to supply “soundslike” information to each problem
word until the reco engine is able to load the grammar without error. For
more information on “soundslike”, see the documentation that is provided
with Voice Toolkit for WebSphere Studio.
It is possible to have automatic baseform generation in DBCS languages by
setting BaseformsSource=soundslike in the reco plugin configuration, but this
feature is disabled by default.
Speech technology engines
You specify the engines used by a voice response application that uses speech
technologies indirectly in the RecoService entry and the InitSessionString of
the plug-in, within the configuration file default.cff. For speech recognition,
you specify an engine by the language it supports. This is a string that looks
very similar to the locale string used in Java. The dtjlstvvsr script
enumerates all the languages you have installed on your system.
Appendix. Using speech recognition and TTS with the WebSphere Voice Response simulator 223
The text-to-speech plug-in supports the IBM ViaVoice Text-To-Speech engine
supplied with Voice Toolkit for WebSphere Studio.
You specify text-to-speech engines in one of two possible ways: with the
locale and product name, or with the GUID (Globally Unique Identifier) of the
text-to-speech engine mode. If you specify the GUID, you will be able to
choose different qualities of synthesized speech (for example male or female
voice) supported by the engine. If you specify an engine locale and product
name, the engine’s default mode is used. The dtjlstts script enumerates all
modes installed on your system.
Configuring speech technologies for the Voice Response simulator
When you have installed Voice Toolkit for WebSphere Studio, you must
update the WebSphere Voice Response Simulator configuration file
default.cff, and run dtjconf to make the updates effective in the
configuration database config.cfd.
The updates provide the Voice Response simulator with information about the
installed speech technologies and the grammars. The supplied configuration
file default.cff contains entries to help you get started.
Note that your configuration file may not contain sample entries if you have
elected to keep your old configuration files during an upgrade install.
For more information about how a speech service is made available to a voice
response node through the configuration entries, see Deploying and managing
VoiceXML and Java applications.
Speech recognition (RecoService entry)
You need to create a RecoService entry, for each instance of the speech
recognition plug-in. Each instance of the plug-in can handle either one BNF
grammar file or one directory of FSG grammar files. To use the speech
services defined in the RecoService entry, they must be referenced in an
application and/or a node entry in the default.cff.
For an example Recoservice configuration entry, see “RecoService example” on
page 229.
The keywords take the following values:
Enabled
This activates or deactivates the RecoService. The values are Yes or
No. The keyword is optional. The default is Yes.
InitTechnologyString
This is not used.
224 Developing Java Applications
InitSessionString
This is a comma-separated list of keyword=value pairs. The parsing of
the InitSessionString follows the usual quoting rules: embedded
spaces, commas and equal signs must be quoted or the special
characters escaped with a backslash. A backslash character must itself
be escaped with a backslash character. The following keywords are
defined:
MaxInitialSilence
This defines the maximum initial silence allowed in a
recognition operation. If the caller does not speak within this
period, from the time the prompt finishes playing, the
recognition operation fails with a time-out. This parameter is
specified in milliseconds with a default value of 5000 (5
seconds). This key is optional.
Language
This defines the language ID of the engine to use. Use the
dtjLstVVSR utility to list the languages installed. Mandatory.
BaseformsSource
This instructs the recognition engine to attempt automatic
baseform generation for any unknown words it finds. The
only valid value for this keyword is soundslike, and it is not
set by default. The keyword applies only to reco engines
running in Chinese and Japanese. The effect of specifying
BaseformsSource=soundslike is equivalent to setting the
asrp.n.Asr.baseformsSource parameter to soundslike in
VVTDefaults on the WebSphere Voice Response for AIX
system. This key is optional.
RejectionThreshold
If the score of a result returned by the speech engine is greater
than the rejection threshold, the result is passed back to the
application. If the score of the result falls below the rejection
threshold, the reco operation completes without any result.
The application sees this as an invalid result. Valid values are
between −50 and +50, which is the range of possible score
values from a WebSphere Voice Toolkit engine. The default
value is 0.
Grammar
This specifies the BNF grammar, using either a source file
name or a directory name:
v If a source file with a file extension of .BNF is specified, it is
compiled on the fly and automatically loaded into the
engine when needed. This is the most convenient way of
specifying a grammar in a test environment. The FSG files
Appendix. Using speech recognition and TTS with the WebSphere Voice Response simulator 225
resulting from the compilation are all put into a directory
named after the base name of the source file (for example,
weather.bnf will result in FSG files created in the weather
directory. The weather directory itself is created in the
directory where weather.bnf is kept). The base parts of the
FSG files are based on the names of the public rules, also
known as the root productions in the WebSphere Voice
Toolkit documentation, in the BNF source. Hence, a public
rule of "abc" will create a FSG file called "abc.fsg". Because
the Windows file system is not case-sensitive, it is
important to ensure that all the public rules within a BNF
file have distinct names regardless of the case, for example,
"start" and "end" are OK but "start" and "Start" are not, as
the files "start.fsg" and "Start.fsg" are not distinguishable
from each other under Windows.
v If a directory is specified for the Grammar key, the
simulator assumes that the user has already compiled the
grammar source and put the FSG files into the specified
directory. In both cases, the actual FSG files loaded by the
engine is determined by the contexts used in the
recognition operation: the simulator takes the context name
and adds the ".FSG" suffix to form the name of the FSG file
to load (that is, using a context of "abc" results in "abc.fsg"
being loaded into the engine). It is recommended that an
absolute path be used to specify the BNF file name or
grammar directory. In this release, only BNF grammars are
supported: there is no support for external vocabulary lists
or flat grammar files.
AlwaysRecompile
This defines the way in which WebSphere Voice Response
Simulator recompiles BNF grammar source files. The Voice
Response simulator automatically recompiles a grammar
source file when the FSG file it attempts to load is out of date
with respect to the BNF source. This will not work if the FSG
file being loaded is generated from an included BNF file. In
this situation, the master source file that needs to be
recompiled will not have the updated timestamp and
therefore will not trigger the recompile process. Setting the
AlwaysRecompile option to "true" will cause the BNF source
to be recompiled every time, before the FSG file is loaded.
This keyword has no effect if the Grammar is specified as a
directory of FSG files. The default is false. This value is
optional.
226 Developing Java Applications
InterruptVoiceOnSpeechStart
This defines the way in which voice interrupt of prompts
works. By default, when using barge-in, the voice prompt
continues to play until the caller utterance is recognized by
the speech recognition engine. You can configure the Voice
Response simulator to interrupt the voice prompt as soon as
the caller starts to speak by setting this option to True. Its
important to note that in this mode, background noise may
unintentionally interrupt the prompt. When set to true, it is
equivalent to BargeInMode=BARGEIN_SPEECH_TECH. When
set to false, it is equivalent to
BargeInMode=BARGEIN_RECO_COMPLETE on WebSphere
Voice Response for AIX.
PlugInClass
This defines the speech technology plug-in class. For the WebSphere
Voice Toolkit the class is
com.ibm.telephony.directtalk.dtsim.smapi.SRPlugIn. This string is
case-sensitive. The value is mandatory.
RecoType
This defines the name that identifies this RecoService in a
platform-dependent way. This value is mandatory.
Text-to-speech (TTSService entry)
You now need to create a TTSService entry for each instance of the
text-to-speech plug-in. To use the speech services defined in the TTSService
entry, they must be referenced in an application and/or a node entry in the
default.cff.
For an example TTSService configuration entry, see “TTSService example” on
page 229.
The keywords take the following values:
Enabled
Yes or No. Optional. Default is Yes.
InitTechnologyString
This is a comma-separated list of keyword=value pairs, where the
following keywords are defined:
LanguageMap
This is a comma-separated list of keyword-value pairs mapping Java
locales to Windows language codes. The purpose of this mapping is to
allow a user to pick an engine of a similar language when an exact
match is not available in the locale in which the application or node
runs. For example, specify fr_CA=1036 if a French-French engine is to
be used in the French-Canadian locale.
Appendix. Using speech recognition and TTS with the WebSphere Voice Response simulator 227
The InitTechnologyString is evaluated and applied once for each
TTSService definition. You must ensure that the same
InitTechnologyString is used for each plug-in class, otherwise the
values specified in one TTSService will overwrite those specified in
another entry. In the case of the Voice Response simulator, there is
currently only one text-to-speech plug-in available:
(com.ibm.telephony.directtalk.dtsim.eci.TTSECIPlugin), so all
InitTechnologyStrings in all the TTSService entries must be the same.
InitSessionString
This is a comma-separated list of keyword=value pairs, where the
following keywords are defined:
ProductName
This is the name of the text-to-speech engine.
For the WebSphere Voice Toolkit, the product name is “IBM
ViaVoice Text-to-Speech”. If not specified, an engine
supporting the requested engine locale will be picked at
random. A user can find out the list of text-to-speech engines
install on the system using the enumeration tool, dtjLstTS.
Optional.
Locale This is the operating locale of the text-to-speech engine.
Required if GUID is not specified.
GUID This is the global universal identifier of the engine mode as
given by the enumeration tool, It overrides the Locale and
ProductName information. Required if Locale is not specified.
The parsing of the InitTechnologyString and InitSessionString
follows the usual quoting rules: embedded spaces, commas
and equal signs must be quoted or the special characters
escaped with a backslash. A backslash character must itself be
escaped with a backslash character.
PlugInClass
This is the technology plug-in Java class
com.ibm.telephony.directtalk.dtsim.eci.TTSECIPlugin
TTSType
This is a name that identifies this TTSService in a
platform-independent way. This key is mandatory.
228 Developing Java Applications
Example configuration
RecoService example
This example sets up a speech recognition plug-in to use a UK-English engine
and the BNF grammar source file weather.bnf. The maximum initial delay
allowed before a user must speak is 5 seconds.
RecoService=DTSim_weather_en_GB
Enabled=yes
InitSessionString=Language=en_uk,Grammar=weather.bnf,MaxInitialSilence=5000
PlugInClass=com.ibm.telephony.directtalk.dtsim.smapi.SRPlugIn
RecoType=weather_en_GB
;
TTSService example
This example sets up a text-to-speech plug-in in the en_GB locale.
TTSService=DTSim_TTS_en_GB
Enabled=yes
InitSessionString=ProductName=“IBM ViaVoice Text-to-Speech”,Locale=en_GB
PlugInClass=com.ibm.telephony.directtalk.dtsim.eci.TTSECIPlugin
TTSType=TTS_en_GB
;
This example sets up a text-to-speech plug-in in the en_GB locale. Normally
the en_GB locale would require a UK English engine (Windows language
code of 2057). In this case the InitTechnologyString overrides the default
mapping via an explicit LanguageMap, causing a US English (Windows
language code of 1033) engine to be used instead.
TTSService=DTSim_TTS_en_GB
Enabled=yes
InitTechnologyString=LanguageMap=en_GB=1033
InitSessionString=ProductName=“IBM ViaVoice Text-to-Speech”,Locale=en_GB
PlugInClass=com.ibm.telephony.directtalk.dtsim.eci.TTSECIPlugin
TTSType=TTS_en_GB
;
Deploying applications developed with the simulator
The main difference between the WebSphere Voice Response Simulator and a
base WebSphere Voice Response system is in the way grammars are specified
to the speech engines. It is easy to develop a speech application on the Voice
Response simulator and then deploy it on a real WebSphere Voice Response
system if you follow a few guidelines:
1. Let each speech-aware application have its own RecoService entry - this
allows you to specify a separate BNF grammar file for each application.
Typically, only a single TTSService entry is needed for each language you
use.
2. Create a library of frequently-used rules. As long as the rules have distinct
names, you can share them among several applications by including them
Appendix. Using speech recognition and TTS with the WebSphere Voice Response simulator 229
into the BNF file that you use for each of your application. Remember that
in the Voice Response simulator each name in the context you specify in
the RecoAttributes represents one grammar rule.
To deploy the application, you need to copy the BNF grammar file to a base
WebSphere Voice Response system. You must then compile the grammar,
create the pronunciation dictionary and pronunciation pool for the grammar,
and create a context profile to access the grammar files on the WebSphere
Voice Server speech recognition server.
If you followed the guidelines above, then each rule used by your application
is represented by one context in the context profile. Each context references
one LST file which points to the FSG file for the rule.
For further information, see WebSphere Voice Server for AIX: Application
Development with State Tables.
230 Developing Java Applications
Notices
This information was developed for products and services offered in the
U.S.A.
IBM may not offer the products, services, or features discussed in this
document in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or
imply that only that IBM product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe
any IBM intellectual property right may be used instead. However, it is the
user’s responsibility to evaluate and verify the operation of any non-IBM
product, program, or service.
IBM may have patents or pending patent applications covering subject matter
in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to:
The IBM Director of Licensing, IBM Corporation, North Castle Drive,
Armonk, NY 10504-1785, U.S.A.
The following paragraph does not apply to the United Kingdom or any
other 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.
© Copyright IBM Corp. 1998, 2008 231
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the
purpose of enabling: (i) the exchange of information between independently
created programs and other programs (including this one) and (ii) the mutual
use of the information which has been exchanged, should contact: IBM UK
Limited, Department 88013, Legal, 4NW, 76/78 Upper Ground, London,
SE1 9PZ, England. Such information may be available, subject to appropriate
terms and conditions, including, in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer
Agreement, IBM International Program License Agreement or any equivalent
agreement between us.
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.
COPYRIGHT LICENSE: This information contains sample application
programs in source language, which illustrates programming techniques on
various operating platforms. You may copy, modify, and distribute these
sample programs in any form without payment to IBM, for the purposes of
developing, using, marketing or distributing application programs conforming
to the application programming interface for the operating platform for which
the sample programs are written. These examples have not been thoroughly
tested under all conditions. IBM, therefore, cannot guarantee or imply
reliability, serviceability, or function of these programs. You may copy, modify,
and distribute these sample programs in any form without payment to IBM
for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM’s application programming interfaces.
232 Developing Java Applications
Trademarks
The following terms are trademarks of IBM Corporation in the United States
or other countries or both:
AIX DB2 DirectTalk
IBM ViaVoice WebSphere
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
Other company, product or service names may be trademarks or service
marks of others.
Notices 233
234 Developing Java Applications
Glossary
The following terms and abbreviations are defined as they are used in the context of
WebSphere Voice Response. If you do not find the term or abbreviation you are looking for,
see IBM Dictionary of Computing, McGraw-Hill, 1994 or the AIX: Topic Index and Glossary,
SC23–2513.
Special Characters
µ-law. The companding algorithm that is used
primarily in North America and Japan when
converting from analog to digital speech data.
(Compand is a contraction of compress and
expand.) Contrast with A-law.
Numerics
2 B-channel transfer feature. See Integrated
Services Digital Network (ISDN) two B-channel
transfer.
3270 host application. An application on the
IBM System/370™ System/390®, or AS/400® that
interacts with terminals that support the 3270
data stream.
3270 script language. See script language.
3270 server. A function of WebSphere Voice
Response that provides a software interface
between WebSphere Voice Response and IBM
System/370, System/390, or AS/400 architecture
business applications that interact with terminals
that support the 3270 data stream. Contrast with
custom server.
5ESS. (1) A Lucent Technologies switch. (2) The
ISDN protocol that is used on the 5ESS switch. It
provides 23 B-channels and a D-channel over a
T1 trunk.
6309 Digital Trunk Quad Adapter. See Digital
Trunk Quad Adapter.
6310 Digital Trunk Extended Adapter (DTXA).
See Digital Trunk Extended Adapter.
6312 Digital Trunk Telephony Adapter
(DTTA). See Digital Trunk Telephony Adapter.
6313 Digital Trunk Telephony Adapter (DTTA)
with Blind Swap Cassette (BSC). See Digital
Trunk Telephony Adapter with Blind Swap
Cassette.
A
A-law. The companding algorithm that is used
in Europe, Latin America, and other countries
when converting from analog to digital speech
data. (Compand is a contraction of compress and
expand.) Contrast with µ-law.
access protocol. A protocol that is used between
an external subscriber and a switch in a
telephone network.
ACD. See automatic call distributor.
ACL. See application connectivity link.
action. See state table action.
Action Palette. An area that contains folders
and icons that can be selected to create state
table actions.
Address Resolution Protocol (ARP). In
HACMP, the Internet communication protocol
that dynamically maps Internet addresses to
physical (hardware) addresses on local area
networks. Limited to networks that support
hardware broadcast.
The usr/sbin/cluster/etc/clinfo.rc script, which is
invoked by the clinfo daemon whenever a
network or node event occurs, updates the
system ARP cache. This ensures that the IP
© Copyright IBM Corp. 1998, 2008 235
addresses of all cluster nodes are updated after
an IP address takeover. The script can be further
customized to handle site-specific needs.
administrator profile. Data that describes a
WebSphere Voice Response user. Information that
is in an administrator profile includes ID,
password, language preference, and access
privileges.
ADSI. See analog display services interface.
ADSI telephone. A “smart” telephone that can
interpret and return ADSI data.
advanced intelligent network (AIN). A
telephone network that expands the idea of the
intelligent network (IN) to provide special services
more efficiently; for example, by giving users the
ability to program many of the services
themselves.
AIN. See advanced intelligent network.
alarm. Any condition that WebSphere Voice
Response thinks worthy of documenting with an
error message. Strictly, the term alarm should
include only red (immediate attention) and
yellow (problem condition), but it is also used to
refer to green (a red or yellow message has been
cleared) and white (information) conditions.
Contrast with alert.
alert. A message that is sent to a central
monitoring station, as the result of an alarm.
Contrast with alarm.
alternate mark inversion (AMI). A T1 line
coding scheme in which binary 1 bits are
represented by alternate positive and negative
pulses and binary 0 bits by spaces (no pulse).
The purpose is to make the average dc level on
the line equal to zero.
AMI. See alternate mark inversion.
analog. Data in the form of continuously
variable signals, such as voice or light signals.
analog display services interface (ADSI). A
Bellcore signaling protocol that is used with
existing voice networks. ADSI supports analog
transmission of voice and text-based information
between a host or switch, voice mail system,
service bureau, or similar, and a subscriber’s
ADSI-compatible screen telephone. A single
voice-grade telephony channel is shared between
voice and data, using a technique by which the
channel is taken over for the transmission of
modem-encoded data.
ANI. See automatic number identification.
annotation. In speech recognition, an
alphanumeric string that is used to mark a
grammar when it is defined. When the grammar
is used in an application, both the word and the
alphanumeric string are returned to the
application.
announcement-only greeting. In voice mail, a
greeting that does not give the caller a chance to
leave a voice message.
application. A (usually) customer-written
program or set of programs that might consist of
one or more state tables or custom servers that
are running on WebSphere Voice Response, with
associated voice segments. See voice application.
application connectivity link (ACL). A service
that transmits out-of-band information between
WebSphere Voice Response and the Siemens
Hicom 300 switch.
application profile. Data that describes initial
actions that are to be performed when the
telephone is answered. Information in an
application profile indicates to the channel
process which state table to load.
application server interface (ASI). The
principal software component of WebSphere
Voice Response that manages the real-time
channel processing.
application server platform (ASP). A platform
that is used for Web and voice applications for
e-business.
ARTIC960RxD Quad Digital Trunk PCI
Adapter. See Digital Trunk Extended Adapter.
ASI. See application server interface.
glossary
236 Developing Java Applications
ASP. See application server platform.
audio name. The audible name that relates to a
specific application profile ID and mailbox.
auto-attendant. Automated attendant. A voice
application that answers incoming calls and asks
callers which number or other service they
would like.
automatic call distributor (ACD). A telephone
system feature that automatically queues and
processes inbound calls according to predefined
rules. For example, a call might be routed to the
agent whose line has been idle longest.
automatic number identification (ANI). A
service available in the U.S. that provides the
telephone number of the calling party. It is
generated by the caller’s originating central office
switch, sent to a telephone network carrier if
required, then sent directly either to a switch or
to a voice processing system.
autostubbing. A state table icon view utility
that automatically converts lines into stubs when
they cross a specified number of columns.
B
B8ZS. Bipolar with 8-zero substitution. A T1
line code that is required for 64Kb channels such
as ISDN.
B-channel. See bearer channel. See also Integrated
Services Digital Network (ISDN) .
background music. Any audio data that is to be
played on a music channel.
barge-in. The capability that allows a prompt to
be interrupted by an utterance that is then
passed to a speech recognizer. See also
cut-through channel.
baseforms. The set of phonetic pronunciations
that are associated with a grammar. In
WebSphere Voice Server, the IBM dictionary of
pronunciations is used.
basic rate interface (BRI). The means of ISDN
access that is normally used by private
subscribers. It provides two B-channels of 64 Kb
per second and one D-channel of 16 Kb per
second for signaling. This is often known as
2B+D. Contrast with primary rate interface (PRI).
beans. Java beans with which you can build
voice applications to use the services of
WebSphere Voice Response on any platform.
bearer channel. In an ISDN interface, a duplex
channel for transmitting data or digital voice
between the terminal and the network. The
B-channel operates at 64 Kb per second.
bearer service. The type of service that defines
how an ISDN connection will be used. Typical
bearer services are speech telephony, 64 Kb per
second data, and high-quality speech.
blind transfer. A type of call transfer in which
the call is routed to another extension and the
original call is ended. No check is made to
determine whether the transferred call is
answered or if the number is busy. Contrast with
screened transfer.
bnf. Abbreviation for Backus-Naur Form, which
is used to describe the syntax of a given
language and its notation. In speech recognition,
a special adaptation of grammar representation
that is specified by Speech Recognition Control
Language (SRCL) (pronounced “circle”).
bos. Base Operating System.
bps. bits per second.
BRI. See basic rate interface.
bridge. See DVT bridge.
British Approvals Board for
Telecommunications. The British standards
organization that is responsible for approval of
equipment that is to be attached to the PSTN.
C
cadence. The modulated and rhythmic
recurrence of an audio signal. For example, a
series of beeps or a series of rings.
glossary
Glossary 237
call. Telephone call. Often used to mean a single
run-time instance of a voice application.
call center. A central point at which all inbound
calls are handled by a group of individuals in a
controlled sequential way. Call centers are
usually a front end to a business such as airline
ticketing or mail order.
Call Control eXtensible Markup Language
(CCXML). Language designed to provide
telephony call control support for VoiceXML or
other dialog systems. Refer to the CCXML forum
web site at http://www.w3.org/TR/ccxml
call forwarding. The process of sending
incoming calls to a different number.
called party. Any person, device, or system that
receives a telephone call. Contrast with caller.
caller. (1) Any person, device, or system that
makes a telephone call. (2) Often used to refer to
any user of a voice application, although
WebSphere Voice Response might have made an
outbound call and the user is really the called
party. (3) In voice mail, any person who makes a
telephone call to a subscriber. Contrast with user.
calling line identification presentation (CLIP).
An ISDN supplementary service that advises the
called party of the caller’s number; for example,
by displaying it on a telephone display panel.
CallPath. Software that provides basic
computer-telephony integration (CTI) enablement
and comprehensive CTI functionality. This
includes access to, and management of, inbound
and outbound telecommunications.
call session. The sequence of events that occurs
from the time a call is started to the time all
activities related to answering and processing the
call are completed.
call transfer. A series of actions that directs a
call to another telephone number. See also
dual-line call transfer.
CAS. See channel associated signaling.
cascading resources. Resources that can be
taken over by more than one node. A takeover
priority is assigned to each configured cluster
resource group in a per-node way. In the event of
a takeover, the node with the highest priority
gets the resource group. If that node is
unavailable, the node with the next-highest
priority gets the resource group, and so on.
CAS tone. Customer Premise Equipment
Alerting Signal tone. In ADSI, this tone is sent to
the ADSI telephone to switch the phone to data
mode.
CBX. See computerized branch exchange.
CCH. See Comité de Coordination de
l’Harmonisation.
CCITT. See Comité Consultatif International
Télégraphique et Téléphonique.
CCS. See common channel signaling (CCS).
central office (CO). A telephone switching
system that resides in the telephone service
provider’s network. Different types of central
office switches exist, depending upon the role of
the switch in the telephone network. Commonly,
a central office switch connects customer lines to
other customer lines or trunks, and is the point
at which local subscriber lines end for switching
to other lines or trunks.
central registry. A component of the Licence
Use Management network topology. A server’s
database that logs requests for licenses, upgrades
for licenses, and journals all license activity in a
tamper-proof auditable file.
CEPT. See Conference Européenne des
Administrations des Postes et Télécommunications.
CGI. See Common Gateway Interface.
channel. One of the 24 channels that are on a
T1 trunk, or one of the 30 channels that are on
an E1 trunk. See also speech recognition session,
music channel.
channel-associated signaling (CAS). A method
of communicating telephony supervisory or line
glossary
238 Developing Java Applications
signaling (on-hook and off-hook) and address
signaling on T1 and E1 digital links. The
signaling information for each traffic (voice)
channel is transmitted in a signaling channel that
is permanently associated with the traffic
channel. On T1 links, supervisory signaling is
sent in the traffic channel by using robbed-bit
signaling (RBS). On E1 links, a separate channel is
used to send signaling. Address signaling can be
transmitted either in the signaling channel
(out-of-band) or in the traffic channel (in-band).
Contrast with common channel signaling (CCS).
channel bank. A device that converts an analog
line signal to a digital trunk signal.
channel number. The identifying number that is
assigned to a licensed channel on the T1 or E1
trunk that connects WebSphere Voice Response to
the switch, channel bank, or channel service unit.
channel process (CHP). The AIX process that
runs the logic of the state table; each active caller
session has one active channel process.
channel service unit (CSU). A device that is
used to connect a digital phone line to a
multiplexer, a channel bank, or directly to
another device that generates a digital signal. A
CSU performs specific line-conditioning and
equalization functions, and responds to loopback
commands that are sent from the CO.
CHP. See channel process.
CIC. See circuit identification code.
CICS. See customer information control system.
circuit identification code (CIC). A 12-bit
number that identifies a trunk and channel on
which a call is carried.
clear message. A message that is displayed by
WebSphere Voice Response to tell the operator
that a red or yellow error message has been
cleared.
client node. In a single system image (SSI), a
WebSphere Voice Response system that handles
interactions with callers. A client node must have
a telephony connection. It does not store
application or voice data; it gets data from the
server node of the SSI.
CLIP. See calling line identification presentation.
cluster. Loosely-coupled collection of
independent systems (nodes) that are organized
into a network to share resources and to
communicate with each other. HACMP defines
relationships among cooperating systems where
peer cluster nodes provide the services that a
cluster node offers if that node cannot do so.
cluster configuration. User definition of all
cluster components. Component information is
stored in the Object Data Manager. Components
include cluster name and ID, and information
about member nodes, adapters, and network
modules.
CO. See central office.
codec. Refers to adapters that compress and
decompress video files. The letters ″codec″
represent ″compression/decompression″; in the
past, they represented ″coder/decoder.″
Comité de Coordination de l’Harmonization.
The CEPT committee responsible for standards.
Comitato Elettrotechnico Italiano. The Italian
standards organization responsible for signaling
protocols.
Comité Consultatif International Télégraphique
et Téléphonique (CCITT). This organization
has been renamed and is now known as the
International Telecommunications Union -
Telecommunication Standardization Sector
(ITU-T).
common channel signaling (CCS). A method of
communicating telephony information and line
signaling events (for example, call setup and call
clearing) on a dedicated signaling channel. The
signaling channel is either a predefined channel
on an E1 or T1 digital link, or a completely
separate link between the switch and WebSphere
Voice Response. For data integrity and reliability,
the information is usually communicated using a
data link protocol. The telephone information
glossary
Glossary 239
and line signaling events are sent as data
packets. SS7 and ISDN are common-channel
signaling protocols. Contrast with channel
associated signaling.
Common Gateway Interface (CGI). An
interface to programs that provide services on
the world wide Web.
compiled grammar file. A grammar in binary
format that was built by the WebSphere Voice
Server grammar development tools.
compound license. In License Use
Management, a type of license that allows a
system administrator to generate license
passwords for a given number of licenses. A
compound license can generate either
nodelocked or non-nodelocked licenses, but not
both
computer-telephony integration (CTI). The use
of a general-purpose computer to issue
commands to a telephone switch to transfer calls
and provide other services. Typically, CTI is used
in call centers.
computerized branch exchange (CBX). A
computer-driven, digital communications
controller that provides telephone
communication between internal stations and
external networks.
Conférence Européenne des Administrations
des Postes et Télécommunications (CEPT).
European Conference of Postal and
Telecommunications Administrations.
configuration file. See parameter file.
configuration parameter. A variable that controls
the behavior of the system or the behavior of all
applications that are running on the system. See
parameter file, system parameter.
container window. A window that lists the
names of all existing objects of the same type.
context. A set of one or more grammars that is
enabled and used during a recognition action.
The grammars are specified by a FILELIST file.
Parameters that influence the recognition, such as
the maximum initial silence period and the
ending silence period, are also defined by the
context. More than one context can be enabled
for a recognition.
context name. The name given to a context in a
context profile that is used for WebSphere Voice
Server.
context profile. Describes to the WebSphere
Voice Server process which contexts should be
loaded into an engine. A WebSphere Voice
Response for Windows application specifies
which context profiles to load into the engine it
has reserved.
context type. Indicates to the recognition engine
how to interpret the grammar file. Possible types
are: VOCAB_FILE, GRAMMAR_FILE, TEXT,
MNR_FILE, MNR, PERSONAL_FILE,
PERSONAL_WDS, BASEFORM_FILE.
continuous speech recognition. Recognition of
words that are spoken in a continuous stream.
Unlike isolated or discrete word recognition,
users do not have to pause between words.
conversation. See speech recognition session.
CPE. See customer premises equipment.
CSU. See channel service unit .
CTI. See computer-telephony integration.
customer information control system (CICS). A
licensed program that enables transactions that
are entered at remote workstations to be
processed concurrently by user-written
application programs. It includes facilities for
building, using, and maintaining databases.
custom server. A C language or C++ language
program that provides data manipulation and
local or remote data stream, database, or other
services that are additional to those that the state
table interface provides. Custom servers provide
an interface between WebSphere Voice Response
and business applications, functions, or other
processes to give callers access to business
information and voice processing functions such
as speech recognition.
glossary
240 Developing Java Applications
customer premises equipment (CPE).
Telephony equipment that is on the premises of a
business or domestic customer of the telephone
company. An example is a private branch
exchange (PBX).
cut-through channel. A channel of voice data
that has been passed through echo-cancellation
algorithms. The channel provides echo-canceled
voice data that can then be used by the engine in
a recognition attempt. This is similar to barge-in.
D
daemon. In the AIX operating system, a
program that runs unattended to perform a
standard service.
database server node. In a single system image
(SSI), a WebSphere Voice Response system that
contains the WebSphere Voice Response DB2®
database. This is usually the same node as the
voice server node.
DBIM. The internal database manager of
WebSphere Voice Response.
DBS. The database server of WebSphere Voice
Response.
DCBU. See D-channel backup.
D-channel. See delta channel.
D-channel backup (DCBU). An ISDN NFAS
configuration where two of the T1 facilities have
a D-channel, one of which is used for signaling,
and the other as a backup if the other fails. See
also non-facility associated signaling.
DDI. See direct inward dialing.
DDS. See production system.
delay start. A procedure that is used with some
channel-associated signaling protocols to indicate
when a switch or PABX is ready to accept
address signaling. After seizure, the switch sends
off-hook until it is ready to accept address
signaling, at which time it sends on-hook.
Contrast with immediate start and wink start.
delta channel. In an ISDN interface, the
D-channel or delta channel carries the signaling
between the terminal and the network. In a basic
rate interface, the D-channel operates at 16 Kb
per second. In a primary rate interface, the
D-channel operates at 64 Kb per second.
destination point code (DPC). A code that
identifies the signaling point to which an MTP
signal unit is to be sent. Unique in a particular
network.
development system. A WebSphere Voice
Response system that is not used to respond to,
or make, “live” calls; it is used only to develop
and test applications. Contrast with production
system.
dial. To start a telephone call. In
telecommunication, this action is performed to
make a connection between a terminal and a
telecommunication device over a switched line.
dial by name. To press the keys that are related
to subscribers’ names instead of to their
telephone numbers or extensions.
dialed number identification service (DNIS). A
number that is supplied by the public telephone
network to identify a logical called party. For
example, two toll-free numbers might both be
translated to a single real number. The DNIS
information distinguishes which of the two
toll-free numbers was dialed.
dialog box. A secondary window that presents
information or requests data for a selected action.
dial tone. An audible signal (call progress tone)
that indicates that a device such as a PABX or
central office switch is ready to accept address
information (DTMF or dial pulses).
DID. See direct inward dialing.
digital signal processing (DSP). A set of
algorithms and procedures that processes
electronic signals after their conversion to digital
format. Because of the specific mathematical
models that are required to perform this
processing, specialized processors are generally
used.
glossary
Glossary 241
Digital Subscriber signaling System Number 1
(DSS1). A signaling protocol that is used
between ISDN subscriber equipment and the
network. It is carried on the ISDN D-channel.
ITU-T recommendations Q.920 to Q.940 describe
this protocol.
Digital Trunk Ethernet Adapter (DTEA). A
Radysis adapter card that provides the audio
streaming (RTP) interface between the
WebSphere Voice Response internal H.100 bus
and Ethernet for a maximum of 120 channels
using uncompressed (G.711) voice, and
compressed G.723.2 and G.729A compressed
voice.
Digital Trunk Extended Adapter (DTXA). The
IBM ARTIC960RxD Quad Digital Trunk PCI
Adapter. In WebSphere Voice Response, this
adapter is known as a DTXA. It allows you to
connect directly to the telephony network from a
pSeries computer without the need for an
external pack.
Digital Trunk No Adapter (DTNA). A software
implementation of the DTEA that only supports
uncompressed (G.711) voice.
Digital Trunk Telephony Adapter (DTTA). The
IBM Quad Digital Trunk Telephony PCI Adapter.
In WebSphere Voice Response, this adapter is
known as a DTTA. It allows you to connect
directly to the telephony network from a pSeries
computer without the need for an external pack.
The DTTA supersedes the DTXA.
Digital Trunk Telephony Adapter (DTTA) with
Blind Swap Cassette (BSC). The IBM Quad
Digital Trunk Telephony PCI Adapter. In
WebSphere Voice Response, this adapter is
known as a DTTA. It allows you to connect
directly to the telephony network from a pSeries
computer without the need for an external pack.
This DTTA includes a short Blind Swap Cassette
(BSC) which is required for installing the DTTA
in machines that use the BSC (for example, the
pSeries 650–6M2).
Digital Trunk Quad Adapter (DTQA). (Feature
code 6309) An adapter that completes the
connection to four packs in a Multiple Digital
Trunk Processor.
diphone. A transitional phase from one sound
to the next that is used as a building block for
speech synthesis. Typically, between one
thousand and two thousand diphones exist in
any national language.
direct dial in (DDI). See direct inward dialing.
direct inward dialing (DID). A service that
allows outside parties to call directly to an
extension of a PABX. Known in Europe as direct
dial in (DDI).
direct speech recognition. Identification of
words from spoken input that are read directly
from the telephony channel. Contrast with
indirect speech recognition.
DirectTalk bean. One of the beans that is
provided with WebSphere Voice Response. It
provides access from a voice application to
simple call control functions: waiting for a call,
making an outgoing call, handing a call over to
another application, and returning a call when
finished.
discrete word recognition. Identification of
spoken words that are separated by periods of
silence, or input one at a time. Contrast with
continuous speech recognition.
disconnect. To hang up or terminate a call.
Distributed Voice Technologies (DVT). A
component of WebSphere Voice Response that
provides an interface to allow you to integrate
your own voice technology (such as a speech
recognizer) with your WebSphere Voice Response
system.
distribution list. In voice mail, a list of
subscribers to whom the same message can be
sent.
DMS100. (1) A Northern Telecom switch. (2)
The custom ISDN protocol that is run on the
glossary
242 Developing Java Applications
DMS100 switch, providing 23 B-channels and a
D-channel over a T1 trunk.
DNIS. See dialed number identification service.
double-trunking. See trombone.
down. The condition in which a device is
unusable as a result of an internal fault or of an
external condition, such as loss of power.
downstream physical unit (DSPU). Any remote
physical unit (data link, storage, or input/output
device) that is attached to a single network host
system.
DPC. See destination point code.
drop-in grammar. A set of precompiled
grammar rules that can be used by an
application-specific grammar to improve the
recognition performance.
DSP. See digital signal processing.
DSPU. See downstream physical unit.
DSS1. See Digital Subscriber signaling System
Number 1.
DTMF. See dual-tone multifrequency.
DTEA. See Digital Trunk Ethernet Adapter.
DTNA. See Digital Trunk No Adapter.
DTQA. See Digital Trunk Quad Adapter.
dtuser. The name of the AIX account that is set
up during the installation process for the use of
all users of WebSphere Voice Response.
DTTA. See Digital Trunk Telephony Adapter.
DTXA. See Digital Trunk Extended Adapter.
dual-line call transfer. A call transfer method in
which the primary and secondary lines remain
bridged until a call is completed. (Also known as
tromboning: see trombone).
dual-tone multifrequency (DTMF). The signals
are sent when one of the telephone keys is
pressed. Each signal is composed of two different
tones.
DVT. See Distributed Voice Technologies.
DVT bridge. The interface between a voice
technology component (such as a speech
recognizer) and the DVT server. A bridge must
exist for each technology that you want to
integrate with DVT.
DVT_Client2. A WebSphere Voice Response
custom server that passes commands and data to
DVT_Server.
DVT interface. A WebSphere Voice Response
programming interface that is used by a DVT
bridge. It enables integration of voice
applications with Distributed Voice Technologies to
provide functions such as speech recognition.
DVT_Server. A component of DVT that
allocates and manages system resources in
response to requests from DVT_Client2.
DVT service. The combination of a voice
application, a DVT bridge, and a voice
technology that allows a caller to interact with
your business.
dynamic vocabulary. A vocabulary that is
defined while an application is running.
E
E&M. A channel-associated signaling protocol
in which signaling is done using two leads: an
M-lead that transmits battery or ground and an
E-lead that receives open or ground.
E1. A digital trunking facility standard that is
used in Europe and elsewhere. It can transmit
and receive 30 digitized voice or data channels.
Two additional channels are used for
synchronization, framing, and signaling. The
transmission rate is 2048 Kb per second. Contrast
with T1.
glossary
Glossary 243
echo cancelation. A filter algorithm that
compares a copy of the voice data that is being
sent to a caller, with the voice data being that is
received from the caller. Any echo of the sent
data is removed before the received data is sent
on, for example, to a speech recognizer.
edge. See result.
EDL. See exchange data link.
emulation. The imitation of all or part of one
computer system by another, so that the
imitating system accepts the same data, runs the
same programs, and gets the same results as the
imitated computer system does.
endpoint. In Voice over Internet Protocol, a place
where calls are originated and ended.
engine. A speech recognition process that
accepts voice data as input and returns the text
of what was said as output. It is the process that
performs the recognition.
engine type. Each engine must be configured
with a specific type. The type is a textual tag that
is associated with a specific engine and does not
change the operation or functionality of the
engine.
error message. Any message that is displayed
by WebSphere Voice Response in the System
Monitor as an alarm and optionally written to the
WebSphere Voice Response error log, or to the
AIX error log (as an alert). Strictly, the term error
message should include only red (immediate
attention) and yellow (problem situation)
messages, but it is also used to refer to green (a
red or yellow message has been cleared) and
white (informational) messages.
Ethernet. A 10/100 network connection between
the VoIP gateway and the Speech Server that
supports VoIP.
ETS. European Telecommunications Standard or
European Telecommunication Specification.
ETSI. European Telecommunications Standards
Institute.
Euro-ISDN. The common European ISDN
standard, agreed in 1993, that provides a basic
range of services and supplementary services
using 30 B-channels plus a D-channel over an E1
trunk.
exchange data link. A serial connection that
carries messaging information between
WebSphere Voice Response and the Lucent
Technologies 1AESS, Northern Telecom DMS100,
Ericsson MD110 switch, or Siemens Hicom 300.
exit. A point in a supplied application from
which control can be passed to another
custom-written application. On completion, the
custom-written application passes control back to
the supplied application.
F
fade in. To gradually increase the volume of
sounds, such as background music.
fade out. To gradually decrease the volume of
sounds, such as background music.
failover. A transparent operation that, in the
event of a system failure, switches responsibility
for managing resources to a redundant or
standby system. Also known as fallover.
FDM. See Feature Download Management.
Feature Download Management (FDM). An
ADSI protocol that enables several alternative
key and screen overlays to be stored in an ADSI
telephone, and to be selected by predetermined
events at the telephone.
Federal Communication Commission (FCC).
The standard body in the United States that is
responsible for communication.
field. An identifiable area in a window that is
used to enter or display data.
FILELIST. A WebSphere Voice Server Telephony
runtime file that defines which files to load into
a WebSphere Voice Server engine. It contains a
list in the form:
context type grammar filename
glossary
244 Developing Java Applications
... ...
Recursion is not permitted; that is, no contexts of
type FILELIST can be specified in a FILELIST.
When a FILELIST is loaded, all the grammars
that are specified in it are loaded into the engine.
From then on, the grammars that are loaded
when the FILELIST is specified are regarded as a
single context.
Foreign Exchange Subscriber (FXS). A
signaling protocol that links a user’s location to a
remote exchange that would not normally be
serving that user, to provide, for example, calls
to outside the local area at the local rate.
frame. A group of data bits that is surrounded
by a beginning sequence and an ending
sequence.
fsg. Abbreviation for finite state grammar. In
WebSphere Voice Server, the extension of a file
that contains grammar specifications in compiled,
binary form. It is generated from a .bnf file and
is called a .fsg file.
function. In ADSI, an ADSI instruction or group
of instructions.
FXS. See Foreign Exchange Subscriber.
G
gatekeeper. A component of a Voice over Internet
Protocol that provides services such as admission
to the network and address translation.
gateway. A component of Voice over Internet
Protocolthat provides a bridge between VoIP and
circuit-switched environments.
G.711. Specification for uncompressed voice for
PSTN and Voice over Internet Protocol access.
G.723.1. Compressed audio codecs that are used
on Voice over Internet Protocol connection for
voice.
G.729A. Compressed audio codecs that are used
on Voice over Internet Protocol connection for
voice.
glare. A condition that occurs when both ends
of a telephone line or trunk are seized at the
same time.
grammar. A structured collection of words and
phrases that are bound together by rules. A
grammar defines the set of all words, phrases,
and sentences that might be spoken by a caller
and are recognized by the engine. A grammar
differs from a vocabulary in that it provides rules
that govern the sequence in which words and
phrases can be joined together.
greeting. In voice mail, the recording that is
heard by a caller on reaching subscriber’s
mailbox. See also announcement-only greeting.
Contrast with voice message.
greeting header. In voice mail, a recording that
is made by a subscriber and played to callers
either before or instead of a personal greeting.
Groupe Special Mobile (GSM). A CEPT/CCH
standard for mobile telephony.
H
HACMP (High-Availability Cluster
Multi-Processing) for AIX. Licensed Program
Product (LPP) that provides custom software that
recognizes changes in a cluster and coordinates
the use of AIX features to create a
highly-available environment for critical data and
applications.
HACMP/ES. Licensed Program Product (LPP)
that provides Enhanced Scalability to the
HACMP for AIX LPP. An HACMP/ES cluster
can include up to 32 nodes.
hang up. To end a call. See also disconnect.
HDB3. High-density bipolar of order 3. An E1
line coding method in which each block of four
successive zeros is replaced by 000V or B00V, so
that the number of B pulses between consecutive
V pulses is odd. Therefore, successive V pulses
are of alternate polarity so that no dc component
is introduced. Note: B represents an inserted
pulse that observes the alternate mark inversion
glossary
Glossary 245
(AMI) rule and V represents an AMI violation.
HDB3 is similar to B8ZS that is used with T1.
HDLC. See high-level data link control.
high-level data link control. An X.25 protocol.
homologation. The process of getting a
telephony product approved and certified by a
country’s telecommunications authority.
hook flash. A signal that is sent to a switch to
request a switch feature (such as call transfer).
host application. An application residing on the
host computer.
hunt group. A set of telephone lines from which
a non-busy line is found to handle, for example,
an incoming call.
I
immediate start. A procedure that is used with
some channel-associated signaling protocols,
when the address signaling is sent within 65
milliseconds of going off-hook. Contrast with
delay start and wink start.
IN. See intelligent network.
in-band. In the telephony voice channel, signals
are said to be carried in-band. Contrast with
out-of-band.
indirect speech recognition. Identification of
words from spoken input that are read from a
file. Contrast with direct speech recognition.
initialize. To prepare a system, device, or
program for operation; for example, to initialize
a diskette.
input parameter. Data that is received by a
program such as a prompt, 3270 script, custom
server, or state table from the program that
called it. Contrast with local variable and system
variable.
integrated messaging. A messaging system in
which more than one copy of a single message is
stored, the copies being kept synchronized by the
applications that are used to access them.
Contrast with unified messaging.
Integrated Services Digital Network (ISDN). A
digital end-to-end telecommunication network
that supports multiple services including, but not
limited to, voice and data.
Integrated Services Digital Network (ISDN) call
transfer. In WebSphere Voice Response, an
application that allows you to transfer calls on
Nortel DMS-100 switches using Integrated Services
Digital Network (ISDN) two B-channel transfer, and
on Nortel DMS-100 and DMS-250 switches using
Nortel’s proprietary Release Link Trunk (RLT)
call transfer protocol.
Integrated Services Digital Network (ISDN)
two B-channel transfer. A call transfer feature
that is defined by Bellcore GR-2865-CORE
specification, and used on Nortel and Lucent
switches.
Integrated Services Digital Network user part
(ISUP). Part of the SS7 protocol that supports
telephony signaling applications. The ISDN user
part is defined to carry signaling information
that relates to digital telephones, terminals, and
PABXs in customer premises.
intelligent network (IN). A telephone network
that includes programmable software that is not
resident on the switch. It allows the service
provider to provide special services, such as
special call-handling, that are not dependent on
the capabilities of the switch. See also advanced
intelligent network.
intelligent peripheral (IP). A voice processing
system (such as WebSphere Voice Response) that
provides enhanced services such as voice
response, speech recognition, text-to-speech,
voice messaging, and database access in an
advanced intelligent network.
interactive voice response (IVR). A computer
application that communicates information and
interacts with the caller via the telephone voice
channel.
International Telecommunications Union –
Telecommunication Standardization Sector
glossary
246 Developing Java Applications
(ITU-T). The name of the organization that was
previously known as the CCITT.
IP. See intelligent peripheral.
ISDN. See Integrated Services Digital Network
(ISDN) .
ISDN two B-channel transfer. See Integrated
Services Digital Network (ISDN) two B-channel
transfer.
ISDN-UP. See Integrated Services Digital Network
user part.
ISUP. See Integrated Services Digital Network user
part.
ITU-T. See International Telecommunications
Union – Telecommunication Standardization Sector.
IVR. See interactive voice response.
J
Java Bean. A reusable Java component. See
beans.
jump out. See call transfer.
K
key. (1) One of the pushbuttons on the
telephone handset; sometimes referred to as a
DTMF key. (2) A component of the keyboard that
is attached to the computer system.
key pad. The part of the telephone that contains
the pushbutton keys.
key pad mapping. The process of assigning
special alphanumeric characters to the keys that
are on a telephone key pad, so that the telephone
can be used as a computer-terminal keyboard.
L
LAN. See local area network.
language model. For speech recognition, a set
of acoustic shapes (in binary format) for a given
set of words, in which word-to-word differences
are maximized, but speaker-to-speaker
differences are minimized. See also vocabulary.
LAPD. See link access protocol for the D-channel.
licensed program product (LPP). A
separately-priced program and its associated
materials that bear an IBM copyright and are
offered under the terms and conditions of a
licensing agreement.
license server. A machine on a network that
holds licenses and distributes them on request to
other machines on the network.
line error. An error on the telephone line that
causes the signal to be impaired.
link access protocol for the D-channel. An
HDLC protocol used in ISDN that ensures a
reliable connection between the network and the
user. Often used as another name for Q.921.
local area network (LAN). A network in which
computers are connected to one another in a
limited geographical area. WebSphere Voice
Response communication with WebSphere Voice
Server speech recognition, text-to-speech, and
single system image (SSI) requires a LAN that is
dedicated to that purpose (unless both are
installed on the same system). A token-ring
network is a type of LAN.
local variable. A user-defined temporary
variable that can be accessed only by the
program (state table, prompt, or 3270 script) for
which it is defined. Contrast with input parameter,
system variable.
M
macro. See system prompt.
MAP. See mobile application part.
MB. See megabyte.
megabyte. (1) For processor storage and real
and virtual memory, 1 048 576 bytes. (2) For disk
storage capacity and transmission rates, 1 000
000 bytes.
glossary
Glossary 247
Message Center. See Unified Messaging
message delivery preference. The subscriber’s
choice of whether voice mail is stored as voice
mail only, as e-mail only, or as both voice mail
and e-mail.
message delivery type. The format in which a
voice message is delivered.
message signal unit (MSU). An MTP packet
that contains data.
message transfer part (MTP). Part of the SS7
protocol that is normally used to provide a
connectionless service that is roughly similar to
levels one through three of the OSI reference
model.
message waiting indicator (MWI). A visible or
audible indication (such as a light or a stutter
tone) that a voice message is waiting to be
retrieved.
MFR1. An in-band address signaling system
that uses six tone frequencies, two at a time.
MFR1 is used principally in North America and
is described in ITU-T recommendations Q.310
through Q.332.
MIME. See multipurpose Internet mail extensions.
mobile application part (MAP). Optional layer
7 application for SS7 that runs on top of TCAP
for use with mobile network applications.
MP. See multiprocessor.
MSU. See message signal unit.
MTP. See message transfer part.
mu(µ)-law. The companding algorithm that is
used primarily in North America and Japan
when converting from analog to digital speech
data. (Compand is a contraction of compress and
expand.) Contrast with A-law.
multiprocessor (MP). A computer that includes
two or more processing units that can access a
common main storage.
multipurpose Internet mail extensions
(MIME). A protocol that is used on Internet for
extending e-mail capability and merging it with
other forms of communication, such as voice
mail and fax.
mumble. Non speech noise that a user interjects
while speaking.
music channel. A channel on which sounds can
be broadcast to one or more telephony (voice)
channels.
music title. The name by which WebSphere
Voice Response knows a tune.
MWI. See message waiting indicator.
N
National ISDN. A common ISDN standard that
was developed for use in the U.S.
NAU. See network addressable unit.
N-Best. The ability to return more than one
speech recognition result. Typically, an array of
results is available in the application in sequence
of descending probability.
NCP. See network control program.
NET. Norme Européenne de
Télécommunication.
Net 5. The test specification for conformance to
the Euro-ISDN standard for primary rate access
to ISDN.
network addressable unit (NAU). Any network
component that can be addressed separately by
other members of the network.
network control program (NCP). Used for
requests and responses that are exchanged
between physical units in a network for data
flow control.
Network File System (NFS). A protocol,
developed by Sun Microsystems, Incorporated,
that allows any host in a network to gain access
to another host or netgroup and their file
glossary
248 Developing Java Applications
directories. In a single system image (SSI), NFS is
used to attach the WebSphere Voice Response
DB2 database.
network termination. See NT mode.
NFAS. See non-facility associated signaling.
NFS. See Network File System.
node. In a single system image (SSI), one of the
WebSphere Voice Response systems that are in
the cluster.
non-facility associated signaling (NFAS). An
ISDN configuration where several T1 facilities
can be controlled by a single D-channel, instead
of the normal T1 configuration where each T1
facility has 23 B-channels and a D-channel
(23B+D). With NFAS, all 24 timeslots of the non
signaling trunks are available for voice, whereas
only 23 channels can be used on the trunk that
carries signaling traffic (23B+D+n24B).
NT mode. Attachment to the ISDN network is
asymmetric. The network side of the connection
operates in network termination, or NT, mode.
User equipment operates in terminal equipment,
or TE, mode.
O
ODM. See Object Data Manager.
Object Data Manager (ODM). A data manager
intended for the storage of system data. The
ODM is used for many system management
functions. Information that is used in many
commands and SMIT functions is stored and
maintained in the ODM as objects with
associated characteristics.
off-hook. A telephone line state, usually
induced by lifting a receiver, in which the line is
ready to make a call.
offline. Not attached or known to the existing
system configuration, and therefore not in active
operation.
on-hook. A telephone line state, usually
induced by hanging up a receiver, in which the
line is ready to receive a call.
online. In active operation.
OPC. See originating point code.
Open Systems Interconnection (OSI). (1.) The
interconnection of open systems as specified in
particular ISO standards. (2.) The use of
standardized procedures to enable the
interconnection of data processing systems.
Open Systems Interconnection (OSI)
architecture. Network architecture that observes
the particular set of ISO standards that relate to
Open Systems Interconnection.
Open Systems Interconnection (OSI) Reference
Model. A conceptual model composed of seven
layers, each specifying particular network
functions. Developed by the International
Organization for Standardization (ISO) in 1984, it
is considered to be the primary architectural
model for intercomputer communications
originating point code (OPC). A code that
identifies the signaling Point that originated an
MTP signal unit. Unique in a particular network.
OSI. See Open Systems Interconnection.
outgoing mail. In voice mail, messages that are
sent by a subscriber to another subscriber on the
same system, and have not yet been listened to
by the addressee.
out-of-band. In the telephony signaling channel,
as opposed to the voice channel. Signals are said
to be carried out-of-band. Contrast with in-band.
P
PABX. See private automatic branch exchange .
pack. Each DTTA or DTXA contains the
equivalent of four packs. The pack is a digital
trunk processor built into the digital trunk
adapter, so there is no need for external
hardware. See also XPACK.
glossary
Glossary 249
parameter file. An ASCII file that sets
configuration parameters.
password. A unique string of characters that is
known to a computer system and to a user. The
user must specify the character string to gain
access to the system and to the information that
is stored in it.
PBX. See private branch exchange.
PCI. See peripheral component interconnect.
PCM. See Pulse Code Modulation.
PCM fault condition. A fault, such as power
supply failure, or loss of incoming signal, in T1
or E1 equipment. (ITU-T G.732 and G.733.)
peripheral component interconnect (PCI). A
computer busing architecture that defines
electrical and physical standards for electronic
interconnection.
personal greeting. In voice mail, a greeting that
is recorded by a subscriber. Contrast with system
greeting.
phone recognition. Communicating with a
computer using voice via a telephone, over a
telephone line. The computer application
recognizes what was said and takes suitable
action.
port. In time-slot management, one end of a 64
Kbps unidirectional stream that can be attached
to the TDM bus.
port set. In time-slot management, a collection
of ports that can be connected using a single
CA_TDM_Connect() API call to a complementary
collection of ports.
PRA. Primary rate access (PRA). Used as
another name for primary rate interface (PRI).
PRI. See primary rate interface.
primary rate access (PRA). See primary rate
interface.
primary rate interface (PRI). The means of
ISDN access that is normally used by large sites.
It provides 30 (E1) or 23 (T1) B-channels of 64 Kb
per second and one D-channel for signaling. This
is often known as 30B+D or 23B+D. Contrast
with basic rate interface.
primary rate ISDN (PRI). See primary rate
interface.
primitive. A message that is sent from one
process to another.
private automatic branch exchange (PABX). An
automatic private switching system that services
an organization and is usually located on a
customer’s premises. Often used as another
name for private branch exchange (PBX) .
private branch exchange (PBX). A switch inside
a private business that concentrates the number
of inside lines into a smaller number of outside
lines (trunks). Many PBXs also provide advanced
voice and data communication features. Often
used as another name for private automatic branch
exchange .
process a call. To answer the telephone and
perform the correct tasks.
Process Manager. In WebSphere Voice Server,
the process that manages the interaction of all
telephony system processes; for example, starting
and stopping text-to-speech or speech recognition
sessions.
production system. A WebSphere Voice
Response system that responds to or makes
“live” calls. A production system can also be
used to develop new applications. Contrast with
development system.
program temporary fix (PTF). An update to
IBM software.
program data. Application-specific data that can
be associated with a call transfer from CallPath
to WebSphere Voice Response, or in the opposite
direction. This is equivalent to CallPath program
data, but WebSphere Voice Response imposes the
restriction that the data must be a printable
ASCII character string, with a maximum length
of 512 bytes.
glossary
250 Developing Java Applications
prompt. (1) A message that requests input or
provides information. Prompts are seen on the
computer display screen and heard over the
telephone. (2) In WebSphere Voice Response, a
program that uses logic to determine
dynamically the voice segments that are to be
played as a voice prompt.
prompt directory. A list of all the prompts that
are used in a particular voice application. Used
by the state table to play the requested voice
prompts.
pronunciation. The possible phonetic
representations of a word. A word can have
multiple pronunciations; for example, “the” has
at least two pronunciations, “thee” and “thuh”.
pronunciation dictionary. A file that contains
the phonetic representation of all of the words,
phrases, and sentences for an application
grammar.
pronunciation pool. A WebSphere Voice Server
resource that contains the set of all
pronunciations.
protocol. A set of semantic and syntactic rules
that determines the behavior of functional units
when they get communication. Examples of
WebSphere Voice Response protocols are FXS,
RE, and R2.
PSTN. An ITU-T abbreviation for public
switched telephone network.
PTF. See program temporary fix.
Pulse Code Modulation (PCM). Variation of a
digital signal to represent information.
pushbutton. (1) A key that is on a telephone
key pad. (2) A component in a window that
allows the user to start a specific action.
pushbutton telephone. A type of telephone that
has pushbuttons. It might or might not send tone
signals. If it does, each number and symbol on
the key pad has its own specific tone.
Q
Q.921. The ITU-T (formerly CCITT)
recommendation that defines the link layer of the
DSS1 protocol. Q.921 defines an HDLC protocol
that ensures a reliable connection between the
network and the user. Often used as another
name for LAPD.
Q.931. The ITU-T recommendation that defines
the network layer of the DSS1 protocol. This
layer carries the ISDN messages that control the
making and clearing of calls.
quiesce. To shut down a channel, a trunk line,
or the whole system after allowing normal
completion of any active operations. The
shutdown is performed channel-by-channel.
Channels that are in an idle state are shut down
immediately. Channels that are processing calls
are shut down at call completion.
R
RAI. See remote alarm indication.
RBS. See robbed-bit signaling.
RE. See remote extension.
Recognition Engine server. In WebSphere Voice
Server, the software that performs the speech
recognition and sends the results to the client.
This consists of one ‘Tsm router’ and at least one
‘tsmp’ and one ‘engine’.
reduced instruction set computer (RISC). A
computer that uses a small, simplified set of
frequently-used instructions to improve
processing speed.
referral number. The phone number to which
calls are routed, when call forwarding is active.
rejection. The identification of an utterance as
one that is not allowed by a grammar.
release link trunk (RLT). A custom specification
from Nortel for ISDN call transfer.
glossary
Glossary 251
remote alarm indication (RAI). A remote alarm
(also referred to as a yellow alarm) indicates that
the far-end of a T1 connection has lost frame
synchronization. The Send RAI system parameter
can be set to prevent WebSphere Voice Response
from sending RAI.
remote extension (RE). An E1 signaling
protocol that is similar to FXS loop start.
resource element. A component of an
Intelligent Network. The resource element
contains specialized resources such as speech
recognizers or text-to-speech converters.
response. In speech recognition, the character
string that is returned by the recognizer, through
DVT_Client, to the state table. The string
represents the result of a recognition attempt.
This is the word or words that the recognizer
considers to be the best match with the speech
input.
result. An indicator of the success or failure of a
state table action. It is returned by WebSphere
Voice Response to the state table. Also known as
an edge.
result state. The state that follows each of the
possible results of an action.
return code. A code that indicates the status of
an application action when it completes.
RISC. See reduced instruction set computer.
RLT. See release link trunk.
robbed-bit signaling (RBS). The T1 channel
-associated signaling scheme that uses the least
significant bit (bit 8) of each information channel
byte for signaling every sixth frame. This is
known as 7-5/6-bit coding rather than 8-bit
coding. The signaling bit in each channel is
associated only with the channel in which it is
contained.
S
SAP. See service access point.
SAS. A T1 signaling protocol that is similar to
FXS.
SCbus. See Signal Computing bus.
SCCP. See signaling connection control part.
SCP. See service control point.
screened transfer. A type of call transfer in
which the transfer of the held party to the third
party is completed only if the third party
answers the call. Contrast with blind transfer.
script. The logical flow of actions for a 3270
server program.
script language. A high-level,
application-specific scripting language, which
consists of statements that are used to develop
3270 scripts. These scripts are part of the
interface between a state table and a 3270-based
host business application.
SCSA. See Signal Computing System Architecture.
SDC. See Server Display Control.
SDLC. See Synchronous Data Link Control.
segment ID number. One or more numbers that
are used to identify a voice or prompt segment.
Server Display Control (SDC). An ADSI
control mode in which the ADSI telephone is
controlled through a dialog with a voice
response system.
server node. In a single system image (SSI), a
WebSphere Voice Response system that contains
either the WebSphere Voice Response DB2
database, or the voice data, or both.
service access point (SAP). An OSI term for the
port through which a service user (layer N+1)
accesses the services of a service provider (layer
N).
service control point (SCP). A component of
the intelligent network that provides
transactional services, such as translation of
toll-free numbers to subscriber numbers.
glossary
252 Developing Java Applications
service information octet (SIO). A field that is
in an MTP message signal unit. It identifies a
higher layer user of MTP, and whether the
message relates to a national or international
network.
service node. An element of an Intelligent
Network. The service node contains the service
logic that controls an intelligent network
application and resources.
service provider. Any company that provides
services for a fee to its customers, such as
telecommunication companies, application
service providers, enterprise IT, and Internet
service providers.
service provider equipment (SPE). The
switching equipment that is owned by the
telephone company.
session. See speech recognition session.
Session Initiation Protocol. A signaling
protocol used for internet conferencing,
telephony, presence, events notification and
instant messaging.
short message service center (SMSC). A
component of the mobile telephony network,
specified by the GSM group of standards, that
provides for exchange of alphanumeric messages
of less than 160 bytes. Messages can be
exchanged between different types of system
such as mobile telephone, alphanumeric pager,
terminal, e-mail, telex, or DTMF telephone.
SIF. See signaling information field.
Signal Computing System Architecture
(SCSA). An architecture that was defined by
Dialogic to support interoperability of software
and hardware components that are developed by
different vendors in the computer telephony
industry.
Signal Computing bus (SCbus). A time
division multiplexed (TDM) hardware bus that
was originated by Dialogic to interconnect
different vendors’ computer telephony adapters.
Specified as part of Signal Computing System
Architecture (SCSA).
signaling. The exchange of control information
between functional parts of the system in a
telecommunications network.
signaling connection control part (SCCP). A
layer 3 protocol that observes OSI.
signaling information field (SIF). The user data
portion of an MTP message signal unit.
signaling link code (SLC). A code that
identifies a particular signaling link that connects
the destination and originating signaling points.
This is used in MTP signaling network
management messages to indicate the signaling
link to which the message relates.
signaling link selection (SLS). A field that is
used to distribute MTP signal units across
multiple signaling links.
signaling mode. The type of signaling protocol,
either channel-associated signaling, or
common-channel signaling.
signaling point. A node in a signaling network
that either originates and receives signaling
messages, or transfers signaling messages from
one signaling link to another, or both.
signaling process. A WebSphere Voice Response
component that controls signaling for an
exchange data link or common-channel signaling
protocol. Some signaling processes are supplied
with WebSphere Voice Response, and others can
be custom-written.
signaling System Number 7 (SS7). The
international high-speed signaling backbone used
for the public-switched telephone network.
silence. A short pause between utterances.
simple mail transfer protocol (SMTP). An
Ethernet protocol that is related to TCP/IP.
simple network management protocol (SNMP).
In the Internet suite of protocols, a network
management protocol that is used to monitor
routers and attached networks. SNMP is an
application layer protocol. Information on
devices managed is defined and stored in the
glossary
Glossary 253
application’s Management Information Base
(MIB). SNMP provides a means of monitoring
WebSphere Voice Response resources remotely.
Simplified Message Desk Interface (SMDI). A
Northern Telecom service that transmits
out-of-band information between WebSphere
Voice Response and particular switches.
Simplified Message Service Interface (SMSI).
A Lucent Technologies service that transmits
out-of-band information between WebSphere
Voice Response and particular switches.
single system image (SSI). A cluster of
WebSphere Voice Response systems that are
connected together using a local area network.
Each system (known as a node) in the cluster is
configured as either a client or a server. A single
system image typically consists of one server
node and multiple client nodes. The client nodes
retrieve applications and voice data from the
server. A second server can be configured for
redundancy.
sink. A port that takes voice data from the
TDM bus. Contrast with source.
SIO. See service information octet.
SIP. See Session Initiation Protocol.
SLC. See signaling link code.
SLS. See signaling link selection.
SMDI. See Simplified Message Desk Interface.
SMIT. See System Management Interface Tool.
SMP. See symmetric multiprocessor.
SMSC. See short message service center.
SMSI. See Simplified Message Service Interface.
SMTP. See simple mail transfer protocol.
SNA. Systems Network Architecture.
SNMP. See simple network management protocol .
source. A port that puts voice data on to the
TDM bus. Contrast with sink.
SPACK. A logical component that consists of a
base card, which connects to the digital trunk
adapter in the pSeries computer, and a trunk
interface card (TIC), which manages the trunk
connection to the switch. Contrast with VPACK
and XPACK.
SPE. See service provider equipment.
speaker-dependent speech recognition.
Identification of spoken words that is related to
knowledge of the speech characteristics of one
speaker. Contrast with speaker-independent speech
recognition.
speaker-independent speech recognition.
Identification of spoken words that is related to
collected knowledge of the speech characteristics
of a population of speakers. Contrast with
speaker-dependent speech recognition.
special character. A character that is not
alphabetic, numeric, or blank. For example, a
comma (,) or an asterisk (*).
speech recognition. The process of identifying
spoken words. See discrete word recognition,
continuous speech recognition, speaker-dependent
speech recognition, speaker-independent speech
recognition.
Speech Recognition Control Language (SRCL).
In WebSphere Voice Server, a structured syntax
and notation that defines speech grammars,
annotations, repetitions, words, phrases, and
associated rules.
speech recognition session. In WebSphere Voice
Server, a sequence of recognition commands that
allocate a recognition engine, and return a
unique identifier to identify the engine.
speech synthesis. The creation of an
approximation to human speech by a computer
that concatenates basic speech parts together. See
also text-to-speech.
SRCL. See Speech Recognition Control Language
(SRCL).
glossary
254 Developing Java Applications
SS7. See signaling System Number 7.
SSI. See single system image.
SSI-compliant custom server. A custom server
that runs correctly in a single system image. The
custom server observes all the guidelines for the
operation of custom servers in an SSI
environment.
SSI-tolerant custom server. A custom server
that runs in a single system image, but with only
some restrictions.
standalone system. A WebSphere Voice
Response system that is not part of a single
system image (SSI). A standalone system is not
connected to other WebSphere Voice Response
systems, so it contains its own application and
voice data.
state. One step in the logical sequence of actions
that makes a WebSphere Voice Response voice
application.
state table. A list of all the actions that are used
in a particular voice application. A component of
WebSphere Voice Response.
state table action. One instruction in a set of
instructions that is in a WebSphere Voice
Response state table that controls how
WebSphere Voice Response processes various
operations such as playing voice prompts or
recording voice messages. See also state.
stub. A line in a state table that is only partially
displayed.
subscriber. In voice mail, any person who owns
a mailbox.
subscriber class. A named set of variables that
defines a specific level of service available to
telephone subscribers, such as maximum number
of messages per mailbox and maximum number
of members per mailbox distribution list.
subvocabulary. A vocabulary that is called by
another vocabulary.
supplementary service. In Euro-ISDN, a service
outside the minimum service offering that each
signatory is obliged to provide. For example,
calling line identification presentation (CLIP) and
call session.
switch. A generic term that describes a
telecommunications system that provides
connections between telephone lines and trunks.
symmetric multiprocessor (SMP). A system in
which functionally-identical multiple processors
are used in parallel, providing simple and
efficient load-balancing.
Synchronous Data Link Control (SDLC). A
discipline for managing synchronous,
code-transparent, serial-by-bit information
transfer over a link connection. Transmission
exchanges can be duplex or half-duplex over
switched or nonswitched links.
system administrator. The person who controls
and manages the WebSphere Voice Response
system by adding users, assigning account
numbers, and changing authorizations.
system greeting. In voice mail, a default greeting
that is heard by callers to the mailboxes of
subscribers who have not recorded a personal
greeting or who have selected the system
greeting. Contrast with personal greeting.
System Management Interface Tool (SMIT). A
set of utilities that can be used for various
purposes, such as loading WebSphere Voice
Response software, installing the exchange data
link, and configuring SNA.
Systems Network Architecture (SNA). An
architecture that describes the logical structure,
formats, protocols, and operational sequences for
transmitting information units through the
networks and also the operational sequences for
controlling the configuration and operation of
networks.
system parameter. A variable that controls some
of the behavior of WebSphere Voice Response or
applications that are running under WebSphere
Voice Response. System parameters are set
through System Configuration or Pack
glossary
Glossary 255
Configuration options on the Configuration
menu. Some system parameter values are
assigned to system variables when an application
is initialized. Contrast with input parameter, local
variable, system variable.
system prompt. The symbol that appears at the
command line of an operating system, indicating
that the operating system is ready for the user to
enter a command.
system variable. A permanent global variable
that is defined by WebSphere Voice Response for
use by state tables. Many system variables are
loaded with values when the state table is
initialized. Some values are taken from system
parameters. Contrast with input parameter, local
variable, system parameter.
T
T1. A digital trunking facility standard that is
used in the United States and elsewhere. It can
transmit and receive 24 digitized voice or data
channels. Signaling can be imbedded in the voice
channel transmission when robbed-bit signaling
is used. The transmission rate is 1544 kilobits per
second. Contrast with E1.
T1/D3. A framing format that is used in T1
transmission.
T1/D4. A framing format that is used in T1
transmission.
tag. A text string that is attached to any instance
of a word in a grammar. A tag can be used (1) to
distinguish two occurrences of the same word in
a grammar or (2) to identify more than one word
in a grammar as having the same meaning.
Tag Image File Format-Fax (TIFF-F). A graphic
file format that is used to store and exchange
scanned fax images.
TCAP. See transaction capabilities application part.
TCP/IP. See Transmission Control Protocol/Internet
Protocol.
TDD. See Telecommunications Device for the Deaf.
TDM. See time-division multiplex bus.
technology. A program, external to WebSphere
Voice Response, that provides processing for
functions such as text-to-speech or speech
recognition.
Telecommunications Device for the Deaf
(TDD). A telephony device that has a QWERTY
keyboard and a small display and, optionally, a
printer.
telephone input field. A field type that contains
information that is entered by a caller who is
using pushbutton signals. See also field.
terminal. (1) A point in a system or
communication network at which data can enter
or leave. (2) In data communication, a device,
usually equipped with a keyboard and display
device, that can send and receive information.
termination character. A character that defines
the end of a telephone data entry.
text-to-speech (TTS). The process by which
ASCII text data is converted into synthesized
speech. See also speech synthesis.
TIC. See trunk interface card.
time-division multiplex bus (TDM). A method
of transmitting many channels of data over a
smaller number of physical connections by
multiplexing the data into timeslots, and
demultiplexing at the receiving end. In this
document, one such channel can be considered to
be a half-duplex unidirectional stream of 64 Kb
per second.
TIFF-F. See Tag Image File Format-Fax
timeslot. The smallest switchable data unit on a
data bus. It consists of eight consecutive bits of
data. One timeslot is similar to a data path with
a bandwidth of 64 Kb per second.
token. A particular message or bit pattern that
indicates permission or temporary control to
transmit.
glossary
256 Developing Java Applications
token-ring network. A local area network that
connects devices in a ring topology and allows
unidirectional data transmission between devices
by a token-passing procedure. A device must
receive a token before it can transmit data.
tone. An audible signal that is sent across a
telephone network. Single (one-frequency) tones,
tritones (three sequential tones at different
frequencies), dual tones (two simultaneous tones
at different frequencies), and dual sequential
tones exist. Each has a different meaning.
transaction. A specific, related set of tasks in an
application that retrieve information from a file
or database. For example, a request for the
account balance or the available credit limit.
transaction capabilities application part
(TCAP). Part of the SS7 protocol that provides
transactions in the signaling network. A typical
use of TCAP is to verify a card number, for the
credit card calling service.
transaction messaging. The ability to associate
an item of data, such as a transaction identifier,
with a voice message. The voice message can
later be retrieved by referencing the data value.
transfer. See call transfer.
Transmission Control Protocol/Internet Protocol
(TCP/IP). A communication subsystem that is
used to create local area and wide area networks.
trombone. A connected voice path that enters
an IVR from a switch on one circuit, then returns
to the same switch on a parallel circuit. Two IVR
ports and two circuits are consumed, but in some
circumstances this might be the only way to
make a connection between two callers if the
attached switch does not support a Call Transfer
function. Also known as double-trunking.
trunk. A telephone connection between two
central offices or switching devices. In
WebSphere Voice Response, a trunk refers to 24
or 30 channels that are carried on the same T1 or
E1 digital interface.
trunk interface card (TIC). The component of
the pack that manages the trunk connection to
the switch.
Tsm Router. In WebSphere Voice Server, a
process that controls which engine processes are
in use at any time. Requests for an engine by a
WebSphere Voice Server Client are accepted or
rejected depending on whether an engine that
meets the Tsm Client’s requirements is available.
tsmp. In WebSphere Voice Server, a process that
is running on the Recognition engine server
machine that passes messages between an engine
and a Tsm Client. One tsmp exists for every
engine.
TTS. See text-to-speech.
tune. A piece of music or other audio data that
is intended to be played as background music.
U
underrun. To run out of audio data to play,
causing voice or music to be audibly broken up
or cut off.
unified messaging. A messaging system in
which a single copy of a message is stored and
accessed by multiple applications (for example,
voice mail and e-mail). Contrast with integrated
messaging.
Unified Messaging. An IBM product that uses
WebSphere Voice Response’s voice processing
capabilities to provide a wide range of voice
mail, fax, and e-mail functions. Previously
known as Message Center.
user. Someone who uses WebSphere Voice
Response as a system administrator, application
developer, or similar. Contrast with caller.
utterance. A spoken word, phrase, or sentence
that can be preceded and followed by silence.
V
variable. A system or user-defined element that
contains data values that are used by WebSphere
glossary
Glossary 257
Voice Response voice applications. See input
parameter, local variable, system parameter, system
variable.
VMS. See Voice Message Service.
vocabulary. A list of words with which
WebSphere Voice Response matches input that is
spoken by a caller. See also language model.
voice application. A WebSphere Voice Response
application that answers or makes calls, plays
recorded voice segments to callers, and responds
to the caller’s input.
voice directory. A list of voice segments that is
identified by a group ID. Voice directories can be
referenced by prompts and state tables. Contrast
with voice table.
voice mail. The capability to record, play back,
distribute, and route voice messages.
voice mailbox. The notional hard disk space
where the incoming messages for a voice mail
subscriber are stored.
voice message. In voice mail, a recording that is
made by a caller for later retrieval by a subscriber.
Voice Message Service (VMS). An Ericsson
service that transmits information between
WebSphere Voice Response and particular
switches.
voice messaging. The capability to record, play
back, distribute, route, and manage voice
recordings of telephone calls through the use of a
processor, without the intervention of agents
other than the callers and those who receive
messages.
voice model. A file that contains parameters
that describe the sounds of the language that are
to be recognized on behalf of an application. In
WebSphere Voice Server, this is a bnf file. See also
grammar.
Voice over Internet Protocol (VoIP). The
sending of telephony voice over Internet Protocol
(IP) data connections instead of over existing
dedicated voice networks, switching and
transmission equipment. See also gatekeeper and
gateway.
voice port library. A library that manages a
socket connection from the client to the voice
technology. The library uses entry points that are
provided by DVT.
Voice Protocol for Internet Messaging (VPIM).
The standard for digital exchange of voice
messages between different voice mail systems,
as defined in Internet Request For Comments
(RFC) 1911.
voice response unit (VRU). A telephony device
that uses prerecorded voice responses to provide
information in response to DTMF or voice input
from a telephone caller.
voice segment. The spoken words or sounds
that make recorded voice prompts. Each segment
in an application is identified by a group ID and
a segment ID and usually includes text.
voice server node. In a single system image
(SSI), a server node that contains the voice data.
This is usually the same node as the database
server node.
voice table. A grouping of voice segments that is
used for organizational purposes. Voice tables
can be referenced by prompts, but not by state
tables. Contrast with voice directory.
voice technology. See technology.
VoiceXML. VoiceXtensible Markup Language.
An XML-based markup language for creating
distributed voice applications. Refer to the
VoiceXML forum web site at www.voicexml.org
VoIP. See Voice over Internet Protocol.
VPACK. A component consisting of a base card,
which connects to the digital trunk adapter in
the pSeries computer, and a trunk interface card
(TIC), which manages the trunk connection to
the switch. The single digital trunk processor
contains one VPACK, and the multiple digital
trunk processor contains slots for up to five
VPACKs. Contrast with SPACK and XPACK.
glossary
258 Developing Java Applications
VPIM. See Voice Protocol for Internet Messaging.
VRU. See voice response unit.
W
World Wide Web Consortium (W3C). An
organization that develops interoperable
technologies (specifications, guidelines, software,
and tools) to lead the Web to its full potential.
W3C is a forum for information, commerce,
communication, and collective understanding.
Refer to the web site at http://www.w3.org
WebSphere Voice Response. A voice processing
system, that combines telephone and data
communications networks to use, directly from a
telephone, information that is stored in
databases.
wink start. A procedure that is used with some
channel-associated signaling protocols to indicate
when a switch or PABX is ready to accept
address signaling. After seizure, the switch sends
a short off-hook signal (wink) when it is ready to
accept address information. Contrast with delay
start and immediate start.
word spotting. In speech recognition, the ability
to recognize a single word in a stream of words.
wrap. In ADSI, the concatenation of two
columns of display data to form a single column.
X
XPACK. A digital trunk processor that is
implemented using DSP technology on the
digital trunk adapter without the need for
external hardware. One digital trunk adapter
(DTTA or DTXA) provides up to four XPACKs
on a PCI card.
Y
yellow alarm. See remote alarm indication.
Z
zero code suppression (ZCS). A coding method
that is used with alternate mark inversion to
prevent sending eight successive zeros. If eight
successive zeros occur, the second-least
significant bit (bit 7, with the bits labeled 1
through 8 from the most significant to the least
significant) is changed from a 0 to a 1. AMI with
ZCS does not support clear channel operation.
glossary
Glossary 259
glossary
260 Developing Java Applications
List of WebSphere Voice Response and associated
documentation
Here is a list of the documentation for WebSphere Voice Response for AIX and
associated products. PDF and HTML versions of the documentation are
available from the IBM Publications Center at http://www.ibm.com/shop/publications/order. Hardcopy books, where available, can be ordered through
your IBM representative or at this Web site.
WebSphere Voice Response for AIX documentation can also be found by going
to the IBM Pervasive software Web site at http://www.ibm.com/software/pervasive, selecting the WebSphere Voice products link, and then selecting
the library link from the WebSphere Voice Response page.
PDF and HTML versions of the WebSphere Voice Response for AIX
publications are available on the CD-ROM supplied with the product. In
addition, WebSphere Voice Response for AIX, WebSphere Voice Response for
Windows, Unified Messaging, and other WebSphere Voice publications are
available together in PDF and HTML formats on a separately-orderable
CD-ROM (order number SK2T-1787).
Note: To read PDF versions of books you need to have the Adobe Acrobat
Reader (it can also be installed as a plug-in to a Web browser). It is
available from Adobe Systems at http://www.adobe.com .
WebSphere Voice Response software
v WebSphere Voice Response for AIX: General Information and Planning,
GC34-6379
v WebSphere Voice Response for AIX: Installation, GC34-6380
v WebSphere Voice Response for AIX: User Interface Guide, SC34-6386
v WebSphere Voice Response for AIX: Configuring the System, SC34-6381
v WebSphere Voice Response for AIX: Managing and Monitoring the System,
SC34–6384
v WebSphere Voice Response for AIX: Designing and Managing State Table
Applications, SC34–6388
v WebSphere Voice Response for AIX: Application Development using State Tables,
SC34–6387
v WebSphere Voice Response for AIX: Developing Java applications, GC34-6377
© Copyright IBM Corp. 1998, 2008 261
v WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and Java
Applications, GC34–6378
v WebSphere Voice Response for AIX: Custom Servers, SC34–6389
v WebSphere Voice Response for AIX: 3270 Servers, SC34–6390
v WebSphere Voice Response for AIX: Problem Determination, GC34–6382
v WebSphere Voice Response for AIX: Fax using Brooktrout, GC34–6385
v WebSphere Voice Response for AIX: Cisco ICM Interface User’s Guide, SC34–6391
v WebSphere Voice Response for AIX: Programming for the ADSI Feature,
SC34–6393
v WebSphere Voice Response for AIX: Programming for the Signaling Interface,
SC34–6392
v WebSphere Voice Response for AIX: Voice over IP using Session Initiation
Protocol, GC34–6383
v WebSphere Voice Response for AIX: Using the CCXML Browser, GC34–6368
IBM hardware for use with WebSphere Voice Response
v IBM Quad Digital Trunk Telephony PCI Adapter (DTTA): Installation and User’s
Guide, part number 00P3119 (DTTA card)
Withdrawn from marketing but still supported
v IBM ARTIC960RxD Quad Digital Trunk PCI Adapter: Installation and User’s
Guide, part number 41L5825 (DTXA card)
WebSphere Voice Response related products
WebSphere Voice Server for Multiplatforms
For Version 4.2 of WebSphere Voice Server, the following documentation is
provided in softcopy with the product, or can be downloaded from the IBM
Publications Center:
v IBM WebSphere Voice Server: General Information
v WebSphere Voice Server for Multiplatforms: Administrator’s Guide
v WebSphere Voice Server for Multiplatforms: Application Development using State
Tables
v WebSphere Voice Server for Multiplatforms: VoiceXML Programmer’s Guide
The WebSphere Voice Server for Multiplatforms: VoiceXML Programmer’s Guide is
also provided as a PDF with the Voice Toolkit for WebSphere Studio Release
4.2.
262 Developing Java Applications
The documentation for Version 5.1 of WebSphere Voice Server is provided in
the form of an HTML-based information center, and can be found at:
http://publib.boulder.ibm.com/pvc/wvs/51/en/infocenter/index.html
Unified Messaging for WebSphere Voice Response
v Unified Messaging: General Information and Planning, GC34-6398
v Unified Messaging: Subscriber’s Guide (Types 0, 1, 2, 3, 4 and 9), SC34-6403
v Unified Messaging: Subscriber’s Guide (Types 5, 6, 7 and 8), SC34-6400
v Unified Messaging: Administrator’s Guide, SC34-6399
v Unified Messaging: Voice Interface, GC34-6401
v Unified Messaging: Web Services Voicemail API, SC34-6975
Unified Messaging publications can be found by going to the IBM Pervasive
software Web site at http://www.ibm.com/software/pervasive, selecting the
products link, and then selecting the library link from the Unified Messaging
page.
AIX and the IBM pSeries computer
v AIX: Installation Guide, SC23-4112
v AIX: Quick Beginnings, SC23-4114
v AIX: System User’s Guide; Operating System and Devices, SC23-4121
v AIX: System Management Guide; Operating System and Devices, SC23-4126
v AIX: System User’s Guide; Communications and Networks, SC23-4122
v AIX: System Management Guide; Communications and Networks, SC23-4127
v AIX: Topic Index and Glossary, SC23-2513
v RS/6000 and pSeries: Site and Hardware and Planning Information, SA38-0508
HACMP
v HACMP for AIX: Concepts and Facilities, SC23-4864
v HACMP for AIX: Planning Guide, SC23-4277
v HACMP for AIX: Planning and Installation Guide, SC23-4861
v HACMP for AIX: HACMP 5.3 Administration Guide, SC23-4862
v HACMP for AIX: HACMP 5.3 Smart Assist for DB2, SC23-5179
v HACMP for AIX: Enhanced Scalability Installation and Administration Guide,
SC23-4279
SS7
v SS7 Support for WebSphere Voice Response: SS7 User’s Guide, GC34-6613
IBM SS7 Support for WebSphere Voice Response observes the applicable parts
of the following specifications for ISUP:
v CCITT Blue book (1988) Q.701 - Q.707
List of WebSphere Voice Response and associated documentation 263
v ITU-T (formerly CCITT) Recommendations Q.700 - Q.716, Volume VI Fascicle
VI.7
v CCITT Blue book (1988) Q.711 - Q.714
v ITU-T White book (1993) Q.711 - Q.714
v CCITT Blue book (1988) Q.721 - Q.724
v ITU-T (formerly CCITT) Recommendations Q.721 - Q.725, Volume VI Fascicle
VI.8
v ITU-T White book (1992) Q.730 group
v CCITT Blue book (1988) Q.761 - Q.764
v ITU-T White book (1992) Q.761 - Q.764
v CCITT Blue book (1988) Q.771 - Q.775
v ITU-T (formerly CCITT) Recommendations Q.771 - Q.775, Q.791, Volume VI
Fascicle VI.9
ADC
v ADC NewNet AccessMANAGER™: Installation and Maintenance
Manual
v ADC NewNet AccessMANAGER™: User Manual
Integrated Services Digital Network
WebSphere Voice Response ISDN support observes the applicable parts of the
following standards for User Side protocol:
Custom ISDN Standards:
v Northern Telecom DMS/250 Primary Rate Interface NIS A211-4 Release
8, July 1995. (IEC05 level)
v Northern Telecom DMS/100 Primary Rate Interface NIS A211-1 Release
7.05, May 1998. (NA007 & RLT)
v AT&T 5ESS Switch. ISDN Primary Rate Interface Specification. 5E7 and
5E8 Software Release AT&T 235-900-332. Issue 2.00 December 1991
v AT&T 5ESS Switch. ISDN Primary Rate Interface Specification. 5E9
Software Release AT&T 235-900-342. Issue 1.00 November 1993
(National ISDN only)
v Lucent 5ESS-2000 Switch ISDN Primary Rate Interface, Interface
Specification, 5E9(2) and Later Software Releases, 235-900-342. Issue
5.00 January 1997 (National ISDN only)
v AT&T ISDN Primary Rate Specification TR41449 July 1989
v AT&T ISDN Primary Rate Specification TR41459 August 1996
Euro-ISDN
The following documents refer to the specifications required for
observing ISDN:
v TBR4-ISDN; Attachment Requirements For Terminal Equipment To
Connect To An ISDN Using ISDN Primary Rate Access, Edition 1, Nov.
95, English
264 Developing Java Applications
v CTR 4 - European Communities Commission Decision 94/796/EC
published in the Official Journal of the European Communities L
329, 20 December 94 (ISDN PRA)
National ISDN
National ISDN is described in the following publications:
v National ISDN, SR-NWT-002006, Issue 1, August 1991, published by
Bellcore
v National ISDN-1, SR-NWT-001937, Issue 1, February 1991, published
by Bellcore
v National ISDN-2, SR-NWT-002120, Issue 1, May 1992, published by
Bellcore
INS Net Service 1500
INS Net Service is described in the following publications:
v Interface for the INS Net Service Volume 1 (Outline), 7th Edition,
published by Nippon Telegraph and Telephone Corporation
v Interface for the INS Net Service Volume 2 (Layer 1 & 2 Specifications),
4th Edition, published by Nippon Telegraph and Telephone
Corporation
v Interface for the INS Net Service Volume 3 (Layer 3 Circuit Switching),
5th Edition, published by Nippon Telegraph and Telephone
Corporation
Bellcore Specifications for ADSI Telephones
The following Bellcore specification documents contain technical details of the
requirements for ADSI telephones, and the interface to voice response systems
such as WebSphere Voice Response:
v SR-INS-002461: CustomerPremises Equipment Compatibility Considerations for
the Analog Display Services Interface
v TR-NWT-001273: Generic Requirements for an SPCS to Customer Premises
Equipment Data Interface for Analog Display Services
List of WebSphere Voice Response and associated documentation 265
266 Developing Java Applications
Index
Aaction methods
equivalent base WebSphere Voice
Response actions 96
agentconsulting with, while caller on
hold 102
transferring a call to 100
ANI property 106
AnswerCall actioncorresponding method 96
applicationdevelopment 59
finishing with a call 57
getting ready to run using the
simulator 26
getting started 48
handling one call after
another 56
international 13, 87
languages, countries and
styles 12
multilingual 89
propertiesSee also
ApplicationProperties 49
run method 48
runningfrom WebSphere Studio Site
Developer 118
setting the CLASSPATH 29
testing 117
testing with a real voice response
node 117
testing with the simulator 117
text-to-speech 94
waiting for an incoming call 55
application call data 106
application default locale 87
application developmentcreating your own classes 8
application namesetting in
ApplicationProperties 51
ApplicationCallData property 106
applicationData propertysetting 98
applicationName propertysetting 98
ApplicationPropertiespurpose 49
setting application locale 87
specifying RecoDefinitions 92
specifying TTSDefinitions 95
asking the caller to enter databy pressing keys 70
by recording a message 85
by speaking (speech
recognition) 91
asking the caller to make a menu
selection 76
AudioCurrency classspeaking an amount in a nonlocal
currency 89
BbargeIn property
purpose 73
BaseIVRNumber property 28
BasePhoneNumber property 28
beepplaying before recording the
caller’s voice input 85
beep propertysetting 85
Bellcore specifications for ADSI
telephones 265
Ccall
finishing with 57
handing to another
application 97
handling one after another 56
incoming 55
on hold 102
transferring to an agent 100
call data 106
call handlingadvanced topics 96
basics 53
Call.play() methodgreeting the caller 59
responding to the caller 59
Call.record() methodusage 85
called and calling numbers 106
callerability to interrupt 72
caller (continued)entering data by pressing
keys 70
entering data by voice 91
failing to enter valid data 73
failing to select a valid menu
option 76
greeting 59
indicating that they have finished
entering data 80
indicating that they have finished
recording 85
on hold 102
presenting a menu to 76
recording a message 85
responding to 59
selecting a menu item 76
category, voice segmentdefinition 10
classescreating your own 8
essential information about
using 41
installing into IBM WebSphere
Studio Site Developer 41
CLASSPATHadding application path 29
constructing the spoken outputdetails 68
consulting with an agent while
keeping the caller on hold 102
control file, dtjplex 114, 115
creating applications 59
creating your own classes 8
currency propertyspeaking an amount in a nonlocal
currency 89
currency values 89
current localechanging 88
getting 88
Ddata entry
by key pressing 70
by recording a message 85
by speech recognition 91
validation 84
default localefor an application 87
© Copyright IBM Corp. 1998, 2008 267
default locale (continued)introduction 13
resetting 88
deleteVoiceSegment() methodusing 107
deleting a voice segment 94, 107
delimiter keyfinding out which was
pressed 81
specifying 80
delimiterKeys propertysetting 80
developing applications 59
creating your own classes 8
DNIS property 106
dtjconf 119
dtjplexfor voice segment
operations 113
dtjplex control fileexample for OS/2 and
Windows 115
introduction 114
DTMFAttributes classusing 70
DTsim.properties file 27
Eenabled property
setting 79
euro amounts 89
euro currency amounts 89
exampledata validation 84
handing a call over to another
application 100
handing a call over to another
application and waiting to get it
back 99
repeating a menu when the caller
fails to select a valid menu
option 79
retrieving a call from an
agent 105
transferring a caller to an
agent 102
exceptions 47
Ffinishing with a call
details 57
fixed length data entry 80
footerMessage propertyexample 79
using 77, 93
GgetApplicationCallData() method
using 106
getting help xiv, 119
greeting the caller 59
Hhanding a call over to another
applicationdetails 97
handling callsadvanced topics 96
basics 53
headerMessage propertyexample 79
using 77, 93
HostManagerstarting in the simulator 21
IIBM support xiv, 119
importing voice segmentsinto the simulator 29
InputAttributes classusing 70
installing the classes into IBM
WebSphere Studio Site
Developer 41
installing WebSphere Voice Response
classes 41
installing WVRSim 19
international applicationsspeaking an amount in a nonlocal
currency 89
internationalizationimplementation 87
introduction 13
interruptible propertyexample 79
setting 72
when mixing keys and voice 93
invalid data 73
invalid menu option 76
invalidInputMessage propertyexample 76, 79
invokeApplication() methodusage 97
InvokeStateTable actioncorresponding method 97
invokinga VoiceXML application 108
an AIX state table 109
another application 97
IP hostnamesetting in
ApplicationProperties 52
JJava voice segment space
definition 9
KkeyPressed property
purpose 85
keysdelimiter 80
mixing with voice input 93
selector 77
used to stop voice recording 85
Llanguage-only locales 14
languagesJava terminology 12
overview 12
See also locale 12
length of the recording,
controlling 85
localecurrent
changing 88
getting 88
default 13
application 87
resetting 88
defining your own variants 14
for speech recognition and
text-to-speech 15
introduction 12
language-only 14
purpose 12
specifying speech recognition
technology for 92
specifying text-to-speech
technology for 95
used for dividing the Java voice
segment space 10
locale propertyusing 89
log filesmanaging 117
looping round to handle another
call 56
MMakeCall action
corresponding method 97
maximumKeys propertysetting 80
268 Developing Java Applications
maximumLength propertysetting 85
MaxLines property 28
MaxPhones property 28
MaxRecordTime property 29
media data classadding to a MediaSequence 68
MediaSequence classadding media data classes to 68
Menu itemdisabling 79
menu selectiondetails 76
MenuAttributes classchanging the order of menu
items 77
menuswith speech recognition 91
message logsSee log files 117
message propertyexample 76, 79
using 77, 93
methodsused for telephony-related
functions 96
monitoring simulator phone
lines 32
multilingual applications 89
multiple calls 56
Nnational characters in voice segment
names 114
nodelog files created by 117
node namesetting in
ApplicationProperties 52
noMoreRepeatsMessage propertyexample 76, 80
numberOfRepeats propertydetails 74
example 79
NumberPlan properties 28
OoneMoreRepeatMessage property
example 76, 80
Pphone, simulated
creating more 25
displaying a hidden window 25
hiding the window 25
using 23
PlayAttributes classusing 70
playing back a recording 86
propertiesapplication 49
headerMessage, message, and
footerMessage 77
locale 89
PlayAttributes, InputAttributes,
DTMFAttributes,
RecoAttributes 70
used for entry field
repetition 73
used for menu repetition 76
RRecoAttributes class
using 70
RecoDefinitionspecifying in
ApplicationProperties 92
ReconnectCall actioncorresponding method 97
recording the caller’s voicedetails 85
recording the caller’s voice input 85
repeating entry field when caller
fails to enter valid data 73
repeating menu when caller fails to
select a valid option 76
responding to the caller 59
returnCall() methodfinishing with a call 57
RMI port numbersetting in
ApplicationProperties 53
run() method 48
run() method, WVRApplication classpurpose 49
running applications 118
Ssaying something to the caller 59
selector keyassociating menu item with 77
silence detectiondifferences between base
WebSphere Voice Response
systems 86
SimPhoneSoundEffect property 28
simulator phone lines,
monitoring 32
speech recognitionin menus and entry fields 91
mixing with key input 93
speech recognition (continued)specifying the technology in an
application 92
spoken outputconstructing
details 68
specifying with
Call.playAndGetInput() 70
SR-INS-002461 Bellcore
specification 265
startingapplications
using the run() method 49
WVRSim 21
state tablehow to invoke 108, 109
stopOnKey propertysetting 85
support, IBM xiv, 119
Ttelephone, simulated
creating more 25
displaying a hidden window 25
hiding the window 25
using 23
TerminateCall actioncorresponding method 97
terminationKey propertypurpose 81
testing applicationsusing a real voice response
node 117
using WVRSim 23
with the simulator 117
text-to-speechspecifying the technology in an
application 95
using in an application 94
TextToSpeech classusing 96
timeoutInputAttributes 73
timeoutMessage propertyexample 76, 79
toneplaying before recording the
caller’s voice input 85
TR-NWT-001273 Bellcore
specification 265
Trademarks 233
TransferCall actioncorresponding method 97
transferring a calldetails 100
Index 269
TTSDefinitionspecifying in
ApplicationProperties 95
Uusing synthesized speech 94
Vvariant, locale 14
definition 12
varying-length data entry 80
voice applicationSee application 59
voice data for applications 9
voice recognitionSee speech recognition 91
voice recordingdetails 85
voice responseusing Call.play() method 59
voice response Java APIintroduction 1
voice response nodetesting applications with 117
voice segmentscontrol file 114, 115
deleting 107
identification and storage 9
importing into the simulator 29
names that use national
characters 114
overview 9
recording 85
VoiceDataMapFile property 28
VoiceDir property 28
VoiceSegmentsusing
definition 60
languages, countries, and
styles 60
presentation style 60
style 60
WwaitForReturn property
setting 98
waiting for an incoming callusing the WVR class waitForCall
method 55
WAV filesimporting into the simulator 29
WebSphere Studio Site Developerinstalling the classes 41
WVR classfinishing with a call 57
in applications 53
WVR class (continued)waiting for an incoming call 55
WVRSimdownload file 117
installing 19
starting 21
system requirements 18
using the telephone 23
270 Developing Java Applications
����
Program Number: 5724-I07
GC34-6377-02
Spine information:
��
�
Web
Sphe
re Vo
ice
Res
pons
e fo
r A
IX w
ith D
irec
tTal
k Te
chno
logy
D
evel
opin
g Ja
va Ap
plic
atio
ns
Vers
ion
4.2