Developing Java Applications - Blueworx...Summary of methods used for telephony-related functions . . . . . .96 Handing a call to another application . .97 Transferring a call to an

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


Tutorial 3: Caller exits from the

application (menu item 5) . . . . . . 142


Tutorial 4: Leave a message (menu item

1) . . . . . . . . . . . . . . 148


Tutorial 5: Application makes a call . . . 154


Tutorial 6: Key in a telephone number

(menu item 2) . . . . . . . . . . 158


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


Tutorial 9: Order information (menu item

3 continued) . . . . . . . . . . 190

Code for Tutorial 9 OrderInfo class . . . 193


Tutorial 10: Transfer to an agent (menu

item 4) . . . . . . . . . . . . 198


Tutorial 11: Using speech recognition and

text-to-speech . . . . . . . . . . 208


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.



where to find more information

About This documentation xiii


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


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


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


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


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


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


Figure 4. Voice segment database

how to get voice data into applications


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



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



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.



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


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



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.



speech technologies


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.


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


Switch

Voice response node

Configurationdatabase

WebSphere Voice Response Simulator

Figure 8. The Voice Response simulator


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


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


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


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


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



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



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



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


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:



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



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



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.



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.



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



#

# 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


;

#

# This is the French version of menu

#

AppName=menu_fr_FR

Enabled=yes

Locale=fr_FR


;




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


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

;




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


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



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



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



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


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


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.



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.



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


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:




The files in this directory required by the Java API are:

v ibmcctl.jar

v ibmdtext.jar

installing the WebSphere Voice Response classes


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"


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


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


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


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



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



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



“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:


// 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


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 {


// 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:



// Create the application properties object

ApplicationProperties appProperties = new ApplicationProperties();


// object that makes or receives the telephone calls

.

.

.

}

getting started


.

.

.

}

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:



// 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) {



}


// 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


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:





// Change some of the properties to match this particular environment

applicationProperties.setApplicationName("app1");

applicationProperties.setLocale(Locale.US);

.

.

.

}

.

.

.

}

getting started


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:





// 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


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


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:



.

.

.



appProperties.setApplicationName("app1");


// Create the WVR object. The this keyword registers the application

// as the owner of the WVR object


// 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


.

}

}

}

To make an outgoing call:







// Create the WVR object. The this keyword registers the application

// as the owner of the WVR object


// 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

.

.

.


// 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():



// Define a reference variable for a Call object, so we avoid

// creating multiple instances later on in the loop

Call call = null;



starting the call




// Create the WVR object


// 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

.

.

.

}


// 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




// Define a reference variable for a Call object, so we avoid

// creating multiple instances later on in the loop

Call call = null;







// Create a boolean to control the call-handling loop


// Create the loop


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

}


// Print debugging information

e.printStackTrace();

}

finally {

// Return the call

call.returnCall();

}

}

}

}

finishing with a call


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


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


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


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:


.

.

.

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


DTMFSequence()

Constructs an empty DTMF sequence object. You can set the sequence

later using the setKeySequence() method.



DTMFSequence(java.lang.String sequence)

Constructs a DTMF sequence object with the specified sequence.

For example:


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


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().



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:


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




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:


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




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:


// 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).


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().



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:


// 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

″&″).


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:


// Create an audio string

public AudioString letters = new AudioString("ABCD");

.

.

.

}



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.


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:


.

.

.

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



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


.

.

.

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



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:


.

.

.

// 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



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


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


appProperties.setApplicationName("myApplication");


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



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.


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:


.

.

.

// 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



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.




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)


a single MediaType, and specified timeout.

InputAttributes(Playable message, int timeout)


a Playable object, and specified timeout.

For example:


.

.

.

// 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");


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



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.


3 invalidInputMessage That is not a valid credit card

number.

Does not

press any

keys, or

presses fewer

than 16.



4 timeoutMessage You did not enter 16 digits. Presses #12#

*123 ###8

8888

(an invalid

number).

oneMoreRepeatMessage You have one more chance...



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:



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



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:


.

.

.

// 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);

.

.

.



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


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




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



terminationKey property of the InputResult class. To find out which key was

pressed, use the InputResult.getTerminationKey() method.


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:


.

.

.


// default values

public DTMFAttributes myDTMFAtts = new DTMFAttributes();


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.



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.


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:


.

.

.


// default values

public RecoAttributes myRecoAtts = new RecoAttributes();


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:


.

.

.

// 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();

.

.

.

}

}



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.



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


.

.

.

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



// 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:


.

.

.

// 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);



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:


.

.

.

// 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


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():


.

.

recording the caller’s voice input


.


ApplicationProperties applicationProperties = new ApplicationProperties();

// Set the application locale


.

.

.

}

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


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:



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



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


file_name = euros.wav

;

segment_name = EUR_minorcur


file_name = cent.wav

;

segment_name = EUR_minorcurs


file_name = cents.wav

;

Figure 20. Example of a control file



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


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.



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



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


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


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


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


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


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


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


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


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


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

}


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



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



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



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()


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()


Returns the CTI keys for this call

getting called and calling numbers and application call data


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:


.

.

.

// 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


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


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


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:


.

.

.

// 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)


invoking a state table


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:


.

.

.

// 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

}





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.


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


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


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


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


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


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.


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:



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.


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


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


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


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


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?


menu” on page 134

Message To leave a message for us... press 1.


menu” on page 134

Number To leave a telephone number so that we

can call you... press 2.


menu” on page 134

Order To order an item from our catalog... press

3.


menu” on page 134

Operator To talk to one of our agents... press 4.


menu” on page 134

Hangup To disconnect... press 5.


menu” on page 134

MenuFooter Please press the key corresponding to

your choice.


menu” on page 134

InvalidKey You pressed an invalid key.


menu” on page 134

OneMore You have one more chance.


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.



PressKey When you have finished, press the

pound key.



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


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.



ThankYou Thank you.



OneMoreTime You have one more chance to key in a

six-digit number.



NoValidInput You have not entered a valid number.



NumberInvalid That is not a valid number.



NotEnough You did not key enough digits.



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.



Quantity Please key in the quantity you require,

followed by the pound key.



YouOrdered You have ordered...



Items ...items of product number...



IsThisOK Is this OK?



ForYesPress1 For yes, press 1.



ForNoPress2 For no, press 2.



MailOrder We will mail your order to you

immediately.


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.



181

ExpiryDate Please key in the expiration date.



181

DateFormat The expiry date is four digits, month

month, year year.



181

InvalidCard Sorry, these credit card details are not

valid.



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



OrderDate ...and will be delivered on...



OrderRef Please note your customer reference is...

“Tutorial 10: Transfer to an agent

(menu item 4)” on page 198

PleaseHold Please hold.



CallerForYou We have a caller for you.



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.


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.


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.


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,


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"




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.


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

*/


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

*/


5

// Define the Call object reference variable

Call call = null;

6

// Set the application properties




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();

}


13



}//try

}//voiceMain()



14 // Create an instance of the class and invoke the run method

InApp aInApp = new InApp();

aInApp.run();

}//main()

}//InApp


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:


page 41.



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

.


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.


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.


Attribute

object


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


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




in “Tutorial 3: Caller exits from the application (menu item 5)” on page

142.


Code for Tutorial 2

package tut;





/**

*

* A simple WVR application

*/




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





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;


7 // Create a flag to control whether we continue to loop around in the voiceMain() method taking calls


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

/**


*/


// Define the Call object

Call call = null;








9

// Create a variable that will be used to give each call a unique number

int callNumber = 0;

try {

10


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 {



15

while (callInProgress) {


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

}


// 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

}


17

// Check if Call object has been created. If yes, play the Difficulties message.

if (call.isActive()) call.play(VS_DIFFICULTIES);



}

finally {

18

// Return the call

call.returnCall();

}//try

}//while

}




}//try

}//voiceMain()

19

// Tell the application to stop taking calls when the node shuts down

public void voiceAppStop() { keepTakingCalls = false; }


// Create an instance of the class and invoke the run method


aInApp.run();

}//main()

}//InApp


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.


tutorial:


page 41.



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.





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?


v Hang up.

v Dial the application again, to make sure that the application has

returned to waiting for a call.



application. Then switch back to the Java perspective to continue coding in

“Tutorial 4: Leave a message (menu item 1)” on page 148.


Code for Tutorial 3

package tut;





/**

*


*/










// Create an array to store the menu choices










// Create the segment objects for the menu items, and store them in an array







};








1 // Create the segment objects for the hangup menu item

private static final VoiceSegment VS_THANKCALLING = new VoiceSegment(CATEGORY, "ThankCalling");






// Create a flag to control whether we continue to loop around in the voiceMain() method taking calls



public InApp() {












}//InApp

/**


*/



Call call = null;









int callNumber = 0;

try {



callNumber++;

// Wait for a call





try {




// Play the menu and get the caller’s response.



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 {


System.out.println("Caller chose option " + choice);

}//if

}//while

}



}



}






}

finally {

// Return the call

call.returnCall();

}//try

}//while

}




}//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);


c return false;

}//hangUp()






aInApp.run();

}//main()

}//InApp


Tutorial 4: Leave a message (menu item 1)


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.


tutorial:


page 41.



You also need to have completed Tutorials 1 through 3 as the code from these

tutorials is used as a base for this tutorial.


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

.

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


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:





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.




“Tutorial 5: Application makes a call” on page 154.


Code for Tutorial 4

package tut;





/**

*


*/



























};







// Create the segment objects for the hangup menu item



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");









public InApp() {












}//InApp

/**


*/



Call call = null;









int callNumber = 0;

try {



callNumber++;

// Wait for a call





try {










2

if (choice.equals(ITEM1_MSG)) {

callInProgress = recordMessage(call);

}

else if (choice.equals(ITEM5_HANGUP)) {


}

else {



}//if

}//while

}



}



}






}

finally {

// Return the call

call.returnCall();

}//try

}//while

}





}//try

}//voiceMain()

3

/**

* Method recordMessage.

* @param call

* @return boolean

*/

a

private boolean recordMessage(Call call) throws WVRException {


b // Play segments to instruct the caller on how to record their message

call.play(VS_RECORD);

call.play(VS_PRESS_KEY);

c


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

*/




return false;

}//hangUp()






aInApp.run();

}//main()

}//InApp


Tutorial 5: Application makes a call


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.


tutorial:


page 41.



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.


classes that will be required by the application

2

:

v java.util.Locale

v com.ibm.telephony.beans.directtalk.ApplicationProperties


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.


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

.


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.




in “Tutorial 6: Key in a telephone number (menu item 2)” on page 158.


Code for Tutorial 5

package tut;

2





/**

*

* 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


4

// Create the voice segment objects

private static final VoiceSegment VS_FOLLOWING_MESSAGE = new VoiceSegment(CATEGORY, "FollowingMessage");


/**


*/


5

// Define the call object reference variable

Call call = null;

6





7



8


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




}


12 finally {

// If the call exists, return it

if (call != null) call.returnCall();

} //try

}//voiceMain()


13


OutApp aOutApp = new OutApp();

aOutApp.run();

}//main

}//OutApp


Tutorial 6: Key in a telephone number (menu item 2)



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.


tutorial:


page 41.



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


1. Return to the InApp class.


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


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


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


Attribute

object


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

.

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.


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






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.




“Tutorial 7: Order an item from a catalog (menu item 3)” on page 167.


Code for Tutorial 6

package tut;





/**

*


*/



























};









// Create the segment objects for the record a message menu item






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() {




return 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;




public InApp() {













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

/**


*/



Call call = null;








// Create a variable which will be used to give each call a unique number

int callNumber = 0;

try {



callNumber++;

// Wait for a call




try {











// Menu item 1 - record a message


}


6 else if (choice.equals(ITEM2_NUMBER)) {

// Menu item 2 - leave a telephone number

callInProgress = leavePhoneNumber(call);

}


// Menu item 5 - hang up


}

else {



}//if

}//while

}



}



}






}

finally {

// Return the call

call.returnCall();

}//try

}//while

}




}//try

}//voiceMain()

/**


* @param call

* @return boolean

*/


// Play segments to instruct the caller on how to record their message







return true;

}//recordMessage()


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);

}


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

*/




return false;

}//hangUp()






aInApp.run();

}//main()

}//InApp


Tutorial 7: Order an item from a catalog (menu item 3)



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.


tutorial:


page 41.






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.


classes that will be required by the Catalog class

2

:



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

:


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

:


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


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

.


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

.

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






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.


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.




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 :


Code for Tutorial 7 Catalog class

package tut;

2



/**

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


4


private static final String ITEM1_YES = "Yes";

private static final String ITEM2_NO = "No";


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



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 };


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





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);




}//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);


19 // Verifies with the caller that the choice is correct, if yes, breaks out of loop


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()

}


Code for Tutorial 7 InApp class

package tut;





/**

*


*/



























};















// Create the segment objects for the key in a telephone number menu item













return null;

}

};














22 // Create an instance of the Catalog class

private Catalog catalog = new Catalog();


public InApp() {












// Set the input attributes for getting the telephone number












}//InApp

/**


*/



Call call = null;









int callNumber = 0;

try {



callNumber++;

// Wait for a call





try {













}

else if (choice.equals(ITEM2_NUMBER)) {



}

23

else if (choice.equals(ITEM3_ORDER)) {

// Menu item 3 - place an order

callInProgress = order(call);

}




}

else {



}//if

}//while

}



}



}






}

finally {

// Return the call

call.returnCall();

}//try

}//while

}




}//try

}//voiceMain


/**


* @param call

* @return boolean

*/


// Play segments to instruct the caller on how to record their message








return true;

}

/**


* @param call

* @return boolean

*/


try {




}


return true;

}//try

// Play the ThankYou message to acknowledge a valid number


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);


c return true;

}//order

/**

* Method hangUp.

* @param call

* @return boolean

*/




return false;

}






aInApp.run();

}//main

}//InApp


Tutorial 8: Credit card validation (menu item 3 continued)


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.


tutorial:


page 41.






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.


classes that will be required by the CardChecker class

2

:



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

.


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


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


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.


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


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

.







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.




in “Tutorial 9: Order information (menu item 3 continued)” on page 190.


Code for Tutorial 8 CardChecker class

package tut;

2



/**

* 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


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


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;


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



package tut;



/**


*/

class Catalog {















};






// Create the segment objects for the verifying the order menu


// Create the segment objects for the result

private static final VoiceSegment VS_MAIL_ORDER = new VoiceSegment(CATEGORY, "MailOrder");


15 private static final VoiceSegment VS_SORRY = new VoiceSegment(CATEGORY, "Sorry");






// Create some attribute objects for getting the product number from the caller
















16 private CardChecker cardChecker = new CardChecker();


public Catalog() {
















}//Catalog()



double prodNum = 0;


while (true) {












call.play(order);

// Verifies with the caller that the choice is correct, if yes, breaks out of loop




}//while

17

if (cardChecker.takeCardDetails(call)) {



}

else {

18

call.play(VS_SORRY);

} //if

}//takeOrder()

}


Tutorial 9: Order information (menu item 3 continued)


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.


tutorial:


page 41.






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.wvr.Playable

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

.


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.







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.




in “Tutorial 10: Transfer to an agent (menu item 4)” on page 198.


Code for Tutorial 9 OrderInfo class

package tut;

2

import java.util.Calendar;


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


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");

}


12 // Return the order information

public MediaType[] toMedia() {

return orderInfo;

}

}



package tut;



/**


*/

class Catalog {















};






// Create the segment objects for the verifying the order menu


// Create the segment object for the result

private static final VoiceSegment VS_SORRY = new VoiceSegment(CATEGORY, "Sorry");






// Create some attribute objects for getting the product number from the caller













private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, MENU_ITEMS);



private CardChecker cardChecker = new CardChecker();


public Catalog() {
















}//Catalog()



double prodNum = 0;


while (true) {












call.play(order);

// Verifies with the caller that the choice is correct, if yes, breaks out of loop




}//while

if (cardChecker.takeCardDetails(call)) {



13 call.play(new OrderInfo(quantity, prodNum));

}

else {

call.play(VS_SORRY);

} //if

}//takeOrder()

}


Tutorial 10: Transfer to an agent (menu item 4)



call transfer functionality to the fourth menu item. This tutorial introduces the

use of the Call class to perform a call transfer.


tutorial:


page 41.






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


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


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

.

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



(default.cff).



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.


Code for Tutorial 10

package tut;





/**

*


*/
















// application within the JVM...











};























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");









return null;

}//validate

};













// Create an instance of the Catalog class



public InApp() {

























}//InApp

/**


*/



Call call = null;









int callNumber = 0;

try {



callNumber++;

// Wait for a call




try {













}





}




}

2

else if (choice.equals(ITEM4_OPERATOR)) {

// Menu item 4 - transfer to an agent

callInProgress = operator(call);

}




}

else {



}//if

}//while

}


// Caller has hung up - ignore exception, application will go to finally block

}



}






}

finally {

// Return the call

call.returnCall();

}//try

}//while

}




}//try

}//voiceMain

/**


* @param call

* @return boolean

*/


// Play segments to instruct the caller how to record their message








return true;

}//recordMessage

/**


* @param call

* @return boolean

*/


try {




}


return true;

}//try

// Acknowledge a valid number



return true;

}//leavePhoneNumber

/**

* Method order.

* @param call

* @return boolean

*/




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();


f // No further action required, so indicate that call can end

return false;

}


g

// Get the original caller back

call.retrieve();

h


call.play(VS_AGENT_NOT_AVAIL);

i


return true;

}//try

}//operator

/**

* Method hangUp.

* @param call

* @return boolean

*/




return false;

}//hangUp




// Create an instance of the InApp class and invoke the run method


aInApp.run();

}//main

}//InApp


Tutorial 11: Using speech recognition and text-to-speech


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.


tutorial:


page 41.






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:





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


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

;


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.


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


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.





v Listen for the text of the menu. Do you hear the text that you wrote for

the menu in the application?


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.



application.


Code for Tutorial 11

package tut;





/**

*


*/















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" };


// application within the JVM...




3



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.")

};




4 private static final TextToSpeech VS_MENU_FOOTER = new TextToSpeech("Please press the key, or say the word,

corresponding to your choice.");



















// 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");









return null;

}//validate

};




6 private MenuAttributes menuAtts = new MenuAttributes(MENU_PROMPTS, MENU_ITEMS, MENU_KEYS, MENU_WORDS);


private RecoAttributes menuRecoAtts = new RecoAttributes();








// Create an instance of the Catalog class



public InApp() {













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);













}//InApp

/**


*/



Call call = null;









int callNumber = 0;

try {



callNumber++;

// Wait for a call




try {














}




}




}

else if (choice.equals(ITEM4_OPERATOR)) {

// Menu item 4 - transfer to an agent

callInProgress = operator(call);

}




}

else {



}//if

}//while

}


// Caller has hung up - ignore exception, application will go to finally block

}



}






}

finally {

// Return the call

call.returnCall();

}//try

}//while

}




}//try

}//voiceMain


/**


* @param call

* @return boolean

*/


// Play segments to instruct the caller how to record their message







return true;

}//recordMessage

/**


* @param call

* @return boolean

*/


try {




}


return true;

}//try

// Acknowledge a valid number



return true;

}//leavePhoneNumber

/**

* Method order.

* @param call

* @return boolean

*/




return true;

}//order


/**

* 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;

}


// Get the original caller back

call.retrieve();


call.play(VS_AGENT_NOT_AVAIL);


return true;

}//try

}//operator

/**

* Method hangUp.

* @param call

* @return boolean

*/




return false;

}//hangUp




// Create an instance of the InApp class and invoke the run method


aInApp.run();

}//main

}//InApp



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


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


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.


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


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.


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.


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.


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


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


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


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.


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.


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.


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


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


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


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


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


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


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


... ...

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


(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


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


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


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


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


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


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


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.




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


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.


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 ITU-T White book (1993) Q.711 - Q.714


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 ITU-T White book (1992) Q.761 - Q.764


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


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


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


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


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


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


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


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


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


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


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


��

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

Documents

Developing Java Applications - Blueworx...Summary of methods used for telephony-related functions . . . . . .96 Handing a call to another application . .97 Transferring a call to an