Designing and Managing State Table Applications...Converting voice data transferred from non-AIX computer systems.....110 Saving voice segments..... 111 The batch voice import utilities

WebSphere Voice Response for AIX with DirectTalk

Technology

Designing and Managing State Table

Applications

Version 4.2

SC34-6388-03

��

WebSphere Voice Response for AIX with DirectTalk

Technology

Designing and Managing State Table

Applications

Version 4.2

SC34-6388-03

��

Note

Before using this information and the product it supports, read the general information under “Notices” on

page 335.

Fourth 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 1991, 2008.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract

with IBM Corp.

Contents

Figures . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . xi

About this book . . . . . . . . . . xiii

Who should use this book . . . . . . . xiii

How to use this book . . . . . . . . xiii

Following the procedures in this book . . . xiv

Typographic conventions . . . . . . . xiv

Accessibility . . . . . . . . . . . . xv

Notes on terminology . . . . . . . . . xv

Where to find more information . . . . . xvi

Useful Web sites . . . . . . . . . xvi

Making comments on this book . . . . . xvi

Part 1. The life cycle of a voice

response service . . . . . . . . . 1

Chapter 1. Introduction . . . . . . . . 3

Requirements and Planning . . . . . . . 4

Business requirements . . . . . . . . 4

Telephony requirements . . . . . . . 4

User requirements . . . . . . . . . 4

Data requirements . . . . . . . . . 5

Programming requirements . . . . . . 5

IBM solutions . . . . . . . . . . . 5

Suggestions . . . . . . . . . . . 5

Design . . . . . . . . . . . . . . 6

High-level and low-level design . . . . . 6

Design considerations . . . . . . . . 6

Suggestions . . . . . . . . . . . 7

Implementation . . . . . . . . . . . 8

What does implementation involve? . . . 9

System parameters . . . . . . . . . 9

Testing the voice response service . . . . 9

Migrating application objects . . . . . 10

Using an external code repository . . . . 10

Suggestions . . . . . . . . . . . 11

Packaging and distribution . . . . . . . 11

Distributing an application to other

WebSphere Voice Response systems . . . 12

Suggestions . . . . . . . . . . . 12

Maintenance and support . . . . . . . 12

Housekeeping . . . . . . . . . . 13

Archiving application objects . . . . . 13

Distributing updates . . . . . . . . 13

Suggestions . . . . . . . . . . . 13

Chapter 2. Designing a voice application 15

User participation in dialog design . . . . 17

Lo-fi prototyping . . . . . . . . . 17

Designing the dialog . . . . . . . . . 18

Design considerations . . . . . . . . 18

Choosing a dialog style . . . . . . . 19

Good things to do in voice applications . . . 22

Wording prompts for speech recognition

applications . . . . . . . . . . . . 23

Handling all responses . . . . . . . 24

Speech recognition while a prompt is

playing . . . . . . . . . . . . 24

Interrupting prompts . . . . . . . . 24

Limitations . . . . . . . . . . . 24

Defining server requirements . . . . . . 24

Chapter 3. Creating and managing

application objects . . . . . . . . . 27

What are application objects? . . . . . . 28

Managing application objects efficiently . . . 29

Using the applications and application

windows . . . . . . . . . . . . . 30

Discovering what applications and objects are

in the system . . . . . . . . . . . . 30

Editing and testing application objects . . . 33

Creating an application . . . . . . . . 34

Exporting an application . . . . . . . . 38

Exporting one or more objects . . . . . . 45

Importing application objects . . . . . . 47

Migrating from an earlier release of IBM

WebSphere Voice Response for AIX . . . . 51

Frequently asked questions . . . . . . . 52

Do you have to create applications? . . . 53

What about the integrity of applications

that are already in use? . . . . . . . 53

Where are newly-created or migrated

objects put? . . . . . . . . . . . 53

What happens when you import objects

belonging to an application that does not

exist on the target system? . . . . . . 54

© Copyright IBM Corp. 1991, 2008 iii

When should you use full export, delta

export, and partial export? . . . . . . 54

When should you export prerequisites

along with an application? . . . . . . 54

What happens to “duplicate” objects? . . 54

What if more than one application needs

to use the same object? . . . . . . . 55

Moving objects from the default or user

applications . . . . . . . . . . . . 56

Deleting an application . . . . . . . . 56

The dtimport and dtexport commands . . . 57

dtexport command . . . . . . . . . 58

dtimport command . . . . . . . . 61

Chapter 4. Overview of application objects 63

State tables . . . . . . . . . . . . 63

State table actions . . . . . . . . . 63

Example state table . . . . . . . . 69

State table variables and parameters . . . 70

Returning data to the state table . . . . 73

Possible results . . . . . . . . . . 73

Entry points . . . . . . . . . . . 74

Prompts . . . . . . . . . . . . . 74

System prompts . . . . . . . . . . 75

System prompts in languages other than

U.S. English . . . . . . . . . . . 77

System prompts in French . . . . . . 78

System prompts in Brazilian Portuguese 80

Changing the system prompts for your

language . . . . . . . . . . . . 80

Voice segments . . . . . . . . . . . 82

Voice directories . . . . . . . . . 82

Voice tables . . . . . . . . . . . 82

System voice segments . . . . . . . 83

System voice tables . . . . . . . . 83

3270 and custom servers . . . . . . . . 85

3270 servers . . . . . . . . . . . 86

Custom servers . . . . . . . . . . 86

Further information . . . . . . . . . 87

Chapter 5. Creating an application profile 89

Introduction . . . . . . . . . . . . 89

How to create an application profile . . . . 90

Using the command line . . . . . . . 94

wvrapplprof command . . . . . . . 94

Part 2. Design topics . . . . . . 99

Chapter 6. Creating the voice output for

voice applications . . . . . . . . . 101

Overview of voice signal processing . . . 101

Planning your voice segments . . . . . 103

Compression . . . . . . . . . . 105

Recording voice segments over the

telephone . . . . . . . . . . . 105

High-quality voice data . . . . . . . 106

Transferring the prerecorded data to

WebSphere Voice Response . . . . . 109

Converting voice data transferred from

non-AIX computer systems . . . . . 110

Saving voice segments . . . . . . . 111

The batch voice import utilities or the

Voice Segments window? . . . . . . 111

The voice segment database . . . . . . 112

Creating prompts . . . . . . . . . . 112

About creating prompt directories . . . 113

About defining prompts . . . . . . 113

Default and language-specific prompts 113

Using languages other than U.S. English 114

Modifying the system voice tables . . . 116

Editing the system prompts . . . . . 116

Creating multilingual applications . . . . 117

Using application profiles . . . . . . 117

Using the System: Current language

system variable . . . . . . . . . 117

Chapter 7. Handling key input from

callers . . . . . . . . . . . . . 119

Making a selection (single key) . . . . . 119

Entering data (multiple keys) . . . . . . 119

Alphabetic to numeric key mapping . . 119

Pressing keys while voice data is being

played . . . . . . . . . . . . . 119

Chapter 8. Handling spoken input from

callers . . . . . . . . . . . . . 121

Speech recognition with distributed voice

technologies . . . . . . . . . . . 121

Barge-in, voice interrupt detection, and echo

cancellation . . . . . . . . . . . . 121

Barge-in . . . . . . . . . . . . 121

Voice interrupt detection . . . . . . 122

Echo cancellation . . . . . . . . . 123

Writing a custom server to handle speech

recognition . . . . . . . . . . . . 125

Chapter 9. Accessing data with a 3270 or

custom server . . . . . . . . . . 127

iv Designing and Managing State Table Applications

Sample 3270 and custom servers . . . . . 128

CustomServerSample . . . . . . . 128

3270ServerSample . . . . . . . . . 129

Chapter 10. Telephony activity . . . . . 133

Handling switch and protocol limitations 133

Handling switch tones . . . . . . . 133

Accounting for protocol limitations . . . 133

Answering calls . . . . . . . . . . 135

How does WebSphere Voice Response

answer an incoming call? . . . . . . 135

Making, transferring, reconnecting, and

terminating calls . . . . . . . . . . 142

Call transfer . . . . . . . . . . 142

State table actions . . . . . . . . . 143

System parameters . . . . . . . . 143

Coordinated call and data transfer . . . . 143

What does the state table have to do? . . 144

What format must the data be in? . . . 145

How much data can you pass? . . . . 145

Examples . . . . . . . . . . . 146

Setting the MessageWaiting Indicator using

CallPath Server . . . . . . . . . . 147

Chapter 11. Designing voice messaging

applications . . . . . . . . . . . 149

Voice messaging resources . . . . . . . 149

Voice mailboxes . . . . . . . . . 149

Greetings . . . . . . . . . . . 150

Audio names . . . . . . . . . . 150

Distribution lists . . . . . . . . . 150

Accessing mailbox information . . . . 150

Using state table actions for voice messaging 152

Interacting with callers and messages . . . 153

Recording messages . . . . . . . . 154

Sending messages . . . . . . . . . 154

Retrieving messages . . . . . . . . 154

Playing messages . . . . . . . . . 155

Forwarding messages . . . . . . . 155

Annotating messages . . . . . . . 156

Changing message attributes . . . . . 156

Deleting messages . . . . . . . . 156

Saving messages . . . . . . . . . 156

System parameters that affect voice

messaging . . . . . . . . . . . . 157

A sample voice message application . . . 157

RecordAudionameSample . . . . . . 157

VoiceMessagingSample . . . . . . . 158

An example state table . . . . . . . 160

An example prompt . . . . . . . . 162

Chapter 12. Managing voice messaging

resources . . . . . . . . . . . . 165

Voice mailboxes . . . . . . . . . . 165

How do I create a mailbox? . . . . . 165

How is mailbox information used? . . . 166

Controlling messages . . . . . . . . 166

Limiting message length . . . . . . 166

Limiting the number of messages . . . 167

What are subscriber classes? . . . . . 167

How do subscriber classes work? . . . 167

When should you define subscriber

classes? . . . . . . . . . . . . 168

Creating mailboxes for application use . . . 168

Before you start . . . . . . . . . 168

Using the graphical interface . . . . . 168

Using the wvrapplprof and wvrmailbox

commands . . . . . . . . . . . 175

wvrmailbox command . . . . . . . 175

Creating a subscriber class . . . . . . . 183

Creating a distribution list . . . . . . . 185

Chapter 13. Telecommunications Devices

for the Deaf . . . . . . . . . . . 189

Making voice applications available to TDD

users . . . . . . . . . . . . . . 189

TDD voice segments and prompts . . . 190

TDD custom server subroutines . . . . 191

Valid TDD characters . . . . . . . 192

Chapter 14. Background music . . . . 193

Why use background music? . . . . . . 193

How many tunes can you play at once? . . 194

When should you play background music? 195

How loud is the background music? . . . 196

T1 A-law systems . . . . . . . . . . 196

Voice interrupt detection and speech

recognition . . . . . . . . . . . . 196

Using the WebSphere Voice Response Juke

Box . . . . . . . . . . . . . . 198

The Juke_Box custom server . . . . . 198

Starting and stopping the Juke_Box

custom server . . . . . . . . . . 198

The Juke Box configuration file . . . . 198

Adding background music to a state table 200

Prerequisites . . . . . . . . . . 200

Debugging your state table . . . . . 203

Getting music into WebSphere Voice

Response . . . . . . . . . . . . 204

Supplied tunes . . . . . . . . . . 204

Contents v

Chapter 15. TDM connection management 207

Concepts . . . . . . . . . . . . . 207

Ports . . . . . . . . . . . . . 207

Port sets . . . . . . . . . . . . 207

Resource groups . . . . . . . . . 208

Port set naming . . . . . . . . . . 209

The TDM sample application . . . . . . 209

Prerequisites . . . . . . . . . . 210

Designing an application . . . . . . . 211

State tables . . . . . . . . . . . 212

Custom servers . . . . . . . . . 212

The design of the sample application . . 212

Implementation notes . . . . . . . 215

Chapter 16. Designing for a single system

image . . . . . . . . . . . . . 221

Querying the single system image

configuration . . . . . . . . . . . 221

Chapter 17. Using ISDN call transfer . . 223

When can I use ISDN Two B-channel

transfer? . . . . . . . . . . . . . 224

When can I use ISDN RLT call transfer? . . 224

When can I use ISDN single step call

transfer? . . . . . . . . . . . . . 225

What the ISDN call transfer application does 225

Limitations of ISDN call transfer . . . . 226

Installing the application . . . . . . 226

Configuring the ISDN_Call_Transfer

custom server . . . . . . . . . . 229

How to use ISDN call transfer . . . . 231

Custom server functions . . . . . . 243

State table definitions . . . . . . . 247

What the ISDN single step call transfer

application does . . . . . . . . . . 254

Limitations of ISDN single step call

transfer . . . . . . . . . . . . 254

Installing the application . . . . . . 254

Configuring the SSTransfer custom server 257

How to use ISDN single step call transfer 258

Custom server functions . . . . . . 258

State table definitions . . . . . . . 264

Chapter 18. Using the

IBM_Trombone_Custom_Server . . . . 267

What is a trombone (in telephony terms)? 267

What you can use a trombone for . . . 268

Installing the IBM_Trombone application . . 269

Components of the IBM_Trombone

application . . . . . . . . . . . 269

Installing the IBM_Trombone application 270

Configuring IBM_Trombone_Custom_Server 271

About child helper processes . . . . . 272

Setting configuration options . . . . . 273

How to use the trombone operation . . . . 274

How tromboning works . . . . . . 275

Setting up a trombone operation . . . . 276

Terminating a trombone operation using

third party hang-up . . . . . . . . 277


caller hang-up . . . . . . . . . . 278


caller DTMF . . . . . . . . . . 279

Voice paths . . . . . . . . . . . 279

Custom server functions . . . . . . . 280

Custom server function definitions . . . 280

TromboneCall . . . . . . . . . . 280

TromboneMakeCall . . . . . . . . 283

TromboneMakeCallStatus . . . . . . 285

TromboneConnectCall . . . . . . . 286

TromboneDisconnectCall . . . . . . 287

State table definitions . . . . . . . . 288

IBMTromboneCall . . . . . . . . . 289

IBMTromboneConn . . . . . . . . 295

IBMTromboneC5 . . . . . . . . . 296

IBMTromboneC10 . . . . . . . . . 296

IBMTromboneDisc . . . . . . . . 297

IBMTromboneLog . . . . . . . . . 298

IBMTromboneMake . . . . . . . . 298

IBMTromboneMus . . . . . . . . 301

IBMTromboneOut . . . . . . . . . 301

IBMTromboneRdy . . . . . . . . 303

IBMTromboneWait . . . . . . . . 304

IBMTromboneXmp . . . . . . . . 306

IBMTromboneXmpA . . . . . . . . 306

IBMTromboneXmpB . . . . . . . . 307

IBM_Trombone_Custom_Server errors . . . 308

Chapter 19. Using the VOX_CTI Custom

Server . . . . . . . . . . . . . 309

Avaya Interaction Center VOX Connector for

WebSphere Voice Response . . . . . . 309

Installation . . . . . . . . . . . . 309

VOX_CTI.ini file configuration . . . . . 309

VOX_CTI Custom Server functions . . . . 311

Alarm . . . . . . . . . . . . . 312

Getvdu . . . . . . . . . . . . 312

Getvox . . . . . . . . . . . . 313

Gone . . . . . . . . . . . . . 314

Newcall . . . . . . . . . . . . 314

vi Designing and Managing State Table Applications

Ping . . . . . . . . . . . . . 314

Pseudo_Ani . . . . . . . . . . . 315

Setvdu . . . . . . . . . . . . 315

Tr . . . . . . . . . . . . . . 316

Transfer . . . . . . . . . . . . 316

VOX_CTI function return codes . . . . . 317

General guidelines . . . . . . . . . 318

Appendix A. ID and name limitations . . 319

Appendix B. Voice interrupt detection:

technical information . . . . . . . . 323

Example of how voice interrupt detection

works . . . . . . . . . . . . . . 325

Summary . . . . . . . . . . . . 326

Appendix C. Background music: technical

information . . . . . . . . . . . 327

Sound levels . . . . . . . . . . . 327

The music volume ceiling and the prompt

volume ceiling . . . . . . . . . . 328

Customizing the Juke Box . . . . . . . 330

Source code files for the Juke Box . . . 330

Collecting statistics from the Juke_Box

custom server . . . . . . . . . . 331

Building music players . . . . . . . 331

Juke_Box custom server communication

with pl_elem and pl_seg . . . . . . 331

Message queue . . . . . . . . . 332

Writing your own background music

subsystem . . . . . . . . . . . . 333

Notices . . . . . . . . . . . . . 335

Trademarks . . . . . . . . . . . . 337

Glossary . . . . . . . . . . . . 339

List of WebSphere Voice Response and

associated documentation . . . . . . 365

WebSphere Voice Response software . . . 365

IBM hardware for use with WebSphere Voice

Response . . . . . . . . . . . . 366

Withdrawn from marketing but still

supported . . . . . . . . . . . 366

WebSphere Voice Response related products 366

WebSphere Voice Server for

Multiplatforms . . . . . . . . . . 366

Unified Messaging for WebSphere Voice

Response . . . . . . . . . . . 367

AIX and the IBM pSeries computer . . . 367

HACMP . . . . . . . . . . . . 367

SS7 . . . . . . . . . . . . . 367

Integrated Services Digital Network . . . 368

Bellcore Specifications for ADSI Telephones 369

Index . . . . . . . . . . . . . 371

Contents vii

viii Designing and Managing State Table Applications

Figures

1. The life cycle of a voice response service 3

2. Example of main activities to be

performed by a voice application. . . . 15

3. Voice application objects . . . . . . 28

4. The Application window . . . . . . 31

5. Two applications, one of which contains

commonly-used objects . . . . . . 55

6. System variables . . . . . . . . . 71

7. A list of parameters to be passed to a

prompt . . . . . . . . . . . . 73

8. Barge-in . . . . . . . . . . . 122

9. Voice interrupt detection . . . . . 122

10. Voice interrupt detection with speech

recognition . . . . . . . . . . 123

11. Calibrating the echo canceller . . . . 125

12. External speech recognition overview 126

13. Accessing data using custom servers

and 3270 servers (for example, a

system/390 server) . . . . . . . 127

14. How WebSphere Voice Response finds

the state table to handle an incoming

call . . . . . . . . . . . . . 137

15. Application profile needed with one

state table for all . . . . . . . . 140

16. Application profiles needed when

using called number . . . . . . . 141

17. Application profiles needed when

using channel identification . . . . 141

18. CallPath Server and WebSphere Voice

Response installed in the same pSeries

computer . . . . . . . . . . . 144

19. Receiving a call and data transferred

by CallPath Server . . . . . . . . 146

20. Transferring a call and data to another

number using CallPath Server . . . . 147

21. Using CallPath Server to set the

message waiting indication . . . . . 148

22. VoiceMsgMenu and VoiceMsgAnswer 158

23. VoiceMsgRecord and VoiceMsgListen 159

24. VoiceMsgOptions . . . . . . . . 160

25. Example listing of the first two states

in a state table . . . . . . . . . 162

26. Two people communicating using TDD 189

27. How WebSphere Voice Response

interacts with a TDD . . . . . . . 190

28. Using background music . . . . . 194

29. What the caller hears at each stage in

the interaction . . . . . . . . . 197

30. Schematic overview of part of a state

table using background music . . . 203

31. Getting tunes into WebSphere Voice

Response for background music . . . 206

32. Ports, port sets, sources, and sinks 208

33. Making and breaking a trombone

connection . . . . . . . . . . 214

34. The TromboneCS state machine 215

35. Voice paths in a trombone connection 218

36. Voice paths when the switch is in TDM

position . . . . . . . . . . . 219

37. Voice paths when the switch is in host

position . . . . . . . . . . . 219

38. Event flow for a blind (immediate)

transfer . . . . . . . . . . . 232

39. Event flow for a screened transfer with

call answer supervision (for a

successful call) . . . . . . . . . 234


call answer supervision (for an

unsuccessful call) . . . . . . . . 236


third party consultation (ending in a

transfer) . . . . . . . . . . . 238


third party consultation (ending up

reconnecting to the original caller) . . 241

43. Voice path between caller and third

party during a trombone operation . . 268

44. High-level flow chart for the

IBMTromboneXmp state table . . . . 275

45. Event flow required to set up a

trombone operation. . . . . . . . 276

46. Event flow required to terminate a

trombone operation when the third

party hangs up . . . . . . . . . 277


trombone operation when the caller

hangs up . . . . . . . . . . . 278

© Copyright IBM Corp. 1991, 2008 ix


trombone operation when the caller

requests this by dialing a DTMF

sequence . . . . . . . . . . . 279

49. WebSphere Voice Response detects a

voice interrupt . . . . . . . . . 324

50. How voice interrupt detection

parameters act on a voice sample . . . 325

51. Musical welcome state table: volume

levels . . . . . . . . . . . . 329

52. Playing prompts and tunes at the same

volume . . . . . . . . . . . 329

x Designing and Managing State Table Applications

Tables

1. Example dialog segments . . . . . . 16

2. Where To find newly-created objects 53

3. Example state table . . . . . . . . 69

4. Creating voice segments for WebSphere

Voice Response . . . . . . . . . 104

5. Responses for spot frequencies 109

6. Application profile examples . . . . 138

7. Fm Variable:Table Sheet Example

prompt . . . . . . . . . . . 162

8. Mailbox field names used with

wvrmailbox command . . . . . . 177

9. Applications simultaneously playing

tunes from music channels . . . . . 195

10. Example of a configuration file for the

Juke_Box custom server . . . . . . 200

11. Configuration options for the

ISDN_Call_Transfer custom server . . 229

12. Configuration options for the

SSTransfer custom server . . . . . 257

13. ISDN single step call transfer return

codes . . . . . . . . . . . . 259

14. Configuration options for

IBM_Trombone_Custom_Server. . . . 271

15. Return values for the

trombone_make_call_status parameter

of the TromboneCall function . . . . 282



of the TromboneMakeCall function . . 285

17. Status values supplied by the

TromboneMakeCallStatus function . . 285







20. Return values from the

IBMTromboneCall state table

(call_status) . . . . . . . . . . 291

21. System variables and parameters for

voice interrupt detection . . . . . . 323

22. System variables and parameters used

for background music. . . . . . . 327

23. Music volume and prompt volume

ceilings . . . . . . . . . . . 328

© Copyright IBM Corp. 1991, 2008 xi

xii Designing and Managing State Table Applications

About this book

This book tells you how to design voice applications to suit your requirements

for voice response services, and then provides guidance for implementing

them with IBM® WebSphere® Voice Response for AIX® with DirectTalk®

Technology. This book also tells you how to put applications into production

on one or more WebSphere Voice Response systems, and keep your

applications running smoothly.

Throughout this book, IBM WebSphere Voice Response for AIX is referred to

as WebSphere Voice Response.

Who should use this book

This book is for anyone involved in designing, implementing, or managing a

voice response service with WebSphere Voice Response. Knowledge of how

the voice response service fits into your business would be valuable for all

readers.

Before starting to read this book, you should be familiar with the first few

chapters of the WebSphere Voice Response for AIX: General Information and

Planning guide.

How to use this book

If you are commissioning a voice response service, you will find guidance on

how to specify and plan for it in Chapter 1, “Introduction,” on page 3 and

Chapter 2, “Designing a voice application,” on page 15.

If you are implementing an application, you should read this book to get

background information, before using the reference and procedural

information in the WebSphere Voice Response for AIX: Application Development

using State Tables reference manual, the WebSphere Voice Response for AIX:

Custom Servers reference manual, or the WebSphere Voice Response for AIX: 3270

Servers reference manual. This book provides specific guidance about

implementing various types of application and including different voice

processing functions in your applications, whereas the procedural information

in the other books is more generic. The background information in this book

is organized by function, whereas the reference information in the other books

is organized alphabetically.

If you are responsible for managing voice response services running in

production, use the information in Chapter 3, “Creating and managing

© Copyright IBM Corp. 1991, 2008 xiii

application objects,” on page 27, Chapter 5, “Creating an application profile,”

on page 89, and Chapter 12, “Managing voice messaging resources,” on page

165, as necessary.

This book contains background information and some procedural information,

with step-by-step instructions. The procedures explain how to complete the

tasks using the WebSphere Voice Response windows.

Following the procedures in this book

The procedures assume that you are already familiar with using a mouse and

window environment and that you know how to use the common actions

such as Save to work with information. If you are new to WebSphere Voice

Response, have a look at the WebSphere Voice Response for AIX: User Interface

Guide, which tells you how to log on and log off, and use the WebSphere

Voice Response windows efficiently.

Typographic conventions

This book uses the following typographic conventions:

boldface

Identifies an item that is in a WebSphere Voice Response window. The

item might be a keyword, an action, a field label, or a pushbutton.

Whenever one of the steps in a procedure includes a word in

boldface, look in the window for an item that is labeled with that

word.

boldface italics

Are used for emphasis. Take extra care wherever you see bold italics.

italics Identify one of the following:

v New terms that describe WebSphere Voice Response components or

concepts. A term that is printed in italics is usually followed by its

definition.

v Parameters for which you supply the actual names or values.

v References to other books.

monospace

Identifies one of the following:

v Text that you type in an AIX window. Because AIX is case sensitive,

ensure that you type the uppercase and lowercase characters exactly

as shown.

v Names of files and directories (path names).

how to use this book

xiv Designing and Managing State Table Applications

Accessibility

WebSphere Voice Response for AIX 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 application

development and system administration tasks with a text editor or line

commands—these are accessible if you use a screen reader product to

interface with them. Also, the default settings of the WebSphere Voice

Response graphical user interface can be changed to produce large fonts and

high contrast colors. Details of how to use these accessibility features can be

found in the WebSphere Voice Response for AIX: User Interface Guide.

Alternatively, application development can be done with Java™ or VoiceXML

development tools that are supplied by IBM and 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

365 at the back of this book).

Notes on terminology

v A glossary of commonly-used terms is at the end of this book.

v The full product name of WebSphere Voice Response for AIX with DirectTalk®

Technology is generally abbreviated in this book to WebSphere Voice Response.

v The term pSeries™ is generically used in this book to refer both to PCI-based

RS/6000® computers and to appropriate models of the System p5™ and

pSeries ranges. (Consult your IBM representative for details of models that

are supported for use with WebSphere Voice Response.) RS/6000 computers

with an MCA bus are not supported.

v The IBM Quad Digital Trunk Telephony PCI Adapter is generally referred to in

this book by its abbreviation DTTA. This adapter is a replacement for the

IBM ARTIC960RxD Quad Digital Trunk PCI Adapter, which is generally

referred to by the abbreviation DTXA.

v References made to the VoiceXML 2.1 specification are intended to include

VoiceXML 2.0 unless otherwise specified.

accessibility

About this book xv

Where to find more information

The information provided in the WebSphere Voice Response library will help

you complete WebSphere Voice Response tasks more quickly. A complete list

of the available books and where you can obtain them is shown in “List of

WebSphere Voice Response and associated documentation” on page 365.

Useful Web sites

The following Web sites are useful sources of information about WebSphere

Voice Response and related products:

IBM WebSphere voice products

Select the Products link on the Pervasive Computing Software home

page at http://www.ibm.com/software/pervasive

IBM WebSphere developerWorks resources (including WebSphere Voice

products)

http://www.ibm.com/developerworks/websphere

VoiceXML Version 2.0 and 2.1 specifications

http://www.voicexml.org/spec.html

CCXML Version 1.0 specification

http://www.w3.org/TR/ccxml

CallPath

For more information on CallPath products go to the Genesys Web

site at http://www.genesyslab.com

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

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,

where to find more information

xvi Designing and Managing State Table Applications

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

making comments on this book

xviii Designing and Managing State Table Applications

Part 1. The life cycle of a voice response service

© Copyright IBM Corp. 1991, 2008 1

2 Designing and Managing State Table Applications

Chapter 1. Introduction

This chapter begins with an overview of the process of providing a voice

response service by means of a WebSphere Voice Response application, and

the components that comprise an application. Subsequent chapters elaborate

on the steps in the process, introducing the components involved. These are

followed by chapters that give more information about implementing specific

types of service, using specific techniques and technologies.

The process is assumed to be top-down, though iterative (as shown in

Figure 1), and throughout the book, the organizing principle is to start with

the high-level, broad view and progress through lower-level views to the

details of individual elements.

Plan

Establishrequirements forthe voiceresponse service:

Businessgoals

Caller needs

WebSphereVoice Response

facilities

Design

Allocate functionsto different parts ofthe application:

Interactionwith caller

Data access

Telephonyactivity

Design the dialogwith the caller:

Key input

Speech input

Speech output

Implement andTest

VoiceSegments

Prompts

State tables

3270 servers

Customservers

Systemparameters

Applicationprofiles

Maintain andSupport

Mailboxes

Distributionlists

Subscriberclasses

Package andDistribute

Applications

Figure 1. The life cycle of a voice response service


Requirements and Planning

The WebSphere Voice Response for AIX: General Information and Planning guide

describes the kind of services that WebSphere Voice Response can support,

and the facilities it uses to support them. Use this information to guide you in

the planning phase.

A voice response service typically handles information requests from

telephone callers.1 You design and develop voice applications to satisfy your

business requirements: the voice application can make calls, answer calls,

perform computations, pass information from local or remote databases,

communicate information to a caller by speaking it back over the telephone,

let callers leave and retrieve messages, transfer calls to other applications,

connect callers to a human operator, and so on.

Business requirements

You need to establish how the proposed service fits in with your business or

organization goals. What is the purpose of the service and is an automated

voice response service the best way of achieving this? What are the benefits of

automating the service to your organization and to the target population? Is

an automated voice response service likely to be accepted by the target

population and generate business or cut costs?

Telephony requirements

How does the new service fit into existing services? Is it going to be a

single-purpose or multi-purpose service in its own right? Or is it just going to

be a new part of an existing service? Does the telephony equipment you use

support this kind of service, or are you going to have to make changes there?

User requirements

What are the characteristics of the target population? What kind of output is

going to be acceptable to them? What kind of input mode are they going to

1. Voice response services can also make outbound calls. However, throughout this book, the word “caller” refers to

the person on the other end of the conversation, who may be either the calling party or the called party.

Plan DesignImplement

andtest

Maintainand

support

Packageand

distribute

requirements and planning


prefer? How big is the target population? How frequently are they likely to

use the service? Is the service likely to be frequently used or rarely used?

Data requirements

What data is to be provided by the service, where is it stored (currently or in

the future), what format is it in? Is it frequently updated or rarely updated?

What kind of output mode is going to be suitable for it? Would you be able to

use other software or write new programs to access data if necessary?

Programming requirements

Who is going to implement the components of the voice response service? Is

the department who understands the business and the callers going to

develop the application themselves? Or do you have professional

programmers or a service bureau that you can call upon? Even if you use

professional programmers or a service bureau, the business departments and

the callers themselves should be involved too. Conversely, even if the business

departments are comfortable with implementing small and medium-scale

systems, it may be advisable to involve system integrators if you are scaling

up to something large.

IBM solutions

Can your requirements be satisfied by an IBM solution? For example, before

starting to develop your own voice mail system, consider the advantages of

buying IBM’s Unified Messaging program offering. This is very much easier

than writing your own system: Unified Messaging comes with additional

system administration utilities and, if it does not fit your requirements exactly,

you can tailor just about every aspect of it. For more information, see your

IBM representative.

Suggestions

Use existing services as a model

Start planning an application by surveying the requests for information that

your company currently receives. Repetitive requests that are time-consuming

for your personnel to satisfy are good candidates for voice applications.

Start small

Begin by serving your most important customers, or set up an application to

service a pilot group. Provide a feedback mechanism to measure how the

system is meeting your customers’ and employees’ needs. Encourage

complaints.

Prioritize your applications

Don’t expect the system to solve every problem from the first day. It’s

important to set fairly easy and reasonable objectives which can be met


Chapter 1. Introduction 5

during the initial phase of use, and then move on to more sophisticated

applications as your staff and customers become better acquainted with the

system.

Design

High-level and low-level design

High-level design consists of analyzing your requirements, both business

goals and caller needs, decomposing the functions of the service, and

determining what application components are required to perform each

function. Low-level design then involves examining how WebSphere Voice

Response facilities and the facilities of other hardware and software (such as

the telephone switch and database access) are to be used to accomplish the

goals of each component. You need to prototype and document, visually, at

each stage in the design process.

Design considerations

In designing the voice response service, you need to consider telephony

activities and data access as well as the dialog design:

v What are the functions of the service, and what is each part of the

application going to do?

v Is the application going to answer, make, transfer, reconnect, or terminate

calls, and how?

v Do the switch and signaling protocol at your site support the telephony

functions required?

v Where is the application going to get data from and how? Will callers be

updating databases or files, and how? What are the security and data

integrity implications?

v How will the application communicate with the caller?

v How will the caller communicate with the application, using tones or

speech or a mixture of the two?

v How will the application handle situations such as the caller hanging up in

mid-transaction or the database link failing?


andtest

Maintainand

support

Packageand

distribute



For more information, see Chapter 2, “Designing a voice application,” on page

15. To design your application, you need to understand the facilities and

programming interfaces that will be used to implement it, as well as the

requirements for it, so you’ll also need to read the appropriate chapters on

implementation before you start designing your own applications to run with

WebSphere Voice Response.

Suggestions

Flowchart applications

Draw step-by-step flowcharts of specific applications both before and after the

system is installed. This will help you to catch duplications or redundancies in

procedure that existed in the past and that might occur again in new

applications. Are there paper documents that need to be maintained? Are

there ways to simplify your business operations before or during your

conversion to voice response? Are jobs going to be changed?

Keep it simple

The basic rule for designing voice applications is: keep prompts simple, short,

and specific. Don’t provide an endless list of options to callers, which will

surely confuse them. Offer callers just what they need in order to get to the

information they want. If there are many options, and you want to make them

all available, create a series of branched prompts that break the options into

small groups of two or three options each.

Accommodate frequent as well as new users

Don’t make experienced users sit through an entire script. Allow them to

override prompts by pressing keys at any time during the call.

Allow callers to change their entries

After a caller has entered an order or request for information, always allow

for a change of mind. Also, try to allow for errors throughout the transaction.

If a caller doesn’t get it right in three or four tries, return to the main menu or

play a prompt that tells the caller to call back and start again.

Develop design documentation

Applications should be clearly documented. Provide the name of the

application, its purpose and benefits, how to access the system for the

application, and the specific steps involved. Include the commands to be

entered via the telephone keypad, the specific actions or results of each

command, what to do in case something goes wrong, and the correct way to

sign off the system.

Develop a draft set of voice segments

Don’t have your voice segments recorded professionally right at the

beginning: record them yourself to begin with, because they are sure to

design


change before the voice response service is put into production, and you don’t

want to waste professional recording fees. With voice segments, the rule is,

“Start early, finish late!”

Design for maintenance

Build tracing and debugging into the voice response service from the start,

and make it configurable. You can either turn on tracing and debugging

statements by setting variables at the beginning of the state table, or you can

include parameters in a command file that is read by a custom server.

Implementation

To implement your design, you need to understand how to create and

manage the objects that are required to make a voice response service work.

These are described in

v Chapter 3, “Creating and managing application objects,” on page 27

v Chapter 4, “Overview of application objects,” on page 63

v Chapter 5, “Creating an application profile,” on page 89

Following this are chapters that contain guidance on the following topics:

v Chapter 6, “Creating the voice output for voice applications,” on page 101

v Chapter 7, “Handling key input from callers,” on page 119

v Chapter 8, “Handling spoken input from callers,” on page 121

v Chapter 9, “Accessing data with a 3270 or custom server,” on page 127

v Chapter 10, “Telephony activity,” on page 133

v Chapter 11, “Designing voice messaging applications,” on page 149

v Chapter 12, “Managing voice messaging resources,” on page 165

v Chapter 13, “Telecommunications Devices for the Deaf,” on page 189

v Chapter 14, “Background music,” on page 193

v Chapter 15, “TDM connection management,” on page 207


andtest

Maintainand

support

Packageand

distribute

design


What does implementation involve?

Implementation of a voice response service involves:

v Recording voice segments

v Designing and building prompts

v Designing and building state tables

v Designing and building 3270 server scripts

v Designing, coding, and building custom server programs

v Testing and debugging components separately and together

We cannot stress too much that testing is vital to the success of your voice

response service. Not only functional testing, but also getting users involved

in early trials, and evaluating their experiences. Early user involvement in

design should ensure that you don’t find reach the beta-test stage before

finding too many usability problems that are costly to fix, but you should also

ensure that the service is tried out by a limited set of users before going live.

There is a gray area between implementation and putting your voice response

service into production. You may think of the following tasks as belonging to

implementation, as you will certainly need some resources with which to test.

However, you should consider these to be administration tasks that belong to

the packaging and distribution or maintenance and support phases:

v Creating application definitions

v Exporting application packages

v Importing application packages

v Creating application profiles

v Defining mailboxes, distribution lists, and subscriber classes

v Ensuring that system parameters are appropriately defined

System parameters

Among the many parameters that control the way the WebSphere Voice

Response system works are two groups of particular importance to

applications:

v Application Server Interface parameter group

v General parameter group

See the WebSphere Voice Response for AIX: Configuring the System guide for

details of each parameter in these groups.

Testing the voice response service

Test phases

Testing should be performed in distinct phases, in which you are checking for

different kinds of problem:

implementation


1. Logical or unit test, to test the basic logical flow

2. Functional test, to test the interaction with the caller

3. Performance or stress test (more than one call at a time, and so on)

4. Critical test (removing the most critical parts of the application, to find out

what callers would hear)

Hints and tips

To use the Debug option in the State Table window, you need to include an

AnswerCall state in the state table. When using the debugger, this is

converted into a MakeCall. Using the debugger, you can step through the

actions, modifying the values of variables to test different paths through the

state table.

It’s useful if a voice application can output its own trace data, using the

LogEvent action or a custom server. You should design this so that tracing can

be switched on or off when the application is in production.

Migrating application objects

If you are migrating to DirectTalk for AIX Version 2.3 from DirectTalk for AIX

Version 2.2 or earlier, use the restoreDT utility to bring your application

objects and data into the new system (see the WebSphere Voice Response for

AIX: Installation book for more information on using restoreDT). When you do

this, all your application objects are placed in the Default application. You can

either leave them there or, if you want to manage application objects

efficiently (see “Managing application objects efficiently” on page 29), you can

create your own applications (see “Creating an application” on page 34) and

move objects into them from the Default application.

If you export applications from IBM WebSphere Voice Response for AIX, you

need to import them (see “Importing application objects” on page 47).

Using an external code repository

If you develop applications using a text editor, and store them in a code

repository such as CMVC, you can import ASCII versions of state tables,

prompts, 3270 servers, and custom servers into WebSphere Voice Response.

Once imported, the object can optionally be stored in WebSphere Voice

Response with a user-specified version ID, which makes synchronization with

external code control systems possible. Optionally, you can make the imported

object read-only, which prevents it from being modified and saved using the

WebSphere Voice Response windows. The read-only property (if set) is

displayed in the object’s container window.

implementation


Suggestions

Modularity

For maintainability, you are recommended to implement applications as

multiple state tables rather than one large state table.

Encapsulation

Consider implementing some parts of the application as common state tables

that can be called as “subroutines” by other state tables.

Commenting and documentation

In state tables, use the Description field in each state to describe what it does.

Add further comments using the DoNothing action.

Packaging and distribution

Creating an application profile will enable you to run state tables that handle

incoming calls, or which are invoked by application profile by other state tables,

in production (see Chapter 5, “Creating an application profile,” on page 89).

You may also need to create voice messaging resources before putting your

application into production (see Chapter 12, “Managing voice messaging

resources,” on page 165).

Packaging involves creating an application definition, which specifies which

components are required to run the voice response service. If you have only

one WebSphere Voice Response system, you don’t need to package your

applications, although creating an application definition can help you keep the

components organized.

To distribute the components of an application, you then use the application

definition to create a package: this is known as exporting. You then send the

package you created using the application definition to whichever systems are

going to run it. The package is simply a file that you can send using any

suitable file transfer method to another pSeries computer. After transferring


andtest

Maintainand

support

Packageand

distribute

implementation


the package, you import it into the WebSphere Voice Response system on the

other pSeries computer and install its contents: the original application

components.

Distributing an application to other WebSphere Voice Response systems

You may develop the components of a voice application on a system reserved

for development, or you may want to run the same voice response service on

multiple systems. In either case, you need to be able to transport application

objects from one system to another. To do this, you export the application

from WebSphere Voice Response. This creates a single AIX file that you can

transport to another system. The file must then be imported into WebSphere

Voice Response. See “Exporting an application” on page 38 and “Importing

application objects” on page 47.

Suggestions

Spread the word

Send a memo around your site announcing the planned installation date of a

new voice application and describe clearly how the system works and what

the benefits are to the staff. Conduct a promotional campaign for your

customers explaining your new service and educate them in the use of the

system by flowcharting the application for them. Also select a staff person

who will serve as a contact for additional information and questions.

Select a system administrator

Assign someone to maintain the system and the applications. The role of the

system administrator is to configure the system as required by your voice

applications, establish the data interface between the system and your host

computer, set up controls and authorizations, monitor system performance,

and take whatever action is necessary to manage and keep the system up and

running.

Maintenance and support


andtest

Maintainand

support

Packageand

distribute

packaging and distribution


Once the application is in production, new requirements may arise, or

problems occur. These can result in a re-iteration of any of the preceding

steps. Requirements for important new function will cause you to go back to

the requirements phase. Major usability issues may return you to the

requirements or the design phase. Performance problems may return you to

design or implementation, as will failure to handle every situation that arises

or provide correct output.

Housekeeping

Some application objects, such as voice segments, take up a lot of storage, so

you need to attend to the housekeeping regularly. Before deleting an object

you think might no longer be used, check its dependencies, to make sure that

no other object uses it. See “What is a dependency?” on page 37 for more

information.

Archiving application objects

To archive the application objects necessary for a voice response service, you

export the application from WebSphere Voice Response. This creates a single

AIX file that you can store on disk, tape, or other media. When the

application is required again, the file can be imported into WebSphere Voice

Response. See “Exporting an application” on page 38 and “Importing

application objects” on page 47.

Distributing updates

Updates to some of the objects in the application can easily be distributed

using delta export: exporting only those objects that have changed since the last

full export, delta export, or since a specified date. See “Exporting an

application” on page 38.

Suggestions

Conduct system user surveys

Gather feedback both before and after system installation. This will help you

to diffuse any fears or misunderstandings and to compare expected and actual

reactions to the system.

maintenance and support


maintenance and support


Chapter 2. Designing a voice application

When you understand the requirements for the voice response service, the

business goals and callers’ needs, you can begin designing your application.

You may not yet know which WebSphere Voice Response facilities and other

software and hardware you will use to implement it. Part of the design

process will be to decide on the implementation of the high-level activities.

This process will be iterative, as you create prototypes and learn more about

both requirements and ways of implementation. Always involve users, both

callers and the departments commissioning the voice response service, in the

design process. However, there will be work you need to do without them.

Welcome and find out if callerhas a pushbutton phone

Account balances

Please try again

Offer choice of services

Interest rates

Transfer a caller without apushbutton phone to a human

agent, or invoke a speechrecognition application

Goodbye and thank you forcalling

Notice that the designerhas already consideredthe possibility that thecaller may press a keythat is not assigned toeither a service offering orto ending the call.

Figure 2. Example of main activities to be performed by a voice application.


1. Before the first meeting with users, identify the main activities to be

performed by the application. An example is shown in Figure 2 on page

15.

2. Together with users, design the dialog for each activity, concentrating on

everything proceeding smoothly (as you hope it will in majority of calls).

You must take into consideration all the possible responses by the caller,

remembering that they may have either keys or speech or both to respond

with.

Table 1. Example dialog segments

ID Words

1 Thank you for calling the WebSphere Voice Response Automated Account

Inquiry Service.

2 To hear your account balance, press 1.

3 To hear the current interest rate, press 2.

21 You have...

22 ...in your current account.

23 ...in your savings account.

31 Today’s interest rate is...

7 To leave the WebSphere Voice Response Automated Account Inquiry Service,

press 7.

15 Thank you for calling. Goodbye.

16 The key you pressed is invalid. Please try again.

Table 1 shows examples of punctuation conventions that you can use in

the text versions of voice segments:

An initial capital letter at the beginning of a voice segment indicates the

beginning of a prompt.

Ellipsis (...) at the beginning of a voice segment indicates the continuation

of a prompt.

Ellipsis (...) at the end of a voice segment indicates that further voice

segments are to be appended in the prompt.

Period (.) at the end of a voice segment indicates the end of the prompt.

3. You need to decide whether you are going to allow both keys and speech

throughout the call, keys for some parts and speech for others, or whether

you are going to restrict the caller to either keys or speech. You may

decide on two versions of the service: one for callers who have pushbutton

phones, and one for callers with rotary phones, who have to use speech.


4. As your dialog design progresses, make sure you document each of the

branches of the application. You can use the WebSphere Voice Response

State Tables window to create a graphical representation of the state table,

filling in the details later.

5. Before the next meeting, identify all the things that could go wrong: for

example, the caller could hang up in the middle of the call, the connection

with a host computer could fail. Again, you can use the WebSphere Voice

Response State Tables window, this time looking at the possible results for

the actions and filling in the details.

6. Again, with users, refine the dialog, taking into consideration all the things

you have identified that could go wrong. The business departments will

want to be assured that the caller is going to hear the right thing whatever

happens. They do not want to lose business through a badly designed

voice application. If the voice application itself cannot continue, ideally, the

caller should be transferred to a human agent.

User participation in dialog design

The words used in the dialog must satisfy both the business goals (including

the company or organization image) and be meaningful and unambiguous to

callers, so you need participation from business people and representative

callers.

Lo-fi prototyping

Before recording anything, act out the dialogs, using the “Wizard-of-Oz”

technique, with one person reading out the application’s words from out of

sight (say behind a screen or curtain), and another person acting the part of a

caller. This avoids the need to write prompts and state tables before you have

refined the design. Recording voice segments and writing code increases your

reluctance to make changes, so try the live Wizard-of-Oz prototyping

technique first.

When you are fairly happy with the dialog design, record the voice segments

using the telephone, or synthesize them using text-to-speech. Recording over

the telephone is easily done with either of two sample programs supplied

with WebSphere Voice Response. To test the dialog, you’ll need to write

prompts and a simple state table too. Start with company employees as the

callers, and, when you are happy with the dialog, try it on potential

customers or clients. If the service is aimed at company employees, start with

experienced employees, but don’t forget to try it out on newcomers.

Only when you are satisfied with the dialog, should you invest in professional

recording.


Designing the dialog

Customer satisfaction with your voice response service will depend on a

number of factors, including the voice you choose, the information you

provide, and the ease with which callers can get the information they want.

The sound and feel of the service is every bit as important as the look and

feel of a visual computer application. With careful design, the caller’s

experience will be pleasurable; with lack of attention to dialog design, the

caller will get frustrated and hang up. At best this will result in your people

handling just as many calls as they ever did; at worst it may mean loss of

business.

You’re already considering a voice response service, so you’re aware of the

strengths of voice response: telephones are ubiquitous, familiar, and

easy-to-use and an automated system can provide more speed, privacy,

efficiency, availability, and accuracy than some human operators, and at lower

cost.

Nevertheless, when designing the dialog, you need to be aware of some of the

limitations of the medium. Compared with people, automated systems are

inflexible, demanding, and intolerant of deviations from the expected

conversation. They are best at handling very routine calls. Almost without

exception, all voice response services should offer help in some way, for

example by offering the choice of transferring to an operator (if call transfer is

provided by the switch) or calling another number to speak to an operator. If

call transfer is provided by the switch, the application can automatically

transfer the caller to a human agent in some circumstances.

You should give human factors and usability a high priority when designing

voice response services, in addition to testing the usability of the services

later.

Design considerations

Compared with today’s multiwindowed screen-based computer applications,

voice response applications have a number of potential limitations. With

careful design, you can overcome the limitations and make your application a

delight to use:

v Auditory output is sequential, and hard to keep in short-term memory: you

have to take great care wording the prompts.

v Auditory output can be slow: unfortunately, someone (either you or the

caller) is paying for the call, and wants the whole transaction to take as

little time as possible: again, the prompts need to be worded carefully so

that they convey the greatest amount of information, unambiguously, and

in the shortest amount of time.

v The very ubiquity and availability of telephones means that callers don’t

have access to manuals and other supporting materials: the whole point is

designing the dialog


that the voice response service can be used from anywhere, so the

application itself must be completely self-documenting.

v Voice data takes up a lot of storage space (one second of voice occupies

8000 bytes of storage). This can be reduced by a factor of 5 by compression,

or even further by generating synthesized speech from text.

On the input side, from the caller’s point of view, the telephone is an inferior

device compared with the computer keyboard and mouse:

v There are two ways of communicating with a WebSphere Voice Response

application: by key or by voice. If keys are used, they must transmit

dual-tone multifrequency (DTMF) tones. If the caller is able to transmit

these tones, keys are the most accurate and efficient method of input.

v Bear in mind that many callers may be using phones with an integral

keypad and handset: they will take longer to press the keys than callers

using traditional phones with a separate keypad.

v Compared with the 100 or so keys on a computer keyboard, the standard

telephone has twelve keys (WebSphere Voice Response supports up to

sixteen: 0 through 9, *, #, A, B, C, and D).

v The standard keypad is fine for numeric input, making simple choices, and

answering yes-no questions, but what about alphabetic input? In some

countries, there are no alphabetic characters on the keys at all; even in

countries where telephones still have the alphabetic characters on the

number keys, people don’t use them enough to be familiar with their

positions. (And note that different countries use different layouts anyway.)

v Many telephones cannot transmit DTMF tones reliably or at all: rotary dial,

hybrid tone, and dial-pulse phones are still in use; cellular and portable

phones often suffer from noise interference; some equipment sends tones of

fixed duration or cannot send tones at all during a call. In these cases, the

only reasonable input device is voice, and for that, you require access to

speech recognition hardware or software.

Faced with all these challenges, you have a number of design decisions to

make. First you need to determine the right dialog style or styles and then

you need to attend to the detail of each interaction, or task, within the

application. If you design your application well, callers will prefer it to the

human agent, and the reward will be savings in business costs.

Choosing a dialog style

No single dialog style is best for all applications, for all tasks within an

application, or for all callers:

v Callers may be familiar or unfamiliar with the mechanics of driving the

application.

v Callers may be familiar or unfamiliar with other voice response services.



v Callers may use the service frequently (and therefore acquire expertise with

the mechanics, or the content, over time) or infrequently (never acquiring

expertise).

v The content of the dialog may be familiar and predictable (for example,

days of the week) or relatively unfamiliar and unpredictable (for example,

toppings available for pizzas).

v It may be appropriate to provide documentation or training sessions, for

example, if callers are employee or students, but it is unreasonable to base

your design on the assumption that documentation will be read or training

sessions attended.

There is a far greater choice of dialog designs for voice response services than

you might imagine. Some less common designs overcome the problems

encountered by callers in using traditional voice response services. Different

styles of dialog may be appropriate in different parts of the service,

depending on the task being performed: after all, these days one expects to

see pull-down menus, radio buttons, check boxes, and so on, used in visual

applications, so it’s not surprising that there might be a variety of techniques

you can use in voice response dialogs.

There are three basic styles of voice response dialog, suited to different types

of task:

Menu:

suited to selecting one of a small number of options

List: suited to choosing multiple items, perhaps from a large number

Form: suited to providing input such as addresses and telephone numbers

Within these basic styles, there are numerous variations. It’s hard to provide

rules for good dialog design, but you need to classify your application and

your callers in these terms before considering the following questions:

1. Composite or separate actions? Composite actions may be simpler for the

caller, but separate actions gives more flexibility. If your callers are

unlikely to use the application often, give them composite actions that

accomplish the most with the fewest keystrokes. If callers are likely to use

the application often, however, they may want to combine actions in

different ways.

2. Keys or speech recognition? The application is using speech to

communicate with the caller, but should the caller be using speech or

keys? Remember it takes longer to speak a command and have it

recognized than it does to press a key. Also, people are better at pressing

keys accurately than speaking clearly enough to be recognized accurately.

3. A mixture of key and speech input? You can mix key input and speech

input in a single application (though you are not recommended to allow



both at the same time). For example, entering a Personal Identification

Number (PIN) is easier using keys, whereas recording a street address is

easier with speech.

4. Command-driven or prompted? You need to make a decision about

whether to let callers interrupt the prompts or not. In general, you should

let them interrupt. Once they learn the choices at each point, they can key

ahead (or speak ahead), without waiting for the prompt to finish. There

may, however be some prompts that you want to force play to the end;

there may even be whole applications in which you want all prompts to

be force played.

The type of dialog that allows key-ahead or speak-ahead is sometimes

known as a command-driven dialog, but you still need to play the

prompts in a voice application, because of the absence of documentation.

5. A single selection key or option-specific selection keys? With a single

selection key, you play each choice to the caller and give them a few

seconds to press the nominated key (for example, 1); if they do not press a

key, you play the next choice, and so on. The caller always presses 1 to

select the current option. There is less for callers to learn if, at any point,

they have only two choices: to select the current option or to proceed to

the next; it can be useful for long lists of options (for example film titles).

On the other hand, this kind of design tends to restrict the caller’s ability

to key ahead and bypass menus.

With option-specific selection keys, you allocate a different key to each

option. This has the advantage of allowing callers to key ahead, but limits

the options available at any one time. It can also be difficult to ensure

consistency of key-allocation throughout the application (for example, on

one menu, 3 may be “Delete message” while on another menu, it is

something less destructive). Again, infrequent use may indicate the single

selection key and frequent use the option-specific selection keys.

6. Passive or active advance through menus? Should each option “drop

through” to the next option, or should the caller have to press a key to

proceed? This becomes an issue if you provide a single selection key.

Again, passive advance is probably most suitable for callers who use the

application infrequently but, to avoid the problem of callers selecting an

option just after the menu has moved on to the next option, you need to

include a few seconds of silence between each option.

Passive advance might seem easiest for the caller, but only at first. Later,

callers may become frustrated at having to sit through whole menus.

Providing a “Next” key would seem to prevent this, but the

“drop-through” behavior often results in callers never learning about the

“Next” key, unless the menus mention it.

7. Long or short prompts? The more information you provide, the more

likely the caller is to learn how to drive the application. However, long

prompts slow down callers, particularly experienced ones. A choice of



novice and expert prompts can help. The difference between them is not

necessarily verbose versus terse: you could actually leave some

information out of the expert prompts altogether.

Always provide essential information before information that is merely

helpful. Provide “Next” and “Previous” keys, so that callers can skip over

information they don’t want to hear.

Good things to do in voice applications

v Voice output can be speeded up with no loss of intelligibility. This could be

under the caller’s control.

v Subdivide the recording of voice output, to allow random access to it.

Callers can skip and scan.

v Make sure that callers know they’re using a machine; don’t try to make

them think they’re talking to a human agent.

v Ask the caller whether they are using a phone that generates tones, by

asking them to press a specific key.

v Allow the caller to interrupt prompts (key ahead) wherever possible (that

is, don’t force play the prompts).

v Refer to the # key as “pound” in the U.S. or “hash” in the U.K.

v Refer to the * key as “star”.

v Use the star key for the control menu.

v Refer to the 0 key as “zero”.

v Use the zero key to provide access to the operator.

v Always phrase your prompts so that the goal precedes the means of

achieving it (for example, “to contact the operator, press 0”); if you mention

the key first, the caller may forget which one it was before realizing that it

was they one they wanted.

v Use questions and commands rather than statements, to encourage callers

to take immediate action. For example:

To check your account balance, press 1.

Is this correct? Press 1 for yes, 2 for no.v Ask closed questions such as “Do you want a large, medium, or small

pizza?” rather than “What size pizza would you like?”.

v Add pauses to encourage the caller to take immediate action.

v Always try to allocate similar functions to the same keys.

v Use directional metaphors where appropriate (use the relative position of

the keys on the keypad to indicate some logical direction associated with

the command, for example, 7 for back, 8 for pause, and 9 for forward).



v Try to limit menus to about four options, with a fifth option (“for more

choices”) if necessary; this adheres to the “magic number 7 plus or minus

2” items that people can hold in short-term memory; also it won’t take too

long to play.

v The order in which you play the options depends on the application: you

might choose to start with most frequently used, or least-frequently used, or

play them in ascending numerical sequence.

v Use simple, explicit language, for example: “Press” for single key entry (no

delimiter) and “Enter” for multiple keys (which need a delimiter).

v Give feedback: repeat long data entries back to the caller.

v If something’s going to take a long time, tell the caller and then play

background music; repeat the message saying it’s going to take a long time

at intervals.

v If the caller does not make a selection, repeat the menu.

v If the caller makes an error, explain valid choices.

v Employ a professional to record the final version of the prompts.

v Don’t mix prompts recorded in more than one voice, unless you do this

consistently to convey information (for example, voice A for menus and

voice B for data retrieved for playback to the caller). For this reason, you

should get the system voice segments recorded by the same professional as

your other voice segments.

Wording prompts for speech recognition applications

Correct wording of your prompts is particularly critical when you are using

speech recognition. Your prompts must tell the caller what to say, when to say

it, and how to say it. Here are several considerations for wording prompts:

v Tell the caller what to say to avoid unrecognizable words; that is, words not

in your vocabulary. For example, you want your caller to answer “yes,” not

“OK” or “Sure.” So your prompt should be worded “If you want to order a

pizza, say YES now” rather than “Do you want a pizza?”

v To encourage the caller to speak digits rather than whole numbers, you

might provide an example. Your recorded voice segment must speak in

digits. “How many bottles of item one seven five do you want?” is better

than “How many bottles of item one hundred and seventy five do you

want?”

v It is useful to include directions such as “say YES or NO now” in the

prompt. This helps callers understand that they must wait for the prompt

to be over before they can speak.

v Your prompts are models for the caller. That is, the caller is likely to mimic

the volume, pace, enunciation, and terseness of the recorded speech.

good things to do in voice applications


Like DTMF applications, your instructions to the caller must be brief. The

caller cannot be expected to remember more than two or three instructions

before making a response.

Handling all responses

When designing a speech-recognition application, you must decide when to

repeat a prompt, request verification, or transfer to a human operator. Your

decisions are based on confidence factors.

Ask for the same information not more than twice, to avoid irritating the

caller and jeopardizing the business transaction. The second prompt should

apologize to the caller, accept responsibility for the communication error, and

repeat the request. You might change the wording in the second request to

give additional clues or information.

Speech recognition while a prompt is playing

Full-duplex barge-in allows the caller to start speaking while the prompt is still

playing. See “Barge-in” on page 121.

Interrupting prompts

To enable callers without DTMF phones to interrupt a prompt with a short

speech utterance (for example “stop!”), you need to enable voice interrupt

detection. See “Voice interrupt detection” on page 122.

Limitations

Speech-recognition applications work best when there is a high signal-to-noise

ratio. The speech recognition process can fail when background noise, such as

traffic, is louder than the caller’s speech.

If you expect many of your customers to be calling from a noisy environment,

your application should include a test and branch to a human operator. For

example, a first prompt asks callers if they have their account number ready.

If the external voice services system fails to find a good match, the state table

could branch to a TransferCall action to transfer the call.

Defining server requirements

Before you create a 3270 server or custom server to access business

information, you need to perform an analysis of your requirements, to

determine how you can most effectively use a server. The analysis involves

identifying information such as:

v Remote data required by a voice application

v Where the required data resides

v Existing applications that access the data

v Data the server needs to satisfy a request

v Processes required (both new and existing) to satisfy a request

wording prompts for speech recognition applications


v Whether voice data is to played or recorded on multiple channels at the

same time: a multiprocess custom server makes this easier to manage

v Whether database access is on a serial link, in which case a single process

will suffice, or on a multilink or virtual session, in which case the server

needs to be multiprocess (3270 host access is multiprocess)

v How the server is to be activated (such as by a state table or a timed event)

v How to respond to both successful and unsuccessful attempts to provide

the requested information

v Considering custom server resource requirements, things such as CPU,

memory and page space

v Any additional processing you may want to perform as a result of a request

(such as maintain a count of types of requests for business activity

statistics).

When you have identified the information that defines the requirements for a

server, you can determine whether a 3270 server or custom server best suits

your needs.

defining server requirements


defining server requirements


Chapter 3. Creating and managing application objects

To implement a voice response service using WebSphere Voice Response, you

need to create a number of objects. This chapter introduces the concept of a

voice application and its constituent objects, and tells you how to create,

manage, and distribute applications and objects. (The object types and their

role in the application are introduced in more detail in Chapter 4, “Overview

of application objects,” on page 63.)

This chapter contains the following sections:

v “What are application objects?” on page 28

v “Using the applications and application windows” on page 30

v “Managing application objects efficiently” on page 29

v “Discovering what applications and objects are in the system” on page 30

v “Editing and testing application objects” on page 33

v “Creating an application” on page 34

v “Exporting an application” on page 38

v “Exporting one or more objects” on page 45

v “Importing application objects” on page 47

v “Migrating from an earlier release of IBM WebSphere Voice Response for

AIX” on page 51

v “Frequently asked questions” on page 52

v “Moving objects from the default or user applications” on page 56

v “Deleting an application” on page 56

v “The dtimport and dtexport commands” on page 57


What are application objects?

To create a voice response service, you need to create (or import) a number of

objects of various types:

v The heart of the voice application is the state table, which provides the logic

(see “State tables” on page 63).

v A state table can invoke:

– Other state tables

– Custom servers, to provide access to data outside WebSphere Voice

Response or services such as speech recognition and speech synthesis.

– 3270 servers, to provide access to data on host computers, via existing

applications that use the 3270 data stream. (See “3270 and custom

servers” on page 85.)v The state table can invoke prompts, which are specialized programs that

control the dialog that the caller hears. (See “Prompts” on page 74).

Prompts are collected together in a prompt directory.

v The recorded words or sounds that the caller hears are known as voice

segments. Although these can be played directly by the state table, it is

much more efficient to play each voice segment from a prompt. (See “Voice

segments” on page 82). Voice segments are collected together in a voice

directory, and can also be indexed by a voice table.

v Typically, most voice applications also include at least one application profile,

which defines various characteristics of the application. Application profiles

have several functions. Each application profile specifies a main (or initial)

state table which:

– Can be invoked in response to incoming calls if the application profile ID

matches the called number or channel identification.

Caller

ApplicationProfile

Application

OtherState Tables

MainState Table

Prompts3270

Servers

VoiceSegments Custom

Servers

Information orresources, such

as speechrecognition

Informationvia 3270 data

stream

Figure 3. Voice application objects

what are application objects?


– Can be invoked by other state tables (but note that you can invoke a

state table from another state table without an application profile).

– Uses the specified language database to play prompts and voice

segments. Thus you can have the same state table to handle calls in

different languages; only the application profiles need to be different.

– Can access up to ten voice mailboxes, together with associated voice

messaging resources, such as distribution lists, for use by the state table

described in the profile.

For information about defining an application profile, see Chapter 5,

“Creating an application profile,” on page 89.

v Files and databases containing information can be accessed by a custom

server.

All these objects comprise the voice response service, or voice application. To help

you manage these objects in an application-oriented way, WebSphere Voice

Response includes an Applications window in which you can see all the

applications in the system, and an Application window for each application,

which shows all the objects in the application, grouped into folders: one folder

for each type of object in the application.

Managing application objects efficiently

All application objects in the WebSphere Voice Response system must be in

one and only one application. The application provides you with:

v A place to keep:

– All the objects required for a voice response service

– All the objects shared by multiple voice response services

– Other objects that are not currently in use, or are under development

This enables you to:

– Find objects easily

– Open objects for browsing or editing

– Delete objects from the systemv A checklist for:

– Listing the dependencies (other objects used by the objects in the

application)

– Exporting all objects required for a voice response service

– Validating that all objects are present on a system (for example, before

exporting or after importing an application package)

– Importing the application package

You can move objects into and out of an application.

what are application objects?

Chapter 3. Creating and managing application objects 29

You can copy objects, with the restriction that you must provide a new name

for the copied object, whether or not it has been copied to a different

application.

Using the applications and application windows

There are several ways of doing many of the tasks described in the following

sections. The procedures describe the simplest way, using the mouse to

single-click, double-click, or drag-and-drop. Most tasks are also available from

one of the pulldown menus on the menu bar, and from the object popup

menu. To use the pulldown menu, select the object first and then select the

menu option using MOUSE BUTTON 1. To use the popup menu, select the object

first and then press MOUSE BUTTON 3. Alternatively, all tasks can be done using

keyboard keys. See “wvrapplprof command” on page 94 and the WebSphere

Voice Response for AIX: User Interface Guide for more information.

Discovering what applications and objects are in the system

Before you start, see the note on “Using the applications and application

windows” on page 30.

From the Welcome window click on, Applications —> Applications

The Applications window shows all the applications in the system.

Opening an application

1. To display the objects in each application, double-click on the line that

represents the application.

managing application objects efficiently


The Application window shows a folder for each type of object in the

application:

Opening a folder and displaying information about objects

2. Single-click on the folder icon to open it.

The folder contains all the objects of that type in the application:

The system displays the date and time of the last update of each object,

and the application that contains it, and other relevant information,

depending on the type of object:

Figure 4. The Application window

discovering what applications and objects are in the system


You can select the names of the objects in this view.

About the supplied applications

When you install WebSphere Voice Response, three applications are supplied:

The Default application

The Welcome, Incoming_Call, Record_Comp, and Record_Uncomp

state tables, and other objects they need are in the Default application.

If you migrated your own application objects from IBM WebSphere

Voice Response for AIX Version 1, they are also placed in the Default

application.

The User application

For information about the User application, see Table 2 on page 53.

The System application

The System application contains only the System application profile.

This is reserved for use by voice messaging applications.

To organize your application-related objects, you should create your own

applications and move your objects into them (see “Creating an application”

on page 34 and “Moving objects from the default or user applications” on

page 56).

discovering what applications and objects are in the system


Editing and testing application objects

You can do most of the work involved in implementing a voice response

service from the Application window.



1. From the Welcome window, click on Applications —> Applications

Opening an object

2. Open the application. In the Application window, open the appropriate

folder. (See “Discovering what applications and objects are in the system”

on page 30).

3. Double-click on the object name.

When you open an application object, or create a new one, a container

window listing all the objects of that type appears, followed by the editing

window for that object. For example, the Prompt Directories window,

followed by the Prompt Directory window:

Using the container windows

The name preceding the type of object (in this example, Default), tells you

which application was selected when the container window opened. However,

the container window lists all the objects of that type in the system.

editing and testing application objects


You can use the container window to find objects, using the Search popup

window (MOUSE BUTTON 3). (For information about using the container windows

and about searching for information, see the WebSphere Voice Response for AIX:

User Interface Guide.)

To open objects such as prompts and voice segments, which are contained in

prompt directories and voice directories respectively, double-click on the

directory name in the container window. This displays all the objects in that

directory. Find the object name and double-click on it.

Using the editing windows

You can develop all the objects, except for the C or C++ code for custom

servers, using the editing window that opens when you open an object.

Importing ASCII files

Alternatively, you can use an ASCII editor to develop the code for state tables,

prompts, and 3270 scripts. Then create a new object (if necessary) and import

the ASCII code into the appropriate editing window, by clicking Utilities —>

Import. Or, you can import ASCII state tables and prompts using a command

that can be issued from the command line or from a script.

For more information

See the appropriate reference manual for all the detailed information you need

about creating, editing, and testing these objects (and importing ASCII code

for them):

v WebSphere Voice Response for AIX: Application Development using State Tables

reference manual

v WebSphere Voice Response for AIX: 3270 Servers reference manual

v WebSphere Voice Response for AIX: Custom Servers reference manual

The remainder of this chapter tells you about creating the application as a

container for your objects, managing the objects within the application, and

exporting and importing whole applications and individual objects.

Creating an application




Naming the application

2. Click Application —> New.

editing and testing application objects


The system displays the New Application window.

3. Type in the name (up to 15 characters) and, optionally, a description (up

to 255 characters). The name must be unique.

4. Click Create.

The name of the new application is displayed in the Applications

window and a new Application window opens automatically.

5. You can now either move or copy existing objects into the application, or

create new objects within it.

Moving an object

6. Open both the source and target Application windows.

Note: It does not matter whether there is a folder for the type of object in

the Application window, because folders are created automatically

by the system; and it does not matter which folder you drop the

object into, because the system makes sure it goes into the right

one.

7. Click an object in the source Application window and drag it, using

MOUSE BUTTON 2, to the target Application window.

The object is moved to the target Application window, and displayed in

the appropriate folder.

Note: If you drag an object from the Object Index window into an

Application window, the object is not removed from the Object

Index window, but the application name is changed. The object

appears in the target Application window.

Moving multiple objects

8. Click multiple objects of the same type (in the same folder): you can

either select adjacent objects by dragging down them using MOUSE BUTTON

1, or you can add objects to the selection by holding down the CTRL key

while clicking with MOUSE BUTTON 1.

9. Drag them, using MOUSE BUTTON 2, to the target Application window.

The objects are moved to the target Application window, and displayed

in the appropriate folder.

Copying an object

10. Click the object in the source Application window and drag it, using

MOUSE BUTTON 2 + CTRL, to the target Application window.

Because you cannot have two objects with the same name, the system

asks you for a new name.

11. Type in the name. The name must be unique.

creating an application


12. Click Copy.

The new object is displayed in the Application window.

Creating a new object

13. Click Object —> New.

14. Click the type of object you want to create.

The system displays the container window for that type of object,

followed by the editing window.

15. Create the contents of the object, validate if necessary, and save it. Refer

to the WebSphere Voice Response for AIX: Application Development using

State Tables reference manual for detailed procedural and reference

information, or use the online help.

When you click View —> Refresh Now, the new object is displayed in

the Application window.

Note: If you create a new object within the Object Index window, the

object is stored in the Default application and displayed in the

Application (Default) window.

Creating more objects

16. You can create further objects of the same type by repeating steps 13 and

14, or by clicking New from the appropriate menu in the container

window.

Displaying dependent objects

17. Click an object and then click Dependencies from the object’s popup

menu.

The system displays the Dependencies window:



What is a dependency?

A dependency is an object that is necessary for another object to run

correctly2. For example, prompt directory B becomes a dependency of state

table A when you specify it as the prompt directory in state table A.

WebSphere Voice Response cannot find all of the dependencies if

variables are used to name them (for example, InvokeStateTable by

variable).

To run a state table on a development system, it is not necessary to

include all dependencies in the same application. Provided that all the

dependencies are actually present, the state table can be run. But, before

you export the state table to another system, you should check that the

state table and all its dependencies (other state tables, prompts, voice

segments, and so on) are present on the target system, whether in this

application or in another one, for example, a common application.

Adding application prerequisites

18. Click Application Prerequisites from the application’s popup menu.

The system displays the Application Prerequisites window.

What is an application prerequisite?

An application prerequisite is another application that contains objects

that are necessary for the application to run. After you’ve traced all the

dependencies of the objects in your application, you can add the

applications that contain them to the Application Prerequisites list.

(When you export the application, the system asks you if you want to

export the prerequisite applications too.)

2. In Version 1 of IBM WebSphere Voice Response for AIX, dependencies were sometimes referred to as

“cross-references” or “references”.



19. Click Add to add applications.

The system displays the Add Application Prerequisites window.

20. Click one or more applications.

21. Click Add.

The system displays the Application Prerequisites window.

Deleting application prerequisites

22. Click the applications that are no longer required.

23. Click Delete.

The system removes the applications from the list in the Add Application

Prerequisites window. The applications are not deleted from the system.

Exporting an application

To distribute a voice application to other systems, or to make a backup copy

of the application, you need to export all the objects that comprise the

application. The export process involves the creation of an export file, in which

all the objects in the application are packaged. It is then up to you to send the

file to another system by any suitable method.

You can export an application from:

v The Applications window (from the Application menu or from the

applications’s popup menu)

v The Application window (from the Application menu)



v The AIX command line (see “dtexport command” on page 58)

v A script (see “dtexport command” on page 58).

You can export a complete application (full export) or only those objects which

have changed since either the last export time or a date and time you specify

(delta export), or you can select individual objects to export (partial export). In

addition, you can choose to export only binary objects. These choices are

explained further on pages 41 and 43.

Multiple simultaneous import or export operations using dtimport or dtexport

from the command line, or using import or export functions from the

Application Manager are not allowed. If you attempt to start an export

operation while another import or export operation is in progress, the

Application Manager will display a warning dialog notifying you that another

import or export operation is already in progress.

Note: The export process uses the AIX tar command to create a file in United

States Tape Archiver (USTAR) format. This supports file path names

with a maximum of 155 characters for the prefix part (the directory

name) and a maximum of 100 characters for the name part (the file

name itself).


Selecting the application

2. Either click the application name in the main Applications window, or

click the Application window, if it is displayed.

Exporting the complete application

3. Click Application —> Export —> Full.

The system displays the Full Export window:

exporting an application


4. Proceed to step 13.

Exporting updated objects only

5. Click Application —> Export —> Delta.

The system displays the Delta Export window:



6. Click the appropriate radio button for objects changed since Last Full

Export, Last Delta Export, or a Specific Date, and if necessary fill in the

date fields.

7. Proceed to step 13.

Choosing objects to export

8. Click Application —> Export —> Partial.

The system displays the Partial Export Preview window.

If the application has prerequisite applications, a window is displayed for

each of the applications. You don’t have to export them all. If you are

sure that a prerequisite application is already on the target system, click

Export —> Cancel.

All the objects in the application are listed:

This window allows you to drag in any objects that you want to add to

the export file, from any other applications.

It also allows you to exclude objects from the list, to prevent them from

being exported.

9. To remove an object from the list, click it and click Exclude from the

popup menu.

10. To add all the objects that are used by an object in the list, click the object

and then click Include Dependencies from the popup menu.



11. To add an object from another application to the list, open the other

application. Then click the object in the Application window and drag it

into the Partial Export window.

Exporting

12. Select Export —> Confirm on the Partial Export Preview window to

display the Partial Export window.

Click the appropriate radio button for Text and Binary objects, or Binary

Only.



What are text and binary objects?

Each state table, prompt, and 3270 script comprises a text file and a

binary (executable or “runtime”) file. You need both files for

development, but only the binary file for running applications in

production.

Select Text and Binary if:

v You are exporting to another development system

or

v You are exporting to a production system but want to ensure that you

don’t lose the source files.

Select Binary Only if:

v You are distributing the object to production systems

and

v You don't want anyone else to see or modify the code.

Note: The Object Settings window for each object has a radio button

for Do not export when "Binary Only" is selected. Selecting

this means that when you select Binary Only, the object is not

exported.

Specifying where to put the export file

13. Click the appropriate radio button for media type.

If you click File, the system displays the Export File window:



a. Click the directory and select or type in the file name for the export

file.

b. Click OK.

The “working” dialog is displayed. The progress of the export is

displayed on the status line in the Applications window.

When the export is completed, the system displays the Export Report

window, giving details of what was exported:

Saving or printing the export report

14. If you want to keep the Export Report you can print it or save it in a file.

v To print the Export Report, click Print. The report is printed on the

printer specified by the Printer Queue system parameter in the

WebSphere Voice Response parameter group.



v To save a copy of the Export Report, click Save. The system displays

the Save Report window:


report file.

b. Click OK.

Next Step

The export file is now ready to be transported to another system. Use

whichever method you normally use for this (for example, file transfer

protocol (ftp)).

Exporting one or more objects

Although the recommended methods of export are full export and delta export

of an application (see “Exporting an application” on page 38), partial export of

one or more objects is also available if necessary. To preserve the integrity of

your applications, however, partial export is not recommended.


Displaying the Object Index

2. If the Object Index window is not already displayed, click Options —>

Object Index from the Applications window.



The Object Index window shows a folder for each type of object in the

system:

The Object Index shows you all the application-related objects in the

system, organized into folders. It’s another view of the objects in the

system, each of which is contained in a single application. In other

words, you cannot move objects out of the Object Index into an

application: all objects are shown in the Object Index.

Opening a folder

3. Single-click on the folder icon to open it.

The folder contains all the objects of that type in the system.

Selecting the objects to export

4. Click one or more objects in the Object Index window.

5. Click Object —> Export —> Partial.

The system displays the Partial Export window.

This window allows you to drag in any objects from any applications.

6. To remove an object from the list, click it and then click Remove from the

popup menu.

7. To add all the objects that are used by an object in the list, click the object

and then click Get Dependencies from the popup menu. For guidance,

see on page 41.

8. To add an object from another application to the list, open the other

application. Then click the object in the Application window and drag it

into the Partial Export window.

exporting one or more objects


Exporting binary objects only

9. Click the appropriate radio button for Text and Binary (executable)

objects, or Binary only. For guidance, see on page 42.

Specifying where to put the export file

10. Click the appropriate radio button for media type.

If you click File, the system displays the Export File window.

a. Click the directory and click or type in the file name for the export

file.

b. Click OK.

The “working” dialog is displayed. The progress of the export is

displayed on the status line in the Applications window. Once the

export is completed, the system displays the Export Report window,

giving details of what was exported.

To keep a record of the export, click Print or Save. When you click Print,

the report is printed on the printer specified by the Printer Queue system

parameter in the WebSphere Voice Response parameter group.

When you click Save, the system displays the Save Report window.


file.

b. Click OK.

Next Step

The export file is now ready to be transported to another system. Use

whichever method you normally use for this (for example, file transfer

protocol (ftp)).

Importing application objects

You can import any file that was exported from a WebSphere Voice Response

system using any of the following methods. You can also import all the files

that are supplied with WebSphere Voice Response as import files (file names

ending in .imp).

v The procedure described in “Exporting an application” on page 38

v The procedure described in “Exporting one or more objects” on page 45

v Using the dtexport command (see “dtexport command” on page 58)

You can import application objects from:

v The Applications window (from the Application menu or from the

applications’ popup menu)

v The Application window (from the Application menu)

exporting one or more objects


v The AIX command line (see “dtimport command” on page 61)

v A script (see “dtimport command” on page 61)

When you import voice prompts or voice directories, you can choose either to

replace existing objects of the same name, or to merge them with existing

objects. When you choose to merge objects, the objects are replaced if they

already exist, and they are added if they do not. For objects other than voice

prompts and voice directories, you can only replace them.

Multiple simultaneous import or export operations using dtimport or dtexport

from the command line, or using import or export functions from the

Application Manager are not allowed. If you attempt to start an import


Application Manager will display a warning dialog notifying you that another

import or export operation is already in progress.

Attention: If the imported object belongs to a different application, it is put

into an application of that name on the target system, even if the replaced

object was in a different application.


Simply importing a file

2. Click Application —> Import —> Merge —> File.

The system displays the Import File window.

3. Type the path name in the Search String field, followed by an asterisk

(*). For example:

/usr/lpp/dirTalk/sw/samples/*

4. Click the file from the Files list.

importing application objects


5. Click OK.

The “working” dialog is displayed. The progress of the import is

displayed on the status line in the Applications window. When the

import has completed, the system displays the Import Report window:

Printing or Saving a Report

6. If you want to keep a the Import Report you can print it or save it in a

file. Click Print. The report is printed on the printer specified by the

Printer Queue system parameter in the WebSphere Voice Response

parameter group.

To keep a record of the import, click Save. The system displays the Save

Report window.

a. Click the directory and select or type in the file name for the import

report file.

b. Click OK.



Simply importing from tape or diskette

7. Ensure that the Default Tape Drive or the Default Diskette Drive system

parameter in the General parameter group is set as appropriate.

8. Click Application —> Import —> Merge —> Tape or Diskette.



import has completed, the system displays the Import Report window.

9. To keep a record of the import, click Save or Print.

Checking the objects you are importing from a file

10. Click Application —> Import with Preview —> Merge —> File.

The system displays the Import File window.

11. Type the path name in the Search String field, followed by an asterisk

(*), for example:

/usr/lpp/dirTalk/sw/samples/*

12. Click the file from the Files list.

13. Click OK.

The system displays the objects included in the file.

14. Open and close the folders by single-clicking on the folder icon. If you do

not want to install all objects, click any object not required, and then click

Exclude from the popup menu.

The selected objects are removed from the list. (If you remove one by

mistake, click Cancel and start over.)



Note: For the most efficient application distribution, you are

recommended to ensure that the export file contains the correct set

of objects and then import all of them, rather than exporting more

than you need and then picking the ones you don’t want. See

“Exporting an application” on page 38.

15. Click OK.




16. If you want to keep the Import Report you can print it or save it in a file.

When you click Print the report is printed on the printer specified by the

Printer Queue system parameter in the WebSphere Voice Response

parameter group.

When you click Save, the system displays the Save Report window:

a. Click the directory and select or type in the file name for the import

report file.

b. Click OK.

Checking the objects you are importing from tape or diskette

17. Ensure that the Default Tape Drive or the Default Diskette Drive system

parameter in the General parameter group is set as appropriate.

18. Click Application —> Import with Preview —> Merge —> Tape or

Diskette.

The system displays the objects included in the file.

19. Open and close the folders by single-clicking on the folder icon. Click

any objects you do not want to import.

20. Click Exclude.

The selected objects are removed from the list. (If you remove one by

mistake, click Cancel and start over.)

21. Click Import —> Confirm.




Done

The application objects are now ready to be used in the target system.

Migrating from an earlier release of IBM WebSphere Voice Response for AIX

As described in the WebSphere Voice Response for AIX: Installation guide, there

are two methods of migrating applications:



v If you used the saveDT command to save your WebSphere Voice Response

application objects and data before installing WebSphere Voice Response,

you must use the restoreDT command to bring them into WebSphere Voice

Response (see the WebSphere Voice Response for AIX: Installation guide for

details).

v If you exported application objects from IBM WebSphere Voice Response for

AIX Version 1, you must import them into WebSphere Voice Response

Version 2, as described in “Importing application objects” on page 47.

In both cases, objects created using IBM WebSphere Voice Response for AIX

Version 1 are

v Automatically migrated into the WebSphere Voice Response Version 2

format when you restore or import them.

v Placed in the Default application in WebSphere Voice Response.

To organize your application-related objects, you should now create your own

applications and move your objects into them (see “Creating an application”

on page 34 and “Moving objects from the default or user applications” on

page 56).

Frequently asked questions

Here are some frequently-asked questions:

v “Do you have to create applications?” on page 53

v “Where are newly-created or migrated objects put?” on page 53

v “What happens when you import objects belonging to an application that

does not exist on the target system?” on page 54

v “What about the integrity of applications that are already in use?” on page

53

v “When should you use full export, delta export, and partial export?” on

page 54

v “When should you export prerequisites along with an application?” on

page 54

v “What happens to “duplicate” objects?” on page 54

v “What if more than one application needs to use the same object?” on page

55.

migrating from an earlier release of IBM WebSphere Voice Response for AIX


Do you have to create applications?

Your state tables will run successfully, whether or not you create your own

applications to put the objects in3. In other words, you can develop and run a

voice response service without creating your own application containers.

Nevertheless, you will find that applications make management and

distribution of objects easier. If you decide to create your own applications

after all, follow the instructions in “Moving objects from the default or user

applications” on page 56.

What about the integrity of applications that are already in use?

Moving objects between applications has no effect on any objects that are in

use. However, if you choose to delete an object, you really will be deleting it

from the system, and a dialog will ask you to confirm your decision, even if

the object is not in use.

Similarly, if you import a new version of a state table when that state table is

already running (and so is already cached), the running state table is not

changed. The new version is used next time you start the application.

Where are newly-created or migrated objects put?

All application objects in the WebSphere Voice Response system must be in

one and only one application. However, objects can “arrive” in a WebSphere

Voice Response system in a variety of ways. Table 2 shows which applications

these objects are put into.

Table 2. Where To find newly-created objects

Method of Creating the Object Application

Migrated from IBM DirectTalk for AIX Version 1 Default

Imported from another WebSphere Voice Response

Version 2 system (including application objects

supplied with the WebSphere Voice Response

product or its features)

The application that contained

the object in the other system

Created by clicking Object —> New in an

Application window

The current application

Created by clicking the object type (for example,

State Tables, from the Applications menu in the

Welcome window and then File —> New

User

Created by clicking Object —> New from the

Object Index window

Default

3. When you put the application into production, it is the application profile that defines the main state table and

entry point to the runtime WebSphere Voice Response system. (See Chapter 5, “Creating an application profile,” on

page 89 for more information.)

frequently asked questions


What happens when you import objects belonging to an application that

does not exist on the target system?

Whether you’re importing an application into a system for the first time, or if

you have deleted the application and are importing it again, the answer to

this question depends on whether you are importing a file that was the result

of:

v A full or delta export

v A partial export

With full or delta export, the application is created in the target system and all

the objects are placed within it.

With partial export, when the file is imported into another system, WebSphere

Voice Response attempts to place each object into the application to which it

belonged on the system from which it was exported. If an application with

that name does not exist on the target system, the object is not created, and an

error is reported.

When should you use full export, delta export, and partial export?

Use full export the first time you need to copy an application to another

system. After the first time, delta export is recommended, because it includes

only the objects that have been changed, and therefore reduces the size of the

file.

Use full export for a complete backup of an application.

Partial export is recommended only for exporting one or a few individual

objects. It’s not recommended as the normal method of exporting voice

application objects: to ensure the integrity of your applications, use delta

export instead.

When should you export prerequisites along with an application?

Prerequisite applications contain objects necessary for the application to run:

these may be objects, such as system prompts, that are used by many

applications. It’s not necessary to export those prerequisite applications unless

you know they don’t exist on the target system or you know that some of the

objects have changed.

What happens to “duplicate” objects?

Each object name must be unique across all the applications in a system. This

means that you have to be careful when importing an application for the first

time. The same applies to using the restoreDT command when migrating from

a release of IBM WebSphere Voice Response for AIX. Any object already in the

target system, with the same name as an object being imported, will be

overwritten.



What if more than one application needs to use the same object?

The application is a “container” of application objects, which means that each

object must be specified in one, and only one, application. In addition, each

object must have a unique name, within that type of object, across all

applications.

It is very likely that some objects will be useful in more than one voice

response service: for example, voice segments for commonly-used phrases.

Copying them has two disadvantages: storage is used unnecessarily and you

have to rename each copy. Instead of copying, you can make an object

available to be used by more than one application, by putting it into a common

application. A common application is just an ordinary application whose

objects are to be used by more than one other application.

You then add the common application to the list of application prerequisites

for any application that is to use it. When you export any of these

applications, the system gives you the opportunity to export the common

application at the same time.

For example, the cemg application in Figure 5 includes all the state tables, and

the specific prompts, voice segments, and voice tables used by those state

tables; while the common application includes prompts, voice segments, and

voice tables that might be used by other applications too.

Figure 5. Two applications, one of which contains commonly-used objects



Moving objects from the default or user applications

If you have just migrated from IBM WebSphere Voice Response for AIX

Version 1, or for some other reason all your objects are in either the Default

application or the User application, you may find it more convenient to sort

them out into application “packages” (for reasons, see “Managing application

objects efficiently” on page 29).

The following instructions assume that the source application is the Default

application, but they work just as well for the User application or any other

application.


Displaying the Default application

2. Find the object named Default and double-click on it to open it.

The Application (Default) window is displayed.

3. In the Applications window, create your own application, and move

objects from the Application (Default) window into the new window,

following the instructions in “Creating an application” on page 34.

Hints and Tips:

v To select objects that are next to each other, hold down MOUSE BUTTON 1

and drag across the object names.

v To select multiple objects that are not necessarily next to each other,

click the MOUSE BUTTON 1 to select one object, and then hold down the

CTRL key while clicking on more objects.

v Use MOUSE BUTTON 2 to drag the objects across to your application.

v You can’t select objects from more than one folder at a time.

v You might be wondering why you shouldn’t use the Object Index to do

this task. You can drag objects from the Object Index to an Application

window, but it’s harder to keep track of what you’ve done, because the

objects are still displayed in the Object Index after you’ve dragged them.

The Object Index is just an Index.

Deleting an application

Before you do this, make sure that the application is not a prerequisite of any

other application, and make sure that the objects in the application are not

used by any other objects. You must first delete or move all the objects from

an application before you can delete it.

Note: You cannot delete the User, Default, or System applications.


Removing the objects from the application

moving objects from the default or user applications


2. Double-click on the name of the application.

The Application window is displayed.

3. Single-click to open the first folder.

4. Move any objects that you want to keep to another application.

5. If you are sure you don’t need some or all of the objects any longer, select

them and then click Object —> Delete.

Click Confirm on the delete confirmation dialog to delete the objects.

The selected objects are deleted from the system.

6. Repeat from step 3 for all the other folders in the Application window.

The Application window is empty.

Removing the application

7. Click Application —> Delete.

Note: If the application still contains any objects, the system does not

allow you to delete it.

8. Click Confirm on the delete confirmation dialog to delete the application.

The selected application is deleted from the system.

The dtimport and dtexport commands

The dtimport and dtexport commands are fully compatible with the Import

and Export options in the windows, but also enable you to:

v Distribute the applications to multiple systems using shell scripts. This can

automate the process of distributing updated application objects.

v Start the dtexport command from the command line on a remote system.

This means that you can capture an application from a remote site and

examine or debug it at your location.

The dtexport and dtimport commands perform most of the same functions as

the Export and Import options. The following functions are not supported by

the dtexport command:

v The option to apply a text or binary selection to all objects in the export list.

All objects must be either text or binary.

v The option to apply dependencies to selected objects in the export list. All

objects must have all or no dependencies.

v A method for setting the application profile selection criteria; you must pass

the list of profiles to be exported through command line arguments.

The following functions are not supported by the dtimport command:

v Selective object deletion. You must install all or none of the objects from the

import file on the destination system.

deleting an application


v Selective object merge. You must merge all or none of the objects that can

be merged.

Once invoked, dtexport and dtimport do not require any user intervention.

They can be started either from within a shell script, or by typing the

commands directly on the AIX command line. Starting the programs from

within shell scripts gives a lot of power to the user because they can have the

programs executed on remote machines and as a part of more complex

operations.

Because the command-line utilities are fully compatible with the options in

the windows, you can use the dtimport command to import files that were

exported by the Export option, and you can use the Import option to import

files that were exported by the dtexport command.

dtexport command

Purpose

Exports application objects into application or partial-export packages.

Prerequisites

v You must be logged onto AIX as dtuser.

v WebSphere Voice Response must be running.

Syntax

dtexport [-dev device | -f filename | -t | -D]

[-x] [-b]

[-appl application [-delta [-since yyyymmddhhmmss]]]

[-stab statetable...]

[-pdir promptdir...]

[-vdir voicedir...]

[-vtab voicetable...]

[-3270 server...]

[-cs server...]

[-prof profileID...]

[-sclass class...]

Flags

-dev device

Export on to the specified device. The device can be either a

fully-qualified AIX file name or a device path (for example,

/dev/rmt0).

-f Export into the AIX file specified as filename. The file name must not

be longer than 100 characters.

the dtimport and dtexport commands


You can also specify the path to the file. The path name must not be

longer than 155 characters.

-t Export on to the tape drive specified in the Default Tape Drive system

parameter.

-D Export on to the diskette drive specified in the Default Diskette Drive

system parameter.

-x Extract all dependencies of the selected objects, and add them to the

package. This option is not valid if you also specify the -appl option.

If you do not specify the -x option, only those objects specified on the

command are included in the package.

-b Export only the binary format of those objects that have both a text

and a binary form (that is, state tables, prompts, and 3270 scripts).

-appl application

Specifies the name of the application to be exported. This option

cannot be specified in conjunction with the object type options

described below.

-delta The application objects to be exported are only those that have been

modified since a certain date. If you do not specify the -since option,

this date is the date of the previous export. If you do specify the

-since option, the date you supply is used. This option is valid only

you also specify the -appl option.

-since yyyymmddhhmmss

Only those objects in the specified application that have been

modified since the time yyyymmddhhmmss are to be exported. This

option is valid only if the -appl and -delta options are also specified.

-stab statetable...

Specifies a space-delimited list of state tables that are to be exported.

This option is not valid if -appl is also specified.

-pdir promptdir...

Specifies a space-delimited list of prompt directories that are to be

exported. This option is not valid if -appl is also specified.

-vdir voicedir...

Specifies a space-delimited list of voice directories that are to be


-vtab voicetable...

Specifies a space-delimited list of voice tables that are to be exported.


-3270 server...

Specifies a space-delimited list of 3270 servers that are to be exported.




-cs server...

Specifies a space-delimited list of custom servers that are to be


-prof profileID...

Specifies a space-delimited list of application profile IDs that are to be


-sclass class...

Specifies a space-delimited list of subscriber classes that are to be


Return values

0 Success

< >0 Failure

Usage notes

v Multiple simultaneous import or export operations using dtimport or

dtexport from the command line, or using import or export functions from

the Application Manager are not allowed. If you attempt to start an export


dtexport command will return an error message notifying you that another

import or export operation is already in progress, and the command will

return an exit code of 2.

Examples

To export objects of a specified type (profiles, in this example) to a file called

/usr1/dtuser/profiles.imp:

dtexport -dev /usr1/dtuser/profiles.imp -prof 4085551234

To export a state table and all its dependents to a file called

/usr1/dtuser/stbl.imp:

dtexport -dev /usr1/dtuser/stbl.imp -x -stab My_State_Table

To export a combination of objects without their dependents to a tape:

dtexport -t -stab Table1 Table2 -pdir Pdir1 -vdir Vdir1 Vdir2 Vdir2

To export a complete application called “Sports_Results”:

dtexport -dev /tmp/sports.imp -appl Sports_Results

To export only those objects in the “Sports_Results” application that have

changed since the last export:

dtexport -dev /tmp/sports.imp -appl Sports_Results -delta



To export only those objects in the “Proto” application that have changed

since a specific date:

dtexport -dev /tmp/proto.imp -appl Proto -delta -since 19970620000000

dtimport command

Purpose

Imports application or partial export packages

Prerequisites

v You must be logged on to AIX as dtuser.

v WebSphere Voice Response must be running.

Syntax

dtimport [-dev device | -f filename | -t | -D]

[-mp] [-mv]

Flags

-dev device

Import from the specified device, which either be a fully-qualified AIX

file name or a device path (for example, /dev/rmt0).

-f Import from the AIX file specified as filename.

-t Import from the tape drive specified in the Default Tape Drive system

parameter.

-D Import from the diskette drive specified in the Default Diskette Drive

system parameter.

-mp Specifies that any prompt directories in the export package will be

merged into the corresponding prompt directory on the target system

(if it exists). This means that prompts will be replaced if they already

exist, and added if they do not.

If you have used this option in Version 1 of WebSphere Voice

Response, see “Usage notes” on page 62.

-mv Specifies that any voice directories in the export package will be

merged into the corresponding voice directory on the target system (if

it exists). This means that voice segments will be replaced if they

already exist, and will be added if they do not.

Return values

0 Success

< >0 Failure



Usage notes

v In WebSphere Voice Response, the -mp (merge prompt) option behaves in a

more appropriate manner than it did in IBM WebSphere Voice Response for

AIX, and is consistent with the -mv (merge voice directories) option.

v In WebSphere Voice Response, the IBM WebSphere Voice Response for AIX

-noprompt option is unnecessary and has been removed.

v Multiple simultaneous import or export operations using dtimport or

dtexport from the command line, or using import or export functions from

the Application Manager are not allowed. If you attempt to start an import


dtimport command will return an error message notifying you that another

import or export operation is already in progress, and the command will

return an exit code of 2.

Examples

To import the objects contained in the file called /usr1/dtuser1/sports.imp:

dtimport -dev /usr1/dtuser1/sports.imp

To import the objects from a on a diskette and merge all matching voice

directories and prompt directories:

dtimport -D -mp -mv



Chapter 4. Overview of application objects

These objects were introduced briefly in the WebSphere Voice Response for AIX:

General Information and Planning guide, and are described in more detail in the

following sections. You’ll need the procedural and reference information in the

WebSphere Voice Response for AIX: Application Development using State Tables;

WebSphere Voice Response for AIX: 3270 Servers; and WebSphere Voice Response for

AIX: Custom Servers reference manuals when you come to create your own

objects to implement a voice response service.

State tables

A state table is a sequence of states, each of which performs a specific action,

which can have one or more possible results. During a telephone call, the

voice application progresses through the states, performing the actions in turn.

The result of each action determines the next state to go to. See Table 3 on

page 69 for an example of a state table.

A state table can invoke a nested state table to perform a set of actions before

returning control to the invoking state table. The state table can invoke

different state tables depending on a condition, such as the response of the

caller to a previous prompt.

State table actions

There is a range of state table actions, from very general (such as AssignData,

which performs a variety of computational functions) to very specific (like

ControlMusic, which is used to turn up or down the volume of background

music). Because the general actions can be combined in so many ways, the

following list may not be exhaustive, but it does give a goal-oriented

overview of which action to choose to perform application functions.

Telephony activity

Respond to a ringing line (incoming call) AnswerCall

Make an outbound call MakeCall

Send a set of numbers, a hook flash, or a ground key

signal to the switch

Dial

Detect the presence of a dial tone Dial

Transfer a caller to an agent or another caller TransferCall

Reconnect a caller to the voice application (for

example, if a TransferCall failed)

ReconnectCall


Disconnect a caller TerminateCall

Voice segments

Record a segment of voice data RecordVoiceSegment

Store a segment of voice data in a voice directory SaveVoiceSegment

Remove a segment of voice data DeleteVoiceSegment

Play a prompt, which may include one or more

prerecorded voice segments

PlayPrompt

Play a single segment of prerecorded voice data PlayVoiceSegment

Output to the caller

Play a prompt, which may include one or more

prerecorded voice segments

PlayPrompt

Play a single segment of prerecorded voice data PlayVoiceSegment

Play speech from a text-to-speech server, database

server, or another WebSphere Voice Response system

PlayVoiceFromHost

Play voice data sent from another WebSphere Voice

Response system and received by a custom server

PlayVoiceFromHost

Play a pacing or other feedback tone PlayBeep

Background music

Start or stop playing a background music tune ControlMusic

Turn the volume of background music up or down ControlMusic

Key input from the caller

Get a single key from the caller GetKey

Get multiple keys from the caller, as digits GetData

Get multiple keys from the caller, as digits or letters GetText

Use keys pressed by the caller to retrieve data from a

3270 server or custom server

GetFindData

Retrieve an application profile, using keys pressed by

the caller

GetFindName

Check the password keyed by the caller with the

password defined in the application profile specified

by SV20 for the mailbox ID specified by SV32

GetPassword

state tables


Program logic and flow of control

Wait for a specified period of time DoNothing

Wait until one of a number of events occurs WaitEvent

Log an event LogEvent

Compare one value with another value EvaluateData

Select the next state to go to on the basis of the value

of a character variable

Case

Invoke another state table InvokeStateTable

Start communication with a custom server OpenHostServerLink

Start communication with a 3270 server OpenHostServerLink

Send data to a custom server SendData

Send data to a 3270 server SendData

Receive data items and return codes, from a custom

server

ReceiveData

Receive data items and return codes, from a 3270

server

ReceiveData

Find out it there is enough storage available in the

WebSphere Voice Response file system for an

application to execute as planned

CheckStorage

Computation and string handling

Define a constant AssignData (Assign)

Assign a value to a variable AssignData (Assign)

Add two numbers and assign the result to a variable AssignData (Add)

Subtract one number from another and assign the

result to a variable

AssignData (Subtract)

Multiply one number by another and assign the result

to a variable

AssignData (Multiply)

Divide one number by another and assign the result

to a variable

AssignData (Divide)

Divide one number by another and assign the

remainder to a variable

AssignData (Modulus)

Assign the absolute value of a number to another

variable

AssignData (Absolute Value)

Truncate one number by the length specified by

another and assign the result to a variable

AssignData (Truncate)

state tables


Round one number at the digit specified by another

and assign the result to a variable

AssignData (Round)

Concatenate one character string to another and

assign the result to a variable

AssignData (Concatenate)

Take a specified number of characters from the

beginning of one character string and assign them to

a variable

AssignData (Left)

Take a specified number of characters from the end of

one character string and assign them to a variable

AssignData (Right)

Take the character that occurs in a specified position

of one character string and assign it to a variable

AssignData (Index)

Search for a specified character string in another

character string and assign the position of it in the

second string to a variable

AssignData (Search String)

Count the number of characters in a character string


AssignData (Length)

Convert all the characters in a string to uppercase,


AssignData (Uppercase)

Convert all the characters in a string to lowercase,


AssignData (Lowercase)

Voice mailboxes

Set or change the attributes of a voice mailbox UpdateProfile

Voice messages

Record a new voice message RecordVoiceMessage

Add more to the beginning of a voice message RecordVoiceMessage

Add more to the end of a voice message RecordVoiceMessage

Set or change the attributes of a voice message ChangeMessageAttributes

Send a voice message to the mailbox specified by the

application profile ID and mailbox ID

SendVoiceMessage

Retrieve all voice messages of a specified type for the

application profile specified by SV20 and mailbox ID

specified by SV32

CheckVoiceMessages

Play a voice message from a mailbox PlayVoiceMessage

Save a voice message, which has been retrieved using

CheckVoiceMessages, in the mailbox for later retrieval

SaveVoiceMessage

state tables


Play back a voice message which has just been

recorded

PlayVoiceMessage

Remove a voice message previously retrieved using

CheckVoiceMessages

DeleteVoiceMessage

Distribution lists

Retrieve names of all recipients on a specified

distribution list for a specified application profile and

mailbox ID

GetDistributionList

Retrieve names of all distribution lists for a specified

application profile and mailbox ID

GetDistributionList

Add a mailbox to a distribution list UpdateDistributionList

Add a distribution list to a distribution list UpdateDistributionList

Remove a name from a distribution list UpdateDistributionList

Remove a distribution list UpdateDistributionList

Copy a distribution list UpdateDistributionList

Append a distribution list to another distribution list UpdateDistributionList

Audio names

Record an audio name RecordAudioName

Store the audio name for the application profile and

mailbox ID

SaveAudioName

Play the audio name of the specified application

profile and mailbox ID

PlayAudioName

Remove the audio name of the specified application


DeleteAudioName

Greetings

Record a greeting RecordUserGreeting

Store the greeting for the specified application profile

and mailbox ID

SaveUserGreeting

Play the greeting associated with the specified


PlayUserGreeting

Remove the greeting specified by system variable

SV102

DeleteUserGreeting

state tables


Endings

Terminate a nested state table and return to the

invoking state table

ExitStateTable

Terminate a link with a custom server CloseHostServerLink

Disconnect a caller TerminateCall

Terminate an application and clean up all resources CloseEverything

state tables


Example state table

Table 3. Example state table

State Table Name: Simple_Sample

Prompt Directory: Simple_Prompts

Description: Account

balances and interest rates

State

Label

Action Parameter Description Possible Results Next

State

Start AnswerCall

1 None Succeeded

Not ringing

Welcome

Exit

Welcome PlayPrompt Prompt name (plays

segment 1)

Succeeded

Line Problem

Nothing Played

Caller Hung Up

Options

Exit

Thanks

Exit

Options PlayPrompt Prompt name (plays

segment 2)

Succeeded

Line Problem

Nothing Played

Caller Hung Up

Retrieve

Exit

Thanks

Exit

Retrieve GetKey Caller’s input (variable) Valid input

Invalid input

No input

Caller hung up

Check

Options

Options

Exit

......

......

...

Thanks PlayPrompt Prompt name (plays

segment 15)

Succeeded

Line Problem

Nothing Played

Caller Hung Up

Exit

Exit

HangUp

Exit

state tables


Table 3. Example state table (continued)

State Table Name: Simple_Sample

Prompt Directory: Simple_Prompts

Description: Account

balances and interest rates

Error PlayPrompt Prompt name (plays

segment 16)

Succeeded

Line Problem

Nothing Played

Caller Hung Up

Options

Exit

HangUp

Exit

HangUp TerminateCall Succeed Exit

Exit CloseEverything

1. The AnswerCall statement is required only for using the Debug option in the

state table window. The call has already been answered by the Incoming_Call

state table: see “How does WebSphere Voice Response answer an incoming call?”

on page 135.

State table variables and parameters

WebSphere Voice Response includes three types of variable:

v System variables

v Local variables

v Input parameters

Use the AssignData action to set the value of a variable and the EvaluateData

action to check the value.

System variables

System variables are global variables predefined by WebSphere Voice

Response; they are available to any WebSphere Voice Response state table or

prompt, but not to 3270 servers or custom servers. There are a large number

of system variables, and they are documented in the WebSphere Voice Response

for AIX: Application Development using State Tables reference manual.

state tables


In the window for selecting system variables (shown in Figure 6), the

variables are organized into groups, and listed by names that reflect those

groupings. Each system variable also has a shorter numeric identifier

preceded by “SV”. For example, the System : Call Info : Called number

system variable (SV185) holds the number dialed by the caller (the called

number passed by the switch), and the System : Call : Channel number

system variable (SV165) holds the logical channel number of the channel

currently in use by the application.

The values of some system variables are read-only (RO) and cannot be

changed by an application; other system variables are read-write (RW) and

their values can be set using the AssignData action.

Global user variables

WebSphere Voice Response supplies 60 read-write system variables for your

use. These include 30 string variables (SV51 through SV80), each of which can

contain up to 3583 characters, and 30 numeric variables (SV241 through

SV270), which are implemented as 32-bit signed integers. These variables, like

other system variables, are global within a state table and all the state tables

nested within it. They are not accessible by state tables running on other

channels. When the main state table starts, the string variables are initialized

to null and the numeric variables are set to 0.

Figure 6. System variables

state tables


Local variables

Local variables are variables that you define for use by a single state table.

You provide the names that identify each local variable and define the type of

the variable as a string of characters or as a number.

Local variables are not permanent. When the application is finished using a

state table, it destroys the local variables you defined for that state table. The

next time the application is invoked and uses the state table, it recreates the

local variables.

The information the local variable contains is accessible to any action in the

state table in which you defined the variable. But only that state table can

access or alter the contents of the variable. If you use an InvokeStateTable

action to call another state table, the local variables defined for the invoking

state table are not available to the invoked state table, unless they are passed

as parameters.

Input parameters

Input parameters are used to define variables received by programs, including

prompts, 3270 scripts, custom servers, or state tables, from the invoking state

table. When you use the InvokeStateTable action to invoke a state table,

parameters are passed by reference to the invoked state table: in other words,

they are global variables accessible to, and modifiable by, both the invoking

and invoked state tables.

To pass parameters from a state table to another state table, prompt, custom

server or 3270 server, click the Parameters pushbutton in the InvokeStateTable

window, the PlayPrompt window, or the SendData and ReceiveData windows.

This displays a window that lists the parameters required by the invoked

state table, prompt, custom server or 3270 server, as shown in Figure 7 on

page 73. Parameters are passed by value to prompts, custom servers, and 3270

servers.

state tables


Note: No parameters can be passed from an application profile to a state

table.

State table action parameters

Some state table actions require parameters to tell them what to do. For

example, the PlayPrompt has a Force Play parameter that specifies that the

prompt must be played through to the end. Some parameters can be constant

values or variables.

Returning data to the state table

An invoked state table can return data to the invoking state table by assigning

a new value to an “input” parameter. Because parameters are passed by

reference to state tables, the new value will be available to the invoking state

table.

A prompt cannot return data to the state table, but the RETURN and ABORT

statements set the value of the System : PlayPrompt status system variable

(SV130), which can then be read by the state table.

A 3270 server or custom server can return data to the state table using

parameters on the ReceiveData action.

Possible results

Each state table action can have one or more possible results. The possible

results of each action are predefined by WebSphere Voice Response. For

example, the PlayPrompt action has four possible results:

v Succeeded

v Line problem

v Nothing played

v Caller hung up

Figure 7. A list of parameters to be passed to a prompt

state tables


For each result, the state table needs to know what to do next. For each

possible result, of each state in your state table, you have two choices:

1. “Fall through” to the next state in the state table

2. “Go to” another state in the state table

When you have identified the state table actions needed for your application,

check the state table action descriptions in the WebSphere Voice Response for

AIX: Application Development using State Tables to make sure that your design

accounts for all possible results. You may need to modify your design if you

find you have not allowed for some possible results. Decide how you want

the application to handle each possible result and create the state you need.

When interpreting results, you may find it useful to look at some of the

system variables, such as the System : Action additional information

system variable (SV180), which gives you additional information about some

actions. (And note that SV180 is reset after every action, including DoNothing,

so you should check its value immediately following the action.)

Entry points

You must define at least one entry point at which execution of the state table

begins. If the state table always starts at the first state and executes through to

the last state, there will be only one entry point. However, you can start

execution at any state by defining entry points where applicable. When you

call a state table from an application profile or another state table, you specify

the entry point at which execution is to start.

Prompts

Prompts are used in state tables to define what a caller hears. A prompt not

only identifies the words the caller hears, but also defines the logic of when

and how the words are played.

A prompt can be simple or complex, depending on whether the prompt

always plays the same words or whether the prompt logic defines conditions

for playing different phrases. For example, you may want an application to

repeat the items that the caller has ordered, so the prompt would construct

the utterance with phrases representing those items: “you ordered a bagel with

sour cream and lox, and a croissant with Canadian ham and salad ”.

Prompts are constructed using the prompt statements described in the

WebSphere Voice Response for AIX: Application Development using State Tables.

The variables used by prompt statements work exactly the same way as state

table variables. Generally, a state table passes input parameters to a prompt

which it then uses to select the voice segments to play to the caller.

state tables


The set of prompts that are used by a particular state table are grouped in a

prompt directory. All prompts used by a state table must be in the same prompt

directory. Multiple state tables can use the same prompt directory.

System prompts

The System prompt directory contains the system prompts, which are included

with WebSphere Voice Response when the system is installed. The system

prompts do not operate any differently from the prompts you create. The only

difference between system prompts and the prompts you write is that the

system prompts are already written for you.

If a state table uses the System prompt directory, the state table can call a

system prompt by supplying the prompt name to the state table action that

plays the prompt as a parameter. If a state table uses its own prompt

directory, you can create new prompts that call the system prompts (using the

SYSPROMPT prompt statement). Each system prompt accepts a number as

input and plays a prompt that speaks the number as one of the following:

v An integer between -999 and 999

v An integer between -999 999 999 999 and 999 999 999 999

v A real number

v An ordinal number

v The date (in U.S. format)

v The time (in 12-hour format)

v An amount of currency (in U.S. currency)

v A telephone number

For example, if an application passes the number 12.34 to the Currency

prompt, the phrase that results is “twelve dollars and thirty-four cents.”

However, passing the same number to the Real_number prompt results in the

phrase “twelve and thirty-four hundredths.”

Note that although very large numbers can be stored and used by WebSphere

Voice Response (using multiple precision format to store large numbers and

floating point numbers), the system prompts cannot play numbers larger than

the maximum size defined by the prompts. To play very large numbers, you

may need to create your own system prompts.

The Small_number prompt

The Small_number system prompt plays an integer between -999 and 999 as

a numeric quantity. Numbers larger than 100 are played without “and”

between the word “hundred” and any of the digits. For example, an input of

123 produces the phrase “one hundred twenty-three.”

prompts


The small number prompt includes prompt statements that reference the

Numbers and the Divisor voice tables.

The Whole_number prompt

The Whole_number system prompt plays a positive or negative integer of up

to 12 digits as a numeric quantity. The prompt does not insert “and” between

any of the units of measure or digits. For example, an input of 1103294

produces the phrase “one million one hundred three thousand two hundred

ninety-four.”

Whole_number includes a prompt statement that references the Divisor voice

table.

The Real_number prompt

The Real_number system prompt plays a positive or negative real number as

a numeric quantity. The prompt expresses fractional amounts in one of two

ways, depending on the amount:

1. If the number is expressed up to three decimal places (tenths, hundredths,

thousandths), it is played as “(number) and (number) (unit of measure).”

For example, an input of 1.2 produces the phrase “one and two tenths.”

An input of 1.23 produces the phrase “one and twenty-three hundredths.”

2. If the number is expressed to more than three decimal places, it is played

as “(digit) point (digit) (digit) (digit) (digit).” For example, an input of

1.2345 produces the phrase “one point two three four five.”

Note that you can change the character to be used for the decimal place by

modifying the System : MPN : Decimal point character system variable

(SV168). The default character is the period (.), which plays the word “point.”

The Ordinal prompt

The Ordinal system prompt plays a positive integer of up to 12 digits as an

ordinal number. For example, an input of 256 produces the phrase “two

hundred fifty-sixth.”

Ordinal includes prompt statements that reference the Numbers, Divisor, and

Ordinal voice tables.

The Date prompt

The Date system prompt plays 8-digit input (yyyymmdd) as the month, day,

and year. The convention followed is to play the name of the month, followed

by the day as an ordinal number, followed by the year as two numbers. For

example, an input of 19930113 produces the phrase “January thirteenth,

nineteen ninety-three.”

prompts


Date includes a prompt statement that references the Month of Year voice

table.

The Time prompt

The Time system prompt plays 6-digit input (hhmmss) as two numbers

followed by AM or PM. The seconds value is not played. If the minutes input

is 00, Time plays “o’clock” following the hours value.

Although the input to Time is in 24-hour clock time, Time plays the time

using a 12-hour clock. Noon is 12 PM and midnight is 12 AM (both 000000

and 240000 are interpreted as midnight).

For example, an input of 160100 produces the phrase “four oh one PM.” An

input of 110000 produces the phrase “eleven o’clock AM.”

Time includes prompt statements that reference the Numbers and Time of

Day voice tables.

The Currency prompt

The Currency system prompt plays an input string as an amount of dollars

and cents. For example, an input of 123.45 produces the phrase “one hundred

twenty-three dollars and forty-five cents.”

Note that you can change the character to be used for the decimal place by

modifying the System : MPN : Decimal point character system variable

(SV168). The default character is the period (.).

The Phone prompt

The Phone system prompt plays an input string as a string of digits. For

example, an input of 5551212 produces the phrase “five five five one two one

two.”

System prompts in languages other than U.S. English

The system prompts supplied with WebSphere Voice Response produce

phrases that are spoken in U.S. English. In addition, system prompts for other

national languages are supplied in the /usr/lpp/dirTalk/sw/samples directory

(if you install the appropriate optional filesets, which are listed in the

WebSphere Voice Response for AIX: Installation guide):

v Belgian Dutch

v Brazilian Portuguese (for more information, see “System prompts in

Brazilian Portuguese” on page 80)

v French (for more information, see “System prompts in French” on page 78)

v German

v U.K. English

prompts


If you want to create system prompts in a language that is not listed here, see

“Changing the system prompts for your language” on page 80.

System prompts in French

Note: The euro is another currency that is configurable but not yet provided.

In addition to the standard translated system prompts, the French samples

include:

v Prompts to be called by the Currency prompt (named xxx_frs)

v Currency voice directory (named Monnaie)

v Currency voice tables (named xxx_frs)

v Phone numbers voice table (named Telephone)

Each French system prompt accepts a number as input and plays a prompt

that speaks the number as one of the following :

v An integer between 1 and 100 000 000 000

v A real number

v A date (in French format: DD MM YYYY)

v A time (in French format: HH MM)

v A phone number (in French format : nn nn nn nn)

v An amount of currency (in French format, using Francs and Centimes)

Note that if you delete the French language from the system, the specific

French system prompts (Small_number_frs, Whole_number_frs, and

Real_number_frs) are not removed. You must remove each prompt

individually.

For help with the French system prompts, contact the French Support Center

in Paris (Centre de Solution VOIX--DCT).

The standard French system prompts are :

Small_number

Plays an integer between -999 and 999.

For example, 121 is spoken as "cent ... vingt et un." Small_number

includes prompt statements that reference the Numbers and the

Numbers_c voice tables.

Whole_number

Plays a positive or negative integer.

For example, 12345 is spoken as "douze mille ... trois cent ... quarante

cinq."

prompts


Whole_number includes prompt statements that reference the Numbers,

the Numbers_c, and the Numbers_m voice tables.

Real_number

Plays a positive or negative number.

For example, 1,23 is spoken as "un ... virgule ... vingt trois."

Date Plays 6 digits (DDMMYY) or 8 digits (DDMMYYYY) as day, month,

and year.

For example, 010194 is spoken as "Le premier ... janvier ... mille ...

neuf cent ... quatre vingt quatorze."

Date includes prompt statements that reference the Month of Year and

the Day of Month voice tables.

Time Plays 6 digits (HH MM SS) as hour and minutes.

For example, 09:30 is spoken as "neuf heures ... trente minutes."

Time includes prompt statements that reference the Time of Day voice

table

Phone Plays 8 digits as 4 numbers

For example, 49057000 is spoken as "quarante neuf ... zero cinq ...

soixante dix ... zero zero." Phone includes prompt statements that

reference the Telephone voice table.

Currency

Plays input as Francs and Centimes associated with the following

specific French system prompts.

The French system prompts called by the Currency prompt are:

Small_number_frs

Plays an currency integer between -999 and 999.

For example, 121 is spoken as "cent ... vingt et un francs."

Small_number_frs includes prompt statements that reference the

Numbers the Numbers_c, the Numbers_frs and the Numbers_cfrs voice

tables.

Whole_number_frs

Plays a positive or negative currency integer.

For example, 12345 is spoken as "douze mille ... trois cent ... quarante

cinq francs."

Whole_number_frs includes prompt statements that reference the

Numbers, the Numbers_c, the Numbers_m, the Numbers_frs, the

Numbers_cfrs, and the Numbers_mfrs voice tables.

prompts


Real_number_frs

Plays a positive or negative currency number.

For example, 1,23 is spoken as "un franc ... vingt trois ... centimes."

Voice directories for French system prompts

To run the French system prompts, there are two voice directories:

v The System voice directory contains numbers:

– Units 1 through 99

– Hundreds 100 through 900

– Thousands 1000 through 99000

– Million, milliard

– Specific System voice segmentsv The Monnaie voice directory contains numbers:

– Units from 1 Franc through 99 Francs

– Hundreds from 100 Francs through 900 Francs

– Thousands from 1000 Francs through 99000 Francs

– Million de Francs, milliard de Francs

System prompts in Brazilian Portuguese

Brazilian Portuguese is a user-defined language, so before importing the

Brazilian Portuguese samples you must define a language called Brazilian

Portuguese with the language code 213. For information on defining

additional languages, see the WebSphere Voice Response for AIX: Configuring the

System guide.

Changing the system prompts for your language

For voice response services in languages other than those described in this

book, you may need to modify the system prompts to use the correct syntax

and conventions. The information in the following sections should help you

determine whether you need to change the prompts.

The number prompts

The English language constructs numbers by concatenating words for smaller

numbers and units of measure, as appropriate. All of the number prompts

(Small_number, Whole_number, Real_number, Ordinal, and Phone) create the

number to be spoken by analyzing the input for the components and then

concatenating the voice segments that play each component.

For example, the number 81 is determined to be “eighty” and “one” and

spoken by playing “eighty” followed by the voice segment that says “one.”

The number 1204 is spoken by playing “one” followed by “thousand”

followed by “two” followed by “hundred” followed by “four.”

prompts


If the language spoken in your location does not construct numbers by

following a concatenation pattern similar to the pattern in U.S. English, you

may need to modify the number prompts to account for the differences.

The System voice directory includes only the unique numbers and the

“building block” components needed by U.S. English. These are the numbers

0 (as both “zero” and “oh”) through 31, 40, 50, 60, 70, 80, 90, and 100. The

System voice directory also includes the word “point” for use in decimal

numbers, and the units of measure “hundred,” “thousand,” “million,” and

“billion.”

Besides recording the voice segments that play these numbers in a different

language, you may need to record some additional voice segments.

All of the number prompts use Small_number to play numbers from -999

through 999.

The Date prompt

Date plays the month first. However, the convention in many other languages

is to play the day first.

Date also plays the day of the month as an ordinal number (for example,

“first,” “sixteenth,” “twenty-second”) using the Ordinal system prompt. If the

convention in your location is to play the day of the month as a cardinal

number (for example, “one,” “sixteen,” “twenty-two”), consider using

Small_number to play the day.

Date uses Small_number to express the year as the number of the decade,

followed by the number of the year within the decade. If the convention in

your location is to express the year in a different format, consider using a

system prompt such as Whole_number to play the year. You will also need to

change the logic in Date that parses and plays the input.

The Time prompt

Time accepts input in 24-hour clock time but plays the time according to a

12-hour clock. In addition, the logic in Time divides the day into two parts:

morning (AM) and afternoon-evening (PM). The convention at your location

may be to divide the day into more than two parts.

If expressions of time in your location are in 24-hour clock time, you will need

to modify Time. You will also need to modify the prompt if your day has

more (or less) than two parts. And since the System voice directory only

includes four voice segments for expressing the time of day (“AM”, “PM”,

“hours”, and “o’clock”), you may need to record some additional voice

segments. Note that Time does not play seconds, although they are required

as input.

prompts


Time uses the following 24-hour clock conventions:

v 000000 is 12 a.m.

v 240000 is 12 a.m.

v 120000 is 12 p.m.

The Currency prompt

Currency plays currency as a number of dollars followed by a number of

cents. In addition to rerecording the units of currency, you may need to

modify the prompt to play smaller units first.

Voice segments

A voice segment defines the spoken words (for example, “hello” or “good

morning”) or sounds (for example, music) available to WebSphere Voice

Response voice applications. A segment can be a single word, a sound, a

phrase, one or more sentences, or a combination of words and sounds. A

segment can also be silence.

System voice segments in several languages, including U.S. English, are

provided with WebSphere Voice Response, and listed in the WebSphere Voice

Response for AIX: Application Development using State Tables.

The same voice application can play voice segments in different languages,

without modification. The language used when the application is run in a

production environment is specified in an application profile, and you can

have one application profile for each language.

Voice directories

Voice segments are stored in voice directories. Prompts can use segments from

any voice directory.

Note: You are recommended to specify the voice directory name in state table

actions, rather than the voice directory ID, which is retained only for

compatibility. If you use don’t use the name, WebSphere Voice

Response cannot identify a voice directory as a dependent object for

export.

Voice tables

Segments can also be logically grouped in a voice table, so that you can

reference the segments using an indexing mechanism. For example, you can

use the numbers 1 through 12 to index the months of the year, and the

numbers 1 through 7 to index the days of the week. Voice tables can help you

find out what segments have been recorded and where they are stored. The

segments in a voice table can be stored in the same voice directory or in

different directories. Voice tables include a description of each voice segment

and indicate where each segment is stored.

prompts


System voice segments

The system voice segments are a group of voice segments that are delivered

with WebSphere Voice Response. They include all of the voice segments

needed by the system prompts to play numbers, letters, days of the week, and

other common terms. The system voice segments are stored in the System

voice directory and should be recorded again to match the voice used in the

voice segments that you create.

Some of the system prompts reference the system voice segments using the

Voice prompt statement. Others use the Table prompt statement. The voice

tables referenced are all system voice tables.

System voice tables

The system voice tables catalog the system voice segments in groups such as

all the letters of the alphabet, numbers, and days of the week. You can create

additional voice tables as you need them, or as you record more voice

segments, you can add them to the existing voice tables.

The names of several of the system voice tables are referenced by other

WebSphere Voice Response objects. For example, the DIGITS prompt

statement uses the Numbers Voice Table Name system parameter, which has a

default value of “Numbers”. If you decide to change the names of the system

voice tables, you need to make the corresponding changes wherever the tables

are referenced.

The Alphabet voice table

The Alphabet voice table contains the voice segments that play the letters of

the alphabet (“A” through “Z”). Alphabet is the value of the Alphabet Voice

Table Name system parameter, which is part of the Application Server

Interface parameter group.

The Alphabet Voice Table Name parameter in the Application Server

Interface group specifies the name of the voice table that the CHARACTERS

prompt statement uses to play alphabetic characters. The default value is

Alphabet.

You can create additional voice tables for the CHARACTERS prompt

statement to use, in which case, you need to set SV192 to specify the name.

The day of month voice table

The day of month voice table (Day_Of_Month) contains the voice segments

that play the days of the month as ordinal quantities (“first” through

“thirty-first”).

voice segments


The day of week voice table

The day of week voice table (Day_Of_Week) contains the voice segments that

play the days of the week (“Sunday” through “Saturday”).

The divisor voice table

The divisor voice table contains the voice segments that play the “divisor”

portion of a numeric quantity (“hundred,” “thousand,” “million,” “billion,”

“tenths,” “hundredths,” “thousandths,” “millionths,” “billionths”).

The month of year voice table

The month of year voice table (Month_Of_Year) contains the voice segments

that play the months of the year (“January” through “December”).

The noise voice table

The noise voice table contains the voice segments for a beep and a warning

tone.

The numbers voice table

The numbers voice table contains the voice segments that play the numbers

“zero” through “twenty,” and multiples of ten from “thirty” through “ninety.”

Numbers is the value of the Numbers Voice Table Name system parameter,

which is part of the Application Server Interface parameter group.

The Numbers Voice Table Name parameter in the Application Server

Interface group specifies the name of the voice table that the DIGITS prompt

statement uses to play numeric digits. The default value is Numbers.

You can create additional voice tables for the DIGITS prompt statement to use,

in which case, you need to set SV193 to specify the name.

The ordinal voice table

The ordinal voice table contains the voice segments that play numbers as

ordinal quantities (“first” through “thirty-first,” and multiples of ten from

“fortieth” through “ninetieth”).

The system messages voice table

The system messages voice table (System_Msgs) contains the voice segment

that plays the system messages. For example, “We are experiencing technical

difficulties.”

The time of day voice table

The time of day voice table (Time_Of_Day) contains the voice segments that

play time quantities (“AM,” “PM,” “O’Clock,” “hours,” “oh,” “minutes,”

“seconds”).

voice segments


The time of week voice table

The time of week voice table (Time_Of_Week) contains the voice segments that

play “yesterday,” “today,” and “tomorrow.”

The tone voice table

The tone voice table contains the voice segments for ringback tone, busyback

tone, and fast busyback tone.

3270 and custom servers

Custom servers and 3270 servers are programs that provide a bridge between

WebSphere Voice Response and data that resides outside WebSphere Voice

Response. The data can be on a remote host computer or on the same pSeries

computer workstation as your WebSphere Voice Response software. The data

can include business information held in a database, or digitized voice data.

v A custom server is a program, using C language or C++ language, that

provides an interface between data on host computers and WebSphere

Voice Response, or performs other processes, such as speech recognition

and speech synthesis, generation of fax output, or coordinated call and data

transfer.

A custom server that uses the signaling interface, a specialized library of C

subroutines, is known as a signaling process. This is used to manage an

external signaling device that controls or monitors telephony channels. For

more information, see the WebSphere Voice Response for AIX: Programming for

the Signaling Interface guide.

v A 3270 server lets you access data on remote 3270 host computers. If you

have existing 3270 host applications that retrieve data needed by your

WebSphere Voice Response applications, you can create a 3270 server to

obtain this data.

Access to remote data means that your voice applications can use this data to

perform a variety of tasks, such as:

v Read a file or database to retrieve information that a caller needs

v Maintain or manipulate files based on a caller’s request

v Obtain information from a combination of sources and business

applications on other host computers

v Call another program to perform any predefined process

v Perform calculations and return the result to the state table

v Generate business statistics based on telephony activity

v Recognize spoken words using an external speech recognition server

v Speak words created by an external text-to-speech server or sent from

another WebSphere Voice Response system

v Generate fax output.

voice segments


Both 3270 servers and custom servers must be invoked from a state table,

which controls the dialog with the caller.

3270 servers

A 3270 server consists of screen definitions and logic in the form of scripts.

3270 screen definitions

The screen definitions are images of the screens used by a host application. A

3270 server uses these screen images to interact with the host application by

sending data to the application in screen input fields, and reading the data

retrieved by the application from screen output fields. When a voice

application sends a request to a 3270 server, the 3270 server sends the

appropriate screen definitions to the host application to start the application,

provide input data, and retrieve output data. It then sends the output to the

calling voice application.

3270 scripts

The logic of a 3270 server is defined in script language, a set of statements that

instructs the server what to do. The WebSphere Voice Response for AIX: 3270

Servers reference manual contains descriptions of each WebSphere Voice

Response script language statement. The statements can accept parameters,

check certain conditions, use the screen definitions to retrieve data from the

host applications, and send the data back to your WebSphere Voice Response

voice application. A set of script language statements is commonly referred to

as a script. A 3270 server may consist of one or more scripts, depending on the

complexity of the required host interaction.

The script uses the screen definition to ensure that the correct screen is

displayed and then retrieves the data.

Scripts interface with WebSphere Voice Response state tables and other scripts

by passing input and output parameters. The input parameters receive the

data from the calling state table or script. The output parameters contain the

data to be returned to the calling state table or script.

Refer to the WebSphere Voice Response for AIX: 3270 Servers reference manual

for guidance about creating a 3270 server and for language reference

information.

Custom servers

Custom servers can be of two types:

v Applications that wait to be called by one or more state tables. This type is

the most common server, typically used for processing functions requested

from incoming calls.



v Applications that are initiated by other means under your control, such as

another program or a timed event. This type is useful for processes like

outbound calling, invoking a state table which might then call other custom

servers and state tables.

A custom server consists of a and user functions.

A main function can be system-generated from information that you provide,

or you can write it yourself using C or C++ language and the custom server

subroutines. If the main function is system-generated, you must develop user

functions to support your WebSphere Voice Response application. The main

function that the system generates can pass required information between

user functions and WebSphere Voice Response and perform other processes. If

you create the main function yourself, user functions are optional, depending

on the requirements of your custom server.

The capabilities of a custom server are limited only by the resources of the

pSeries computer and the connectivity options at your site. You can

communicate with other systems such as the IBM System/36, or the Apple

Macintosh, Hewlett Packard, or DEC personal computers, using any

communications protocol supported by the pSeries computer (refer to the AIX:

Communications Programming Concepts for RISC System/6000 manual for

information about communications protocols).

Refer to the WebSphere Voice Response for AIX: Custom Servers guide for

guidance about creating a custom server and for language reference

information.

Further information

For procedural and language reference information, see the following

reference manuals:

v WebSphere Voice Response for AIX: Application Development using State Tables

v WebSphere Voice Response for AIX: 3270 Servers

v WebSphere Voice Response for AIX: Custom Servers



further information


Chapter 5. Creating an application profile

You need to create an application profile for any state table that is to be

invoked in response to an incoming call or by another state table specifying

the profile name, or to define one or more mailboxes for an application.

Introduction

Application profiles contain the following information:

v A unique application profile name, which can be used by callers and

applications to identify the profile. You specify the name, which can be a

meaningful string of characters.

v A unique digit name, which can be used by callers and applications to

identify the profile. WebSphere Voice Response creates the digit name by

translating the application profile name into digits.

v A unique application profile ID, which is used by WebSphere Voice

Response to find the state table to answer an incoming call. You specify the

ID, making it the same as one of the following:

– The number callers to the service are going to dial. You must ensure that

called number information is sent by the switch.

– The application profile ID assigned to the channels you want to carry

calls for this applicationv A state table name and, optionally, an entry point, which are used to

invoke state tables. You specify these.

Not all state tables need an application profile: if a state table is invoked

only by other state tables, it does not need an application profile. However,

invoking a state table by specifying a profile name is also an option.

A state table can be referred to by more than one application profile (for

example, specifying different entry points, languages, or mailbox details).

v The language in which prompts are initially to be played. You can specify

different application profiles for each language, each specifying the same

state table. Because the state table uses the language specified by the

application profile, this makes your state tables potentially multilingual. To

do this, you have to provide different variants of the prompts and

translations of the voice segments, but the state table can be identical for all

languages.

v Mailbox definitions and other voice messaging information, described

further in “What mailbox information does the application profile include?”

on page 165. This information defines voice mailboxes for voice messaging

applications that require them.


An application profile is required for a state table that is to respond to

incoming calls, and is required for voice messaging. Application profiles are

not required for other state tables.

How to create an application profile

There are three methods for creating application profiles:

v Start from the Application window (see Figure 4 on page 31), which

displays the other objects in your application (see Chapter 3, “Creating and

managing application objects,” on page 27). In the Application window

click Object —> New —> Application Profile . The advantage of this

method is that the resulting application profile is created in the same

application. This is the method described in this procedure.

v In the Configuration window click Application Profiles —> File —> New.

Application profiles created in this way are put into the User application.

You then need to move them to the appropriate applications as necessary.

v Use the wvrapplprof command, as described in “wvrapplprof command”

on page 94. Application profiles created in this way are put into the User

application and can then be moved to the appropriate application, if

necessary.

Naming the profile

1. Type a unique name in the Name field. The name can be up to 50

characters long, including blanks.

As you type, you’ll see digits appearing in the Digit Name field. This is

the numeric equivalent of the name. The digit name is used by the

introduction


GetFindName action to find an application profile that matches digits

keyed in by the caller. You need to be aware that the digit name is used

in this way, to help you determine what profile names should be

allowed. You can’t have two profile names whose corresponding digit

names are the same, because each digit name must be unique.

For example, if you have a profile called AAA, you cannot have a profile

called BBB unless A and B are mapped to different keys on the telephone

keypad. (For more information, see “Entering data (multiple keys)” on

page 119.)

Specifying the initial state table for the application

2. Click the State Table pushbutton.

The system lists all validated state tables.

3. Click the appropriate state table. If you have implemented your

application as a set of state tables, click the main state table that includes

the first part of the interaction with the caller.

4. Click OK.

Specifying an entry point

If the state table you selected has only one entry point, that entry point is

listed in the Entry Point field. If the state table has more than one entry point,

the Entry Point is Undefined, in which case you must specify one.

5. Click the Entry Point pushbutton.

The system lists all defined entry points in the state table.

6. Click the entry point at which this application starts.

7. Click OK.

how to create an application profile


Changing the language (optional)

The language listed is the language identified as the language specified in the

administrator profile for the ID you used to log on. The language specifies

which language database to use. The state table can be the same for all

languages: only the application profiles, prompts, and voice segments are

language-specific.

8. Click the Language pushbutton.

The system lists all defined languages in the system.

9. Click the language in which this application runs.

10. Click OK.

Specifying subscriber classes (optional)

Subscriber classes are used for controlling the use of mailboxes.

11. Click the Subscriber Classes pushbutton.

The system lists the subscriber classes.

12. Click a subscriber class.

13. Click OK.

Entering the profile ID

14. Click File —> Save.

The system prompts you for a profile ID.

The profile ID can be up to 20 characters long and can include any

characters valid for a telephone number (the digits 0 through 9 and the

letters A, B, C, and D). WebSphere Voice Response does not accept blanks

or special characters as part of the profile ID.



The profile ID depends on how you intend the application profile to be

used:

v For a state table that is to handle incoming calls when the called

number is available, it should be the number callers are to dial to reach

this application (the called number).

v For a state table to be used to handle all incoming calls on a specific

channel, or channels, when the called number is unavailable, it should

be the channel identification, as specified in the Pack Configuration

window.

v For a state table to be used if an application profile matching the called

number or the channel identification cannot be found, it should be the

value of the System Default Application Profile parameter.

v If the application profile is not to be used to identify a state table to

handle incoming calls, you can choose any valid value to identify it.

Note: In a voice mail system, the profile ID is typically the extension

number of the subscriber, and the state table is the main state

table of the voice mail application.15. Click OK.

16. In the Application window, click View —> Refresh.

The system displays the Application Profiles folder.

17. Single-click on the folder icon to display the new Application Profile icon

inside it.

The new profile is also listed in the Application Profiles window:

Up to 250,000 application profiles can be displayed in the Application

Profiles window. If you have more this number, use the command line



tool wvrapplprof to manage the application profiles, as described in

“wvrapplprof command.”

The Application Profile window is still open, so that you can create

further application profiles or, if necessary, continue with the procedure

in “Creating mailboxes for application use” on page 168. (If you prefer,

you can add mailboxes later.)

Note: You can create a profile to use as a template, editing it and saving

it as a new profile when necessary.

Using the command line

You can perform the same functions of managing profiles and mailboxes as

the graphical user interface, by using the wvrapplprof and wvrmailbox

commands. See WebSphere Voice Response for AIX: User Interface Guide.

wvrapplprof command

Purpose

List application profiles, or view details of, add, change, delete, or copy, an

application profile. Note that this command does not allow you to modify any

of the mailbox properties or options.

Syntax

wvrapplprof

{ -c -I profile_ID -O target_profile_ID -N target_profile_name

| -d -I profile_ID [-N profile_name]

| -h

| -l {-I {all | profile_ID_spec} | -N profile_name_spec}

| -m -I profile_ID [-N profile_name] [-S state_table] [-E entry_point]

[-L language] [-C subscriber_class]

[-G active_greeting_ID]

| -n -I profile_ID -N profile_name -S state_table -E entry_point

[-L language] [-C subscriber_class]

[-B number_of_active_mailboxes ][-G active_greeting_ID]

| -v {-I profile_ID | -N profile_name}

| -?

}

Action flags

All action flags are lowercase.

-c Copy the application profile identified by -I profile_ID, to create an

identical profile identified by -O target_profile_ID.

-d Delete the application profile identified by profile_ID. The -N flag can



optionally be specified to help prevent inadvertent deletion of the

wrong profile. Both profile_ID and profile_name must match those of

the profile for it to be deleted.

-h Display help for the command

-l List all the application profiles whose profile IDs match the

profile_ID_spec, or the profile_name_spec. These specifications can

include percent (%) signs to indicate zero or more characters, or

underscore to specify a single character. To list all application profiles

on the system, use wvrapplprof -l -I all

-m Modify the application profile identified by profile_ID, as specified by

the other parameters.

-n Create a new application profile identified by profile_ID.

-v View the details of the application profile identified by profile_ID or

profile_name.

-? Display syntax of the command

Attribute flags

All attribute flags are uppercase.

-B The number of active mailboxes to be initially associated with this

application profile. Mailboxes are numbered sequentially from 1 up to

a maximum of 10. For example, if you specify -B5, mailboxes from 1

to 5 are created and activated. Mailboxes from 6 to 10 will not exist.

See “wvrmailbox command” on page 175 for more details.

-C The subscriber class to be associated with the application profile.

-E The entry point in the state table invoked by the application profile.

-G The identifier of the active greeting, a number in the range 1 to 255, to

be used by the active mailboxes associated with this application

profile.

-I The profile ID of the application profile.

-L The language in which the state table is to be run. A number in the

range 1 to 255. Here is a list of example language numbers:

1 = US English

2 = Belgian Dutch

3 = Belgian French

4 = Canadian French

5 = Danish

6 = Finnish

7 = Swedish

8 = French



9 = German

10 = Italian

11 = Netherlands Dutch

12 = Norwegian

13 = Portuguese

14 = Spanish

15 = Swiss French

16 = Swiss German

17 = UK English

18 = Icelandic

19 = Greek

20 = Turkish

101 = US English TDD

Other numbers can be created by the user. To find out what the

numbers of the installed languages are, click Languages in the

Configuration window.

-N The name of the application profile.

-O The output profile ID when copying an application profile (this is the

letter ’O’, not the digit zero).

-S The name of the state table invoked by the application profile.

Examples

Copy the application profile 123456 to create an identical profile 998877, with

a profile name "newapp":

wvrapplprof -c -I 123456 -O 998877 -N newapp

Delete the application profile 123456:

wvrapplprof -d -I 123456

List all application profiles:

wvrapplprof -l -I all

List all application profiles whose profile IDs begin 9988:

wvrapplprof -l -I 9988%

List all application profiles whose names contain Saver:

wvrapplprof -l -N %Saver%

Modify the application profile 123456, changing its language to French:

wvrapplprof -m -I 123456 -L 8



Create a new application profile 665123, specifying only the mandatory

parameters:

wvrapplprof -n -I 665123 -N accounts -S AVF_Main -E start

View the details of application profile whose name is Banking:

wvrapplprof -v -N Banking

View the details of application profile 123456:

wvrapplprof -v -I 123456





Part 2. Design topics



Chapter 6. Creating the voice output for voice applications

This chapter provides information about:

v “Overview of voice signal processing”

v “Planning your voice segments” on page 103

v “The voice segment database” on page 112

v “Creating prompts” on page 112

v “Creating multilingual applications” on page 117

Overview of voice signal processing

Normally, voice is transmitted to the human ear by means of an acoustic

wave travelling through the air at the speed of sound. A conventional analog

telephone transmits sound through a wire as an electrical signal which travels

at close to the speed of light. To do this, the acoustic signal generated by the

human vocal chords must first be converted to an electrical signal, and then

converted back to an acoustic form before it can be heard by the human ear.

These two conversions are done by a telephone mouthpiece and earpiece

respectively.

The electrical signal sent over the telephone wire for a conventional telephone

is of an analog form. That is, it is represented as a voltage which varies

continuously in a given range (for example, 0 to 1 volt) where the louder the

signal, the higher the voltage. The normal electrical signal is described as

analog because the voltage can take any value in the possible range, that is an

infinite number of possible values. As well as the signal varying continuously

in the voltage limits, an analog signal is able to vary continuously over time

with no requirement to change only at fixed time intervals.

Although analog signals are the easiest to handle in a simple telephone

system, they give rise to a number of problems if they are to be stored or

processed by computer or if they are to be sent over a long distance. Sending

an analog signal over long distances rapidly decreases the signal strength, and

can increase background noise level, both of which lead to severe quality

degradation. For these reasons, almost all modern telephone systems are

based on the concept of digital processing of voice, where the signal is

converted to a form which can be handled by standard digital computers as a

sequence of numbers. This means that voice can be stored on a standard

computer as a set of numerical values, for example, just like a spreadsheet,

and an operation such as increasing the volume of a segment is equivalent to

multiplying every number in a spreadsheet by a certain value.


To convert an analog signal into a digital form two steps are needed:

First, the analog signal is sampled at a fixed rate to break it into a sequence of

analog samples which can be handled individually. For the highest possible

audio quality (such as CD audio), the sampling rate is usually very high, that

is 44,000 times per second (44 kHz), whereas for the telephone, where a much

lower voice quality is acceptable, the sampling rate is only 8,000 times per

second (8 kHz). This is a fixed sampling rate now used by all telephone

systems of the world.

Note: The sampling rate is one factor limiting the voice quality that can be

achieved over a telephone link as it limits the frequency response (the

highest audio signal that can be carried) to one half of the sampling

rate, that is 4 kHz. The human ear can detect frequencies up to about

18 kHz; dogs and bats can detect even higher frequencies.

Second, each analog sample is converted to a number to allow it be handled

by the digital computer. For example, if the input signal has a range of 0 to 1

volt and 16-bit numbers are used to represent the digital form of each signal

sample, the digital value 0 would represent 0 volts, the digital value 65535

would represent 1 volt with a linear sliding scale for intermediate values (for

example, 32767 = 0.5 volt).

Note: Analog voltages are more usually transmitted with a center value of

zero and, say, maximum and minimum values of +0.5 volt and -0.5 volt

respectively. This corresponds with a two's complement digital

numbering system which can, for 16-bit values, range from +32767

down to -32768 with a center value of zero.

A special technique known as companding is used to reduce the number of bits

for each voice sample from 16 to 8 bits. This halves the amount of data to be

processed and stored. Companding applies a logarithmic conversion to each

sample, resulting in a signal format known as µ-law (used in North America,

Japan, and some other countries) or A-law (used in Europe, Latin America,

and some other countries). These 8-bit samples can then be stored, transmitted

and processed, and a reverse (anti-log) process applied to the signal at the

receiver to reproduce the original signal with very little loss in quality.

Note that almost without exception, T1 digital trunks are encoded as µ-law,

and E1 trunks as A-Law. Also note that µ-law and A-law signals are not

compatible, they must be converted to move from one to the other.

When WebSphere Voice Response plays voice to, or records voice from, the

telephone line, it is at the standard 8 kHz 8-bit rate (µ-law for T1, A-law for

E1). When the data is stored on disk it can be in either uncompressed form

(which is always 8 kHz 8-bit µ-law or A-law), or compressed. WebSphere Voice

overview of voice signal processing


Response applies a compression algorithm to the signal to reduce its size by a

factor of five. When compressed voice is played to the line, WebSphere Voice

Response decompresses it to reproduce the original 8 kHz, 8-bit signal.

WebSphere Voice Response uses a compression algorithm known as GSM

(used in the digital mobile phone system of the same name). This gives a very

good quality at a compression ratio of five to one, that is the data rate is

reduced to 1600 bytes per second. Other compression techniques, such as

ADPCM, are also used in the voice processing industry to reduce the size of

voice data. WebSphere Voice Response uses only the five to one GSM

compression algorithm; this is supplied as part of WebSphere Voice Response.

The advantages of using compressed voice are that you use less disk storage,

less system memory, less processing time, and less bus bandwidth. The

disadvantage of compressed voice is that the quality of voice is slightly

reduced. Depending on your application, this may or may not be a problem,

although you can take steps to ensure that the quality of compressed voice is

as high as possible (see the WebSphere Voice Response for AIX: Application

Development using State Tables reference manual).

Planning your voice segments

Step-by-step instructions on how to create voice segments are given later in

this chapter, but there are different approaches to this, so it is worthwhile

taking some time to plan what you are going to do:

1. Decide whether to store voice segments in compressed format,

uncompressed format, or both.

2. Decide on the source for your voice segments. You have the following

options:

v Record directly into WebSphere Voice Response using the telephone.

v Record high-quality voice data, by one of the following methods:

– Recording directly into WebSphere Voice Response using a

microphone and an audio adapter such as the Ultimedia Audio

Adapter in the pSeries computer

– Using a recording studio.3. If using a recording studio, decide how to transfer the voice data into the

pSeries computer. You can use either direct file transfer (recommended),

digital audio tape (DAT), or analog tape. Note that you may have to

convert the format of the voice data after transfer.

4. If using a microphone directly or transferring voice data from a recording

studio, decide how to import segments into the WebSphere Voice Response

voice segment database. There are two methods:

v The Voice Segments window (select the voice segment in the

Application window and open it)

overview of voice signal processing

Chapter 6. Creating the voice output for voice applications 103

v The Batch Voice Import command-line process (a set of command line

utilities, with a control file).

Note that you can use both the voice segment editor and the Batch Voice

Import (BVI) utility to import voice data created on another system. The voice

segment editor supports only raw unformatted voice data files, the BVI utility

supports .wav files and audio interchange file format (AIFF) files. Table 4

shows you which tool to use.

Table 4. Creating voice segments for WebSphere Voice Response

Source Tool

Ultimedia Audio

Adapter Required?

Telephone Record_Comp,

Record_Uncomp

No

Microphone Voice segment editor,

BVI utility

Yes

Tape recorder, CD player,

DAT

Voice segment editor,

BVI utility

Yes

‘Raw’ unformatted audio

file

Voice segment editor No

Windows .wav file BVI utility No

Apple Macintosh AIFF file BVI utility No

Other file format Custom server you have

written. (Not supplied with

WebSphere Voice Response)

No

Notes:

1. Although the voice segment editor can be used to import multiple voice

segments, depending on the number of voice segments, you might find it

quicker to use the BVI utility.

2. The voice segment editor and the BVI utility both support only IBM audio

adapters for direct input of voice from microphone, tape recorder, and so

on. For PCI pSeries computers, you might or might not have the audio

function available on the planar (there is currently no PCI plug-in audio

board).

If you do not have audio on your PCI pSeries computer, you can record

voice segments in one of the following ways:

v Using the telephone

v Using another pSeries computer with a Ultimedia Audio Adapter

installed

planning your voice segments


v Using a separate personal computer with an industry audio adapter,

and import standard audio files (such as .wav) using Batch Voice

Import.3. To import audio files from other computers, use either the TCP/IP file

transfer program (FTP) over a LAN or other network, or use a removable

storage device, such as a tape. You might find tape more convenient to

move bulk voice data to your pSeries computer.

4. For top-quality audio segments, we recommend that you record your voice

segments in a professional recording studio, then either import a digital

file (.wav or .aiff) or use digital audio tape.

Compression

When you store a voice segment in the database, you can save it in

compressed format, uncompressed format, or both. WebSphere Voice Response

uses a compression algorithm derived from the Groupe Speciale Mobile

(GSM) digital mobile phone system, which gives high-quality voice suitable

for telephony applications. Saving voice segments in a compressed format

saves disk space and bus bandwidth (the compression ratio is 5:1), but tends

to cause a slight loss of sound quality. If you compress a voice segment, then

uncompress it, the sound quality of the resulting voice segment will not be

equivalent to that of the original. However you can support more channels

(more simultaneous calls) by using compressed voice.

If, on the other hand, it is important to preserve the highest possible sound

quality, choose uncompressed format.

You can mix compressed and uncompressed voice segments in the same

application using the System : PlayPrompt voice compression type system

variable (SV182) to specify the compression type (or the System : Voice

segment compression type system variable (SV50) if you are using the

PlayVoiceSegment action). You might, for example, use uncompressed

segments in the opening dialog and most frequently used menus, to give a

good impression, but use compressed segments for less frequently used, or

less essential, information.

Note: If you use uncompressed voice segments with the PlayVoiceSegment

action, this produces more network traffic when your WebSphere Voice

Response system is part of a single system image. This is because the

PlayVoiceSegment action has to retrieve the segment from the database

every time it plays the segment.

Recording voice segments over the telephone

This does not always give the highest quality sound, and should be used for

prototyping and testing rather than for production applications. To record via

the telephone you use the Record_Comp or the Record_Uncomp voice

applications supplied with the base WebSphere Voice Response system.



The segments recorded using Record_Comp are stored by default as

compressed voice segments. The segments recorded using Record_Uncomp are

stored by default as uncompressed voice segments.

The files for the applications are automatically imported into a directory at

installation time, but, if they get corrupted by mistake, you can reimport them

from /usr/lpp/dirTalk/sw/samples/BaseData.imp.

Before anyone can use either application, you must create an application

profile that allows people to access it over the telephone. In the profile,

specify the language in which you intend to record segments. Otherwise, the

voice segments are stored in the wrong database. You can create an

application profile for each application for each language you intend to use.

In addition, you will probably want to create additional voice directories.

Otherwise, all of the voice segments can only be stored in the system

directory. The WebSphere Voice Response for AIX: Application Development using

State Tables describes how to create voice directories.

High-quality voice data

Sampling rate

All voice segments stored in the WebSphere Voice Response database use an 8

kHz sampling rate, consistent with standards used for telephony transmission.

The Voice Segment window lets you digitally input data from other sources,

but converts it to 8 kHz if necessary. There is no advantage to using sampling

rates other than 8 kHz when recording new voice segments using the Voice

Segment window. Similarly, the command line utilities, bvi_aiff and bvi_wav,

convert any sampling rate greater than 8 kHz to the required 8 kHz rate.

Source format

Use the best-quality source for your voice segments and import these into

WebSphere Voice Response in 16-bit PCM (linear) format at an 8 kHz

sampling rate. To do this, use studio-quality DAT tape through the line-in of

the Ultimedia adapter with the Ultimedia format set to 16-bit PCM.

Alternatively, you may already have 16-bit PCM voice segments as files that

can be imported directly into the Voice Segment Editor. The editor can change

sampling rates are required, although slight distortion will usually result from

a change in sampling rate. You should therefore always use an 8 kHz

sampling rate for imported voice data if possible.

Dynamic range

When using the voice segment editor or the batch voice input utility to record

voice segments via the Ultimedia adapter with an audio source connected to

the its line input, you may find that the audio signal is relatively small

compared to the available ‘dynamic range’. 16-bit PCM allows signal levels of



up to 32K, whereas typical input signals from the Ultimedia adapter may

have an amplitude of around 2K. When using 5:1 compression, the best

quality is obtained if the input signal occupies as much of the 32K range as

possible without signal peaks exceeding the available limits. This can be done

with an external preamplifier or by using the MAXIMIZE option of the voice

segment editor or batch voice input utility which digitally scales the input

signal to occupy 90% of the full range.

Note that the maximize button of the voice segment editor is only enabled

when operating in 16-bit PCM mode.

Filters

When you record a high-quality input signal for use over the telephone, it is

necessary to filter out all frequencies above 4 kHz to allow transmission at the

digital 8 kHz rate. (The voice segment editor does this automatically when it

stores the segment in the database.) Loss of these high frequencies can make

the signal sound relatively dull. You can improve this by using the Boost

button of the voice segment editor before saving the recorded segment. This

increases the volume of frequencies in the range 1.5 kHz to 4 kHz by 2 dB,

and decreases the volume of frequencies in the range 500 Hz to 1.5 kHz by 2

dB. An identical effect can be achieved with the “Boost” option of the batch

voice input utility where the boost amount can be set to any value.

Note that the boost button of the voice segment editor is only enabled when

operating in 16-bit PCM mode.

Recording directly using a microphone

A direct microphone input can provide excellent quality input. However, the

pSeries computer must be within 10-15 feet (maximum) of the microphone in

order to minimize electrical noise pick-up. This may be difficult to achieve in

a studio environment because fan and disk noise prohibit the pSeries

computer from being in the same room as the microphone.

Using a recording studio

For the best results when recording voice segments, keep to the following

rules:

v It is recommended that a professional recording studio with an anechoic

chamber be used to record the audio if you want segments to be of the

highest possible quality. It is important to achieve a good acoustic ambience

(a normal office has too much reverberation).

v Keep background noise to an absolute minimum. Even low-level noise

generated by cooling fans in machines such as personal computers, should

be avoided.



v If you are editing segments in the studio, do not put absolute silence

between segments, as this sounds unnatural. Instead, insert room-tone

silence breaks (background studio ambient sound).

v Half a second of silence at the beginning and end of each segment is

recommended.

v Record segments as a continuous stream of audio with a silence gap

between consecutive segments. The recommended silence gap is five

seconds, because this allows the batch voice import utility to distinguish the

silence gaps between segments from the natural gaps that occur within

segments.

v If a mistake is made during the recording of a segment, just stop, wait for

five seconds (or whatever inter-segment gap you have decided to use) and

then re-record the segment. Bad segments can be removed by the voice

segment editor or the batch voice import utility.

If you are working with a studio which has reasonably sophisticated audio

processing capabilities, it is wise to apply the audio boost function at source

rather than with batch voice import utility. The best frequency-shaping

function to apply is defined in the ITU P-Series Blue Book (Volume 5 1988) in

Supplement No. 10 (P332). This is the preferred response for a telephone

microphone as determined by user trials, and can be applied to flat-spectrum

audio, achieving the same results as if the voice was being spoken through a

telephone.

The frequency shaping function recommended by the ITU boosts the treble

and cuts the bass in a signal in order to restore some of the brightness lost

when a full-bandwidth audio signal is low-pass filtered at 3400 Hz prior to

sampling at 8 kHz and is similar to the BOOST option of the voice segment

editor or the batch voice import utility. Be sure that the shaping is not done

both in the studio and by one or other of WebSphere Voice Response’s voice

utilities.

The ITU-recommended frequency response characteristic is as follows:

v 0 dB reference at 1kHz

v Under 1kHz, 4 dB/octave roll-off to 200 Hz

v Below 200 Hz, 8 dB/octave roll-off

v Above 1kHz, smooth increase to +7 dB peak at 2600 Hz.

v Sharp cutoff at 3.4kHz



Responses for spot frequencies are shown in Table 5 on page 109.

Table 5. Responses for spot frequencies

Frequency Response attenuated or amplified by

50 Hz -20 dB

100 Hz -12 dB

200 Hz -4.5 dB

400 Hz -2 dB

800 Hz -1 dB

1000 Hz 0 dB

1500 Hz +2.5 dB

2000 Hz +6 dB

2500 Hz +7 dB

3000 Hz +6 dB

3400 Hz 0 dB

To get the best results when recording data for use as background music:

v Don’t use the BOOST option of the voice segment editor or the batch voice

import utility

v Filter the signal using a graphic equalizer before the it reaches the

Ultimedia adapter.

Transferring the prerecorded data to WebSphere Voice Response

v Direct transfer from the studio

v Diskette or other removable storage device

v Digital Audio Tape (DAT)

v Analog Tape

v Microphone

Direct transfer from the studio

Most recording studios use specialized voice processing systems for

processing audio data. The best possible method for moving this data from

the studio system to the WebSphere Voice Response system is direct file

transfer across a network (for example, using TCP/IP FTP). If you transfer

digital data directly, when using the batch voice import utility, you should

bypass the bvi_rec step and go straight to bvi_seg.

Diskette or other removable storage device

This gives identical results to direct file transfer as the movement of data is

100% digital. If the recording studio uses Apple Macintosh based



sound-processing applications, you can use Apple’s system extension,

Macintosh PC Exchange, or an equivalent product, to format a Macintosh

diskette so that it can be read by a pSeries computer. Write a diskette in a

DOS format and use the AIX supplied utility ‘dosread’ to read it.

You can fit about two minutes of 8 kHz sampled voice on a 2 MB diskette.

Digital audio tape (DAT)

This is a good way of moving digitally-recorded audio data in bulk from a

studio to the pSeries computer. However, there is currently no method of

taking a digital output from a DAT player and transferring it directly into the

pSeries computer without translating to analog and back again, using the

Ultimedia Audio Adapter. The digital-to-analog and analog-to-digital

conversions always introduce some low-level noise and distortion, but these

are usually negligible for a system with optimum input level.

Analog tape

This is not recommended, because analog tape, even of the highest quality on

the best audio equipment, can introduce low-level noise that can cause voice

quality problems especially with compressed data. The compression algorithm

operates best with a noise-free input signal. However, if you have no

alternative, write a tape in AIX format and then copy data directly from it into

the AIX file system.

Converting voice data transferred from non-AIX computer systems

You can transfer audio data from other systems provided that you can get the

audio data into the AIX file system. The audio data can be in one of the

following formats:

“Raw” (unformatted) data

The data must be stored in the file in the following format:

v Single channel

v Linearly encoded PCM 16-bit samples (two’s complement)

v 8 kHz sampling rate

v Big-endian format (ms byte before ls byte)

v No header

AIFF (Macintosh audio interchange file format)

The bvi_aiff utility converts files stored in AIFF format into the required

format for processing by bvi_seg. It takes an input file specified as a

parameter and generates a file whose name is specified in the bvi.control file

by the VOICE_FILE_NAME parameter. The AIFF file must be written in the

following format:

v Single channel



v 16-bit samples (two’s complement)

v Sample rate equal to or greater than 8 kHz (bvi_aiff will convert to 8 kHz)

WAV (Microsoft Windows format)

The bvi_wav utility converts files stored in Microsoft WAV format (files with

an extension of .wav) into the required format for processing by bvi_seg. It

takes an input file specified as a parameter and generates a file whose name is

specified in the bvi.control file using the VOICE_FILE_NAME parameter. The

WAV file must be written in the following format:

v Single channel

v 16-bit samples (two’s complement)

v Sample rate equal to or greater than 8 kHz (bvi_wav will convert to 8 kHz)

Saving voice segments

The WebSphere Voice Response database only allows voice data to be stored

at an 8 kHz sampling rate in one of two formats:

v 8-bit uncompressed A-law or µ-law (depending on your country).

v 5:1 compressed.

Note: A-law and µ-law voice cannot be mixed on the same system.

It is not necessary to manually convert 8 kHz 16-bit PCM data to your default

(A-law or µ-law) when saving with the Voice Segment window. This is done

automatically when you save a segment as either uncompressed or

compressed. Note that converting from 16-bit PCM to 8-bit A-law or µ-law

and back will degrade voice quality, as will compressing and uncompressing

voice data. To save voice data for future use, always save it in 16-bit mode to

an AIX file using the voice segment editor Export function. Don’t just save it

in the WebSphere Voice Response voice segment database.

To find out more about the batch voice import process, see the WebSphere

Voice Response for AIX: Application Development using State Tables. If you have

only a few voice segments to record, use the Voice Segments window (also

documented in the WebSphere Voice Response for AIX: Application Development

using State Tables).

The batch voice import utilities or the Voice Segments window?

If you only need to create a few voice segments, you may find the Voice

Segments window convenient, but if you are dealing with many voice

segments, you will probably find it worthwhile to use the batch voice import

process. Both processes allow you a choice of different input media.



The voice segment database

There is a voice segment database

for each language. By creating an

application profile for each

language, you can make the same

application work with different

languages.

Each voice segment has:

v A segment ID

v A description

v Digitized audio data in either

compressed or uncompressed

format, or both.

Each voice segment is stored in a

voice directory, and can also be

referenced by one or more voice

tables.

A voice directory has:

v A name

v A voice directory ID (retained

only for compatibility with

earlier releases)

The voice directory must exist

before you create the voice

segment.

German WebSphere Voice Response voice segment database

French voice segment databaseWebSphere Voice Response

Voice Directory

U.S. English voice segment databaseWebSphere Voice Response

Voice directory

Voicesegment

Voicetable

Voicesegment

System voicedirectory

Voice tables are optional, and you can create them at any time. Voice

tables are particularly useful if you have applications that use voice

segments which can be referenced using an index value, such as the

spoken words for the months of the year. A voice table has:

v A name

v A description

Creating prompts

The set of prompts that are used by a particular state table are grouped in a

prompt directory. All prompts used by a state table must be in the same prompt

directory. Different state tables can use the same prompt directory. If a state

table uses its own prompt directory, you can use the system prompts by

creating new prompts that call the system prompts (using the SYSPROMPT

prompt statement).

Note: System prompts cannot be exported as a dependency of another

application object (for example, a state table), so we recommend that

you don’t use the System_Macros prompt directory for application

specific, or user, prompts. You can distribute changes to system

prompts only by explicitly exporting them and importing them to

another system.

the voice segment database


If you want to store the prompts in a new, rather than an existing, prompt

directory, the first step is to create the new prompt directory. Then, you create

the prompts by defining new prompts, copying existing prompts, or

importing prompts. You can edit the prompt statements that comprise the

prompts that you create.

About creating prompt directories

Before you can save a prompt, the prompt directory to which it belongs must

exist. A prompt directory is referred to by a prompt directory name. You must

specify a default compression type for playing the voice segments included in

the directory.

Overriding the default compression type

You can override the default compression type by setting the System :

PlayPrompt voice compression type system variable (SV182) before the

PlayPrompt action. A value of 0 specifies that the clear channel version of the

segments is to be played; a value of 2 specifies that the compressed version is

to be played; and a value of -1 indicates that the default compression type is

to be used.

A prompt can play audio names and greetings.

About defining prompts

Prompts are constructed using the prompt statements described in the

WebSphere Voice Response for AIX: Application Development using State Tables. A

prompt statement can use any of the following elements to define what a

caller will hear:

v Voice segments (stored in voice directories or voice tables)

v Greetings

v Audio names

v Other prompts

v Parameters passed from the calling state table

v System variables or local variables

v Conditional tests that determine what should happen in different cases

For examples of prompts, look at the system prompts that are delivered with

WebSphere Voice Response in the System prompt directory. For more

information about the system prompts, see “System prompts” on page 75.

Default and language-specific prompts

Each new prompt that you create is called a default prompt. A default prompt

is language-independent. If the logic of a particular prompt does not change

from one language to another, the same prompt can be used for all languages.

You will need to record the segments for all languages that reference the

prompt, but you will not need to alter the prompt itself.

creating prompts


Only one language can be active at any one point during the execution of a

voice application. The active language is identified by the value in

the System : Current language system variable (SV39). When the prompt

references a voice segment, it uses the segment ID and voice directory name

to locate the required segment in the active language. As long as the ID for a

particular voice segment is not changed when the segment is translated into

other languages, the default prompt will find the segment it needs to play.

In some cases, the logic of a prompt may need to be altered for a specific

language. For example, the system prompt that speaks the date (Date) uses

U.S. English syntax to play the month, followed by the day spoken as an

ordinal quantity, followed by the year. In other languages, the date syntax

may be different. For example, the German version of Date will need to play

the day, followed by the month, followed by the year. In such cases, you will

need to create a language-specific version of the default prompt. The

language-specific prompt for a particular language will be used instead of the

default prompt when that language is the active language for the currently

executing voice application. The inputs to the language-specific and default

versions of a prompt, if any, must match exactly in number and type. Refer to

“Using languages other than U.S. English” on page 114 for information about

modifying the system prompts for other languages.

All default and corresponding language-specific prompts for a state table are

stored in the same prompt directory. When a state table encounters a

PlayPrompt action, the system searches the specified prompt directory for the

prompt to be played. If a language-specific version of the prompt exists for

the active language, that version is played; otherwise, the default version of

the prompt is played.

Using languages other than U.S. English

When it has been installed, WebSphere Voice Response is ready to work in

U.S. English. If you want to use other languages in your voice response

services, you need to:

1. Install the language environment (locale) for each required language on

your system. This is a system-level activity performed on AIX (see the

Installation Guide).

2. Install the optional fileset that contains the system prompts and voice

segments for the languages you need (see the WebSphere Voice Response for

AIX: Installation guide). If the system prompts are not supplied in the

languages you require, you may have to select one of the supplied

languages, and then make modifications to suit your language (see

“Modifying the system prompts for other languages” on page 115).

3. Establish a database for the new language (see the WebSphere Voice

Response for AIX: Configuring the System guide)

creating prompts


4. If your language was supplied in an optional fileset, import the

appropriate language.imp file (for example, BelgianDutch.imp) from the

/usr/lpp/dirTalk/sw/samples directory.

Ensure that objects in the System_Macros prompt directory are replaced,

not merged, when you install them.

You now have the following:

v The System_Macros prompt directory containing the default prompts

along with the derived language-specific prompts

v The System voice directory containing language-specific voice segments

v Language-specific voice tables

Modifying the system prompts for other languages

The prompts that are supplied in the System prompt directory are described

in “System prompts” on page 75. To modify the system prompts, you must be

familiar with programming logic and with the prompt statements described in

the WebSphere Voice Response for AIX: Application Development using State Tables.

To modify the system prompts, you need to perform the following tasks:

1. Review the system prompts stored in the *System_Macros prompt

directory.

2. List the prompts to be modified and the changes you need to make.

3. Review the voice segments in the System voice directory.

4. List the voice segments to be recorded.

5. List any additional voice segments you plan to record.

6. Review the segments that are grouped in the following voice tables,

which are used by the system prompts:

v Numbers

v Divisor

v Ordinal

v Time_Of_Day

v Month_Of_Year 7. Make a list of the voice segments that will need to be changed or added

to each of the voice tables. Make sure all of these voice segments are on

the list you made in Step 5.

8. Record the voice segments for the system prompts in the new language

and also record any new segments (see the WebSphere Voice Response for

AIX: Application Development using State Tables).

9. Modify the system voice tables to include any new voice segments (see

the WebSphere Voice Response for AIX: Application Development using State

Tables).

creating prompts


10. Edit the system prompts to play voice segments using the correct syntax

(see the WebSphere Voice Response for AIX: Application Development using

State Tables).

Refer to “Creating multilingual applications” on page 117 for information

about using the system prompts that you have created for the new language.

Modifying the system voice tables

Some of the system prompts invoke voice segments using the Table prompt

statement. One of the parameters of the Table statement identifies the table in

which the required segments are cataloged. For example, Small_number calls

the voice segments that play numbers using the Table statement, with the

Numbers table as a parameter. If you record a new number for Small_number

to play and do not add it to the Numbers table, Small_number fails when it

tries to play it. In this case, you must either add the new voice segment to the

Numbers table or edit Small_number so that it no longer uses the Table

statement.

The other system prompts invoke voice segments using the Voice prompt

statement. One of the parameters of the Voice statement identifies the

directory (in this case, the System voice directory) in which the required

segments are stored. As long as the voice segments you record are stored in

the System voice directory for the language specified in the application

profile, these prompts will be able to locate them.

If you create additional voice segments for use by one of the prompts that

includes a Table statement, either catalog it in the voice table that is the

parameter for the statement, or edit the prompt to use the Voice statement

instead. The WebSphere Voice Response for AIX: Application Development using

State Tables explains how to edit a prompt and how to modify a voice table:

open the voice table you need to modify, then follow the procedure to add

voice segments to the table.

Editing the system prompts

In some languages, the logic of a system prompt may need to be altered, for

example, the Date system prompt which plays the date using U.S. English

syntax. Before you start editing the system prompts, make sure you are

familiar with the information in “System prompts” on page 75.

Some of the system prompts rely on other system prompts, so make sure you

edit the prompts in the following order:

1. Small_number

2. Whole_number

3. Real_number

4. Ordinal

creating prompts


5. Date

6. Time

7. Currency

The Phone prompt does not rely on any other prompts.

Refer to the procedures in the WebSphere Voice Response for AIX: Application

Development using State Tables for instructions about defining a

language-specific prompt.

Creating multilingual applications

You can create a voice database for each language, dialect, or regional accent

you want to use for voice output. You can even use different voice databases

for different voices speaking the same voice segments in the same language.

You also create a voice database for each TDD language to be used for

telephony devices for the deaf.

Using application profiles

Typically, multilingual applications are set up by defining a different

application profile for each language. Thus, callers dial different numbers

according to the language to be used, or you can call the state table by

application profile, depending on a choice that the caller has made. Each

profile refers to the same state table, but a different language is specified. The

Application : Language system variable (SV142) contains the code for the

language specified in the application profile. The System : Current language

system variable (SV39) is also initially set to this value.

Using the System: Current language system variable

If the language defined for the application profile does not specify the

required language, you can change the value of the System : Current

language system variable (SV39), using the ReceiveData, AssignData, GetKey,

or GetData state table actions in your voice application.

For example, your voice application can prompt callers to press a key to

request a specific language (“Por español, prensa el uno... ...for English, press

two... ...pour Français, appuyez sur trois... ...Für Deutsch, bitte drücken Sie auf

die Vier.”) Then set the System : Current language system variable (SV39) to

the code for the language chosen (the codes are listed in the Languages

window (Configuration —> Languages). The value of SV39 specifies which

language database is to be used for prompts.

creating prompts


creating multilingual applications


Chapter 7. Handling key input from callers

WebSphere Voice Response supports up to 16 keys on the telephone keypad:

A, B, C, and D in addition to the twelve normal keys (1 through 9, *, 0, and

#). Callers can press single keys (for example, to select options) or multiple

keys (to enter data such as personal identification numbers).

Making a selection (single key)

Use the GetKey action to get a single key press from the caller.

Entering data (multiple keys)

Use the GetData action to get a sequence of key presses from the caller. To

indicate that the caller has finished entering data, the last key pressed must be

the key specified by the Enter Key system parameter in the Application Server

Interface parameter group. The default is # (pound or hash).

The GetFindName action allows you retrieve an application profile whose

digit name matches a sequence of key presses from the caller. The digit name

is the numeric equivalent of the application profile ID. Again, the Enter Key is

used to indicate the end of the data entry, and the Stop Key allows the caller

to cancel the entry and start again. The default value for the Stop Key system

parameter is * (star).

The GetFindData action allows you to pass a sequence of key presses from the

caller to a custom server or 3270 server, to retrieve information. Again, the

Enter Key is used to indicate the end of the data entry, and the Stop Key

allows the caller to cancel the entry and start again. The default value for the

Stop Key system parameter is * (star).

Alphabetic to numeric key mapping

Alphabetic characters are assigned to the keys on the keypad, so that callers

can enter alphabetic data if necessary. You can change the character-to-key

assignments using system parameters in the Key Signals parameter group.

Pressing keys while voice data is being played

The PlayPrompt action can be interruptible or force played. Force played means

the prompt is always played through to the end. If you do not specify force

play, the caller can interrupt the prompt by pressing a DTMF key. You can

specify that the caller can use any DTMF key to interrupt the prompt, or that

they can use only one of a set of keys that you define.


The caller can also interrupt the prompt by speaking. For more information on

this, see “Voice interrupt detection” on page 122.

The PlayVoiceFromHost action can also be interruptible or force played. In

addition, you can specify that it can either be interrupted by any key or only

by the Pause and Stop Keys.

During the PlayAudioName, PlayUserGreeting, PlayVoiceSegment, and

PlayVoiceMessage, the following keys are available to the caller: Forward Key

(default value 9), Pause Key (default value 8), Reverse Key (default value 7)

and Stop Key (default value *). These values can be changed by resetting the

system parameters in the Application Server Interface parameter group.

pressing keys while voice data is being played


Chapter 8. Handling spoken input from callers

Speech recognition means that you can write voice applications that take action

based on spoken input from the caller. You can implement speech recognition

in your applications by sending commands from the state table to a custom

server that interfaces with a speech recognizer. As an example, the custom

server could be a DVT_Client—see “Speech recognition with distributed voice

technologies” below.

Speech recognition with distributed voice technologies

The distributed voice technologies (DVT) subsystem provides support for

communication with speech recognition technologies. The DVT subsystem

includes a fully functional custom server that passes data from your state

table to a speech recognizer.

Using the DVT subsystem, WebSphere Voice Response can be integrated with

TDM-based DSP or software-based speech recognition products. For more

information, ask your IBM representative for the WebSphere Voice Response for

AIX: Distributed Voice Technologies Integrator’s Guide.

Barge-in, voice interrupt detection, and echo cancellation

When handling spoken input, it is important to understand three concepts:

v “Barge-in”

v “Voice interrupt detection” on page 122

v “Echo cancellation” on page 123

Barge-in

Barge-in, properly referred to as full-duplex barge-in, allows voice data to be

recorded from the voice channel at the same time as voice data is being

played in the opposite direction; voice data is going both ways at the same

time, just as it is when two people are having a conversation and both are

speaking at once. The most important use of barge-in is to allow spoken input

to be sent to a speech recognizer while a prompt is being played.


Essentially, to implement barge-in, you start a recognition session before

beginning to play the prompt. You can use barge-in either with or without

voice interrupt detection, depending on the needs of your application. With

voice interrupt detection, the prompt stops as soon as the caller speaks, even

if the word is not in the expected vocabulary. Without voice interrupt

detection, the prompt continues until a custom server event happens (for

example, when an utterance is recognized) or to the end.

Voice interrupt detection

Voice interrupt detection allows a caller to interrupt the playing of a prompt or

a voice segment by speaking. This can be used in an application with speech

recognition or it can be used on its own.

If callers are using speech recognition rather than key input to interact with

the voice application, voice interrupt detection is particularly useful. It can,

however be used independently of speech recognition; you do not have to

implement speech recognition to enable voice interrupt detection. And, of

course, you can use voice interrupt detection, and speech recognition, in any

combination along with DTMF-key input.

With DTMF-keys, the application can allow callers to interrupt prompts or

voice segments while they are being played. On the PlayPrompt and

PlayVoiceFromHost actions, if you don’t select Force Play when you define

the action, the caller can interrupt. On PlayAudioName, PlayUserGreeting,

PlayVoiceMessage and PlayVoiceSegment the caller can always interrupt.

Time

Prompt is playing

Voice data from the calleris being sent to aspeech recognizer

Figure 8. Barge-in

Time

Prompt is playing

An utterance from thecaller stops the prompt

Figure 9. Voice interrupt detection

barge-in, voice interrupt detection, and echo cancellation


In the same way, if you enable voice interrupt detection in an application, the

caller can interrupt without pressing a DTMF-key, but simply by speaking.

The caller can say anything: it does not have to be a recognizable word. Be

aware that one of the drawbacks of using voice interrupt detection is that not

all sounds picked up by the caller’s phone are intended to be interruptions. In

noisy environments it can be difficult to use an application that has voice

interrupt detection enabled.

To turn on voice interrupt detection, set the System : Voice interrupt

detection On/Off system variable (SV217) to 1. To turn it off (the default), set

SV217 to 0.

For more information about voice interrupt detection, see Appendix B, “Voice

interrupt detection: technical information,” on page 323.

Using voice interrupt detection with speech recognition

You need to pay careful attention to the way you implement applications,

because, if you are not using barge-in, the word detected as the interrupt is

thrown away and is not passed on to the recognizer. Without barge-in, you

can let the caller stop the prompt and then start speaking the words to be

recognized. Start the recognition session after the prompt has been

interrupted. Play a pacing tone to let the caller know when the recognition

session is ready to accept input.

In most applications, however, callers find this unnatural: they expect to be

able to speak-ahead, in the same way that they can key-ahead in a key-based

application, with the word they utter during the prompt being passed on to

the recognizer. Voice interrupt detection is probably better used with barge-in,

in speech recognition applications.

Echo cancellation

Both barge-in and voice interrupt detection are enhanced by echo cancellation,

which filters out any echo of the prompt from the spoken input. Echo

cancellation is available to any custom server that records voice data from the

line: it is not directly available to a state table.

Time

Prompt is playing

An utterance from thecaller stops the prompt,but is then discarded

Voice data can now besent to a speech recognizer

Figure 10. Voice interrupt detection with speech recognition


Chapter 8. Handling spoken input from callers 123

The echo cancellation available for use with Digital Trunk Telephony Adapters

(DTTAs) is implemented in a slightly different way to that available for use

with Digital Trunk Extended Adapters (DTXAs), and is more efficient. (The

improved echo cancellation for DTTAs is not available with versions of

WebSphere Voice Response for AIX prior to Version 4.2 or for use with

DTXAs.)

Calibration

Before using echo cancellation in a state table, you need to instruct WebSphere

Voice Response to calibrate the echo canceller for the line being used. Unless

you are using the improved echo cancellation for DTTAs, each time the

characteristics of the line change, for example, when the call is transferred, the

echo canceller must be recalibrated. The enhanced echo cancellation for

DTTAs continues to monitor and reduce the echo when any prompt or voice

segment is played. It is therefore particularly suitable for situations where the

echo path is likely to change, for example when a call is transferred or when

call tromboning is used.

The calibration is requested by the state table, before invoking a custom server

to begin recording voice data. Set the System : Echo Cancellation :

Calibration system variable (SV231) to 1 and then use a PlayPrompt or

PlayVoiceFromHost action to force play some uncompressed voice data. The

outcome of the calibration is indicated by the value of SV231 following the

Play action; if the value is 2, the calibration was successful. If calibration was

unsuccessful, echo cancellation will not be used.

Initial calibration of the improved echo cancellation for DTTAs is performed

in the same way as the standard echo cancellation for DTXAs, but provided

that the duration of the uncompressed voice data used for calibration is at

least 0.5 seconds, the calibration will always be successful. With DTTAs, echo

cancellation is recalibrated automatically, at every opportunity, as the call

proceeds.

Using echo cancellation with speech recognition

Start the recognition by invoking a custom server using the SendData action.

If the custom server was designed to use echo cancellation, and the calibration

was successful, echo cancellation will be used.



Writing a custom server to handle speech recognition

If none of the speech recognition implementations offered with WebSphere

Voice Response satisfy your requirements, you can write your own custom

server to pass voice data to an external voice services system for speech

recognition. The custom server subroutines for voice handling are

documented in the reference manual.

Contact your IBM representative for more information if you plan to

implement your own custom server for speech recognition.

SendData DVT_Start_Recognition

ReceiveData DVT_Start_RecognitionStart a speech recognition

session

EvaluateData

If SV231 = 2, calibrationwas successful. Echo

cancellation will be usedduring speech recognition

if calibrationwas successful

PlayPrompt

Force Play someuncompressed data: thiscan be a normal prompt

AssignDataSV231 = 1

OpenHostServerLink with DVT_Client2

PlayPromptFurther prompts need not

be force-played oruncompressed

Figure 11. Calibrating the echo canceller

writing a custom server to handle speech recognition

Chapter 8. Handling spoken input from callers 125

DataCommunications

Network

InformationCaller

TelephoneNetwork

VoiceProcessing

WebSphereVoice

Response LocalArea

Network

LocalArea

Network

SpeechRecognition

Server

State Table

CustomServer

pSeries

SpeechRecognition

ServerSpeech

RecognitionServer

Figure 12. External speech recognition overview

writing a custom server to handle speech recognition


Chapter 9. Accessing data with a 3270 or custom server

To invoke a server to access data, you must set up one or more WebSphere

Voice Response state tables to do the following:

v Initiate dialog with your customer.

v Receive and control customer requests.

v Activate the server when required, passing request parameters as necessary.

v Log system events or detail records as needed.

v Activate an appropriate response based on the results achieved by the

server.

The state table actions used to access data are:

v OpenHostServerLink: Establishes a connection to a server.

v GetFindData: Requests a list of items that match or begin with a specified

generic key.

Caller

LocalDatabase

TelephoneNetwork

VoiceProcessing

DataCommunications

Network

LocalArea

Network

Sun

HP

Macintosh

IBM PersonalComputer

CommunicationsFacility

3270Server

CustomServer

TCP/IPOSI

SNAASYNC

APPCX.25EthernetToken ring

Caller

TelephoneNetwork Caller

TelephoneNetwork

Caller

TelephoneNetwork

Caller

TelephoneNetwork

System/390

WebSphereVoice

Response

pSeries

Figure 13. Accessing data using custom servers and 3270 servers (for example, a system/390

server)


v SendData: Sends request data to the server.

v ReceiveData: Receives responses from the server.

v CloseServerHostLink: Closes the session and disconnects the link to the

server.

Refer to the WebSphere Voice Response for AIX: Application Development using

State Tables reference manual for information about these actions.

Sample 3270 and custom servers

WebSphere Voice Response includes many custom servers, which perform

services for state tables. The following are supplied in object code only:

v DVT_Client: to send requests to speech recognition servers

v CallPath_SigProc: to send requests to CallPath Server

The following are supplied in source form as well, so you can use them as

examples:

v SpeechServer: to send requests to speech recognition servers

v CustomServerSample.

In addition, the 3270ServerSample is also supplied in source form.

CustomServerSample

The application called CustomServerSample contains two sample custom

servers. Before you can use CustomServerSample you must:

1. Import the CustomServerSample.imp file. The import file is located in the


2. Build the custom servers and install them (see the WebSphere Voice Response

for AIX: Custom Servers reference manual).

3. Create an application profile for the SrvrSamp_Main state table with Start

as the entry point (see Chapter 5, “Creating an application profile,” on

page 89).

The CustomServerSample application comprises six state tables and two

custom servers that perform the following activities:

1. The state table SrvrSamp_Main greets a caller, then prompts the caller for

the function to be performed. The caller can add scheduled wakeup calls,

list scheduled wakeup calls, update scheduled wakeup calls, and delete

scheduled wakeup calls.

2. From the caller’s input, the SrvrSamp_Main state table then invokes the

SrvrSamp_Write, SrvrSamp_Read, SrvrSamp_Update, or

SrvrSamp_Delete state table to perform the appropriate function. The

caller is prompted to input the phone number to make the wakeup call,


the time to call (in 24 hour format), and an indication of whether this is a

one-time call or a daily call. The CS_Request_Call custom server is used

to manipulate the corresponding database, based on the user inputs.

3. Whenever the database is modified, the CS_Wakeup_Call custom server

checks it to determine the time of the next call. When it is time to make

the wakeup call, CS_Wakeup_Call opens a channel process link and

requests that the SrvrSamp_Wakeup state table be executed, which will

make the actual wakeup call. The SrvrSamp_Wakeup state table will play

a wakeup greeting, then prompt the called party whether or not to use the

snooze feature to call again in 10 minutes.

3270ServerSample

The application called 3270ServerSample contains a sample 3270 server. Before

you can use 3270ServerSample you must do the following:

1. From the Welcome window, click on Configuration —> System

Configuration

Select Virtual Mode.

The sample server is just that, a sample. Unless your environment is identical

to the environment in which the sample was constructed, the sample can run

only if you reconfigure the 3270 host connection to virtual mode.

If you try to run the sample server in a different environment in real mode,

you will disable the 3270 sessions defined for it. Therefore, we recommend

that you run the sample only in virtual mode or use it as an example of the

types of scripts and the kinds of logic you can include in the 3270 servers you

write.

2. Open Application Server Interface

3. Open 3270 Mode

4. Click Virtual Mode

5. Click OK.

6. Before closing the System Configuration window, you need to Save the

new value.

7. Finally, you must stop WebSphere Voice Response and start it again to

make the new value take effect.

Import and install

8. Import the 3270ServerSample.imp file. The import file is located in the


9. Configure a session for use by the server. Use the instructions in

WebSphere Voice Response for AIX: Configuring the System to configure a

3270 terminal session for use by the 3270ServerSample server.

sample 3270 and custom servers

Chapter 9. Accessing data with a 3270 or custom server 129

10. Create an application profile for the SrvrSample_3270 state table (see

Chapter 5, “Creating an application profile,” on page 89).

Done

You can now run the 3270ServerSample application in virtual mode.

3270ServerSample is an example of a 3270 server that performs a simple

query of an account balance based on a 6-digit account number. The sample

includes script language statements that facilitate operation of the script in

virtual mode.

The SrvrSample_3270 state table

The state table SrvrSample_3270 plays the initial greeting and prompts the

caller to enter a 4-digit ID that identifies a valid application profile. The caller

is allowed three attempts to enter a valid ID before the state table terminates

the application with a good-bye message.

Upon registering a valid ID, the state table uses the OpenHostServerLink state

table action to call the 3270 server, SrvrSample_3270. The caller is then

prompted to enter the 6-digit account number of the account to be queried. If

the sample is run in virtual mode, interaction is not with real host screens but

with screens stored in the WebSphere Voice Response database. Consequently,

the list of valid account numbers in virtual mode is limited to those present

on the abrw screen. These valid account numbers are:

v 006006

v 006016

v 006670

v 006968

If the account number that the caller enters is valid, the account balance is

played to the caller; otherwise, the caller is advised that the account number

entered was not valid.

The state table performs a CloseHostServerLink action on SrvrSample_3270.

This is followed by a good-bye message and a CloseEverything action.

The 3270ServerSample scripts

The 3270ServerSample scripts fall into two groups: those used as part of the

login and those called from the state table.

The scripts that are used for the login navigate to the amnu screen, which is

the main menu screen of the host application. These scripts are:

v login_amnu



v login_blank

v login_cics

v login_unformatted

v login_samon

The main login script is login_amnu, which calls the other scripts, depending

on the screen encountered. The remaining scripts are used to navigate to the

screen containing the account information, namely abrw.

Review the scripts themselves for a more detailed description of their

behavior.


Chapter 9. Accessing data with a 3270 or custom server 131



Chapter 10. Telephony activity

This chapter contains the following sections:

v “Handling switch and protocol limitations” on this page

v “Answering calls” on page 135

v “Making, transferring, reconnecting, and terminating calls” on page 142

v “Coordinated call and data transfer” on page 143

v “Setting the MessageWaiting Indicator using CallPath Server” on page 147

Handling switch and protocol limitations

When you design your voice applications, you need to consider the

limitations and operation of the signaling protocol and switch you are using.

For example, some switches and signaling protocols do not allow WebSphere

Voice Response to initiate a call transfer.

Handling switch tones

A switch issues different tones, to indicate the current activity on the phone

line. However, any one activity, for example, ringing, is indicated differently

by each switch; the tones may be switch-specific or defined by national

standards. In addition, some switches send different tones depending on

whether the target number is internal or external to the switch.

For example, when a ROLM switch receives a signal that the telephone

receiver is off-hook, it generates a dial tone for a set number of seconds while

waiting for dialing to begin, followed by a beep tone if the telephone is not

dialed, followed by a howl tone after a set period of no activity.

For more information about all progress tones, see the WebSphere Voice

Response for AIX: Configuring the System guide.

Accounting for protocol limitations

You need to be aware of the operation of the signaling protocol your system

uses and design your state table accordingly. In general, trunk protocols

provide call information (called and calling numbers) but not call transfer,

while line-side (station) protocols provide call transfer but not call

information. To get both call information and call transfer, you may need to

use an exchange data link. For example, the exchange data link using CallPath

Server provides call information.


Far-end hangup detection is another function that is not supported by some

protocols. Again, if you use an exchange data link that uses CallPath Server,

far-end hangup detection is supported. (See “Coordinated call and data

transfer” on page 143.)

Getting call information when answering a call

The best way of choosing a state table to handle an incoming call is to use the

called number (appearing to callers that they have “gone straight through to”

the voice response service). However, if the called number is unavailable there

are two other options: see “Handling incoming calls in your production

system” on page 140.

Ayava switches with the converse feature cannot send DNIS information

using the incoming address signaling options, and therefore cannot be

retrieved by the WebSphere Voice Response system variable SV185. Such

switches send DNIS information as DTMF keys after WebSphere Voice

Response answers the call. To handle this, you need to modify the state table

identified by the system parameter: State Table Name for Incoming Calls

(the default is Incoming_Call). See “Can you write your own state table to

answer calls?” on page 139 for details of how to do this.

Making and transferring calls

When using line-side (station) protocols such as FXS and RE, you are

recommended to use dial tone detection when making outbound calls and call

transfers (see the information about MakeCall in the WebSphere Voice Response

for AIX: Application Development using State Tables reference manual).

Detecting far-end hangup

You need to be aware that some protocols, generally loop start protocols such

as FXS, do not include positive hangup detection.

In the absence of any indication from the switch, when a caller hangs up, the

state table continues to run until a CloseEverything action. To avoid executing

a state table unnecessarily:

v Consider using relatively low timeouts in actions that get caller input (for

example, GetKey or GetData). If the Last Timeout result branches to a

CloseEverything action, low timeout and repeat count values will end the

state table execution soon after a caller hangs up.

v After a Record... action or a speech recognition request, evaluate the

System : Action additional information system variable (SV180), which

may indicate that the recording was terminated because the time limit

specified by the Maximum Silence Duration system parameter was

exceeded.

Example: Here’s an example that highlights the potential for various

problems you may encounter based on your specific configuration. Suppose

handling switch and protocol limitations


your system is connected to a ROLM 9751 switch that is configured to use the

FXS Loop Start protocol. When a caller hangs up before a voice application

has completed execution, the following events occur:

1. The protocol does not detect the hang up and WebSphere Voice Response

remains off-hook.

2. As the voice application continues to execute, the ROLM switch issues an

error tone for a number of seconds, then pauses, then issues a second error

tone that alternates between the tones for the * and # keys.

3. The voice application state table encounters a GetData action and waits for

caller input before timing out for the first time.

4. The state table branches to the state specified in the time-out result field

(perhaps a PlayPrompt to prompt the caller for input), then again

encounters the GetData action to wait for caller input.

5. Assuming a high time-out value, the repeat count value (the maximum

number of timeouts allowed before branching to the state specified in the

last timeout result field) may not be reached before the ROLM switch

issues the second error tone.

6. GetData recognizes the # key in the error tone as “end of input,” but does

not recognize the * key.

7. GetData exits with a result of “Input Too Short,” and branches to the state

specified for this result.

8. If the state that is branched to is not CloseEverything, the state table

continues to execute.

9. If the execution again encounters the GetData action, and the switch

continues to issue the second error tone, the state table loops indefinitely.

The problem in this example could have been eliminated by reducing the

timeout and repeat count values so that the voice application timed out before

the switch issued the second error tone.

Answering calls

AnswerCall is the state table action that answers an incoming call. An

AnswerCall action in every state table is not mandatory, but it is useful for

debugging. (See the WebSphere Voice Response for AIX: Application Development

using State Tables reference manual for information about using the debug

option in the State Table window.)

How does WebSphere Voice Response answer an incoming call?

When WebSphere Voice Response receives an incoming call it uses the call’s

application profile ID to determine how it should be answered.

handling switch and protocol limitations

Chapter 10. Telephony activity 135

Initially, control of the call is always passed to the Incoming_Call state table.

Incoming_Call issues the AnswerCall action then the InvokeStateTable action

to invoke the state table specified in the application profile.

If the application profile specifies a state table called JavaApplication and the

Java and VoiceXML environment is installed and running, control of the call

passes to a Java application. The JavaApplication state table needs to be

available in case the Java and VoiceXML environment is not running. For

more information on configuring your system to answer incoming calls with

Java applications, see WebSphere Voice Response for AIX: Deploying and

Managing VoiceXML and Java Applications.

Each state table that is designed to handle incoming calls therefore requires an

application profile, and WebSphere Voice Response must find the appropriate

application profile before Incoming_Call can invoke the right state table to

handle the call.

answering calls


SV22 and SV185 areset to the applicationprofile ID.

SV129 isset to 0

SV129 is set to 1

SV129 isset to 2

IsWebSphere Voice

Responseconfigured to receive the

callednumber?

Has a called numberbeen received?

Is therean application profile to

match thecalled number?

Is therean application profile to

match the channelidentification?

Is therean application profileto match the SystemDefault Application

Profile?

The call is notanswered

Yes

Yes

Yes

Yes

Yes

No

No

No

No

No

Incoming_Call answers the calland invokes the state table

specified in the profile

Control is passed to the state tablespecified by the application profile

No

Yes

Control is passed to a Javaapplication

Is state tablename=Java Application

and is Java and Voice XMLEnvironment

running?

Figure 14. How WebSphere Voice Response finds the state table to handle an incoming call

answering calls


How does WebSphere Voice Response find the application profile?

Incoming_Call works on the basis that an application profile specifying a state

table has been found. Figure 14 on page 137 shows how WebSphere Voice

Response finds the application profile. When a call comes in and the called

number is available, WebSphere Voice Response looks for an application

profile whose ID matches the called number. (If the called number was

received on an exchange data link, the area code specified in the channel

group is concatenated to the beginning of the number before the search.) If

the called number is unavailable for any reason, WebSphere Voice Response

looks for an application profile whose ID matches the channel identification (for

details, see the WebSphere Voice Response for AIX: Configuring the System guide).

If no profile is found, WebSphere Voice Response looks for an application

profile whose ID matches the value of the System Default Application Profile

system parameter (whose supplied value is 0000000000).

If there is no qualifying application profile ID, the call is not answered.4

Table 6. Application profile examples

Profile ID State Table Name Function

1234567 Accounts_Main Tell callers their account details.

1238800 Interest_Main Tell callers the current interest rates.

0000000000 Main Offer callers a choice of services.

What happens when Incoming_Call answers the call?

After issuing the AnswerCall action, the Incoming_Call state table invokes the

state table specified in the application profile. Because it invokes the state

table by application profile, Incoming_Call cannot pass any parameters to the

state table. The following system variables are, however, available for the state

table to use:

Application - Profile ID (SV22)

The ID of the application profile found by WebSphere Voice Response.

System : Call Info : Called Number (SV185)

The called number or, if no called number is available, the channel

identification.

Caller - Profile ID (SV20)

The calling number (if available).

System : Call Info : Calling Number (SV186)

The calling number (if available).

4. If WebSphere Voice Response is configured to go off hook in order to receive DNIS information, the system plays

the caller a message saying that there are technical difficulties, and then hangs up.

answering calls


System : Call Info : Call info status (SV129)

Indicates whether call information (called number and calling

number) was received. If the value of this variable is 1 (successful),

SV185 is the called number; if the value is 0 (undefined) or 2 (failed),

it is the channel identification.

What happens if the state table is invalid?

If there is a problem with the state table specified in the application profile,

for example, if it is not found or is invalid, Incoming_Call invokes another

supplied state table, Welcome, which greets the caller and hangs up. Welcome

is also invoked during the installation test described in the WebSphere Voice

Response for AIX: Installation guide: WebSphere Voice Response finds the

application profile whose ID is 0000000000, and this application profile

specifies Welcome as the state table.

Do Incoming_Call and Welcome need customizing?

Incoming_Call and Welcome are set up and ready to use. You should record a

new voice segment for Welcome to play, perhaps explaining to the caller that

the system is experiencing technical difficulties.

Both of these applications are imported into WebSphere Voice Response as

part of the installation process.

Do not delete the state table specified in the State Table Name for Incoming

Calls parameter (Incoming_Call), because WebSphere Voice Response cannot

answer calls without it. Do not delete the application profile specified in the

System Default Application Profile parameter (0000000000), because

WebSphere Voice Response may need it to answer a call if no other

application profile can be found.

If they get modified or deleted by mistake, you can reimport them from

/usr/lpp/dirTalk/sw/samples/BaseData.imp.

Can you write your own state table to answer calls?

If you prefer to write your own state table to answer incoming calls, you can.

If you choose a different name for it, you must change the State Table Name

for Incoming Calls parameter in the Application Server Interface parameter

group (after you’ve done this, you need to stop WebSphere Voice Response

and start it again to make the new value take effect).

If your “state table for incoming calls” does not include an AnswerCall action,

each state table invoked by it must include its own AnswerCall action.

Ayava switches send DNIS information as DTMF keys after WebSphere Voice

Response answers the call, instead of using the incoming address signaling

options. To use such switches with WebSphere Voice Response you must

answering calls


either customize the state table identified by the system parameter: State

Table Name for Incoming Calls (the default is Incoming_Call) or substitute

one of your own.

The customized state table must include the GetData action immediately after

the AnswerCall action. The KeyBuffer, Minimum, Maximum, and Timeout

parameters for the GetData action should be set according to the length of the

DNIS digits and the expected time to receive all digits.

If you want to use the received digits to select the application profile, add an

AssignData action to set SV22 with the received digits before calling the

InvokeStateTable action.

Handling incoming calls in your production system

Even if you do not change Incoming_Call, there are several method of

handling incoming calls, and your decision partly depends on the capabilities

of the switch to pass the called number on to WebSphere Voice Response. You

need to decide whether to:

v Have one state table to handle all incoming calls

v Choose the state table on the basis of the called number

v Dedicate a group of channels to each voice response service, and let the

switch make the decision based on the called number

Have one state table to handle all incoming calls: With this method, the

state table asks the caller which service they require, and invokes another

state table. You only need one application profile to make this work: you can

use one of the following methods:

v Make the application profile ID match the value of the System Default

Application Profile parameter in the General system parameters group

v Give all your channels the same identification (the same area code and

phone number) and make the application profile ID match this.

Choose the state table on the basis of the called number: With this method,

WebSphere Voice Response can respond with the appropriate voice response

service for each caller. Each caller dials a different number depending on

which service they require, and gets straight through to that service. In the

0000000000

Figure 15. Application profile needed with one state table for all

answering calls


example shown in Table 6 on page 138, callers dial 1234567 for the accounts

application (Accounts_Main) or 1238800 for the interest rates application

(Interest_Main).

You should have one application profile for each state table that might be

invoked in this way. You also need a default application profile and state

table. Typically, the default state table would ask the caller which service they

require, in the event that the called number is, for some reason outside your

control5, unavailable.

This is the most efficient method. However, if your switch is unable to pass

the called number to WebSphere Voice Response, you cannot use this method.

Dedicate a group of channels to each voice response service: This method

has the same advantage as choosing the state table on the basis of called

number. The disadvantage of this method is that it ties channels to specific

applications, which is inefficient if all the calls at one time are for one of the

applications: it makes load-balancing difficult. If it’s possible to get the called

number from the switch, you should use that method.

Again, you need one application profile for each state table that might be

invoked in this way.

5. The called number may be unavailable if, for example, the switch did not receive the full information, or because

the task the switch uses to send the information is busy.

0000000000

1238800

1234567

Figure 16. Application profiles needed when using called number

1238800

1234567

Figure 17. Application profiles needed when using channel identification

answering calls


Making, transferring, reconnecting, and terminating calls

Call transfer

Most voice response services offer the caller the opportunity to transfer a call.

Call transfer can be provided in several ways, although the only standard

method uses PABX station or Centrex line features. Other methods of transfer

include a release link trunk, unique T1 or E1 protocols, or exchange data link.

There are two types of call transfer:

v Screened (or supervised) transfer

v Blind transfer

Screened transfer is usually preferable, but a blind transfer does reduce the

duration of a successful transfer process and may be acceptable.

Screened transfer

With a screened transfer, the state table places the caller on hold (suspending

the call) and completes the transfer only if the call to the third party is

answered. If the state table detects busy tone while transferring a call, or if the

third party does not answer, the state table can take one of the following

actions:

v Reconnect to the original caller and offer another option

v Dial an alternate number

v Play a “please hold” message and continuously retry the number until it

becomes free.

Blind transfer

With a blind transfer, the state table places the caller on hold, sends the

address of the third party, and then disconnects from the call. If the transfer is

unsuccessful, the switch usually places a new call to the party that originally

initiated the transfer request.

Implementing call transfer with WebSphere Voice Response

With channel associated signaling (CAS), WebSphere Voice Response can

generate call transfer request signals using feature codes (character strings

consisting of 0 through 9, *, and #) with or without hook or ground flash. To

transfer a call, invoke the TransferCall action. With the Transfer Call Request

Signal parameter (in the Signaling Type parameter group) set to Feature Code,

the Transfer Call Feature Code (in the same group) identifies the character

string recognized by the switch as a call transfer request.

If the CAS protocol being used does not support call transfer, but the switch

has a host access control link that does support it, a custom-written signaling

process (see the WebSphere Voice Response for AIX: Programming for the Signaling

Interface guide for details).

making, transferring, reconnecting, and terminating calls


State table actions

Refer to the WebSphere Voice Response for AIX: Application Development using

State Tables guide for information about the following state table actions:

v MakeCall

v Dial

v TransferCall

v ReconnectCall

v TerminateCall

System parameters

Telephony activity is defined by a number of system parameters; those that

are of interest to you when designing a state table to make outbound calls

include:

v Maximum Ring Time (in the Application Server Interface parameter group)

v Maximum Ring Wait (in the Application Server Interface parameter group)

v Maximum Dial Tone Wait (in the Application Server Interface parameter

group)

v Reconnect Call Feature Code (in the Signaling Type parameter group)

v Transfer Call Feature Code (in the Signaling Type parameter group).

For details, see the online help information for these parameters, or the

WebSphere Voice Response for AIX: Configuring the System guide.

Coordinated call and data transfer

Coordinated call and data transfer is the process of transferring a caller to

another phone number together with some data. Typically, an account number

or some other identifier is passed, to allow the receiving agent to find details

about the caller without having to ask them for their account number again.

The receiving agent can be a person, or another voice application.

To implement coordinated call and data transfer in a voice application, you

need the following:

v A switch that supports program data.

v CallPath Server installed, either on the same pSeries computer or on

another pSeries computer or a personal computer connected by a local area

network (LAN).

v The CallPath_SigProc custom server imported from /usr/lpp/dirTalk/sw/samples/CTI.imp into your WebSphere Voice Response system.

A single-system installation is shown in Figure 18 on page 144.

making, transferring, reconnecting, and terminating calls


What does the state table have to do?

The CallPath_SigProc commands are documented in the WebSphere Voice

Response for AIX: Application Development using State Tables reference manual.

The commands are used to read or set the program data. In addition, the state

table also has access to information about an incoming call in the following

system variables:

System : Call Info : Called Number (SV185)

The called number (the number to which the call has been

transferred).

System : Call Info : Calling Number (SV186)

The number from which the call has been transferred.

System : Call Info : User 1 (SV187)

The dialed number (the number the caller originally dialed).

System : Call Info : User 2 (SV188)

The length of the program data.

Receiving Data From Another Number (Read_Program_Data)

Use the EvaluateData action to test the System : Call Info : User 2 system

variable (SV188). If the value is 0, there is no program data to be read.

Otherwise, use a SendData to send the Read_Program_Data command to

DataCommunications

Network

Information

Caller

Switch

TelephoneNetwork

VoiceProcessing

LocalArea

Network

CallPath_SigProcCustom Server

CallPath Server

State Table

pSeries


Figure 18. CallPath Server and WebSphere Voice Response installed in the same pSeries

computer

coordinated call and data transfer


CallPath_SigProc, followed by a ReceiveData to receive two parameters: the

program data itself and the length of the string. These steps are shown in

Figure 19 on page 146.

Transferring Data To Another Number (Set_Program_Data)

Pass the data you want to associate with the transfer as a parameter when

you use the SendData action to send the Set_Program_Data command to

CallPath_SigProc. Use a ReceiveData action following the SendData, and

check the return code. If the Set_Program_Data appears to have been

successful, use the TransferCall action to make the call transfer. These steps

are shown in Figure 20 on page 147.

What format must the data be in?

The data must be printable ASCII characters: that is, no imbedded control

characters are allowed in the string.

How much data can you pass?

WebSphere Voice Response has a limit of 512 bytes, but your switch may have

a smaller limit. If so, it is your responsibility to ensure that you do not send a

longer string.



Examples

If the value of SV188 is not 0,there is program data to be

read.

CloseHostServerLink

OpenHostServerLink to CallPath_SigProc

SendData Read_Program_Data

ReceiveData Read_Program_Data

EvaluateData SV188

Read the program data

Call transferred by CallPath Server andanswered by WebSphere Voice Response

Application can use the information itreceived in the program data.

Figure 19. Receiving a call and data transferred by CallPath Server



Setting the MessageWaiting Indicator using CallPath Server

You can use CallPath Server to set the message waiting indicator on any

phone, for example, when virtual mailboxes are in use. To do this, you need

the following:

v A switch that supports message waiting indication

v CallPath Server installed, either on the same pSeries computer or on

another pSeries computer or a personal computer connected by a local area

network (LAN)

v The CallPath_SigProc custom server imported into your WebSphere Voice

Response system.

A single-system installation is shown in Figure 18 on page 144. The steps that

the state table performs are shown in Figure 21 on page 148. For details about

the CallPath_SigProc Set_MWI command and its parameters, see the

WebSphere Voice Response for AIX: Application Development using State Tables

reference manual.

TransferCall

CloseHostServerLink


SendData Set_Program_Data

ReceiveData Set_Program_Data

Set the program data. Thismight be an account

identifier or any other data.

Transfer the call. The datais set along with the call.

A call is in progress; the caller wants to betransferred, or the application decides to

transfer them

Figure 20. Transferring a call and data to another number using CallPath Server

setting the Message Waiting Indicator using CallPath Server


CloseHostServerLink


SendData Set_MWI

ReceiveData Set_MWI

Set the message waitingindicator on or off at thespecified phone number.

Optionally, you can set theduration that the MWI is to

be on for, and the LEDfrequency.

A call is in progress

Figure 21. Using CallPath Server to set the message waiting indication

setting the Message Waiting Indicator using CallPath Server


Chapter 11. Designing voice messaging applications

You can create your own voice messaging applications or add voice

messaging to existing applications. For example, in an ordering application,

you may choose to let people leave a voice message to be associated with an

order. This is known as transaction-related voice messaging.

Your state table can include actions that record, send, check, play, annotate,

delete, and save voice messages, and change their attributes.

Note: If you require a voice mail system, you should also consider whether

IBM’s Unified Messaging program offering would satisfy your needs.

Unified Messaging is a fully functional voice mail application that can

be extensively tailored. For more information, see your IBM

representative.

Voice messaging resources

These are the resources used for voice messaging:

v Voice Mailboxes

v Greetings

v Audio Names

v Distribution lists

Voice mailboxes

Voice messages are stored in mailboxes. To define mailboxes, you need an

application profile. You can define up to ten mailboxes in one application

profile, or you can give each mailbox its own profile. The application profile

ID can be any value you want, but, for a voice mail application, the phone

number or extension number of the subscriber who owns the mailbox is

probably most convenient. In transaction messaging, you can use the different

mailboxes in an application profile to store different categories of voice

message.

In this case, each subscriber has an application profile, each of which specifies

the name of your voice mail application’s initial state table.

For more information about creating and maintaining mailboxes, see

Chapter 12, “Managing voice messaging resources,” on page 165.


Greetings

An application profile can define up to 255 greetings. Each mailbox defined

for the profile can use one or more greetings; a mailbox can play different

greetings depending on the value of the Caller : Mailbox : Owner Status

system variable (SV102). Each greeting is identified by a greeting ID.

In releases of IBM WebSphere Voice Response for AIX before Version 2

Release 2, greetings were always compressed before they were stored. The

administrator of a WebSphere Voice Response system can specify that all new

greetings recorded using state table actions are compressed, or that they are

all not compressed. The administrator specifies this using the User Greeting

Compression Type system parameter.

Audio names

Each mailbox can also have an associated audio name that is normally used to

contain the digitized voice data that identifies the owner of a mailbox. The

audio name can be played to callers who leave and retrieve messages to

identify the owner of a mailbox. Audio names are stored in compressed

format only.

In releases of IBM WebSphere Voice Response for AIX before Version 2

Release 2, audio names were always compressed before they were stored. The

administrator of a WebSphere Voice Response system can specify that all new

audio names recorded using state table actions are compressed, or that they

are all not compressed. The administrator specifies this using the Audio Name

Compression Type system parameter.

Distribution lists

A distribution list is a list of application profile IDs and mailbox IDs or other

distribution list IDs, to which a message can be sent. There is no limit to the

number of members in each distribution list. The distribution list is identified

by a four-digit ID. A distribution list can be public or private to the mailbox

for which it is defined. There are state table actions to manipulate distribution

lists and distribution list editing functions available to the system

administrator. For more information about creating distribution lists, see

Chapter 12, “Managing voice messaging resources,” on page 165.

Accessing mailbox information

To access mailbox information, the state table must set the Caller - Profile

ID system variable (SV20). To access information about a specific mailbox in

the application profile, the state table must set the Caller : Mailbox - ID

system variable (SV32). The rest of the Caller system variables are initialized

with appropriate values when SV20 and SV32 are set.

SV20 can be set in the following ways:

voice messaging resources


v When WebSphere Voice Response automatically loads it with the calling

number information. In this case, the profile data is not retrieved from the

database until the state table writes to SV20 (use AssignData to set

SV20=SV20).

v When the state table assigns a value to it using GetFindName, GetData,

ReceiveData, or AssignData. In this case, the profile data is retrieved from

the database when the state table writes to SV20.

voice messaging resources

Chapter 11. Designing voice messaging applications 151

Using state table actions for voice messaging

Voice mailboxes

Set or change the attributes of a voice mailbox UpdateProfile

Voice messages

Record a new voice message RecordVoiceMessage

Add more to the beginning of a voice message RecordVoiceMessage

Add more to the end of a voice message RecordVoiceMessage

Set or change the attributes of a voice message ChangeMessageAttributes

Send a voice message to the mailbox specified by the

application profile ID and mailbox ID

SendVoiceMessage

Retrieve all voice messages of a specified type for the

application profile specified by SV20 and mailbox ID

specified by SV32

CheckVoiceMessages

Play a voice message from a mailbox PlayVoiceMessage

Save a voice message, which has been retrieved using

CheckVoiceMessages, in the mailbox for later retrieval

SaveVoiceMessage

Play back a voice message which has just been

recorded

PlayVoiceMessage

Remove a voice message previously retrieved using

CheckVoiceMessages

DeleteVoiceMessage

Distribution lists

Retrieve names of all recipients on a specified

distribution list for a specified application profile and

mailbox ID

GetDistributionList

Retrieve names of all distribution lists for a specified


GetDistributionList

Add a mailbox to a distribution list UpdateDistributionList

Add a distribution list to a distribution list UpdateDistributionList

Remove a name from a distribution list UpdateDistributionList

Remove a distribution list UpdateDistributionList

Copy a distribution list UpdateDistributionList

Append a distribution list to another distribution list UpdateDistributionList

using state table actions for voice messaging


Audio names

Record an audio name RecordAudioName

Store the audio name for the application profile and

mailbox ID

SaveAudioName

Play the audio name of the specified application


PlayAudioName

Remove the audio name of the specified application


DeleteAudioName

Greetings

Record a greeting RecordUserGreeting

Store the greeting for the specified application profile

and mailbox ID

SaveUserGreeting

Play the greeting associated with the specified


PlayUserGreeting

Remove the greeting specified by system variable

SV102

DeleteUserGreeting

Interacting with callers and messages

A caller is anyone who dials or calls into the system, for example, to record a

message or greeting or listen to a voice message. This caller is represented by

the Caller : Profile - ID system variable (SV20), and the mailbox from

which voice messages are sent or retrieved for listening is represented by the

Caller : Mailbox - ID system variable (SV32). Each voice message is always

associated with the Profile ID and Mailbox ID from which it was sent and the

Profile ID and Mailbox ID from which it is to be retrieved.

Recorded voice messages are stored in temporary workspace until they are

sent to a mailbox. Voice messages can be retrieved from mailboxes to be

played, annotated (repeatedly, if required), sent, deleted, saved, or their

attributes can be changed before sending them to a specified mailbox. The

attributes of a message in a mailbox are defined by the Message system

variables, described in the WebSphere Voice Response for AIX: Application

Development using State Tables reference manual. The status of a message is

stored in the Message : Status system variable (SV47).

Incoming messages are received messages in the recipient’s mailbox; the status

of incoming messages can be New, Checked, Listened, Saved, or

Undeliverable. Outgoing messages are sent messages in the sender’s

mailbox; the status of outgoing messages can be New or Future.

using state table actions for voice messaging


Recording messages

The RecordVoiceMessage state table action records a message in the

workspace. Recording a new message clears the workspace of any existing

voice data. RecordVoiceMessage is also used to annotate an existing message,

as described in “Annotating messages” on page 156.

After recording, a message is typically sent to a specified mailbox using the

SendVoiceMessage state table action.

Sending messages

The SendVoiceMessage state table action sends a message to a mailbox. The

message is stored in the recipient’s mailbox as a New message, and is added

to the sender’s outgoing messages. If sent to someone else’s mailbox, the

message will be kept in the sender’s outgoing messages until the recipient

checks the message. If the message is future dated (status is Future), the

message is not sent to the recipient’s mailbox until the specified date and

time. SendVoiceMessage is also used to forward messages from one mailbox

to another, as described in “Forwarding messages” on page 155.

If the sender requested acknowledgment of the message (using the Receipt

Acknowledgment parameter of ChangeMessageAttributes), the message will

be sent to the sender’s mailbox as a New message when the recipient plays or

deletes the message. The Message : Receipt acknowledgment status system

variable (SV161) is set to indicate whether the message was listened to or not.

Retrieving messages

The CheckVoiceMessages state table action retrieves a list of messages from a

mailbox. Before a message in a mailbox can be played, forwarded, annotated,

saved, deleted, or the attributes changed, it must be retrieved from the

mailbox by CheckVoiceMessages. When a message is retrieved, the Message

system variables are initialized with the message information. Whenever the

mailbox is accessed and a New message is counted, SV32 is set and the status

of the message is changed to Checked . A retrieved message remains Checked

until it is listened to, saved, or deleted.

CheckVoiceMessages can retrieve one of the following categories of messages:

v First Incoming New. Includes all incoming New, Checked, Listened, or

Undeliverable messages.

v First Incoming Saved. Includes all incoming Saved messages.

v First Outgoing To All Recipients. Includes all outgoing messages (the

messages that have a status of New or Future that have not been checked

by the recipient).

v First Outgoing To Selected Recipient. Includes outgoing messages sent to a

specific recipient (the messages that have a status of New or Future that

have not been checked by the recipient).

interacting with callers and messages


v Next Message. Retrieves the next message in the list.

When a list of messages is retrieved, the first message in the list is the current

message, which can be played, forwarded, annotated, saved, deleted, or the

attributes changed. Once the list is retrieved, subsequent CheckVoiceMessages

(Next Message) actions update the current message to the next message in the

list. The Message system variables are always initialized with the current

message information.

To select a specific message in the list, you can use the AssignData state table

action to assign a value to a Message system variable that defines the message

you want. For example, to select the third message in a list retrieved by

CheckVoiceMessages, you can assign the Message : Message number system

variable (SV21) a value of 3. This automatically updates the current message

to the third message in the CheckVoiceMessages list.

You can also select a specific message based on the transaction ID of the

message. By setting the Message : Transaction ID system variable (SV126) to

a value, the list is searched for a message with a transaction ID that matches

the value. If the first message in a newly retrieved list matches, that message

remains the current message. Subsequent AssignData actions select and

refresh the workspace information with subsequent matching messages in the

list. In other words, subsequent checks for matches with the same transaction

ID begin following the current message, not starting with the current message.


Acknowledgment parameter of ChangeMessageAttributes), the Message :

Receipt acknowledgment status system variable (SV161) has a value of 1.

Playing messages

If the voice message has just been recorded, the PlayVoiceMessage action

plays it from the workspace; if the voice message is the current message in the

list of retrieved messages, the PlayVoiceMessage action plays it from the

mailbox. As soon as the mailbox is accessed, the status of all messages

changes from New to Checked. When a message has been played successfully

all the way through to the end, the status changes to Listened.

If the sender requested acknowledgment of the message, (using the Receipt

Acknowledgment parameter of ChangeMessageAttributes), the message is

sent to the sender’s mailbox as a New message when the recipient plays the

message and the Message : Receipt acknowledgment status system variable

(SV161) has a value of 2, which indicates that the message was listened to.

Forwarding messages

After a message has been retrieved from a mailbox, the SendVoiceMessage

state table action can be used to forward the message from one mailbox to



another. The recipient of a message can forward the message directly to

another mailbox or can first change the attributes of a message or annotate the

message before forwarding. In all cases, the sender information of the

forwarded message reflects the forwarder. The sender information of the

original message remains unchanged.

For example, if Jay sends a message to Nick’s mailbox, and Nick then

forwards it to Daisy, the message in Daisy’s mailbox will indicate Nick as the

sender. Nick can also record an annotation to the message before sending it to

Daisy. Jay’s outgoing messages include the original message sent to Nick, but

not the annotated message sent by Nick to Daisy. Nick’s incoming messages

include the original message sent by Jay; his outgoing messages include the

message sent to Daisy. Daisy’s incoming messages include the message sent

by Nick.

Annotating messages

The RecordVoiceMessage state table action can use the options Add To

Beginning and Add To End to annotate the message. The message can be a

newly recorded message in the workspace or the current message retrieved by

CheckVoiceMessages. The same message can be annotated multiple times.

Changing message attributes

The ChangeMessageAttributes state table action sets and changes the

attributes of the message in the workspace. The attributes that can be changed

are the date it is to be delivered, the security level, urgency level, whether to

acknowledge receipt of the message, or transaction ID.

Deleting messages

After a voice message has been retrieved from a mailbox, the

DeleteVoiceMessage state table action can be used to change the status of the

message in the list to Deleted and clears the Message system variables.


Acknowledgment parameter of ChangeMessageAttributes), and the recipient

did not play the message before deleting it, the message is sent to the

sender’s mailbox as a New message and the Message : Receipt

acknowledgment status system variable (SV161) has a value of 3, which

indicates that the message was received but not listened to.

Saving messages

After a voice message has been retrieved from a mailbox, the

SaveVoiceMessage state table action can be used to change the status of the

message in the mailbox from Checked, Listened, or Undeliverable to Saved.

If you make any changes to a voice message (by using

ChangeMessageAttributes or RecordVoiceMessage), you have created a new

message, which must be sent to a mailbox. The mailbox can be the sender’s



own mailbox, or a different mailbox. If sent to the sender’s mailbox, the

message will be a New incoming message. If sent to someone else’s mailbox,

the message will be kept in the sender’s outgoing messages until the recipient

checks the message. Whether a message is sent to the sender’s own mailbox

or to another mailbox, the message is always added to the sender’s outgoing

messages list.

System parameters that affect voice messaging

The following parameters in the Application Server Interface parameter group

affect voice applications that include messaging or use mailboxes:

v Password Minimum Length

v Play Skip

v User Identifier Minimum Digits

The following parameters in the General parameter group control the length

of each voice message:

v Record Voice Maximum Pause

v Record Voice Maximum

A sample voice message application

The sample called VoiceMessagingSample is a voice application that includes

messaging. The sample called RecordAudionameSample allows you to record

the name of the owner of a mailbox for a voice application to speak to a caller

(an audio name). To use these samples, you must

1. Import the VoiceMessagingSample.imp and RecordAudionameSample.imp

files. The import file is located in the /usr/lpp/dirTalk/sw/samples

directory.

2. Create an application profile for it (see Chapter 5, “Creating an application

profile,” on page 89).

3. Create the mailboxes for which you plan to record the audio names (see

“Creating mailboxes for application use” on page 168).

4. Use RecordAudionameSample to record some audio names.

RecordAudionameSample

RecordAudionameSample enables you to record an audio name for an

application profile mailbox.

Note: This sample includes a state table and a prompt that are both named

RecordAudioName. This is a reserved word in the ASCII state table

language, so if you export these files for use as the basis for a new

application, you must rename them.



VoiceMessagingSample

VoiceMessagingSample is an example of a messaging application that allows

callers to:

v Record messages

v Listen to messages

v Send messages (to individuals or to a distribution list)

v Annotate (add to) messages

v Save messages

v Forward messages

v Change personal options such as distribution lists, passwords, and greetings

The flow of control in VoiceMessagingSample is illustrated in Figures

Figure 22 through Figure 24 on page 160. The application is modular, with the

state table VoiceMsgMenu as the main controlling loop that calls the other

state tables according to the caller’s input.

Answer the call Answer the call

Get the profile ID

Get the password

Home state

Invoke VoiceMsgListen

Invoke VoiceMsgOptions

Play the greeting

Invoke VoiceMsgRecord

Exit

VoiceMsgMenu VoiceMsgAnswer

1

2

3

9

0

Record a message

Listen to your messages

Personal options

Help

Exit


Figure 22. VoiceMsgMenu and VoiceMsgAnswer

a sample voice message application


VoiceMsgListen

Listen

Play the message

Check next message

Summary

Message type

1

2

3

New

Saved

Outgoing

Message options

1

2

3

5

7

9

Reply

Next message

Save

Delete

Listen

Forward

VoiceMsgRecord

Record the message

Send

Annotate the message

1

2

3

5

7

Append

Prefix

Re-record

Send

Listen

Special delivery

1

2

5

Acknowledgement

Future delivery

Send

Destination

1

2

To single recipient

To distribution list

Resend

1

2

Send again

Finished



Figure 23. VoiceMsgRecord and VoiceMsgListen



An example state table

Figure 25 on page 162 shows an example of the listing you get when you

print a state table from WebSphere Voice Response. For each state, the listing

has three sections:

1. The optional state State Label, the Action, and an optional Description.

In Figure 25 on page 162, the first state in the table is labeled summary, its

action is a PlayPrompt, and its description is Play summary of messages

prompt. The second state is unlabeled, it is also a PlayPrompt, and its

description is Play message type selection prompt.

2. TRANSITIONS

Choose a person option

Distribution lists

Modify distribution list

1 Greeting

Password

Distribution lists

3

5

1 Modify distribution list

Review distribution list

Delete distribution list

2

6

1

2

6

Add recipient

Review recipient

Delete recipient

Greeting

1

2

6

Record new greeting

Listen to current greeting

Select standard greeting

Figure 24. VoiceMsgOptions



This section tells you the possible results that can be returned by the

action, with the label of the state specified as the Goto State (the next

state for that result). A blank in the Goto State column indicates that the

state that follows this one will be the next state for that result.

For example, the first action (summary) has four possible results:

v If the action succeeds, the state table proceeds with the state that follows

this one.

v If there is a line problem, the next state is the state labeled error.

v If nothing is played, the next state is the state labeled error.

v If the caller hangs up, the next state is the state labeled end.3. PARAMETER VALUES

This section lists the parameters and the values set for them. In the first

action (summary), the Prompt parameter specifies the name of the prompt

(in this case, the Summary prompt) and the Force Play parameter, which is

set to False, specifies that the prompt can be interrupted by the caller.

State Table - VoiceMsgListen

Voice Messaging Sample - "Listen"

State Label Action Description

=============== ==================== ======================================

summary PlayPrompt Play summary of messages prompt

TRANSITIONS

Result Goto State

------------------------------ ---------------

Succeeded

Line Problem error

Nothing Played error

Caller Hung Up end

PARAMETER VALUES

Parameter Value

------------------------------ ------------------------------

Prompt Summary

Force Play False



An example prompt

The prompt for VoiceMsgSummary is typical of those you will write when

creating a WebSphere Voice Response application.

Table 7. Fm Variable:Table Sheet Example prompt

IF SV28 = 0 AND SV29 = 0 AND SV31 =0 THEN

VOICE VoiceMsg (200); # You have no...

VOICE VoiceMsg (220); # ...messages

If the caller’s mailbox

contains no new messages

(SV28), saved messages

(SV29), or outgoing

messages (SV31), this

section plays “You have no

messages” (voice segment

200 followed by voice

segment 220 in the

VoiceMsg voice directory).

State Label Action Description

=============== ==================== ======================================

PlayPrompt Play message type selection prompt

TRANSITIONS

Result Goto State

------------------------------ ---------------

Succeeded

Line Problem error

Nothing Played return

Caller Hung Up end

PARAMETER VALUES

Parameter Value

------------------------------ ------------------------------

Prompt MessageType

Force Play False

Figure 25. Example listing of the first two states in a state table



Table 7. Fm Variable:Table Sheet Example prompt (continued)

ELSE

VOICE VoiceMsg (210); # You have...

IF SV28 != 0 THEN

SYSPROMPT Whole_number (SV28);

VOICE VoiceMsg (250); # ...new...

PROMPT Message_s (SV28);

This section plays “You

have” (voice segment 210).

It then checks SV28 to see if

the caller has any new

messages. If there are new

messages, the

Whole_number system

prompt plays the value of

SV28.

This is followed by voice

segment 250, which plays

the word “new” and then

the Message_s prompt.

Message_s is a subroutine

that determines whether the

value passed as a

parameter is 1, or >1. If this

value is 1, the word

“message” is played,

otherwise the word

“messages” is played.

IF (SV29 = 0 AND SV31 !=0) OR

(SV29 != 0 AND SV31 = 0) THEN

VOICE System (301); # ...and...

ENDIF

ENDIF

ENDIF

Next, SV29 (saved

messages) and SV31

(outgoing messages) are

checked. If either variable

contains a number other

than 0, the system prompt

301, which contains the

word “and”, is played.



Table 7. Fm Variable:Table Sheet Example prompt (continued)

IF SV29 != 0 THEN


VOICE VoiceMsg (250); # ...saved...


# Determine whether to say “and”

IF SV31 = !0 THEN

VOICE System (301); # ...and...

ENDIF

ENDIF

This section checks SV29 to

determine if the caller has

saved messages. If so, it

calls the system prompt

Whole_number to play the

value in SV29, followed by

voice segment 250, which

plays the word “saved”.

The prompt Message_s

again determines whether

to play the work “message”

or the word “messages”.

Next, SV31 (outgoing

messages) is checked. If it

contains a number other

than 0, the system prompt

301, which contains the

word “and”, is played.

IF SV31 != 0 THEN


VOICE VoiceMsg (270); # ...outgoing...


ENDIF

This section checks SV31 to

determine if the caller has

outgoing messages. If so, it

calls the system prompt

Whole_number to play the

value in SV31, followed by

voice segment 270, which

plays the word “outgoing”.

The prompt Message_s

again determines whether

to play the word “message”

or the word “messages”.



Chapter 12. Managing voice messaging resources

This chapter describes how to create and maintain mailboxes, subscriber

classes and distribution lists for use by a voice messaging application.

Messages occupy disk space, and disk space usage must be monitored.

You can control the use of mailboxes by defining subscriber classes and

assigning mailboxes to them. This can be done at any time, either when you

first create the application profile, or later.

The system administrator creates mailboxes for new users, removes unwanted

mailboxes, and can also create, update, and remove distribution lists for

general use or as required by subscribers. The system administrator can also

view the number and status of messages in the mailboxes (the content of the

messages cannot be accessed by the system administrator).

If you are implementing a large-scale voice messaging application, you should

also read about supporting applications that require a large amount of voice

data in the WebSphere Voice Response for AIX: Installation guide.

Voice mailboxes

Voice mailboxes are required for voice messaging. They are logical mailboxes, not

physical ones: the system does not reserve space on the disk for each mailbox.

When you “define mailboxes” for an application to use, you are really

activating a mechanism that enables the state table messaging actions to work

properly. If no mailboxes have been created, the messaging actions cannot

work correctly.

How do I create a mailbox?

Mailboxes always belong to an application profile. Up to 10 mailboxes can be

activated on any one application profile. You can do this either in the

Application Profile window or by using the wvrapplprof and wvrmailbox

commands. See “Creating mailboxes for application use” on page 168

What mailbox information does the application profile include?

The application profile includes information that the voice application and the

system administrator can use to control the usage of the mailboxes. The

profile specifies, for example:

v How many mailboxes the application can use.

v What greeting the application plays to callers by default.

v A password for each mailbox.


v A referral telephone number at which the mailbox owner can be reached.

v What greeting the owner of a mailbox wants played to callers who reach

the mailbox when the owner has recorded more than one greeting.

v A status for the owner, which can also control which greeting is played.

v Whether a mailbox takes messages or only plays the owner’s greeting.

v The order in which messages are retrieved.

v Whether callers can leave and retrieve messages in any mailbox controlled

by the application or only in the current mailbox.

v Which set of prompts a caller accessing the mailbox should hear when the

application includes more than one set of prompts.

How is mailbox information used?

When the Caller - Profile ID system variable (SV20) and Caller - Mailbox

ID system variable (SV32) have been set by an AssignData action, causing the

profile information to be retrieved, the system loads each item of the mailbox

information into a separate system variable. For example, if the application

profile includes information about the owner’s status, WebSphere Voice

Response loads the information into the Caller: Mailbox: Owner status

system variable (SV102).

Voice applications can make control decisions based on the value of a

variable. In this example, assuming the owner had recorded alternative

greetings to be played when he was out of town or sick, the messaging

application could use the value of SV102, Caller : Mailbox: Owner status to

determine which greeting to play.

Whether an application checks the value of the system variable that holds

profile information is up to the application developer.

Controlling messages

All messages assigned to a mailbox are stored on the hard disk in the pSeries

computer. If one mailbox accumulates a lot of messages (or even a few very

long messages), the messages can take up a large amount of disk space.

WebSphere Voice Response includes two tools to help you control how much

disk space messages can use. One controls the maximum length of a message.

The other controls how many messages an application can store in a single

mailbox.

Limiting message length

The maximum length of a message is controlled by the Record Voice

Maximum system parameter in the General parameters group. This controls

the length of any voice data that is recorded over the telephone, both

voice mailboxes


messages and voice segments. If you change the value of Record Voice

Maximum, you will have to stop WebSphere Voice Response and start it

again, for the new value to take effect.

When the system is delivered, the parameter is set at 120 seconds. You can

reset it to limit recorded voice to any number of seconds between 30 and

3600.

In a state table, you can override the value of the Record Voice Maximum

system parameter, by setting the System : Maximum record time system

variable (SV179).

Limiting the number of messages

The object that controls the maximum number of messages in a single mailbox

is called a subscriber class. The use of subscriber classes is optional.

What are subscriber classes?

Subscriber classes specify values that allow a voice application to control the

use of mailboxes. Each subscriber class can specify different value for:

v The maximum number of mailboxes that can be assigned to guest users

v The maximum number of messages that a mailbox can accept

v The maximum number of distribution lists that can be constructed for each

mailbox

v The maximum number of entries in a distribution list constructed for any

mailbox

v The maximum record time per message

v The maximum number of greetings that the mailbox owner can record for a

mailbox

How do subscriber classes work?

Subscriber classes allow you to limit the use of one or more sets of mailboxes

at once. Using subscriber classes, you can also specify limits other than the

system limits to a group of mailboxes. To use a subscriber class, specify it in

an application profile. Specifying a subscriber class in an application profile

indicates that you want the limits included in the definition of that subscriber

class to apply to all mailboxes defined by that application profile.

When the Out Mail - Profile ID system variable (SV25) and Application -

Profile ID system variable (SV22) have been set and a profile that specifies a

subscriber class has been retrieved, the system loads the values specified in

the subscriber class definition into the appropriate Caller : Subclass system

variables . (For more information on the system variables, see the WebSphere

Voice Response for AIX: Application Development using State Tables reference

manual.) Once the values have been loaded into the variables, the voice

application can check them and enforce the limits.

controlling messages

Chapter 12. Managing voice messaging resources 167

WebSphere Voice Response does not automatically enforce the limits in a

subscriber class definition. The voice application itself must include state table

actions to ensure that the limits are not exceeded.

When should you define subscriber classes?

You can define subscriber classes at any time, before you create application

profiles, or after your system has been operating for a while.

You may find that you never need subscriber classes. Remember, subscriber

classes only specify limits on the use of mailboxes. The voice application that

is written to access the mailboxes must check these limits and then enforce

them.

Creating mailboxes for application use

You can create mailboxes in two ways, using either the graphical user

interface (GUI), or the wvrapplprof and wvrmailbox commands.

Before you start

WebSphere Voice Response does not automatically check mailbox definitions:

only the messaging application can check to make sure mailboxes are being

used properly. Therefore, the application designer must tell you what

information is necessary.

The application designer can interpret the system variables in any way that is

appropriate. For example, value 0 for the Caller : Mailbox : Access mode

system variable (SV106) is documented as meaning “Global”, but your

application may use it to mean “Read-only”. To make it easier to use such

Mailbox Options in the Application Profile window, you could edit the

display text in the language database (see the WebSphere Voice Response for

AIX: Configuring the System guide for details).

Using the graphical interface

1. In the Welcome window, click on Configuration —> Application Profiles

Activating mailboxes

2. Open the application profile. If you haven’t yet created it, follow the

instructions in Chapter 5, “Creating an application profile,” on page 89.

controlling messages


3. Click Show Mailbox 1 Properties.

The window expands to display the properties of mailbox 1.

A single application profile can contain details of up to 10 mailboxes.

Each mailbox is identified with a number from 1 through 10. When an

application uses more than one mailbox, callers can enter this mailbox ID

to select a mailbox to access. The selected mailbox then becomes the

current mailbox.

4. Click the Active checkbox to make this mailbox active.

5. To specify a default active greeting for this mailbox, type the identifier of

the greeting in the Profile Active Greeting field.

6. To activate another mailbox, click the Mailbox drop-down button, which

reveals the mailbox identifiers 1 through 10. Click the identifier of the

mailbox you want to activate.

Note: The active mailbox IDs do not have to be sequential. For example,

an application requiring three mailboxes can use 2, 6, and 10.

The window changes to display the properties of the selected mailbox.

creating mailboxes for application use


Defining options for a mailbox

7. Click the mailbox from the Mailbox drop down button.

8. Click Show Mailbox 1 Options.

The window opens up to display the options for the selected mailbox.

9. Fill in the fields as appropriate for your application. Note that WebSphere

Voice Response itself does not use this information: it passes the



information on to the state table, without any validation. The following

text describes each field name displayed in the Mailbox Options . Similar

field names are used in the wvrmailbox command prompt as shown in

Table 8 on page 177, where the corresponding GUI field names are shown

in italics.

Active Greeting Number

identifies which greeting an application should play to callers

when the owner has recorded more than one greeting.

Announce and

determines whether a caller who reaches the mailbox can leave a

message. The default is Announce and Take Messages.

Application Status

indicates whether the owner of the mailbox is In, Out, Sick,

Busy,or Traveling.

Access Mode

specifies how callers can use any mailboxes created for use by the

application. Global access means that a caller can retrieve or

leave messages in any mailbox. Read All access means that a

caller can retrieve a message from any mailbox but only leave

messages in the current mailbox. Read Write means that a caller

can access only the current mailbox. The default is Global.

Mailbox Busy

indicates whether the mailbox is currently being used.

Password

identifies a password that “opens” the mailbox for the caller to

retrieve messages. Password use is optional: you can create a

mailbox without a password. It is up to the application to check

such things as the length against the Password Minimum Length

parameter in the Application Server Interface parameter group.

The default value for this is four digits. The maximum length of

a password is always eight digits. Again, it is up to the

application to check this.

Password change date

date after which password must be changed.

Email address

address for e-mail notification.

Retrieval Order

specifies how messages are ordered in the message selection lists

you can use to maintain the contents of a mailbox. It also defines

the order in which messages are retrieved for a caller. (For more

information on mailbox maintenance, see the information in the



WebSphere Voice Response for AIX: Managing and Monitoring the

System guide.) Messages are grouped first by priority. All

messages of the same priority are then sorted into chronological

order: first in, first out (FIFO), or last in, first out (LIFO). The

default is FIFO (the system lists the earliest message received

first).

Prompt Level

specifies whether callers should hear Normal prompts, Novice

prompts, or Expert prompts. If voice application developers have

written three different sets of prompts and the application

includes logic to check which set to use, this information

determines which prompts the caller hears. The default is

Normal.

Play headers

plays message header, before listening to each message: Play

message headers, or Don’t play message headers.

New message delete

allows subscribers to elect to delete new messages without

listening to the whole message. The default is Don’t delete

messages without listening.

Save messages automatically

allows subscribers to elect to save new messages automatically

after listening. The default is Only save when requested.

Send message

allows subscribers to select when to specify the address of the

message: before, or after, recording the message. The default is

Address after recording the message.

Clock preference

clock preference used by notification schedules, either 12-hour

clock or 24-hour clock.

Bilingual greeting user

specifies whether to play bilingual greetings.

First time user

indicates the status of the subscriber: Yes: mailbox has never

been entered or No: the user has listened to the tutorial already.

Use the scroll bar to reveal more fields in the Mailbox Options



Assistant number

an assistant (also known as deputy ) number is the number of

another person who might be a useful contact for your callers.



Temporary assistant number

specifies a temporary alternative number for your assistant

number.

Reach-Me number

ReachMe number.

Temporary Reach-Me number

PIN to be used when receiving calls transferred via the reach-me

facility.

Operator number

Operator number.

Referral Number

specifies a number at which the mailbox owner can be reached.

The number must be a string of up to 20 digits (no hyphens or

parentheses).

Temporary referral number

temporary call-forwarding number.

Referral Type

specifies whether the referral number is a telephone number or a

beeper number. The default is Telephone.

Pager number

paging bureau number.

Pager reference

pager reference number.

Temporary pager number

temporary paging bureau number.

Temporary pager reference

temporary pager reference number.

Default fax number

specifies fax number; a 20-character numeric string.

Temporary fax number

specifies temporary fax number

VPIM address

address for SMTP/MIME delivery

VPIM MDP

specifies the message delivery preference for VPIM. It can be

Local, Remote, or Local and Remote. The default is Local.

VPIM voice format

VPIM voice format



Notification schedule status

specifies whether all notification schedules are turned On or Off.10. To set the options for another mailbox, click on the Mailbox drop down

button, which reveals the mailbox ids 1 through 10. Select the mailbox

number you want to activate.

The window changes to display the properties and options of the selected

mailbox.

Done

11. Click File —> Save. The mailboxes are defined and ready for use.

Using the wvrapplprof and wvrmailbox commands

Before you can use the wvrmailbox command, you must import the admin

custom server (see “Importing application objects” on page 47) and make sure

that it is running (see WebSphere Voice Response for AIX: Managing and

Monitoring the System).

To activate mailboxes:

1. If the application profile does not already exist, use the wvrapplprof -n

command to create it and set the number of active mailboxes. For

example, if you want to allow five mailboxes to be associated with the

application profile, type the following command and press Enter:

wvrapplprof -n -I 123456 -N name -S application -E entrypoint -B 5

2. If you need more mailboxes, activate them using the wvrmailbox

command. For example, to activate mailbox 6 type:

wvrmailbox -m -I 123456 -M 6 -F mailbox_status -V 1

For more information see “wvrapplprof command” on page 94 and

“wvrmailbox command.”

To set or modify the options for a mailbox, use the wvrmailbox -m command

with the -F and -V flags as described in “wvrmailbox command.”

wvrmailbox command

Purpose

List mailboxes associated with an application profile, or change, or view

details of mailboxes associated with an application profile. Note that the

application profile must already exist (see “wvrapplprof command” on page

94).

Prerequisites

Before you can use the wvrmailbox command, you must import the admin

custom server (see “Importing application objects” on page 47) and make sure

that it is running (see WebSphere Voice Response for AIX: Managing and

Monitoring the System).



Syntax

wvrmailbox

| -h

| -l -I profile_ID

| -m -I profile_ID -M mailbox_ID [[-F field_name -V value] ...]

| -v -I profile_ID -M mailbox_ID {-F all | -F field_name ] ...]

| -?

}

Action flags

All action flags are lowercase.

-h Display help for the command

-l List all the mailboxes associated with the application profile identified

by profile_ID.

-m Modify the mailbox identified by profile_ID and mailbox_ID, as

specified by the other parameters.

-v View the details of the mailbox identified by profile_ID and

mailbox_ID.

-? Display help for the command.

Attribute flags

All attribute flags are uppercase and followed by a value.

-I The profile ID of the application profile.

-M The number of the mailbox.

-F The field name to be modified or viewed. To specify multiple fields,

specify -F as many times as you need.

-V The corresponding value for the field to be modified. You must

specify a -V flag and value for each -F flag and field name.

Examples

List all mailboxes of application profile 123456:

wvrmailbox -l -I 123456

Activate mailbox 1 for application profile 123456:

wvrmailbox -m -I 123456 -M 1 -F mailbox_status -V 1

Modify some details of mailbox 2 for application profile 123456:

wvrmailbox -m -I 123456 -M 2 -F deputy_number -V 123333 -F email_address

-V [email protected]



View some details of mailbox 1 for application profile 123456:

wvrmailbox -v -I 123456 -M 1 -F mailbox_status -F clock_pref

View all the details of mailbox 1 for application profile 123456:

wvrmailbox -v -I 123456 -M 1 -F all

Field names

For an alphabetical list of field names that are valid with the -F attribute flag,

see the table that follows. All of these fields are user-modifiable except those

marked as display-only in the Field Data column. Corresponding fields names

used in the GUI are shown in italics.

Table 8. Mailbox field names used with wvrmailbox command

Field Name Description Length Field Data

access_mode

Access Mode

This specifies how

callers can use any

mailboxes created

for use by the

application. Global

access means that a

caller can retrieve

or leave messages

in any mailbox.

Read All access

means that a caller

can retrieve a

message from any

mailbox but only

leave messages in

the current

mailbox.

Read Write means

that a caller can

only access the

current mailbox.

1 0 = Global (default)

1 = Read All

2 = Read/Write

announce_only

Announce and

Determines

whether a caller

who reaches the

mailbox can leave a

message.

1 0 = take messages (default)

1 = don’t

autosave_new_msgs

Save messages automatically

Allows subscribers

to elect to save

new messages

automically after

listening.

1 0 = no (default)

1 = yes



Table 8. Mailbox field names used with wvrmailbox command (continued)


bilingual_grt

Bilingual greeting user

Bilingual greeting

user.

1 1 = play

0 = don’t play

box_id

Mailbox

Indicates the

mailbox number.

2 From 1 to 10

This is a mailbox property display-only

field

clock_pref

Clock preference

Clock preference

used by

notification

schedules.

1 0 = 12-hour (default)

1 = 24-hour

delete_new_msgs

New message delete

Let subscribers

delete new

messages without

listening to the

whole message.

1 0 = no (default)

1 = yes

deputy_number

Assistant number

Assistant number 20 numeric string

email_address

Email address

Address for e-mail

notification

255 text

fax_number

Default fax number

Fax number; a

twenty-character

numeric string

20 numeric string

first_time_user

First time user

First time user

status

1 0 = New mailbox (default)

1 = Tutorial has been used

mailbox_active_grt

Active Greeting Number

Identifies which

greeting an

application should

play to callers

when the owner

has recorded more

than one greeting.

3 0 = Default

1 = Personal greeting 1





7 = Announcement-only greeting

9 = System default

10 = System default announcement-only

11 = Alternative system announcement-only

12 = Alternative announcement-only

mailbox_busy

Mailbox Busy

Is the mailbox

currently busy on a

call.

1 0 = no

1 = yes





mail_status

Active

Indicates whether

mailbox is active or

inactive

1 0 = inactive

1 = active

new_messages

New

Displays how

many new

messages are in the

mailbox

This is a mailbox property display-only field

notif_sched_status

Notification schedule status

This specifies

whether all

notification

schedules are

turned On or Off.

1 0 = All off

1 = Active on

number_of_mailboxes

Total Active Mailboxes

The number of

mailboxes which

are active.


operator_number

Operator number

The number of the

switchboard

operator at your

location. This is the

default number to

which a call is

transferred if a

caller chooses that

option when

leaving a message.

Subscribers can set

their own operator

number to override

the system default.

20 numeric string

outgoing_messages

Outgoing

Displays how

many outgoing

messages are in the

mailbox.


pager_number

Pager number

Phone number of

your pager

20 numeric string





pager_ref

Pager reference

Some pagers are

identified by a

unique reference

number. If your

pager uses a

reference number,

you can set this by

entering it in this

field.

20 numeric string

password

Password

This identifies a

password that

“opens” the

mailbox for the

caller to retrieve

messages.

Password use is

optional. You can

create a mailbox

without a

password. It is up

to the application

to check such

things as the length

against the

Password

Minimum Length

parameter in the

Application Server

Interface parameter

group. The default

value for this is

four digits. The

maximum length of

a password is

always eight digits.

Again, it is up to

the application to

check this.

8 max numeric string

password_change_date

Password change date

Date after which

password must be

changed

8 YYYYMMDD

play_headers

Play headers

Play header before

message.

1 0 = no (default) - never play header

1 = yes





profile_active_grt

Profile Active Greeting

Specifies the

identifier of the

active greeting that

will be played

when a caller

reaches this

mailbox.

Reserved for use by Unified Messaging

prompt_level

Prompt Level

Verbosity level for

prompts the

subscriber hears.

1 0 = Normal prompts (default)

1 = Novice prompts

2 = Expert prompts

reachme_number

Reach-Me number

A number where

the subscriber can

be reached. Calls

can be forwarded

to this number

20 numeric string

referral_number

Referral Number

This specifies a

number at which

the mailbox owner

can be reached.

20 numeric string

referral_type

Referral Type

This specifies

whether the

referral number is

a telephone

number or a beeper

number.

1 0 = Telephone

1 = Beeper

retrieval_order

Retrieval Order

Indicates the order

in which to retrieve

messages from the

mailbox. An

application can

retrieve messages

in the order that

they arrived, or it

can retrieve the

most recent

messages first. The

possible values are:

First in first out

(the order in which

the messages

arrived), Last in

first out (the most

recently received

message first).

1 0 = FIFO (default)

1 = LIFO





saved_messages

Saved

Displays how

many saved

messages are in the

mailbox


send_msg_address

Send message

Indicates that you

will specify the

message address

before or after

recording the

message.

1 0 = Message first, address after (default)

1 = Address first, message after

temp_deputy_number

Temporary assistant number

Temporary

assistant number

20 numeric string

temp_fax_number

Temporary fax number

Temporary fax

number

20 numeric string

temp_pager_number

Temporary pager number

Temporary paging

bureau number

20 numeric string

temp_pager_ref

Temporary pager reference

Temporary pager

reference number

20 numeric string

temp_reachme_number

Temporary Reach-Me

number

The PIN to be used

when receiving

calls transferred via

the reach-me

facility.

20 numeric string

temp_referral_number

Temporary referral number

Temporary

call-forwarding

number

20 numeric string

user_status

Application Status

Indicates whether

the subscriber is in,

out, sick, traveling

or busy

1 0 = in (default)

1 = out

2 = sick

3 = busy

4 = traveling

vpim_address

VPIM address

Address for

SMTP/MIME

delivery

255 text

vpim_msg_del_pref

VPIM MDP

Message delivery

preference for

VPIM

1 0 = Local

1 = Remote

2 = Local and remote





vpim_voice_type

VPIM voice format

VPIM voice format 1 0 = wav

1 = au

2 = 32KADPCM

3 = DT6 elements

4 = DT6 GSM

Creating a subscriber class

Use this procedure to create a subscriber class.

Each subscriber class is identified by a name. The name can be any

combination of 15 characters.

From the Welcome window, click on Configuration —> Subscriber Classes

Defining a subscriber class

1. Click File —> New.

The system displays the Subscriber Class window:



2. Type in the limits to be used for all mailboxes defined by application

profiles that are assigned to this subscriber class.

Maximum number of guest mailboxes

specifies the number of mailboxes that can be assigned to guest

users. For example, if one of your customers runs a messaging

application for which they “buy” 10 mailboxes, but then sublease

five of those mailboxes to other people, those five mailboxes

become guest mailboxes. This limit can be any number between 1

and 9 (the system limit).

Maximum number of messages per mailbox

specifies how many messages an application can accept and store

in one mailbox: any number between 0 and 999 (the system limit).

Maximum distribution lists per mailbox

specifies how many distribution lists can be created for one

mailbox. When a voice application includes the logic for it, callers

can use the telephone to create distribution lists to distribute

messages from a mailbox. You can also use WebSphere Voice

Response to create distribution lists for a mailbox, as explained in

“Creating a distribution list” on page 185). This limit can be any

number between 0 and 90 (the system limit).

Maximum distribution list entries

specifies how many members a single mailbox distribution list can

have. A member can be a mailbox or another distribution list. This

limit can be any number between 0 and 90 (the system limit).

Maximum record time per message

specifies the length of the messages that can be recorded. Don’t set

this higher than the value of the Record Voice Maximum system

parameter in the General parameter group.

Maximum number of greetings per mailbox

specifies how many different greetings the mailbox owner can

record for a mailbox. The maximum number of greetings can be

any number between 0 and 20. The system limit is 20.

Identifying the subscriber class

3. Save the definition.

The system prompts you for a subscriber class name.

4. Type in a name for the class.

5. Click OK. Even though the Subscriber Class window is still displayed, the

system has created the subscriber class and saved it. When you Close the

Subscriber Class window, you will see the new class listed.

creating a subscriber class


Done

After you have created a new subscriber class, you must shutdown and

restart WebSphere Voice Response to make the subscriber class available.

To assign a subscriber class to an application, specify the subscriber class in

the application profile (see “Specifying subscriber classes (optional)” on page

92).

Creating a distribution list

Use this procedure to create a distribution list for a mailbox. This procedure

assumes that you have already created an application profile that includes

mailbox definitions and saved the profile. However, you can combine this

procedure with the procedures in Chapter 5, “Creating an application profile,”

on page 89 and “Creating mailboxes for application use” on page 168 and

create a distribution list for each mailbox after you define the mailbox and

save the definition.

Each distribution list is identified by a four-digit number. The number can be

any combination of the digits 0 through 9.

A distribution list can be public or private. A private distribution list is

reserved for the use of the mailbox owner. A public list can be used by

anyone. However, only the person who created the public list can modify it.

The system limits the number of distribution lists to 90 per mailbox. There is

no limit to the number of members on each distribution list. However, if the

application profile is assigned to a subscriber class, the limitations defined by

the subscriber class may apply. (For more information on subscriber classes,

see “What are subscriber classes?” on page 167.)

To create a distribution list for a mailbox:

1. From the Welcome window, click on Configuration —> Application

Profiles

Selecting the mailbox

creating a subscriber class


2. Open the application profile that defines the mailbox.

The system displays the profile information in the Application Profile

window.

3. Click Options —> Distribution List.

The system displays the Distribution List window.

4. Select the button to the left of the number that identifies the mailbox for

which you are creating the list.

Naming the list

5. Click Add New List.

The system prompts you for a list ID.

6. Type in the 4-digit list ID.

7. Click OK.

The system displays the list ID under the label Distribution List.

8. Click the list ID.

Classifying the list

9. Click the button next to Private or Public.

Adding a mailbox to the list

10. To add a mailbox to the list, click Add Box to List.

creating a distribution list


The system displays a list of application profiles.

11. Click the application profile that you want to add to the distribution list.

12. Click the button next to the mailbox that you want to put on the

distribution list.

13. Click OK.

The system adds the mailbox to the distribution list and displays it as a

member.

14. To add more mailboxes, repeat steps 10 through 13.

Adding a distribution list to the list

15. To add a distribution list to the list, click Add List to List.

The system displays the Add List to List window with a list of

Application Profiles on the left.

16. Click the application profile and then click a Mailbox.

The system displays all the distribution lists that belong to the selected

mailbox:



17. Click the distribution list that you want to add to the current distribution

list.

18. Click OK.

The system adds the distribution list as a member of the current

distribution list.

19. To add more distribution lists, repeat steps 15 through 18.

Done

20. When you are finished, click Close.

The system displays the Application Profile window.

21. Save the application profile. Even though the Application Profile window

is still displayed, the system has created the distribution list for the

mailbox and saved it.



Chapter 13. Telecommunications Devices for the Deaf

The Telecommunications Device for the Deaf (TDD) is a telephony device

with a QWERTY keyboard and a small display and, optionally, a printer.

Instead of speaking into a mouthpiece, the caller types messages on the

keyboard; instead of hearing a voice from the receiver, the caller views the

messages on the screen, and can print them for later reading. Usually, at both

ends of the conversation, TDDs are being used.

Although the TDD itself does not generate DTMF tones, most users use a

TDD in conjunction with a telephone that generates tones, and probably think

of the whole thing as a TDD.

TDD support can be ordered as an optional feature of WebSphere Voice

Response.

WebSphere Voice Response’s support is designed to operate with devices

meeting the EIA Standard Project PN-1663 TDD Draft, 9 June 1986

specification.

Making voice applications available to TDD users

Enabling your WebSphere Voice Response applications to communicate with

TDDs makes your services and information available to callers who are

unable to use an ordinary telephone. WebSphere Voice Response can send

characters as if it were another TDD. The voice application can recognize and

generate TDD characters dynamically.

Figure 26. Two people communicating using TDD


TDD voice segments and prompts

To make a voice application available to TDD users, you have to add a new

language to WebSphere Voice Response. The only TDD language supplied is

“U.S. English TDD”. If you want to support TDD users in other languages,

you can define other TDD languages. A TDD language is a voice-only

language, containing only voice segments, prompts, and voice tables. It does

not contain any window text.

Voice segments? Yes, the signals that are transmitted along the voice channel

to the caller are stored in exactly the same way as ordinary voice segments.

They can be generated automatically from the text descriptions of the default

(spoken) voice segments in a custom server using CA_Get_Segment_Info()

and CA_TTD_Create-Segment(). This uses the same mechanism as that used

for converting text to speech, but TDD characters are generated instead of

spoken words. Voice segments are played to the caller using the PlayPrompt

action, just as spoken voice segments are.

To add a TDD language to the system, see the WebSphere Voice Response for

AIX: Configuring the System guide.

TelephoneNetwork

DataCommunications

Network

Information

VoiceProcessing

LocalArea

Network

State Table

WebSphereVoice

Response

CustomServer

pSeries

Caller

TDD

TDDCharacters

Figure 27. How WebSphere Voice Response interacts with a TDD

making voice applications available to TDD users


The prompts need to be tailored for usability with a TDD. For example,

whereas a state table might usually speak “one thousand three hundred and

ninety-two dollars”, it would be more appropriate for a TDD user to see

“$1,392”. The supplied U.S. English TDD language database includes system

prompts tailored in this way

To create tailored versions of prompts, you must create language-specific

prompts, in the same way as you would for any other language, as described

in the WebSphere Voice Response for AIX: Application Development using State

Tables reference manual.

TDD custom server subroutines

There is a set of custom server subroutines for use in applications that work

with TDDs:

v CA_TDD_Create_Segment() works like CA_Create_Segment(), but the

segment is created from an ASCII text string you supply, instead of from

digitized voice data.

v CA_TDD_Play_String() works like CA_Play_Voice_Stream(), taking an

ASCII string and playing it as TDD characters directly on a voice channel.

v CA_TDD_Get_String() works like CA_Record_Voice_Stream(), decoding

the input signal and returning an ASCII string.

These subroutines are included in the library /usr/lpp/dirTalk/sw/lib/libtdd.a. To use these subroutines, you must explicitly link in the libtdd.a

library in the following way:

1. Open the Properties window of the custom server that uses the TDD

subroutines.

2. In the Object Libraries pane, add the following entry:

${VAE}/sw/lib/libtdd.a

This puts the libtdd.a reference in the custom server makefile.

For detailed information about the subroutines, see the Custom Servers manual.

There is a sample TDD custom server application that shows you how to use

the subroutines. The sample is called TDD_sample; it is supplied as an import

file, TDDSample.imp in the samples directory /usr/lpp/dirTalk/sw/samples,

and must be imported as described in “Importing application objects” on page

47. The sample application uses a shell script, TDD_talk, which is also

supplied.

You can make many of your voice applications enabled for TDD users, but the

TDD technology imposes some restrictions :


Chapter 13. Telecommunications Devices for the Deaf 191

v TDD segments are stored in uncompressed format, because the data would

not meet TDD specifications after compression and decompression. So there

is no support for voice messages, audio names, or user greetings.

Note: When playing TDD segments or using a custom server to receive

TDD input ensure that you set the System : Voice Compression Type

system variable (SV50) to 1, and the System : PlayPrompt

Compression Type system variable (SV182) to 0.

v In addition, uncompressed segments are sensitive to the voice encoding

scheme used on the trunk interface. The supplied U.S. English TDD

segments are only suitable for T1 trunk interfaces. If you create your own

segments using CA_TDD_Create_Segment(), the appropriate encoding, for

E1 or T1, is automatically selected.

v A TDD cannot generate DTMF tones. You need to adapt your existing

DTMF-based applications to accept TDD strings as input from the caller.

Valid TDD characters

A TDD has a limited character set consisting of:

the space character the uppercase alphabet the digits 0 through 9

- (hyphen) : (colon) ? (question mark)

$ (dollar) ( (left parenthesis) + (plus)

’ (single quote) “ (double quote) . (period)

, (comma) ) (right parenthesis) / (slash)

! (exclamation mark) = (equals) ; (semicolon)

Lowercase alphabetic characters are automatically folded to uppercase.

Your application must send only valid characters to a TDD. The TDD also

supports the following control codes :

BACKSPACE <BS>

LINEFEED <LF>

CARRIAGE RETURN <CR>

It is recommended that your application inserts a <CR><LF> sequence after at

most 68 printable characters, to help the TDD printer to display the messages

properly.



Chapter 14. Background music

WebSphere Voice Response includes a background music subsystem called the

juke box, which you can use to play background music in your applications.

This chapter tells you how to implement background music using the juke

box:

v “Why use background music?”

v “Using the WebSphere Voice Response Juke Box” on page 198

v “Adding background music to a state table” on page 200

v “Getting music into WebSphere Voice Response” on page 204

To hear what background music sounds like, import the /usr/lpp/dirTalk/sw/samples/juke_box.imp, and then run the sample state table

Musical_Welcome. Also, look at this state table to see how it defines music,

starts and stops music, and changes the volume.

If the supplied juke box does not satisfy your requirements, you can

customize it, or you can write your own background music subsystem. Details

are available on request: contact your IBM representative.

Why use background music?

Some requests take a while to process: playing background music during such

periods can help to indicate to the caller that the application is still working

on the request. Your organization may already play music on hold, and your

decision to play music during voice applications, and your choice of music,

should take this into consideration. You may decide to play neutral

easy-listening music that suits the image of your organization, or you may

decide to play something related to your latest advertising campaign. Your

“background music” does not have to be musical: it could be spoken

information about your product, a dialog or interview about it, or even just

“keyboard noises”, if you want to make it sound as if the request is being

processed by a person!

In this chapter, the word tune is used to mean a piece of music or other

uncompressed audio data saved in a format that WebSphere Voice Response

can play on a music channel. Tunes are held as voice segments or in element

files.

Note: It is your responsibility to obtain the necessary permission from the

owner of any rights to the music you intend to use, such as copyright


in the music and recording. However, you have permission to use the

sample tunes supplied with WebSphere Voice Response.

How many tunes can you play at once?

The background music is played on up to eight background music channels

per telephony trunk, while the prompts are played on the regular telephony

channels (as shown in Figure 28). Any application can use any one of the

music channels, so you can have all applications playing the same tune or up

to eight applications can be playing different tunes; one application can play

only one tune at a time, but can change from one tune to another.

However, the use of music channels does have a performance impact on the

telephony channels.

In the example shown in Table 9 on page 195, the applications on channels 1,

2, 4, 5, and 9 are playing Tune 1, while the applications on channels 3, 7, and

8 are playing Tune 2. At the same time, on channel 6, an application plays

Tune 3, followed by Tune 4, finishing up with Tune 1.

TelephonyChannel

BackgroundMusic

MusicChannel

pSeries

Caller

TelephoneNetwork

VoiceProcessing

BackgroundMusic

Subsystem

State TablePrompts

CustomServer

Database

File

Tunes

Tunes

WebSphereVoice

Response

Figure 28. Using background music

why use background music?


Table 9. Applications simultaneously playing tunes from music channels

Telephony Channels

Music Channels

Tune

1

Tune

2

Tune

3

Tune

4

Tune

5

Tune

6

Tune

7

Tune

8

1 Application A Play


3 Application B Play



6 Application C Play

1st

Play

2nd

Play

3rd




up to 24 T1 or 30 E1

The applications determine when to turn music on and off, and what music to

play. However, the application cannot control the point at which the music

starts and stops, it can only control the volume. It’s as if the application was

tuning into a radio station that is already broadcasting music. A music

channel continues to play the same tune until the last application turns it off.

The music channel is then free to play a different tune.

When should you play background music?

The most common use of background music is to play something while the

caller is waiting for something to happen. Playing background music during

prompts is not recommended.

The background music is effectively mixed in with the prompts: the caller

should be able to hear both if both are playing at once. Figure 29 on page 197

shows what the caller is hearing at each stage in the interaction, on the

telephony channel and on the music channel. If required, you can turn down

the music during prompts.

how many tunes can you play at once?

Chapter 14. Background music 195

How loud is the background music?

Normally, background music is played at a lower volume than the prompts,

but the application can determine the volume at which the music is played,

and can even play the “background” music louder than the prompts.

(WebSphere Voice Response ensures, however, that the combined volume of

prompts and background music does not exceed the maximum volume for

your telephone network.)

The volume of the prompts can be changed during the course of the

application, and can fade in and out gradually. While the music is fading in or

out, the application can either wait or continue with the next action. If the

application continues with the next action, and the next action is a

PlayPrompt, the prompt will start while the music is fading out, giving a

voice-over effect.

The action of one application using a music channel does not affect the way

other users of that music channel hear the music.

T1 A-law systems

T1 A-law systems rely on the fact that A-law encoded voice can be converted

by WebSphere Voice Response to µ-law. If you are using such as system,

provided you obey the rule that music segments, elements, or data must use

the same encoding law as the other output (voice segments and so on) from

WebSphere Voice Response, all will work as planned.

Voice interrupt detection and speech recognition

The echo from background music may be picked up by the voice interrupt

detection algorithm or the speech recognition algorithm, causing

unpredictable results. For this reason we recommend that you do not use

background music with either voice interrupt detection enabled or during

speech recognition.

If you want to use background music with voice interrupt detection, either

lower the volume of the background music to suit the current voice interrupt

detection threshold, or raise the voice interrupt detection threshold. This

should result in a level of echo which is ignored by the voice interrupt

detection algorithm. When testing your application, use the loudest music you

have, or a peak in the background music volume may cause problems later.

how loud is the background music?


Callers interactionwith the application

Caller listensto prompt

Application waitsfor caller’s input



Caller listensto background music

while the requestis being processed

Caller listensto background music

while the requestis being processed




What the callerhears on the

music channel

Background musicquieter thanthe prompt



Background music


Background music

What the callerhears on the

telephony channel

Prompt

Prompt

PromptPrompt

Prompt

Figure 29. What the caller hears at each stage in the interaction

voice interrupt detection and speech recognition


Using the WebSphere Voice Response Juke Box

The Juke Box comprises:

v The Juke_Box custom server

v Two music player programs, pl_seg and pl_elem used by the Juke_Box

custom server

Two sample tunes and a utility custom server, cvelem, for converting a static

voice file to an elements file (that can be used by WebSphere Voice Response)

are also supplied.

The Juke_Box custom server

Using the Juke_Box custom server your state table can start and stop a tune

being played and add tunes to the music catalog dynamically.

The Juke_Box custom server maintains a music catalog of tunes. This catalog

contains entries from a configuration file and entries added dynamically by

state tables. Each entry in the music catalog contains details of the music title,

the name of the music player it is to use, and a list of parameters.

When your state table asks the Juke_Box custom server to start playing a

tune, it starts a music player process which remains active until your state

table tells the Juke_Box custom server to terminate it.

The Juke_Box custom server handles requests from all state tables for all

packs on a WebSphere Voice Response system, so you need only one copy of

the custom server running.

Starting and stopping the Juke_Box custom server

Each time WebSphere Voice Response starts, the Juke_Box custom server is

started automatically. If you need to stop and restart the Juke_Box custom

server, for example, to use a different configuration file, follow the

instructions for starting and stopping custom servers in the WebSphere Voice

Response for AIX: Configuring the System guide.

Stopping the Juke_Box custom server stops all music players, and releases any

resources used by them. Note that callers may hear their tunes cut off when

this happens.

The Juke Box configuration file

When the Juke_Box custom server starts, it reads a configuration file to build

the music catalog. The supplied music_catalog configuration file is ready to

use on T1 systems. The music_catalog_u_law file is a backup copy of this file.

If you are using an E1 system, you must remove the music_catalog file, and

copy the music_catalog_a_law file:

cp music_catalog_a_law music_catalog

using the WebSphere Voice Response Juke Box


Defining a tune in the configuration file

Before playing a tune, it must be defined to the Juke_Box custom server,

either in the configuration file or dynamically, by the state table.

You modify the configuration file using a text editor. The Juke_Box custom

server reads the configuration file only when it starts, so to make changes

effective immediately you must stop and restart the Juke_Box custom server.

The name of the configuration file is passed to the Juke_Box custom server’s

main() function as a parameter. If you want to use a configuration file other

than the default (music_catalog), you must change the properties on the

Juke_Box custom server and restart it.

Note: If you are using the Juke_Box custom server on a cluster of WebSphere

Voice Response systems that are configured as a single system image,

files that the configuration file specifies must exist either:

v On the database server node of the single system image

or:

v On every system that is part of the single system image

If you don’t specify a configuration file, or there is a problem with it, the

Juke_Box custom server generates a yellow alarm. The Juke_Box custom

server continues without a configuration file, that is, it starts with an empty

music catalog. You can still use background music in your application by

configuring tunes dynamically from your state table.

Configuration file format

Each tune in the configuration file has three fields; each field is surrounded by

double quotation marks, as shown in Table 10 on page 200. Lines starting with

# are treated as comments; blank lines are ignored. For an explanation of the

music title, music player name, and parameters, see the parameter

descriptions for the juke_box_configure_music custom server command in

the WebSphere Voice Response for AIX: Application Development using State Tables

reference manual.



Table 10. Example of a configuration file for the Juke_Box custom server

# Configuration File for use by Juke_Box custom server.

# music title music player name parameters

# =========== ================= ==========

“WebSphere Voice Response Theme 1” “juke_box_dir/pl_seg” “-l 1 -d music_u_law -s 1 -a”

“WebSphere Voice Response Theme 2” “juke_box_dir/pl_seg” “-l 1 -d music_u_law -s 2 -a”

“WebSphere Voice Response Theme 3” “juke_box_dir/pl_elem” “-f juke_box_dir/dt_theme_1_u_law.elem -a”

“WebSphere Voice Response Theme 4” “juke_box_dir/pl_elem” “-f juke_box_dir/dt_theme_2_u_law.elem -a”

# End of the configuration file.

Adding background music to a state table

Figure 30 on page 203 shows a simplified overview of the actions involved in

using background music in a state table.

Use pairs of SendData and ReceiveData commands to send commands to the

custom server to:

v Define a tune (juke_box_configure_music command)

v Start playing a tune (juke_box_start_music command)

v Stop playing a tune (juke_box_stop_music command)

Use SendData to pass these commands to the Juke_Box custom server, and

ReceiveData to check return codes.

Use the ControlMusic command to increase or decrease the volume of the

tune that is playing.

Prerequisites

1. If the music voice segment you use is specific to your state table, store the

music data in a segment before you write your state table. This can be

packaged to be imported and exported with the state table.

2. Unless you want to define tunes dynamically in the state table, you can

define your tunes in the configuration file. However, you should always

define a default tune in the configuration file, so that if an application fails

to dynamically configure a tune, there is always a tune configured and

available to be played by the application.

3. Ensure that a call has already been connected. The Juke_Box custom server

rejects SendData requests unless a call is already established or connected.

State table

Start



1. Use the OpenHostServerLink action to set up a link between the state

table and the Juke_Box custom server. Check that the action succeeds. If

it fails, let your application continue without using background music.

2. If the tune you want to play is in the configuration file, go to step 5.

Define a tune dynamically

3. Use the SendData action, specifying the juke_box_configure_music

command. For details, see the WebSphere Voice Response for AIX:

Application Development using State Tables.

4. Use the ReceiveData action and then check the return code. If the

Juke_Box custom server was unable to configure the tune, don’t ask the

Juke_Box custom server to play it. Instead, either use a tune that you

know is available, or don’t use background music for the rest of the call.

Don’t let your state table fail because it could not configure a tune. Make

your application as robust and forgiving as you can.

Start playing a tune

5. Use the SendData action, specifying the juke_box_start_music command

to tell the Juke_Box custom server which tune to play. For details, see the


reference manual.

6. Use ReceiveData to get the return code and check that the tune starts to

play.

7. If the tune doesn’t start playing, set up alternative paths for your state

table to follow. For example, if all the music channels are in use, you may

want your state table to use a “music-of-the-day” default tune (if your

system has this set up).

8. Take appropriate action for all possible results from the SendData and

ReceiveData actions.

Fade the tune in

9. Use the ControlMusic action to increase the volume of the tune while it is

playing. The initial volume is low: increase it so that the tune can be

heard.

Smooth Volume Change

If you want the background music in your application to fade

smoothly, use ControlMusic with a non-zero value for the Fade

Time parameter . You can fade the music in two ways:

v Wait for the fade action to complete before proceeding with the

next action in the state table.

v Proceed with the next action in the state table, while the music

fades.

adding background music to a state table


Instant Volume Change

To change the volume instantly, use ControlMusic with the Fade

Time parameter set to 0. This is not recommended, as it can cause

“clicks” on the line, which can be disconcerting to the caller.10. Take appropriate action for all possible results from the ControlMusic

action.

Change Smoothly from One Tune to Another

11. If you want to change from one tune to another smoothly, use two

ControlMusic actions in your state table. In the first action, fade out the

current tune by setting the fade option to wait until fade actions complete

and set the volume to 80dBm (silence). In the second action fade in the

new tune (use wait until fade actions complete or not, as you want).

12. Take appropriate action for all possible results from the ControlMusic

action.

Perform normal application activities

13. Some actions work with background music playing to the caller, some

fade out background music before the action starts, and fade in the music

when it is complete. You can override the automatic fading using the

system variables (see Table 22 on page 327).

Fade the tune out

14. When your state table has finished with the tune, use the ControlMusic

action to fade the music to silence. Use a value of 80 dBm for silence.

Stop playing a tune

15. If the tune plays successfully, make sure that your state table stops it

playing (to release resources) before closing the host server link.

16. Use the SendData action, specifying the juke_box_stop_music command

to tell the Juke_Box custom server when you have finished using a tune,

so that the resources can be released and reallocated. For details, see the


reference manual.

17. Use ReceiveData to get the return code and check that

juke_box_stop_music command was successful.

Note: The tune does not stop if it is still playing on another channel. In

this situation, it stops when a juke_box_stop_music command has

been received by the custom server from each of the channels on

which the tune is playing. (In effect, the custom server needs to

receive a juke_box_stop_music command for every

juke_box_start_music command that was issued.)



Cleaning up

18. Use the CloseHostServerLink action, specifying the Juke_Box custom

server.

19. End the call, free any resources that the application used, and terminate.

Debugging your state table

To debug your state table, use the state table debugger. You may also need to

trace the custom server, and you will probably find it useful to monitor the

background music channels.

ControlMusic (fade out)

CloseHostServerLink

OpenHostServerLink

(You don’t need to do thisif your tune is in the configuration file)

Add music titleto the music catalogue dynamically

Confirm that the title was added

SendDate juke_box_configure_music

ReceiveData juke_box_configure_music

Finish with the tune

Confirm that the tune has stopped

SendData juke_box_stop_music

ReceiveData juke_box_stop_music

Make the tune available

Confirm that the tune is available

SendData juke_box_start_music

ReceiveData juke_box_start_music

Play tune to caller

ControlMusic (fade in)

Figure 30. Schematic overview of part of a state table using background music



Errors generated by the Juke_Box custom server are listed in the WebSphere

Voice Response for AIX: Problem Determination guide.

Tracing the custom server

Use custom server trace to capture information about how your custom server

is working with your state table. See the WebSphere Voice Response for AIX:

Custom Servers reference manual for details.

You can select entries for the Juke_Box custom server only from the custom

server trace and write them to a the file ca.trace using the command:

print_trace | grep juke_box > ca.trace

To select trace entries for the segment music player use:

print_trace | grep pl_seg > ca.trace

To select trace entries for the element music player use:

print_trace | grep pl_elem > ca.trace

Monitoring background music

See the WebSphere Voice Response for AIX: Configuring the System guide for

more information.

Use the following procedure to monitor background music:

1. From the Welcome window, click on Operations —> System Monitor

2. Click the pack you want to look at.

3. Click Music Available from the pop-up window.

The Music Available window shows a list of tunes that are currently playing,

and their status.

Getting music into WebSphere Voice Response

To use background music, you need music or other audio data in a format

that WebSphere Voice Response can use. Figure 31 on page 206 shows some

possible sources of music and how to convert your source.

Supplied tunes

Two tunes are supplied in both segment and element formats.

music_u_law is the default voice directory supplied for use on µ-law systems

(T1). This voice directory contains the following segments:

v WebSphere Voice Response theme 1

v WebSphere Voice Response theme 2



A music_a_law voice directory is supplied for use on A-law systems (E1).

The same tunes are in the $DB/current_dir/ca/juke_box_dir/ directory as

element files. They are:

v WebSphere Voice Response theme 3 (the same tune as theme 1)

v WebSphere Voice Response theme 4 (the same tune as theme 2)

getting music into WebSphere Voice Response


Follow the batch voice import processdescribed in the State Tables, Prompts,and Voice Segments reference manual.When converting tunes, edit the ASCIIindex file to check that the tune does notspread over several segments. Alsocheck that there is only one tune persegment. When you make the ASCIIdescription file (using bvi_desc) provide atitle for the music.

ElementFile

.WAV file


database segment

music player(not supplied)

bulk voice import utility

CA_Play_Voice_Stream()custom server routine

CA_Play_Voice_Elements()custom server routine

music channel on WebSphere Voice Response

cvelem utility

dynamic blocks ofaudio data

(uncompressedm-law or A-law)

bvi_rec utility bvi_aiffbvi_wav

.AIFF file

Ultimedia Audioadapter from DAT,microphone, tape,

CD, or line-in

static voice file8kHz,16-bitbig-endian

pl_elem (music player)called by the Juke_Box

custom server

linear audio datafile from another

system

pl_seg (music player)called by the Juke_Box

custom server

Figure 31. Getting tunes into WebSphere Voice Response for background music

getting music into WebSphere Voice Response


Chapter 15. TDM connection management

TDM connection management helps to coordinate the making and breaking of

time-division multiplex (TDM) connections between resources such as channels

on packs, and channels on digital signal processor (DSP) adapters. Custom

server subroutines allow you to write applications that exploit

industry-standard time-division multiplex (TDM) bus (TDM bus) capabilities

such as matrix switching, one-call fax, speech recognition, and text-to-speech.

In addition, TDM connection management also enables you to implement

facilities such as tromboning: connecting a caller to an agent or other service,

via WebSphere Voice Response. This type of connection can be used even

when the switch does not support call transfer.

WebSphere Voice Response supports the TDM bus, through the Digital Trunk

Telephony Adapter (DTTA) and the Digital Trunk Extended Adapter (DTXA).

Support for other adapters can be added by writing a connection server.

Concepts

This section introduces the concepts of TDM connection management.

Ports

A port is one end of a 64 kbps unidirectional stream, which can be attached to

the TDM bus. Ports can be seen as sources, which put voice on to the TDM

bus, or sinks which take voice data from the TDM bus. Examples of source

ports are:

v The stream received from a caller via a telephony channel and placed on

the TDM bus by the DTTA or DTXA.

v The stream that may be generated by a fax card.

An example of a sink port is:

v The stream taken from the TDM bus by a fax card to decode a fax.

Port sets

Often, an application needs to connect multiple streams. For example, a

custom server for matrix switching must connect caller A’s transmit stream to

caller B’s receive stream and vice versa. For this reason the concept of a port

set is useful. A port set is a set of one or more ports which may need to be

connected to a complementary port set as a single operation. Examples of port

sets containing more than one port are:

v The transmit-receive pair of a telephony channel on a DTTA or DTXA.


v For speech recognition with barge-in and the ability to play beeps as a

prompt to the caller, a speech recognition port set requires three ports:

1. A sink to accept the caller’s speech.

2. A sink to accept a copy of the prompt being played to the telephony

channel, which is needed to perform echo cancellation.

3. A source to play beeps to prompt the caller that a recognizer is

activated.

Port sets are defined and named in a configuration file supplied as part of the

software support for an adapter. You do not need to modify this file, but you

may need to refer to it to understand what port sets have been defined. The

custom server subroutines accept port set names as parameters. A port set

may consist of a single port. A port can be a member of several port sets as it

may need to be used in different combinations by different applications. Port

sets to be connected must be compatible, that is they must contain a

complementary number of sources and sinks.

Resource groups

A resource group usually corresponds to a physical entity such as an adapter,

E1 or T1 interface or a DSP. Each resource group contains a number of port

sets. In a running system, there may be multiple instances of each defined

resource group. TDM connection management will create multiple instances of

the resource group, depending on how many adapters, E1 or T1 interfaces or

DSPs are installed.

For example, a fax adapter may support 12 fax channels. This would be

defined as one resource group containing 12 port sets. If two fax adapters are

installed, there would be two resource groups, each with 12 port sets.

TDM bus

TDM bustimeslots(64kbps)

Adapters

Source Sink

Ports

Port Set ComplementaryPort Set

Figure 32. Ports, port sets, sources, and sinks

concepts


The main benefit of the resource group concept is that a resource group is

only defined once when a new resource group type is configured, and the

actual number of resource groups in the system can be discovered

dynamically at system startup. No configuration changes are needed just to

add a new instance of an existing resource group.

Port set naming

The custom server subroutines relating to TDM connection management

require port set names as parameters. A standard naming scheme is adopted:

ResourceGroupName.N.PortSetName.M

ResourceGroupName

is the name of the resource group type, as specified in a

resource_group_name= keyword entry within a configuration file.

N is the instance number of that resource group within the system

(instance numbers begin at 1)

PortSetName

is the name of the port set type, as specified in a port_set= keyword

entry within a configuration file.

M is the instance number of that port set within the resource group

(again, instance numbers begin at 1).

For example, a configuration file, /usr/lpp/dirTalk/sw/tslot/config/dtpack.rg, defines the port sets associated with digital trunk adapters. The

resource group name for all of these port sets is dtpack. A port set called

channel consists of two ports: a sink port (raw_out) which takes speech from

the TDM bus and plays it to a caller, and a source port (raw_in1) which puts

a caller’s voice onto the TDM bus. This port set can be used in applications

such as matrix switching, or one-call fax. The first channel on the first digital

trunk adapter of a WebSphere Voice Response system is called:

dtpack.1.channel.1 .

The TDM sample application

WebSphere Voice Response includes a sample application, which demonstrates

how you can use TDM connection management to implement your own

applications.

This application is similar to the calling card service provided by many

telephone companies. A customer dials in to the calling card application, and

enters the telephone number to which they wish to connect. In a real calling

card service, the customer would also provide card details and a personal

identification number, but these are omitted from the sample application.

concepts


After the customer has entered a phone number, WebSphere Voice Response

places a second call to the specified number, and as soon as this call is

answered, the two calls are connected via the TDM bus. The customer can

now talk to the called party.

This arrangement is sometimes called a trombone, or hairpin, a reference to

the shape of the voice path between the two parties; from the switch to the

IVR via one circuit, and returning from the IVR to the switch, via a different,

parallel circuit.

WebSphere Voice Response stays on the line during the conversation, and can

monitor DTMF key presses made by either party. This feature is not used in

the sample application, but in a real service, DTMF keys could be used to

request additional services, such as conference calling, or putting a caller on

hold.

WebSphere Voice Response also detects when either party hangs up the call.

When this happens, the application disconnects the TDM bus connection,

makes a short announcement to the remaining party, and then terminates the

remaining call.

Prerequisites

v A PCI WebSphere Voice Response system with one or two DTTA or DTXA

adapters. If two adapters are installed they should be connected using the

supplied H.100 ribbon cable. If only one is installed, an H.100 cable is not

needed.

Note: DTTAs and DTXAs cannot coexist in the same system unit.

v A connection to a switch or public network using a trunk that supports

both incoming and outgoing calls.

v Two telephones attached to the same switch or network. In the instructions,

these are referred to as Phone A and Phone B.

v A third valid phone number, to be used as an application profile ID.

Procedure


Importing the application

2. Click Application —> Import.

3. Click the /usr/lpp/dirTalk/sw/samples/IBM_Trombone.imp file.

Creating an application profile

4. Open the Trombone application.

The system displays the Application (Trombone) window.

TDM sample application


5. Click Object —> New —> Application Profile.

The system displays the Application Profiles window followed by the

Application Profile window.

6. Type any name in the Name field (for example, “Trombone Sample”).

7. Click the State Table button and then TromboneIn.

8. Click OK.


10. Specify the phone number to be used as the Application Profile ID.

11. Click OK.

12. In the Application (Trombone) window, click View —> Refresh.

The system displays the Application Profiles folder, with the new

Application Profile icon inside it.

Building and installing the custom server

13. Open the TromboneCS custom server.

14. Click Utilities —> Build.

15. Click Utilities —> Install.

Note: Full instructions for building and installing custom servers are

included in the WebSphere Voice Response for AIX: Custom Servers

reference manual.

Running the Application

16. Pick up Phone A’s handset and dial the application profile ID.

WebSphere Voice Response answers the call and prompts you to input a

telephone number.

17. Enter Phone B’s number, followed by a # key.

After a short delay, Phone B rings.

18. Pick up Phone B’s handset.

The two calls are connected via the TDM bus completing a voice path

between the two telephones.

Designing an application

A TDM application consists of:

v State tables

v Custom servers

TDM sample application


State tables

State tables manage the interaction with callers. State table actions are used to

answer calls, and to place outgoing calls. They may send requests to custom

servers to invoke additional facilities, such as TDM connections.

Custom servers

TDM port sets are connected and disconnected by custom server library

subroutines, CA_TDM_Connect() and CA_TDM_Disconnect(), therefore an

application using TDM connection management must contain at least one

custom server. The custom server is responsible for connecting TDM port sets

in response to requests from state tables, and for disconnecting port sets on

request from an state table, or cleaning up TDM connections in error

conditions.

Custom server subroutines

WebSphere Voice Response provides two custom server subroutines for

connecting and disconnecting port sets:

CA_TDM_Connect()

Makes a connection between two port sets via the TDM bus.

CA_TDM_Disconnect ()

Breaks an existing TDM bus connection between two port sets.

The design of the sample application

The TDM sample application uses three different state tables, and one custom

server.

TromboneIn state table

TromboneIn answers the customer’s call and prompts the customer to enter a

telephone number. When the customer has entered the number, TromboneIn

makes a request to the custom server to dial the number on a second channel,

and when the call is answered, to make a TDM connection between the two

channels. TromboneIn then waits for completion of this custom server request.

When the custom server confirms that it has completed this request,

TromboneIn invokes the TromboneMonitor state table (described later) to

monitor activities of the calling party.

TromboneOut state table

TromboneOut is invoked by the custom server dial the telephone number

specified by the customer. The number is passed to TromboneOut by

parameter. TromboneOut uses a MakeCall action to select a free outgoing

channel and dial the telephone number. The MakeCall action completes either

when the call is answered by the called party, or when the call fails, for

example because the number is invalid or busy, or there are no outbound

lines available. On completion of the MakeCall action, TromboneOut notifies

designing an application


the custom server of the outcome of the call attempt, and then invokes the

TromboneMonitor state table to monitor subsequent activities of the called

party.

TromboneMonitor state table

TromboneMonitor monitors one channel for DTMF keys, caller hangup events,

or asynchronous channel events from the custom server. If a caller presses a

DTMF key, the name of the key is announced to the caller; this feature does

not serve any real purpose, but demonstrates how a real application could use

DTMF keys to invoke service features. In this application, custom server

channel events are used to report that the other party has hung up, so when

TromboneMonitor receives such an event, it plays a brief message to the caller

on this channel, then exits. If the party on this channel hangs up, the state

table exits.

TromboneCS custom server

TromboneCS is a custom server which manages the relationships between

different channels, including making and breaking TDM connections between

them. TromboneCS provides two user functions which may be used by state

tables, and one system function:

t_outdial()

This function represents a request to allocate a new channel and dial a

specified phone number on that channel. TromboneCS executes this

by allocating a new channel process (CHP) and executing the

TromboneOut state table with that new CHP. t_outdial() sends a

response to the calling state table when the outbound call attempt is

complete, indicating whether the attempt succeeded or failed.

t_outdial_complete()

This function represents an indication from a state table that an

outbound call attempt has been completed, and whether the attempt

succeeded or failed. There is no response to this user function.

t_chsl()

This is a CloseHostServerLink function, which is invoked

automatically when state tables close their connection to TromboneCS,

or exit from the main state table.

TromboneCS uses these three functions as events in a state machine which

coordinates the making of the trombone connection between the two parties,

and breaking that connection when one of the parties hangs up. Figure 33 on

page 214 summarises the steps involved in making and breaking the

connection.



Channel A

Incomingcall

TromboneIn

SendDatat_outdial(ph_num)

AnswerCall

ReceiveData

GetData(ph_num)

Callerhangs up

TromboneMonitor

TromboneIn

WaitEventfor DTMF,Hangup,

or Host event

ExitStateTable

CloseEverythingt_chsl()

TromboneCSCustom Server

Destroytrombone

data structure

Channel B

Answered

TromboneOut

SendDatat_outdial

_complete()

MakeCall(ph_num)

TDMConnectt_outdialresponse

Createtrombone

data structure

WebShereVoice

Responsehangs up

TromboneMonitor

TromboneOut

WaitEventfor DTMF,Hangup,

or Host event

ExitStateTable

PlayPrompt"disconnecting"

CloseEverythingt_chsl()

TDMDisconnectReport

Channel Event

Figure 33. Making and breaking a trombone connection



Implementation notes

This section provides more detailed information about the implementation of

the sample application, and suggestions for developing your own applications

which use TDM connection management.

Error handling

Error handling in the sample application is simplified to make the code easy

to understand. Errors in the custom server are treated as fatal and the custom

server will exit. Errors in the state tables cause a “technical difficulties”

announcement to be played to the caller and the call terminates. If you

develop a production application based on this sample, you should enhance

the error handling to improve reliability and usability.

ASCII state tables

TromboneIn, TromboneOut and TromboneMonitor were written as ASCII state

tables. The source code for the state tables is in the custom server directory,

$CUR_DIR/ca/TromboneCS_dir. The ASCII state table format makes it easier

to understand how the application works. If you want to change the state

tables, you may find it easier to change the ASCII versions, and import the

modified state tables, rather than making changes using the State Table

window.

TromboneCS state machine

Each “trombone”, that is, connection between a calling and a called party, is

described by a state machine, so that the trombone moves between various

states according to events, which are the custom server user functions.

Figure 34 shows the states and events in this state machine.

Data structures

TromboneCS uses two main data structures:

trombone

A structure which holds the status of one trombone, including the

link_id of each of the two channel processes involved, the

connection_id returned from CA_TDM_Connect(), the current state of

the connection, and a copy of the t_outdial() request which initiated

t_idle

t_chsl() t_chsl()

t_outdial()

t_outdial_complete()

t_dialing

t_connectedt_disconnected

Figure 34. The TromboneCS state machine



this trombone, and which is modified to become the t_outdial()

response when the trombone is connected.

t_array

An array of pointers to trombone structures, one for each channel

process in the system. This provides a way to access the trombone

data structure for a particular channel process, by using the link_id as

an index into the array. A null pointer in this array means that the

corresponding channel process is not involved in a trombone

connection.

Custom server main() function

When you develop a custom server, you can choose to have WebSphere Voice

Response create the main() function, or provide your own. TromboneCS

provides its own main() function, because the system generated main()

assumes that each user function will return a response to the state table when

the user function returns. TromboneCS cannot return a response to the state

table as the t_outdial() function returns, because it must wait for the

t_outdial_complete() message from TromboneOut to discover whether the

outdial attempt was successful. The main() function is modified compared to

the system-generated main() to take account of this.

TDM connection token

When you make a TDM connection using CA_TDM_Connect(), you have to

supply an unsigned integer as a token for that connection. The same token

must be supplied when the connection is broken, either by

CA_TDM_Disconnect() or by making a new connection involving the same

ports. This simple security mechanism prevents unauthorized custom servers

from breaking your connections. As a custom server writer, it is your

responsibility to choose a token for your connections. The sample application

uses a four character string, “TROM”, and casts this into an unsigned integer

for use as a token.

Cleaning up TDM connections

TDM connection management is designed to break TDM connections

automatically when a caller involved in the connection hangs up. This

protects against callers hearing spurious speech when a call ends and the

telephony channel is reused. However, resources associated with the

connection remain allocated until the connection has been explicitly

disconnected by a call to CA_TDM_Disconnect(). So it is your responsibility as

a custom server writer to disconnect any TDM connections you establish. A

good way is to keep track of connections made by each channel process, and

to provide a CloseHostServerLink function. When the custom server is

notified via this function that a channel process has detached from the custom

server, it can disconnect all TDM connections associated with that channel

process. This technique is illustrated by TromboneCS.



Notifying hang-ups to the partner channel process

When one of the parties connected by a trombone hangs up, the

TromboneMonitor state table interacting with this party detects the hangup

event and exits. But the application must also provide a way for this hangup

to be notified to the state table interacting with the other party. There are two

steps in this process:

1. TromboneCS detects that the hung-up party’s state table has terminated, as

the t_chsl() function is called.

2. t_chsl() uses the CA_Report_Channel_Event() subroutine to send a channel

event to the remaining party’s state table. A channel event is an

asynchronous notification from custom server to a state table. A channel

event interrupts Play... actions and the WaitEvent action.

TromboneMonitor uses the WaitEvent action to monitor for any one of:

DTMF key, caller hangup or channel event. WaitEvent can also be

configured to detect voice energy or fax tones if you wish, by setting

system variables, as described in the WebSphere Voice Response for AIX:

Application Development using State Tables reference manual. Each channel

event contains an event type and an information field, which can be used

to provide different types of notifications from custom servers to state

tables.

The sample application uses only one type of event, so the event and

information fields are set to zero. When TromboneMonitor receives a

channel event, it makes a short announcement to the attached party and

then terminates the call.

Moving to a multiprocess custom server

The CA_TDM_Connect() and CA_TDM_Disconnect() custom server

subroutines will block your custom server process while waiting for a

response from TDM connection management. This means that a single-process

custom server design, as implemented in the sample, may not be suitable for

a production environment where high throughput is required. This issue is

discussed in “Designing a multiprocess custom server” in the WebSphere Voice

Response for AIX: Custom Servers reference manual.

A multiprocess non-associated design would be a good choice for this

application. You could fork() several identical copies of the custom server

process to increase throughput, and place t_array, the array of trombone data

structures in shared memory to allow access from any of the processes. You

should allocate storage for the trombone data structures statically in shared

memory, instead of using malloc() as in the sample, because storage allocated

by malloc() is not accessible outside the process which allocated it.

Voice paths

The main purpose of the trombone application is to allow the two parties

carry out a conversation. However, one of the benefits of using WebSphere



Voice Response to provide this service is that your application can also make

announcements to the parties, record their voices or allow them to use DTMF

keys to invoke features of the service. In general, you can use Play, Record

and GetKey actions freely in your state tables, and they will behave as you

expect. But it is useful to have a clear understanding of the voice paths in the

system so that you understand WebSphere Voice Response’s capabilities and

limitations.

Figure 35 shows the voice paths which are in effect while a trombone

connection is established. State table A can always record the spoken voice of

party A, Tom for example, or detect Tom’s DTMF keys. Likewise, state table B

can always hear party B, Daisy for example.

State table A cannot hear Daisy’s voice or detect Daisy’s DTMF keys.

Likewise, state table B cannot hear Tom.

Figure 36 on page 219 and Figure 37 on page 219 show the switches that

control what each party can hear. Your application does not need to do

anything to control the position of these switches: they are manipulated

automatically by WebSphere Voice Response. Each switch can be in one of

two positions:

v While a TDM connection is active, the switch is normally in the TDM

position (as shown in Figure 36 on page 219). In this example, Daisy can

hear Tom’s voice.

State Table A

State Table B

TDM bus

Tom

Daisy

Figure 35. Voice paths in a trombone connection



v But when state table B plays an announcement, WebSphere Voice Response

throws the switch into the host position (as shown in Figure 37 on page

219), so that Daisy can hear the announcement. Tom does not hear this

announcement. The switch remains in the host position for the duration of

the announcement, during which time Daisy cannot hear Tom’s voice. At

the end of the announcement, the switch reverts to the TDM position so

that Tom and Daisy can resume their conversation.

Echo susceptibility

“Voice paths” on page 217 stated that state table A cannot hear Daisy’s voice

and state table B cannot hear Tom. This rule may not hold true if the circuit

connecting WebSphere Voice Response to one of the parties is prone to echo.

In this case, state table A may hear Daisy’s voice or DTMF echoed via Tom’s

voice circuit or handset. The echo cancellation feature of the digital trunk

adapters cannot be used to reduce these echoes, because the output from the

TDM bus by-passes the digital signal processors in the pack.

If your customers use echo-prone telephone connections, you should take this

into account in your application design. For example, it may be better to offer

State Table B

Daisy

From Tom

Daisy can hear Tom

Record

Play

Switch inTDM position

Figure 36. Voice paths when the switch is in TDM position

State Table B

Daisy

From Tom

Daisy cannot hear Tom

Record

Play

Switch inHost position

Figure 37. Voice paths when the switch is in host position



DTMF facilities to the calling party but not to the called party. If you disable

DTMF detection in one of the state tables, you avoid the risk that a DTMF

detector may be triggered by an echoed DTMF tone.



Chapter 16. Designing for a single system image

Most voice applications will run without any changes on WebSphere Voice

Response systems that are configured as a single system image. State tables,

prompts, or custom servers that use application data (by, for example, playing

or recording voice segments) do not need to be aware of whether they are

running on a single system image: they will access that data in exactly the

same way whether they are running on a stand-alone WebSphere Voice

Response system, on a client node, or on a database server node.

However, you should consider the following points when you design a voice

application that will be run on a single system image:

v The LogEvent state table action causes application data to be written to an

AIX file on the node on which the event occurs. This file is not shared in

the single system image, so an application that processes this data for the

whole single system image will have to collect data from the log files on

each node.

v If your voice application uses custom servers to access hardware or

software resources that cannot be made available in exactly the same way

on all client nodes of the single system image, your application must be

able to handle any differences. For example, if a telephone call cannot be

directed to the particular node that is known to have the resource required

to process it, the voice application may need to transfer the call to that

node.

v Applications that play voice segments using prompts will perform better in

a single system image because such voice data may be cached locally on the

client nodes, and will not require voice data to be accessed using the

network.

v Using uncompressed voice segments instead of compressed voice segments

will increase the network bandwidth required by a factor of 5, unless such

data has been cached using the prompt mechanisms and the segments are

played using prompts.

Querying the single system image configuration

An application may need to determine whether it is running on a client node

or a server node of a single system image, or if it is running on a stand-alone

system. It may need to do this, for example, to restrict the running of

housekeeping processes to one machine.

The application can find this information like this:


v In a state table, test the value of SV540 (System : SSI (Single System Image)

: State). This numeric system variable represents the mode in which the

node has been configured. For more information, see the description of this

system variable in the WebSphere Voice Response for AIX: Application

Development using State Tables book.

v In a custom server, call the CA_Get_DT_Info() subroutine. The

DT_INFO_ST structure returned from this subroutine has a member,

ssi_state, which contains the mode in which the node has been configured.

For more information, see the description of DT_INFO_ST in the WebSphere

Voice Response for AIX: Custom Servers book.

To find from the command line the type of system you are logged on to, use

the ssistatus command. For more information, see the description of this

command in the WebSphere Voice Response for AIX: Configuring the System book.

querying the single system image configuration


Chapter 17. Using ISDN call transfer

This chapter describes how to transfer calls on WebSphere Voice Response

using ISDN. WebSphere Voice Response supports four protocols, EuroISDN

and E1 QSIG Single Step Transfer Supplementary Service protocols, the ISDN

two B-channel transfer protocol, and the Nortel proprietary Release Link

Trunk (RLT) call transfer protocol.

The ISDN call transfer application works with the two B-channel transfer and

the Nortel RLT protocols, and where there are differences between the two

these are noted, otherwise the information in the following section applies to

both protocols.

The ISDN single step call transfer works in a different way, and uses a

different custom server to that used by the other ISDN call transfer protocols.

It also uses different state tables.

This chapter is laid out as follows:

v “When can I use ISDN Two B-channel transfer?” on page 224 on this page

v “When can I use ISDN RLT call transfer?” on page 224

v “When can I use ISDN single step call transfer?” on page 225

v “What the ISDN call transfer application does” on page 225

– “Limitations of ISDN call transfer” on page 226

– “Installing the application” on page 226

– “Configuring the ISDN_Call_Transfer custom server” on page 229

– “How to use ISDN call transfer” on page 231

– “Custom server functions” on page 243

– “State table definitions” on page 247v “What the ISDN single step call transfer application does” on page 254

– “Limitations of ISDN single step call transfer” on page 254

– “Installing the application” on page 254

– “Configuring the SSTransfer custom server” on page 257

– “How to use ISDN single step call transfer” on page 258

– “Custom server functions” on page 258

– “State table definitions” on page 264


When can I use ISDN Two B-channel transfer?

WebSphere Voice Response implements the ISDN Two B-channel transfer

protocol that is defined in the Bellcore document Generic Requirements for

ISDN PRI Two B-Channel Transfer, GR-2865-CORE Issue 2.

WebSphere Voice Response supports one specific version of ISDN Two

B-channel transfer:

v Nortel DMS-100 at release level NA012.

This version is described in the document NT - NI Primary Rate User

Network Interface Specification, publication number NIS-A233-1, standard

release 05.03, issue date 3rd August 1999.

Blind ISDN Two B-channel transfer is supported by WebSphere Voice

Response at Fix Level 4.2.0.287 PTF U812107 (APAR IY99811).

To use ISDN Two B-channel transfer, you must:

1. Configure your telephony trunk to supply ISDN with two B-channel

transfer.

2. Ensure your Nortel switch is running the specified level of software.

3. Connect your trunk to the Nortel switch.

When can I use ISDN RLT call transfer?

WebSphere Voice Response supports one specific version of Nortel’s ISDN

RLT call transfer protocol as defined in the Nortel document ISDN Primary

Rate User Network Interface Specification, publication number NIS-A211-1,

standard release 07.05, issue date May 1997.

The supported switches are listed below with their release numbers:

v Nortel DMS-100 at release level NA007.

This version is described in the Nortel document ISDN Primary Rate User

Network Interface Specification, publication number NIS-A211-1, standard

release 07.05, issue date May 1997.

v Nortel DMS-250 at release level IEC05.

This version is described in the Nortel document PRI RLT Feature

Application Guide publication number 297–2621–347, standard release 02.03,

issue date March 1999.

To use ISDN RLT call transfer, you must:

1. Configure your telephony trunk to supply ISDN RLT call transfer.

2. Ensure your Nortel switch is running the specified level of software.

3. Connect your trunk to the Nortel switch.

when can I use ISDN Two B-channel transfer?


When can I use ISDN single step call transfer?

WebSphere Voice Response implements the Euro ISDN single step transfer

protocol as defined in the ECMA-300 document, edition 2 Dec 2001.

To use ISDN single step call transfer, you must:

v Replace the default Incoming_Call state table with the supplied

TIncoming_Call state table or modify the existing Incoming_Call state table

so that the contents of SV542 (call data) are saved into SV51 before the call

is answered and the call data lost.

v From the Welcome window, click Configuration -> System

configuration->Change->Application server interface.

v In the Application Server Interface window displayed, set State table name

for incoming calls to TIncoming_Call.

v From the Welcome window, click Operations->Custom server manager.

v In the Custom Server Manager window, ensure that the SStransfer custom

server is running.

What the ISDN call transfer application does

The WebSphere Voice Response signaling model assumes that any type of

call-transfer operation uses the same channel as the incoming call when it

makes the call to the third party to prepare for a transfer. However, ISDN call

transfer requires that the call to the third party is made on a different channel

from that used for the original call. To match these two requirements, the

ISDN call transfer application of WebSphere Voice Response for AIX modifies

the ISDN Signaling Process and provides a custom server that performs the

call to the third party when a TransferCall request is received.

WebSphere Voice Response implements ISDN call transfer in the following

way:

1. A call arrives at WebSphere Voice Response, and the application decides

that the user needs to be transferred to a third party. The application uses

the TransferCall state table action to initiate the transfer.

2. The ISDN Signaling Process makes an outgoing call using the custom

server and an outbound state table on another channel. When you create

your voice application, you may have to modify the supplied outbound

state tables, depending on the needs of your application (for example, the

Ring Time parameter of MakeCall can be changed).

3. When the third party has answered, the outbound state table informs the

ISDN Signaling Process using the custom server.

4. For a blind transfer, the ISDN Signalling Process then asks the switch to

complete the transfer using a request and then ends the TransferCall action

in the incoming state table. For screened transfer, the ISDN Signalling

when can I use ISDN single step call transfer?

Chapter 17. Using ISDN call transfer 225

Process ends the TransferCall action in the incoming state table

straightaway. Screened transfer is sometimes known as supervised transfer.

5. When the TransferCall state table action returns in the original state table,

a TerminateCall state table action is called.

6. On receipt of the TerminateCall action, the ISDN Signaling Process asks

the switch to complete the transfer using a request.

7. The caller and third party should now be connected within the switch. The

two call stubs connected to WebSphere Voice Response (the inbound call

from the original caller and the outbound call to the third party) are

terminated by the switch after a short time. If they do not get terminated,

WebSphere Voice Response terminates them after a suitable guard time.

Limitations of ISDN call transfer

There are some limitations associated with using ISDN call transfer with

WebSphere Voice Response. These limitations are:

v The two calls involved in the transfer (the original inbound call and the

outbound call to the third party) must be connected to WebSphere Voice

Response from the same switch. The Bellcore specifications allow the two

calls to be on different trunks, provided that both trunks support ISDN Two

B-channel transfer. The same is true for Nortel’s ISDN RLT call transfer.

If the WebSphere Voice Response system has a mixture of CAS and ISDN

trunks, the user application should ensure that the outbound call is made

on the correct trunk for an ISDN call transfer to be successful.

Note: The Nortel DMS-100 switch at release level NA008 permits a transfer

only if the two calls (inbound and outbound) are on the same trunk.

This must be taken into account when writing your application.

v No user access is given to the information elements on the transfer.

v ISDN call transfer is not totally compatible with the WebSphere Voice

Response signaling model, so application changes may be required when

porting applications that involve transfer operations from different

telephony configurations. This applies mainly if you want to perform a

third party consultation during a screened transfer operation.

v ISDN RLT blind transfer is not supported.

Installing the application

The ISDN call transfer application is supplied as an installp image that you

install using the System Management Interface Tool (SMIT). The application

contains three components, including some source code to help you customize

the ISDN call transfer capability to your specific needs. For a straightforward

use of the ISDN call transfer capability, no customizing should be required.

The components of the application are:

v Updated ISDN support.

what the ISDN call transfer application does


v State tables (including source code):

The following state tables are provided (for definitions for these state tables,

see “State table definitions” on page 247):

ISDN_Imm_Xfer

ISDN_SupA_Xfer

ISDN_Xfer_C5

ISDN_Xfer_C10

ISDN_Xfer_Data

ISDN_Xfer_Stat

ISDN_Xfer_Log

The source code for these state tables is supplied in an ASCII file in the

same directory as the custom server: $CUR_DIR/ca/ISDN_Call_Transfer_dir

v Custom server:

A custom server, named ISDN_Call_Transfer, is supplied to perform the

low-level functionality of the trombone operation (for details of the

available calls, see “Custom server function definitions” on page 243).

Note: Only the executable version (not the source code) of this custom

server is supplied.

Before you install

Before you can install the ISDN call transfer application, you must have:

v A WebSphere Voice Response system running Version 3 Release 1 of

WebSphere Voice Response for AIX.

v A connection to a telephony switch using one or more trunks that support

ISDN Two B-channel transfer or ISDN RLT call transfer.

v Two telephones attached to the same switch. In the instructions in this

chapter, these telephones are referred to as Phone A and Phone B.

v A third valid phone number that can be used to call into WebSphere Voice

Response, to be used as an application profile ID.

v An application that performs a transfer operation using a screened transfer

with simple call-answer supervision.

v A copy of the WebSphere Voice Response for AIX WebSphere Voice Response

for AIX: Installation guide.

v Sufficient disk space for the components you are installing (the WebSphere

Voice Response for AIX: Installation guide explains how to check this; see the

section “Ensuring you have enough disk space for the new software”).

Installing


installing the application


1. Follow the instructions in “Installing the WebSphere Voice Response

software” in the WebSphere Voice Response for AIX: Installation guide to use

the System Management Interface Tool (SMIT) to install the PTF that

contains the ISDN call transfer application.

Starting WebSphere Voice Response

2. Start WebSphere Voice Response and log in to the user account you use

for WebSphere Voice Response administration.

Importing the custom server and state tables

3. In the WebSphere Voice Response Welcome window, click Applications

—> Application —> Import—> Replace—> File.

4. Select the file /usr/lpp/dirTalk/sw/isdn/call_transfer/ISDN_Call_Xfer.imp.


5. Open the ISDN_Call_Xfer application.

The system displays the Application (ISDN_Call_Xfer) window.


The system displays the Application Profiles window, followed by the


7. Type any name in the Name field (for example, ISDN2BCT_Test).

8. Click State Table, then select your application that performs a call

transfer.

9. Click OK.



12. Click OK.

13. In the Application (ISDN_Call_Xfer) window, click View —> Refresh.



Starting the custom server

14. Open the Custom Server Manager window, and click Welcome —>

Operations —> Custom Server Manager

The system displays the available custom servers in a window.

15. Start the ISDN_Call_Transfer custom server by clicking Run Status —>

Start.

The Run Status button displays Waiting after a short while.




Note: The exact sequence here depends on your application. Assuming your

application is a simple one that asks for a number to transfer to, then

performs a TransferCall, the sequence of events should be:16. Pick up Phone A’s handset and dial the application profile ID.

WebSphere Voice Response runs your application, which performs the

transfer to a third party. It answers the call and prompts you to input the

telephone number that you want to transfer to, followed by a # key.




The application completes the transfer when Phone B is answered and

the voice path for the two calls is connected within the switch.

19. The two remaining connections to WebSphere Voice Response (originally

connected to Phones A and B) are disconnected shortly after the transfer

is completed.

Configuring the ISDN_Call_Transfer custom server

The ISDN_Call_Transfer custom server has some command line parameters

that you can set to help you debug problems, or to fine-tune the operation of

the custom server.

The parameters are defined in Table 11 on page 229. For information on how

to set the parameters, see “Setting configuration options” on page 230.

Table 11. Configuration options for the ISDN_Call_Transfer custom server

Parameter Default setting Description

-a off Send extra information alarms to the error log.

-d off Provide extra debugging information (in addition to

the information that always gets sent). Valid values

are 0 (none) to 4 (everything). To set the logging

level to 3, specify –d3 . Level 4 traces Protocol Data

Unit creation, and is always written to

DTstatus.out. Normally level 3 tracing should be

sufficient for problem determination.

-en n=0 The event data (n) sent by the custom server if the

third party hangs up (see

CA_Report_Channel_Event() in the WebSphere Voice

Response for AIX: Custom Servers guide).

-in n=0 The information field (n) sent by the custom server

if the 3rd party hangs up (see

CA_Report_Channel_Event() in the WebSphere Voice

Response for AIX: Custom Servers guide).

-s off Print debugging information to stdout, as well as to

AIX system trace.



Table 11. Configuration options for the ISDN_Call_Transfer custom server (continued)


-z off This parameter is for test purposes only. It causes

the custom server to enrol one of each type of error

possible on custom server startup, then terminates.

The enrolment of errors takes about 30s.

-Bsttbl_name sttbl_name =

ISDN_Imm_Xfer

Name of the state table to use for blind (immediate)

transfers.

-Eentry_point entry_point =

begin

The name of the state table entry point to use in the

outbound state table. This must be the same for all

of the outbound state tables used in ISDN transfer

operations.

-Lfile_name file_name = null Name of the log file to be used for logging debug

information. If this is blank, no logging information

will be sent.

-Ssttbl_name sttbl_name =

ISDN_SupA_Xfer

Name of the state table to use for screened transfers

(that follow the WebSphere Voice Response

signaling model for transfer operations).

Setting configuration options

To set one or more of the configuration options, follow the procedure below:

1. From the Welcome window, click onApplications —> Custom Servers

Setting a command line parameter for the custom server

2. Highlight the ISDN_Call_Transfer custom server.

3. Click Server —> Open.

The system displays the Custom Server (ISDN_Call_Transfer) window.

4. Click File —> Properties.

The system displays the Properties (ISDN_Call_Transfer) window.

5. Enter your command line parameters in the panel titles main() args.

6. Click OK.

The system closes the Properties (ISDN_Call_Transfer) window.

7. In the Custom Server (ISDN_Call_Transfer) window, click File —> Save.

Restarting the custom server

8. Open the Custom Server Manager window by clicking Welcome —>

Operations —> Custom Server Manager.


9. If the ISDN_Call_Transfer custom server Run Status is set to Waiting,

stop the custom server by clicking Run Status —> Stop.

configuring the ISDN_Call_Transfer custom server


The Run Status button should display None, after a short while.

10. Start the ISDN_Call_Transfer custom server by clicking Run Status —>

Start.

After a short while the Run Status button should display Waiting. The

new command line parameters are now in effect. If the Run Status

remains at None, there is probably an error with one of the command

line parameters. Check the error log for details.

How to use ISDN call transfer

This chapter describes how to perform a transfer operation using the ISDN

call transfer mechanism.

If your requirements for transfer are fairly simple, you should not have to

change your applications or the supplied state tables.

The description in the WebSphere Voice Response for AIX: Application

Development using State Tables book of how the TransferCall state table action

works gives general information on how to perform a transfer. Transfer using

ISDN works in generally the same manner, and differs significantly only

where a third party consultation is required.

There are three types of transfer available:

v Blind (Immediate) transfer

This is a transfer that completes before knowing if the caller has

successfully contacted the third party.

This type of transfer should require little or no modification to your

application or to the supplied state tables.

v Screened transfer (with call-answer supervision)

This is a transfer that completes after knowing whether or not the third

party has answered. If the third party did not answer, the application can

continue interacting with the caller.

This type of transfer should require little or no modification to your


v Screened transfer (with third party consultation)

This is a transfer that can interact with the third party, if it answers, during

the transfer. The transfer can then be completed, or the application can

reconnect to the original caller and continue.

The outbound call state table application performs the interaction with the

third party.

This type of transfer requires modifications to your application and to the

supplied state tables. The supplied state tables have been written to make

this as easy as possible.

configuring the ISDN_Call_Transfer custom server


The type of transfer you use will depend on your application requirements.

The following sections describe how to implement the various types of

transfer and highlight any changes that you may have to make to your


Blind (immediate) transfer

Blind (immediate) transfer is a transfer that completes before knowing if the

caller has successfully contacted the third party.

The sequence of events in Figure 38 is:

1. The Caller state table issues a TransferCall request with the ring_wait and

ring_time parameters set to zero to indicate that a blind transfer is

required.

2. The ISDN Signalling Process receives the TransferCall request and initiates

an outbound call to the third party using the ISDN_Imm_Xfer state table

with the aid of the ISDN_Call_Transfer custom server.

3. The outgoing state table connects to the ISDN_Call_Transfer custom server.

It then issues a MakeCall with the ring_wait and ring_time parameters set

to zero to indicate that a blind make call is required. The make call returns

Caller

Third Party

Incoming Channel Outgoing Channel

User Incoming

InvokeStateTable(default = ISDN_Imm_Xfer)

ISDN_Imm_Xfer

MakeCall

OpenHostServerLink(ISDN_Call_Transfer)

Wait for response from switch WaitEventWait for DTMF, Hangup

or Host event for up to 30

TerminateCall

TransferCallring_wait = 0ring_time = 0

application

EDGE:

ring_wait = 0ring_time = 0

Note the OHSL

MakeCall returns as soon asthe call is in progress (the

third party phone should beringing at this stage if thereturn edge is Success).

SendData(MakeCallStatus)

Returns the edge from theprevious MakeCall action.

seconds to allow the transferoperation to complete.

Send request to the switchto connect the caller and the

third party (transfer)

Return the correct edgeto the TransferCall requestAny

At this time, the caller is connected to the third party within the switch andthe incoming and outgoing channels will be hung up after a short period.

The ISDN SignallingProcess and

ISDN_Call_Transfercustom server

Figure 38. Event flow for a blind (immediate) transfer

how to use ISDN call transfer


as soon as the call is underway, or if there is a problem with the supplied

parameters (for example, the phone number contains invalid characters).

4. When the MakeCall action returns, the outbound state table informs the

ISDN_Call_Transfer custom server (and so the ISDN Signalling Process) of

the result and enters into a WaitEvent. It should not hang up at this stage

because this may interfere with the completion of the transfer.

5. The ISDN Signalling Process sends a message to the switch to request that

the caller and third party are connected together (the actual transfer) and

waits for the switch to confirm this.

6. The ISDN Signalling Process sends the result of the transfer to the

incoming state table, which causes the TransferCall action to return.

Soon after step 5, the switch hangs up both the incoming and outgoing calls

connected to WebSphere Voice Response. If these calls are not disconnected by

the switch within a reasonable time, the WebSphere Voice Response

applications disconnect the calls (after the TransferCall for the incoming call,

and after the WaitEvent for the outgoing call).

For most applications, this type of transfer can be used without modification

to either the user application or to the ISDN_Imm_Xfer state table. The most

likely modification that may have to be made though, is to specify which

channels may be used to make the outbound call (see SV178 definition in the


book). This modification should be made in the ISDN_Imm_Xfer state table

before the MakeCall action is performed.

Screened transfer (with call answer supervision)

Screened transfer (with call answer supervision) is a transfer that completes

after knowing whether or not the third party has answered. If the third party

does not answer, the application can continue interacting with the caller.

These two scenarios are described in the following sections:

v Figure 39 on page 234 shows what happens when the third party answers

and the transfer completes.

v Figure 40 on page 236 shows what happens when the third party is not

contactable and the transfer is abandoned so that the incoming application

can continue interacting with the original caller.





ring_time parameters set to non-zero values to indicate that a screened

transfer is required.

2. The ISDN Signaling Process receives the TransferCall request and initiates

an outbound call to the third party using the ISDN_SupA_Xfer state table




to non-zero values to indicate that a screened make call is required. The

make call returns as soon as the call is answered (because this is a

successful transfer).


ISDN_Call_Transfer custom server (and so the ISDN Signaling Process) of

the result and enters into a WaitEvent. It should not hang up at this stage

because this will interfere with the completion of the transfer.

Caller

Third Party


InvokeStateTable(default = ISDN_SupA_Xfer) ISDN_SupA_Xfer

MakeCall


Return the Success edgeto the TransferCall request

WaitEventWait for DTMF, Hangup


TerminateCall

TransferCallring_wait > 0ring_time > 0

User Incomingapplication

EDGE:

ring_wait > 0ring_time > 0

Note the OHSL

MakeCall returns as soon asthe result of the call is known.Since the result was success,

third party phone will beanswered at this stage.


Returns the edge from theprevious MakeCall action.




Success

Wait for response from switch

Return Success edgeto the TerminateCall requestEDGE:

Success

Send Host Event to theoutbound state table EDGE:

HostEvent

TerminateCall



At this time, the caller is connected to the third party within theswitch and the incoming and outgoing channels will be hung up.

Figure 39. Event flow for a screened transfer with call answer supervision (for a successful call)



5. The ISDN Signaling Process sends the result of the transfer to the


6. The incoming state table should then perform a TerminateCall to complete

the transfer.

7. On receiving the TerminateCall from the incoming state table, the ISDN

Signaling Process sends a message to the switch to request that the Caller

and third party are connected together (the actual transfer), and waits for

the switch to confirm this.

8. The ISDN Signaling Process sends a HostEvent to the outbound state

table, which should then hang up.

9. The ISDN Signaling Process sends Success to the incoming state table,

which causes the TerminateCall action to return.


either to the user application or to the ISDN_SupA_Xfer state table. The most


channels may be used to make the outbound call (see the SV178 definition in


book), or to modify the ring_wait and ring_time parameters used in the

MakeCall state table action. Modifications to system variables should be made

in the ISDN_SupA_Xfer state table before the MakeCall action is performed.












to non-zero values to indicate that a screened make call is required. The

make call returns as soon as the result of the call is known (for example,

no answer, or busy, because this is an unsuccessful transfer).


ISDN_Call_Transfer custom server (and hence the ISDN Signaling Process)

of the result and terminates the call.

5. The ISDN Signaling Process sends the result of the transfer (not successful,

in this case) to the incoming state table which causes the TransferCall

action to return.

6. The incoming call state table performs a ReconnectCall.

Figure 40. Event flow for a screened transfer with call answer supervision (for an unsuccessful call)



7. The ISDN Signaling Process returns Success or CallerHungUp, depending

on the current state of the call. This causes the ReconnectCall action to

return.

8. If the edge returned from the ReconnectCall action was Success, the

incoming application can continue to interact with the caller; otherwise it

must hang up.


either to the user application or to the ISDN_SupA_Xfer state table. The most


channels may be used to make the outbound call (see the SV178 definition in


book), or to modify the ring_time and ring_wait parameters used in the

MakeCall state table action. Modifications to the system variables should be

made in the ISDN_SupA_Xfer state table before the MakeCall action is

performed.

Screened transfer (with third party consultation)

Screened transfer (with third party consultation) is a transfer that can interact

with the third party, if it answers, during the transfer. The transfer can then be

completed, or the application can reconnect to the original caller and continue.

Due to limitations with the WebSphere Voice Response hardware, the original

caller state table cannot perform the third party interaction, and so the

WebSphere Voice Response signaling model for a transfer operation cannot be

followed precisely. Instead, the outbound state table must perform the third

party interaction. Two custom server calls (and associated state tables) have

been added to allow the inbound and outbound state tables to perform some

basic communications during the transfer. This should keep any changes to

your application to a minimum.

Figure 41 on page 238 shows a third party consultation that ends with a

transfer, and Figure 42 on page 241 shows a third party consultation that ends

with a reconnection to the original caller.




1. The Caller state table decides that a screened transfer with third party

consultation is required. It sets up some data to tell the outbound state

table what needs to be done on the consultation. This data is set up by

an OpenHostServerLink to the ISDN_Call_Transfer custom server and a

SendData using the SetUserData function.

Caller

Third Party



MakeCall





TerminateCall



EDGE:


Note the OHSL




Returns the edge from theprevious MakeCall action




Success

Wait for response from switch

Return Success edgeto the TerminateCall request

EDGE:Success

Send Host Event to theoutbound state table EDGE:

HostEvent

TerminateCall


Note the OHSL

SendData(SetUserData)

Sets up user_data passedto the outbound. state table

Record the user data to bepassed to the outbound state

table when it is invoked.

Interact with the third partyand gather responses

and the third party response.and record third partyresponses for later

SendData +

(GetUserStatus)Retrieves the third party

response gathered by the

Return the third partyresponse that was stored.

ReceiveData

outbound state table

Process the third partyresponse



At this time, the caller is connected to the third party within the switchand the incoming and outgoing channels will be hung up.

Figure 41. Event flow for a screened transfer with third party consultation (ending in a transfer)



Note: A state table called ISDN_Xfer_Data is supplied to help perform

this function.







4. The outgoing state table connects to the ISDN_Call_Transfer custom

server. It then issues a MakeCall with the ring_wait and ring_time

parameters set to non-zero values to indicate that a screened make call is

required. The make call returns as soon as the call is answered (because

this is a successful transfer).

5. When the MakeCall action returns, the outbound state table can interact

with the third party (for example, to ask if the third party wants to

accept a call at this time). The third party responses are gathered.

6. The outbound state table then informs the ISDN_Call_Transfer custom

server (and so the ISDN Signaling Process) of the result of the MakeCall

and the third party responses to the consultation, and enters into a

WaitEvent. It should not hang up at this stage because this would

interfere with the completion of the transfer.



8. The incoming state table should then use a SendData/ReceiveData pair

of actions calling the GetUserStatus function to determine the response

from the third party. This example assumes that the response is to

continue with the transfer operation.

Note: A state table called ISDN_Xfer_Stat is supplied to help perform

this function.

9. The incoming state table should then perform a TerminateCall to

complete the transfer.

10. On receiving the TerminateCall from the incoming state table, the ISDN

Signaling Process sends a message to the switch to request that the Caller

and third party are connected together (the actual transfer), and waits for

the switch to confirm this.

11. The ISDN Signaling Process sends a HostEvent to the outbound state

table, which should then hang up.


which causes the TerminateCall action to return.

For most applications, this type of transfer will need modifications to be made

to both the user application and to the ISDN_SupA_Xfer state table. The



changes involve moving the third party consultation logic to the outbound

state table (this would normally be performed in the inbound state table).

Another modification that may have to be made is to specify which channels

may be used to make the outbound call (see the SV178 definition in the








1. The Caller state table decides that a screened transfer with third party

consultation is required and sets up some data to tell the outbound state

table what needs to be done on the consultation. This data is set up by

an OpenHostServerLink to the ISDN_Call_Transfer custom server and a

SendData using the SetUserData function.

Caller

Third Party

Outgoing Channel


MakeCall





ReconnectCall



EDGE:


Note the OHSL




Returns the edge from theprevious MakeCall action


Send a host event to theoutbound state table to tellit to hang up the third party

Success

Return Success edgeto the ReconnectCall requestEDGE:

Success

EDGE:HostEvent

TerminateCall

OpenHostServerLink(ISDN_Call_Transfer) Note the OHSL

SendData(SetUserData)

Sets up user_data passedto the outbound. state table

Record the user data to bepassed to the outbound state

table when it is invoked.

Interact with the third partyand gather responses

and the third party response.and record third partyresponses for later

SendData +

(GetUserStatus)Retrieves the third party

response gathered by the

Return the third partyresponse that was stored.

ReceiveData

outbound state table

Process the third partyresponse

At this time, the caller is connected to the third party within the switchand the incoming and outgoing channels will be hung up.

Incoming Channel The ISDN SignallingProcess and


Figure 42. Event flow for a screened transfer with third party consultation (ending up reconnecting

to the original caller)



Note: A state table called ISDN_Xfer_Data is supplied to help perform

this function.







4. The outgoing state table connects to the ISDN_Call_Transfer custom

server. It then issues a MakeCall with the ring_wait and ring_time

parameters set to non-zero values to indicate that a screened make call is

required. The make call returns as soon as the call is answered (because

this is a successful transfer).

5. When the MakeCall action returns, the outbound state table can interact

with the third party (for example, to ask if the third party wants to

accept a call at this time). The third party responses are gathered.

6. The outbound state table then informs the ISDN_Call_Transfer custom

server (and so the ISDN Signaling Process) of the result of the MakeCall

and the third party responses to the consultation, and enters into a

WaitEvent. It should not hang up at this stage because this would

interfere with the completion of the transfer.



8. The incoming state table should then use a SendData/ReceiveData pair

of actions calling the GetUserStatus function to determine the response

from the third party. This example assumes that the response is to

abandon the transfer operation and connect back to the original caller.

Note: A state table called ISDN_Xfer_Stat is supplied to help perform this

function.

9. The incoming state table should then perform a ReconnectCall to

abandon and tidy up the abandoned transfer.

10. On receiving the ReconnectCall from the incoming state table, the ISDN

Signaling Process sends a host event message to the outbound state table

to tell it to hang up the outbound call, if it hasn’t already done so.


which causes the ReconnectCall action to return.

12. The inbound state table can now continue with the original caller.

For most applications, this type of transfer will need modifications to be made

to both the user application and to the ISDN_SupA_Xfer state table. The

changes involve moving the third party consultation logic to the outbound

state table (this would normally be performed in the inbound state table).



Another modification that may have to be made is to specify which channels

may be used to make the outbound call (see the SV178 definition in the





Custom server functions

This section describes the custom server functions supplied with the ISDN call

transfer application.

Custom server function definitions

Three functions are provided with the ISDN_Call_Transfer custom server:

MakeCallStatus

The outbound state table uses this function to return information

about the success of the outbound call to the third party.

MakeCallStatus is described on page 245.

GetUserStatus and SetUserData

Use these functions only if you need a method of communication

between the inbound and outbound state tables during a transfer

operation that uses ISDN call transfer. For example, you might want

to specify the prompts played to the third party during consultation,

and to gather the third party responses and return them to the caller

state table. The caller state table could then decide either to complete

the transfer or to reconnect to the original caller. GetUserStatus is

described on page 244, and SetUserData is described on page 245.

Messages from the custom server

The ISDN_Call_Transfer custom server issues the following types of message:

v Red messages are issued for all fatal problems.

v Yellow messages are warnings of any problems that may cause future

failures.

v White messages give information.

The messages are issued as standard custom server messages. The

ISDN_Call_Transfer custom server error title and ID are shown in parameters

1 and 2 of the standard custom server errors. The error IDs have the form

ISDN_XFERnnn. The remaining parameters contain information specific to the

particular error.

With any of these errors, if you have followed the suggestions in the User

Response, and you are unable to solve the problem, contact IBM Support.

When you call, you will need details of any errors, your system setup, and

details of the conditions that cause the problem. You may also require an AIX



system trace taken when the problem occurs. Before taking the trace, set the

-d option in the custom server. For more information on the command line

options see “Configuring the ISDN_Call_Transfer custom server” on page 229.

Error messages generated by the ISDN_Call_Transfer custom server, together

with explanations and suggested responses, are listed in the WebSphere Voice

Response for AIX: Problem Determination guide.

GetUserStatus

Description: The GetUserStatus function is called by the inbound state table

after a transfer. Use it to retrieve any user data set by the outbound state table

during the transfer operation. This call must be made after the TransferCall

action and before the TerminateCall or ReconnectCall actions.

Input parameters: None.

Output parameters:

short status: The status of the call to get the user status information. The

possible values are:

0 User status data is present.

1 Request to get user status is not valid at this time.

2 No user status data is available.

char user_status1[64]: User-defined data field sent by the outbound state table

to the inbound state table during a transfer after the outbound call has been

made.



made.



made.



made.



made.

custom server functions


MakeCallStatus

Description: The MakeCallStatus function is called by the outbound state

table after the outbound call has been made. If there is any user data to return

(for example, data from a third party consultation), it can be placed in the

user_status parameters.

Input parameters:

short call_status: The return code from the MakeCall state table action.

char user_status1[64]: User-defined data field sent to the inbound state table

during a transfer after the outbound call has been made.









Output parameters: None.

SetUserData

Description: The SetUserData function is called with several parameters to

send information to the outbound state table used during the transfer

operation. This call must be made before the TransferCall action is performed.

The parameters are all strings, and the format of the data contained within the

strings is user defined.

Input parameters:

char user_data_1[64]: User-defined data field sent to the outbound state table

during a transfer.


during a transfer.


during a transfer.




during a transfer.


during a transfer.

Output parameters: None.



State table definitions

This section describes the state tables supplied with the ISDN call transfer

application.

Six state tables are provided as compiled state tables and ASCII state table

source code. The compiled state tables are compiled directly from the ASCII

state table source code. The source code for the state tables is provided in the

directory $CUR_DIR/ca/ISDN_Call_Transfer_dir.

The state tables fall into two groups:

Outbound state tables

An outbound state table provides functions to make the outbound call

for the transfer operation:

v “ISDN_Imm_Xfer” on page 247

v “ISDN_SupA_Xfer” on page 248

Helper state tables:

The helper state tables encapsulate code that is used to provide

interaction between the inbound and outbound state tables during the

transfer, and other utility functions:

v “ISDN_Xfer_C5” on page 250

v “ISDN_Xfer_C10” on page 250

v “ISDN_Xfer_Data” on page 251

v “ISDN_Xfer_Log” on page 252

v “ISDN_Xfer_Stat” on page 252

The following sections describe the state tables.

ISDN_Imm_Xfer

The ISDN_Imm_Xfer state table is used as the default outbound state table for

blind transfers. It attempts to perform a blind make call and returns the

success or failure to the ISDN Signalling Process using the ISDN_Call_Transfer

custom server.

After the results of the MakeCall have been reported, it enters into a

WaitEvent for up to 30 seconds to allow the transfer to complete. When the

switch completes, the transfer channel is hung up and the WaitEvent exited. If

the switch does not hangup, the WaitEvent times out and the state table

terminates, which hangs up the call.

You can customize the application, but you must not change the basic

functions.

Parameters:

state table definitions


String phone_number (maximum of 40 characters): The number to dial for the

outgoing part of the transfer. For more information, see the definition of

phone_number in the description of the MakeCall state table action in the


book.

String format (maximum of 50 characters): The format string for the number to

dial for the outgoing part of the transfer. For more information, see the

definition of format in the description of the MakeCall state table action in the


book.

String log_filename (maximum of 64 characters): If this parameter is blank, no

event logging is performed.

If you specify a file name, event logging of the transfer calls is performed and

the results are logged in the file you specify. The logging is performed by the

ISDN_Xfer_Log state table.

String user_data1 (maximum of 64 characters): User data supplied by the

SetUserData custom server call. Also see “ISDN_Xfer_Data” on page 251,

which is a state table that can set this data for you.













ISDN_SupA_Xfer

The ISDN_SupA_Xfer state table is used as the default outbound state table

for screened transfers when using neither DTTA nor DTXA hardware.

The state table attempts to perform a make call and returns the success or

failure to the ISDN Signaling Process using the ISDN_Call_Transfer custom

server.



After the results of the MakeCall have been reported, if the make call was

successful, it enters into a WaitEvent for up to 30 seconds to allow the transfer

to complete. When the switch completes, the transfer channel is hung up and

the WaitEvent exited. If the switch does not hang up, the WaitEvent times out

and the state table terminates, which hangs up the call. If the make call was

not successful, it hangs up immediately.


functions. Comments in the source code show where you can insert code to

perform a consultation with the third party.

Parameters:

String phone_number (maximum of 40 characters): The number to dial for the

outgoing part of the transfer. For more information, see the definition of

phone_number in the description of the MakeCall state table action in the


book.

String format (maximum of 50 characters): The format string for the number to

dial for the outgoing part of the transfer. For more information, see the

definition of format in the description of the MakeCall state table action in the


book.



If you specify a file name, event logging of the transfer calls is performed and

the results are logged in the file you specify. The logging is performed by the

ISDN_Xfer_Log state table.


















ISDN_Xfer_C5

The ISDN_Xfer_C5 state table encapsulates the states needed to concatenate

up to 5 strings. It returns the result as a single string.

Parameters:

String in0: The first string.

String in1: The second string.

String in2: The third string.

String in3: The fourth string.

String in4: The fifth string.

String out (this value is returned): The concatenation of the input strings (in0 +

in1 + in2 + in3 + in4).

ISDN_Xfer_C10

The ISDN_Xfer_C10 state table encapsulates the states needed to concatenate

up to 10 strings. It returns the result as a single string.

Parameters:

String in0: The first string.

String in1: The second string.

String in2: The third string.

String in3: The fourth string.

String in4: The fifth string.

String in5: The sixth string.

String in6: The seventh string.

String in7: The eighth string.

String in8: The ninth string.



String in9: The tenth string.

String out (this value is returned): The concatenation of the input strings (in0 +

in1 + in2 + in3 + in4 + in5 + in6 + in7 + in8 + in9).

ISDN_Xfer_Data

The ISDN_Xfer_Data state table encapsulates the actions necessary to use the

SetUserData custom server function. It is called by the incoming state table to

set up some user-defined data to be supplied to the outbound state table

during a transfer. This call must be made before the TransferCall action is

performed.


functions.

Parameters:



If you specify a file name, event logging of the supplied data is performed

and the results are logged in the file you specify. The logging is performed by

the ISDN_Xfer_Log state table.

String user_data1 (maximum of 64 characters), (this value is returned): User data

supplied to the SetUserData custom server call.









Number return_code, (this value is returned): This value is returned to indicate

whether or not the call to the ISDN_Xfer_Data state table was successful. The

possible return values are:

0 The state table ran successfully

1 The OHSL to the ISDN_Call_Transfer custom server failed.

2 The SendData to the ISDN_Call_Transfer custom server failed.



ISDN_Xfer_Log

The ISDN_Xfer_Log state table encapsulates the actions needed to log debug

data in a file.

The state table first checks the logging_on flag to see if the supplied data

should be sent to the log file. The data to be logged consists of a header

string, followed by six general strings; these are concatenated before being

logged using a LogEvent action. The state table always returns edge 0,

regardless of any errors.

Parameters:

Number logging_on: A value of 1 means perform data logging; any other

value causes the state table to exit without logging anything.

String header: The header string for the logging function. This must contain at

least the file name, in a format required by the LogEvent state table action.

String in_1: The first string to log.

String in_2: The second string to log.

String in_3: The third string to log.

String in_4: The fourth string to log.

String in_5: The fifth string to log.

String in_6: The sixth string to log.

ISDN_Xfer_Stat

The ISDN_Xfer_Stat state table encapsulates the actions necessary to use the

GetUserStatus custom server function. It is used by the incoming state table to

receive the user-specified status values returned by the outbound state table

after the make call. This call must be made after the TransferCall action and

before the TerminateCall or ReconnectCall actions.


functions.

Parameters:





If you specify a file name, event logging of the supplied data is performed

and the results are logged in the file you specify. The logging is performed by

the ISDN_Xfer_Log state table.

Number user_status: The status of the call to get the user status information.

The possible values are:

0 User status data is present.

1 Request to get user status is not valid at this time.

2 No user status data is available.

char user_status1[64]: User-defined status field that was sent by the outbound

state table during a transfer after the outbound call was made.









Number return_code (this value is returned): This value is returned to indicate

whether or not the call to the ISDN_Xfer_Data state table was successful. The

possible return values are:

0 The state table ran successfully

1 The OHSL to the ISDN_Call_Transfer custom server failed.

2 The SendData to the ISDN_Call_Transfer custom server failed.

3 The ReceiveData failed with a Timeout edge.

4 The ReceiveData failed with a No More Data edge.

5 The ReceiveData failed with a Data Not Found edge.

6 The ReceiveData failed with a Host Problem edge.

7 The ReceiveData failed with a Host Not Open edge.



What the ISDN single step call transfer application does

The SSTransfer custom server generates the ASN1 encoding data for the

facility message. Your application invokes the ssct_transfer state table to create

a facility message and send it to the network, which then connects the

existing incoming call with a new party. The process does not involve using

the ISDN_Call_Transfer custom server. For more information, refer to the

supplied ssct_tag example state table, which demonstrates how to use the

ssct_transfer state table.

The TIncoming_Call state table is used in place of the default Incoming_Call

state table. It is exactly the same as the Incoming_Call state table but saves

call data to a global variable before answering the call. The saved call data is

used to extract the calling party number when transfer is requested. The ssct

example state table demonstrates how to use SSTransfer custom server

alternative function call. Use this when the calling number is available to your

application.

Limitations of ISDN single step call transfer

There are some limitations associated with using ISDN single step call transfer

with WebSphere Voice Response. These limitations are:

v The two calls involved in the transfer (the original inbound call and the

outbound call to the third party) must be connected to WebSphere Voice

Response from the same switch. The specifications allow the two calls to be

on different trunks, provided that both trunks support ISDN single step call

transfer.

If the WebSphere Voice Response system has a mixture of CAS, SS7, and

ISDN trunks, the user application should ensure that the outbound call is

made on the correct trunk for a ISDN single step call transfer to be

successful.

v No user access is given to the information elements on the transfer.

v ISDN single step call transfer is not totally compatible with the WebSphere

Voice Response signaling model, so application changes will be required

when porting applications that involve transfer operations from different

telephony configurations.


The ISDN single step call transfer application is supplied as an installp image

that you install using the System Management Interface Tool (SMIT). The

application contains three components, including some source code to help

you customize the ISDN single step call transfer capability to your specific

needs. For a straightforward use of the ISDN single step call transfer

capability, no customizing should be required.

The components of the application are:



v Updated ISDN support.

v State tables (including source code):

The following state tables are provided (for definitions for these state tables,

see “State table definitions” on page 264):

ssct_transfer

ssct_tag

TIncoming_Call

ssct

The source code for these state tables is supplied in an ASCII file in the

same directory as the custom server: $CUR_DIR/ca/SSTransfer_dir

v Custom server:

A custom server, named SSTransfer, is supplied to perform the low-level

functionality of the transfer operation (for details of the available function

calls, see “Custom server function definitions” on page 259).

Note: Only the executable version (not the source code) of this custom

server is supplied.

Before you install

Before you can install the ISDN single step call transfer application, you must

have:

v A WebSphere Voice Response system running Version 4 Release 2 of

WebSphere Voice Response for AIX.

v A connection to a telephony switch using one or more trunks that support

ISDN single step call transfer.

v Two telephones attached to the same switch. In the instructions in this

chapter, these telephones are referred to as Phone A and Phone B.

v A third valid phone number that can be used to call into WebSphere Voice

Response, to be used as an application profile ID.

v A copy of the WebSphere Voice Response for AIX WebSphere Voice Response

for AIX: Installation guide.

v Sufficient disk space for the components you are installing (the WebSphere

Voice Response for AIX: Installation guide explains how to check this; see the

section “Ensuring you have enough disk space for the new software”).

Installing


1. Follow the instructions in “Installing the WebSphere Voice Response

software” in the WebSphere Voice Response for AIX: Installation guide to use

the System Management Interface Tool (SMIT) to install the PTF that

contains the ISDN single step call transfer application.



Starting WebSphere Voice Response

2. Start WebSphere Voice Response and log in to the user account you use

for WebSphere Voice Response administration.

Importing the custom server and state tables

3. In the WebSphere Voice Response Welcome window, click Applications

—> Application —> Import—> Replace—> File.

4. Select the file /usr/lpp/dirTalk/sw/SST/SSTransfer.imp.


5. Open the SSTransfer application.

The system displays the Application (SSTransfer) window.


The system displays the Application Profiles window, followed by the


7. Type any name in the Name field (for example, ISDNSST_Test).

8. Click State Table, then select your application that performs a call

transfer.

9. Click OK.



12. Click OK.

13. In the Application (SSTransfer) window, click View —> Refresh.




14. Open the Custom Server Manager window, and click Welcome —>

Operations —> Custom Server Manager


15. Start the SSTransfer custom server by clicking Run Status —> Start.

The Run Status button displays Waiting after a short while.


Note: The exact sequence here depends on your application. Assuming your

application is a simple one that asks for a number to transfer to, and

then evokes the ssct_transfer state table, the sequence of events should

be:16. Pick up Phone A’s handset and dial the application profile ID.



WebSphere Voice Response runs your application, which performs the

transfer to a third party. It answers the call and prompts you to input the

telephone number that you want to transfer to, followed by a # key.




The application completes the transfer when Phone B is answered and

the voice path for the two calls is connected within the switch.

19. The two remaining connections to WebSphere Voice Response (originally

connected to Phones A and B) are disconnected shortly after the transfer

is completed.

Configuring the SSTransfer custom server

The SSTransfer custom server has some command line parameters that you

can set to help you debug problems, or to fine-tune the operation of the

custom server.

The parameters are defined in Table 12 on page 257. For information on how

to set the parameters, see “Setting configuration options” on page 257.

Table 12. Configuration options for the SSTransfer custom server


-d off Provide extra debugging information (in addition to

the information that always gets sent). Valid values

are 0 (none) to 4 (everything). To set the logging

level to 3, specify –d3 .

-f DTstatus.out A fully qualified file name where trace output is to

be written, for example -f/home/dtuser/sstransfer.log. The SSTransfer custom server will

continue to write some critical information to

DTstatus.out.


To set one or more of the configuration options, follow the procedure below:

1. From the Welcome window, click on Applications —> Custom Servers

Setting a command line parameter for the custom server

2. Highlight the SSTransfer custom server.


The system displays the Custom Server (SSTransfer) window.


The system displays the Properties (SSTransfer) window.



5. Enter your command line parameters in the panel titles main() args.

6. Click OK.

The system closes the Properties (SSTransfer) window.

7. In the Custom Server (SSTransfer) window, click File —> Save.

Restarting the custom server

8. Open the Custom Server Manager window by clicking Welcome —>

Operations —> Custom Server Manager.


9. If the SSTransfer custom server Run Status is set to Waiting, stop the

custom server by clicking Run Status —> Stop.

The Run Status button should display None, after a short while.

10. Start the SSTransfer custom server by clicking Run Status —> Start.

After a short while the Run Status button should display Waiting. The

new command line parameters are now in effect. If the Run Status

remains at None, there is probably an error with one of the command

line parameters. Check the error log for details.

How to use ISDN single step call transfer

This section describes how to perform a transfer operation using the ISDN

single step call transfer mechanism.

If your requirements for transfer are fairly simple, you should only need to:

v Replace the default Incoming_Call state table with the supplied

TIncoming_Call state table or modify the existing Incoming_Call state table

so that the contents of SV542 (call data) are saved into SV51 before the call

is answered and the call data lost.

v Change your application so that it invokes the SST_Transfer state tables.

To support ISDN single step call transfer, the TransferCall state table action

has been upgraded to detect the presence of saved facility (FAC) tag data. If it

finds such data, it sends a facility message to the network using the

information contained in the tag.

The description in the WebSphere Voice Response for AIX: Application

Development using State Tables book of how the TransferCall state table action

works gives general information on how to perform a transfer. ISDN single

step call transfer using ISDN supports blind transfer only and not screened

transfer.


This section describes the custom server functions supplied with the ISDN

single step call transfer application. The purpose of the SSTransfer custom

server is to take address information and encode it as ASN.1 encoded data in

configuring the SSTransfer custom server


accordance with the facility message definition in Single Step Call Transfer

(SSCT) Supplementary Service (ECMA-300, edition 2 Dec 2001)


Two functions are provided with the SSTransfer custom server:

TransferTag

Allows calling number addressing details to be supplied in the TAG

format captured in SV252, supplied when an incoming call arrives.

TransferTag is described on page 262.

Transfer

Allows calling number addressing details to be supplied as separate

(number , number plan, and number type) parameters. Transfer is

described on page 263.

Messages from the custom server

The SSTransfer custom server issues standard custom server return codes only.

It does not issue alarms with a severity color code.



When you call, you will need details of any errors, your system setup, and

details of the conditions that cause the problem. You may also require an AIX

system trace taken when the problem occurs. Before taking the trace, set the

-d option in the custom server. For more information on the command line

options see “Configuring the SSTransfer custom server” on page 257

The possible return codes generated by the ISDN single step call transfer,

together with explanations and suggested responses, are as follows:

Table 13. ISDN single step call transfer return codes

Error

Code Description Explanation User response

0 Success ASN1 has been generated

successfully.

None required

1 Transfer to number

plan not valid

The custom server received a

number plan value which did

not conform to the allowed

values in the Single Step Call

Transfer (SSCT) Supplementary

Service (ECMA-300, edition 2

Dec 2001) specification.

Review the Single Step Call Transfer

(SSCT) Supplementary Service

(ECMA-300, edition 2 Dec 2001)

specification and change the number

plan setting to an allowed value.



Table 13. ISDN single step call transfer return codes (continued)

Error



type not valid


number type value which did not

conform to the allowed values in

the Single Step Call Transfer



specification.





type setting to an allowed value.


plan and number

type not consistent

The custom server received

number plan and number type

values which did not conform to

the allowed combinations in the

Single Step Call Transfer (SSCT)

Supplementary Service


specification.





plan and number type values to an

allowed combination.

4 AwaitConnect not set

to a valid value

The custom server received an

AwaitConnect parameter value

which did not conform to the

allowed values in the Single Step

Call Transfer (SSCT)



specification.




specification and change the

AwaitConnect parameter setting to

an allowed value.

6 Transferred number

not present and

presentation field

does not indicate it

should not be

present.

The custom server received no

transferred from number value

but the transfer from number

presentation value indicates that

it should be present.




specification and either add a

transferred from number or change

the transfer from number to indicate

that no transfer from number is

required.


presentation field not

valid


transferred number presentation

value which did not conform to

the allowed values in the Single

Step Call Transfer (SSCT)



specification.






setting to an allowed value.




Error



presentation and

screening fields are

inconsistent.

The custom server received


and screening values which did

not conform to the allowed

combinations in the Single Step

Call Transfer (SSCT)



specification.





transferred number presentation and

screening type values to an allowed

combination.

10 Internal error with

ASN1 generation

The custom server has

experienced an internal error in

its ASN1 generation

Re-create the problem and take an

AIX system trace (specify the –d3

command-line parameter for the

custom server), before calling IBM

Support.

21 No transferred

number present

The custom server received tag

data that does not contain a

transferred number within the

CLGN tag.

Review the tag data that is being

passed into the custom server by

taking a system-level trace. Correct

the tag data as appropriate.

22 Unable to determine

transferred number’s

number plan


data that does not contain or

does not contain a valid number

plan within the

CLGN.NUMBER_PLAN tag

attribute.







number type




type within the

CLGN.NUMBER_TYPE tag

attribute.







screening value




screening value within the

CLGN.NUMBER_SCREEN tag

attribute.







presentation value




presentation value within the

CLGN.NUMBER_PRESENT tag

attribute.








Error


31 State table

openhostserver failed

scct_transfer state table error Re-create the problem and take an

AIX system trace, before calling IBM

32 State table senddata

failed



33 State table receive

data failed with no

more data error



Support.


data failed with data

not found



Support.


data failed with host

problem



Support.


data failed with host

not open




data failed with

timeout



40 State table

TransferCall action

failed

An Edge other than Succeeded

was returned from the

TransferCall action

Re-create the problem and take an


TransferTag

Description: Allows calling number addressing details to be supplied in the

TAG format captured in SV252, supplied when an incoming call arrives.

Input parameters:

char TransferTag_TransfertoNumber[32]: The number to which the call is to be

transferred.

short TransferTag_TransfertoNumberPlan: The number plan for the number to

which the call is to be transferred.

short TransferTag_TransfertoNumberType: The number type for the number to


short TransferTag_AwaitConnect: Set to determine when the call should be

disconnected, either as soon as transfer is attempted or only after connection



is established to the third party. The values are as defined in Single Step Call

Transfer (SSCT) Supplementary Service (ECMA-300, edition 2 Dec 2001).

char TransferTag_callingdata[250]: The data as provided in SV252 on the

incoming call.

Output parameters:

short TransferTag_rc: The return code.

char TransferTag_data[250]: The ASN1 BER encoding of supplied called and

calling number parameters.

Transfer

Description: Allows calling number addressing details to be supplied as

separate (number, number plan, and number type) parameters.

Input parameters:

char Transfer_TransfertoNumber[32]: The number to which the call is to be

transferred.

short Transfer_TransfertoNumberPlan: The number plan for the number to


short Transfer_TransfertoNumberType: The number type for the number to


char Transfer_TransferredNumber[32]: The number to set as the number from

which the call is transferred.

short Transfer_TransferredNumberScreen: The screening indicator for the

number set as the number from which the call is transferred.

short Transfer_TransferredNumberPresent: The presentation indicator for the

number set as the number from which the call is transferred.

short Transfer_AwaitConnect: Set to determine when the call should be




Output parameters:

short TransferTag_rc: The return code.



char TransferTag_data[250]: The ASN1 BER encoding of supplied called and

calling number parameters.


This section describes the state tables supplied with the ISDN single step call

transfer application.

Four state tables are provided as compiled state tables and ASCII state table


state table source code. The source code for the state tables is provided in the

directory $CUR_DIR/ca/SSTransfer_dir.

The following sections describe the state tables.

TIncoming_Call

The TIncoming_Call state table replaces the default Incoming_Call state table.

It is exactly the same as Incoming_Call state table but saves call data to SV51

global variable before answering the call. The saved call data in SV51 can be

used to extract the calling party number when transfer is requested. If

Incoming_Call state table has already been modified, add a statement to save

SV252 to SV51. If SV51 is already in use then use another string global

variable and modify ssct_transfer state table to use it rather than SV51.


functions.

Parameters: None

ssct_transfer state table

The ssct_transfer state table is invoked from your application to create facility

message contents using the SSTransfer TransferTag function call and pass it

toWebSphere Voice Response. The transfer state table action is then used to

trigger the sending of the facility message and transfer the call. Refer to the

ssct_tag state table for an example of how to use the ssct_transfer state table.

The ssct_transfer state table assumes that call data (SV252) has been saved in

SV51.

The ssct_transfer state table only works if TIncoming call state table, or one

with similar functionality, has been used to replace Incoming_call state table.

The state table returns the following return code values:

31 State table openhostserver failed

32 State table senddata failed

33 State table receive data failed with no more data error



34 State table receive data failed with data not found

35 State table receive data failed with host problem

36 State table receive data failed with host not open

37 State table receive data failed with timeout

These return code values are issued along with those returned by the

SSTransfer custom server.

Parameters:

char TransferTag_TransfertoNumber[32]: The number to which the call is to be

transferred.

short TransferTag_TransfertoNumberPlan: The number plan for the number to


short TransferTag_TransfertoNumberType: The number type for the number to


short TransferTag_AwaitConnect: Set to determine when the call should be




char TransferTag_callingdata[250]: The data as provided in SV252 on the

incoming call.

ssct_tag

The ssct_tag state table is an example of how to use the ssct_transfer state

table.

Parameters: None

ssct

The ssct state table demonstrates how to use SSTransfer custom server

Transfer function call, which is used when calling party number details are

passed as individual parameters. You may choose to use this when you want

to specify a different calling party number from that passed on the original

call.

Parameters: None





Chapter 18. Using the IBM_Trombone_Custom_Server

This chapter describes the IBM_Trombone_Custom_Server.

v “What is a trombone (in telephony terms)?” on page 267

v “Installing the IBM_Trombone application” on page 269

v “Configuring IBM_Trombone_Custom_Server” on page 271

v “How to use the trombone operation” on page 274

v “Custom server functions” on page 280

v “State table definitions” on page 288

v “IBM_Trombone_Custom_Server errors” on page 308

What is a trombone (in telephony terms)?

A trombone operation occurs when a call coming in on one WebSphere Voice

Response channel connects directly with an outgoing call on another

WebSphere Voice Response channel.

This is how it works:

v A call arrives at WebSphere Voice Response, and the application decides

that the user needs to be connected to a third party using a trombone

operation.

v WebSphere Voice Response makes an outgoing call to the third party on

another channel.

v When they answer, the third party is connected to the original caller using

the TDM bus internal to the WebSphere Voice Response system. At this

point, the connection looks like this:


Note: Because the trombone operation uses the TDM bus, this function

requires either a DTTA or a DTXA card installed in the WebSphere

Voice Response system. A DTTA and a DTXA cannot coexist in the

same system unit.

What you can use a trombone for

There are two main reasons for using a trombone operation:

1. To simulate transfer.

If the combination of switch and WebSphere Voice Response you are using

cannot support transfer, you can use the trombone operation to simulate a

transfer operation with a trombone operation. The connection is

maintained until either the caller or the third party terminates the call by

hanging up.

This has the disadvantage over a normal switch-based transfer operation

that two WebSphere Voice Response channels are occupied for the whole

time that the caller and third party are talking. With a switch-based

transfer, the channel between the caller and WebSphere Voice Response is

broken as soon as the caller is transferred to the third party.

2. To allow consultation with a third party, returning to the WebSphere Voice

Response application.

The trombone allows the caller to consult with a third party. When the

third party hangs up, or the caller terminates the consultation, the caller is

connected back to WebSphere Voice Response at the point where they left

the application they were using.

This might be useful in a voice mail application, for example, where a

caller can break out to respond to an urgent voice mail message, then

return to processing the rest of the voice mail after dealing with the urgent

matter.

Switch WebSphere Voice Response

LineInterface

TDM bus ApplicationCaller connects toWebSphere Voice Response

WebSphere Voice Responsecalls third party

and connects them tocaller using the TDM bus

Figure 43. Voice path between caller and third party during a trombone operation

what is a trombone (in telephony terms)?


Installing the IBM_Trombone application

This section describes the components of the IBM_Trombone application, and

the procedure you use to install it and check its operation.

Components of the IBM_Trombone application

The IBM_Trombone application is available in an import file called

IBM_Trombone.imp, which you can find in the $VAE/sw/samples directory. (You

must install the samples LPP to have access to this function.)

The application contains four components and some source code to help you

customize the trombone operation to your specific needs. If you just need

straightforward tromboning, you need no customization. The components of

the application are:

State tables

There are 14 state tables:

IBMTromboneCall IBMTromboneMus

IBMTromboneConn IBMTromboneOut

IBMTromboneC5 IBMTromboneRdy

IBMTromboneC10 IBMTromboneWait

IBMTromboneDisc IBMTromboneXmp

IBMTromboneLog IBMTromboneXmpA

IBMTromboneMake IBMTromboneXmpB

For definitions of these state tables, see “State table definitions” on

page 288.

Prompt directories

A prompt directory called IBMTrombone holds the prompts required

by the IBMTromboneXmp state table sample application.

Note: All the supplied state tables specify this prompt directory; you

may need to change it if you customize the state tables.

Voice directories

A voice directory called IBMTrombone holds the voice segments

required by the IBMTromboneXmp state table sample application. The

prompts in the IBMTrombone prompt directory access these segments.

Custom servers

A custom server called IBM_Trombone_Custom_Server performs the

low-level functions of the trombone operation.

installing the IBM_Trombone application

Chapter 18. Using the IBM_Trombone_Custom_Server 269

See “Custom server function definitions” on page 280 for details of

the available calls.

Note: We supply only the binary (not the source code) of this custom

server.

Source code

Source code for the 14 state tables listed above is supplied in ASCII

format in the same directory as the custom server. See the directory

$CUR_DIR/ca/IBM_Trombone_Custom_Server_dir for the source code.

Installing the IBM_Trombone application

To install the application and check that you can use the trombone operation

on your system, follow the procedure given below:

Prerequisites

v A WebSphere Voice Response system with one or more DTTA or DTXA

adapters. If two or more DTTA or DTXA adapters are installed, connect

them together using an H.100 ribbon cable. If only one is installed, you do

not need an H.100 cable.

Note: DTTA and DTXA adapters cannot coexist in the same system unit.

v A connection to a switch or public network using a trunk that supports

both incoming and outgoing calls.

v Two telephones attached to the same switch or network. In the instructions,

these are referred to as Phone A and Phone B.

v A third valid phone number, to be used as an application profile ID.

Procedure


Importing the application

2. Click Application —> Import.

3. Click the /usr/lpp/dirTalk/sw/samples/IBM_Trombone.imp file.

The system displays the IBM_Trombone application icon.


4. Open the Trombone application.

The system displays the Application (IBM_Trombone) window.


The system displays the Application Profiles window followed by the


6. Type any name in the Name field (for example, “Trombone Example”).

7. Click State Table —> IBMTromboneXmp



8. Click OK.



11. Click OK.

12. In the Application (IBM_Trombone) window, click View —> Refresh.




13. Open the Custom Server Manager window: Welcome —> Operations

—> Custom Server Manager


14. Start the IBM_Trombone_Custom_Server: Run Status —> Start.

The Run Status button should display Waiting after a short while.

Running the application

15. Pick up Phone A’s handset and dial the application profile ID.

WebSphere Voice Response answers the call and prompts you to input a

telephone number.




The two calls are connected by the TDM bus completing a voice path

between the two telephones.

18. If phone B hangs up, or Phone A dials 1234, the trombone operation

terminates and Phone A is prompted to enter another telephone number.

If the trombone operation doesn’t work, WebSphere Voice Response plays

a “Technical difficulties” message, and hangs up the call with Phone A

(and Phone B if the operation got that far).

Configuring IBM_Trombone_Custom_Server

IBM_Trombone_Custom_Server has a number of command-line parameters

that you can set to help debug problems, or to fine tune the operation of the

custom server. These are defined in Table 14.

Table 14. Configuration options for IBM_Trombone_Custom_Server.

Parameter Default Description

-d off Provide extra debugging information (over and above

the normal information that always gets sent).



Table 14. Configuration options for IBM_Trombone_Custom_Server. (continued)

Parameter Default Description

-s off Print debugging information to stdout as well as to

AIX system trace.

-a off Send extra Information alarms to the error log.

-pn n=0.1 Number of child helper processes to run.

See “About child helper processes” on page 272 for

information about setting this parameter.

-en 0 The event data (n) sent by the custom server if the

third party hangs up (see the WebSphere Voice Response

for AIX: Custom Servers guide:

CA_Report_Channel_Event()).

-in 0 The information field (n) sent by the custom server if

the third party hangs up (see the WebSphere Voice

Response for AIX: Custom Servers guide:

CA_Report_Channel_Event()).

-z off This parameter is for test purposes only. It causes the

custom server to enrol one of each type of error

possible on custom server start-up, then terminates.

The enrolment of errors takes about 30 seconds.

About child helper processes

IBM_Trombone_Custom_Server uses a number of child helper processes to

make the TDM connection and disconnection requests, which block other

TDM connection and disconnection requests while they are being processed.

These helper processes are required only during the actual connection or

disconnection phase of a trombone, so you must have enough to cope with

the peak demand of trombone connections or disconnections.

A good compromise between process availability and response time is to have

one process for every 10 possible trombone operations. This is why the

default value for the -pn parameter is 0.1. If you only need the trombone

operation rarely, you can reduce this value, slightly reducing the system load.

If you supply a value for n to override the default, the meanings of various

values are:

0 < -pn <= 1

The number of child processes to run = n * max_trombones (with a

minimum of 2 child processes)

-pn > 1

The number of child processes to run = n (with a maximum of number

of channels/2)

configuring IBM_Trombone_Custom_Server


-pn < 0

Use the default value of -pn=0.1

Note: Maximum number of trombones = number of channels/2.


To set one or more of these options, follow the procedure below:

Procedure

1. From the Welcome window, click on Applications —> Custom Servers

2. Highlight IBM_Trombone_Custom_Server

Setting a command- line parameter for the custom server


The system displays the Custom Server (IBM_Trombone_Custom_Server)

window.


The system displays the Properties (IBM_Trombone_Custom_Server)

window.

5. Enter your command-line parameters in the panel title main() args.

6. Click OK.

The system closes the Properties (IBM_Trombone_Custom_Server)

window.

7. From the Custom Server (IBM_Trombone_Custom_Server) window, click

File —> Save.

Re-starting the custom server

8. Open the Custom Server Manager window: Welcome —> Operations

—> Custom Server Manager.


9. If the IBM_Trombone_Custom_Server Run Status is set to Waiting, the

custom server must have stopped. Stop IBM_Trombone_Custom_Server:

Run Status —> Stop.

The Run Status button should display None after a short while.

10. Start IBM_Trombone_Custom_Server: Run Status —> Start.

The Run Status button should display Waiting after a short while and the

new command-line parameters will be in effect.

11. If the Run Status remains at None, there is probably an error with one of

the command-line parameters. Check the error log for details.

configuring IBM_Trombone_Custom_Server


How to use the trombone operation

A number of state tables are provided to allow you to set up a trombone

operation. If your requirements for the trombone function are straightforward,

you can use the supplied state tables without modification. The

IBMTromboneXmp sample application demonstrates how to use the

IBMTromboneCall state table to make a tromboned call to a third party in one

simple operation, and a high level flow chart for this application is given in

Figure 44 on page 275.

If your requirements are more complex, a number of state tables are provided

that break down the function provided by the IBMTromboneCall state table

into several stages. For most users, this should allow more control over setting

up the trombone operation without having to modify the supplied state

tables. The state tables that break down the IBMTromboneCall function are

IBMTromboneMake, IBMTromboneRdy, IBMTromboneConn,

IBMTromboneDisc, and IBMTromboneWait. The two state tables

IBMTromboneXmpA and IBMTromboneXmpB show two slightly different

ways of using these state tables to setup a trombone operation.

This section uses the IBMTromboneXmp application to explain trombone

operation.

As you can see, you must supply the IBMTromboneCall state table with the

phone number to which to make the outbound part of the trombone call and

the format string for dialing this number. You can leave all other parameters

to the IBMTromboneCall state table blank, unless you want to use the extra

functionality they provide.

In the IBMTromboneXmp state table, two additional features are used:

1. The log_file_name parameter is set to Trombone_Test to provide an event

log of all the trombone calls. See the WebSphere Voice Response for AIX:

Configuring the System guide for information about viewing logged events.

2. The end_on_DTMF parameter is set to “1234” to allow the caller to

disconnect the trombone call by dialing 1234 during the trombone

operation.

how to use the trombone operation


How tromboning works

This section describes the calls that should occur to set up and terminate a

trombone operation. These actions are encapsulated within IBMTromboneCall

(caller state table), IBMTromboneOut (third party state table), and

IBM_Trombone_Custom_Server. They describe the order in which events

Incoming Call starts state table IBMTromboneXmp

Initialize variables and AnswerCall

PlayPrompt and use GetData to determine thenumber to trombone to

Make a format string for the number (all #s in thisexample, but you may need to add a leading .

(period) or , (comma) depending on your telephony

Playprompt toindicate a

disconnection.

InvokeStateTable(IBMTromboneCall)phone_number=supplied phone number

format=derived format stringlog_file_name=”Trombone_Test”

user_data=blankout_stbl_name=blank (default:IBMTromboneOut)

end_on_DTMF=”1234”music_on_hold=blank (default: no music on hold)

call_status (return code)-------------------------------------------------------------------

Return Edge 0--------------------------------------------------------------------

Return Edge 1Return Edge 2Return Edge 3

PlayPrompt to indicate a technical problem

CloseEverything

Figure 44. High-level flow chart for the IBMTromboneXmp state table



should occur for a successful trombone operation. If you customize the

supplied state tables, make sure that you don’t change this event flow, or the

customized trombone function may not work correctly.

This section describes:

1. “Setting up a trombone operation”

2. “Terminating a trombone operation using third party hang-up” on page

277

3. “Terminating a trombone operation using caller hang-up” on page 278

4. “Voice paths” on page 279

Setting up a trombone operation

1. The Caller state table issues an OpenHostServerLink and a TromboneCall

request to IBM_Trombone_Custom_Server and waits for the result.

2. IBM_Trombone_Custom_Server invokes the IBMTromboneOut state table.

3. The IBMTromboneOut state table makes a call to the third party and

returns the success or failure using the TromboneMakeCallStatus function

of IBM_Trombone_Custom_Server after issuing an OpenHostServerLink. It

then uses the WaitEvent state table action to wait for a hang-up or host

event.

4. IBM_Trombone_Custom_Server connects the caller and third party on the

TDM bus and informs the caller state table of the success or failure of the

original TromboneCall request.

Caller

Third party

Incoming Channel Outgoing ChannelIBM_Trombone_Custom_Server

IBMTromboneCall

OpenHostServerLink

SendData(TromboneCall) InvokeStateTable

(default = IBMTromboneOut) IBMTromboneOut

ReceiveData(TromboneCall) MakeCall

Third partyanswers

SendData(TromboneMakeCallStatus)Connect caller and third party

using CA_TDM_Connect()

Send response toTromboneMakeCall request

Note new connection

WaitEventfor DTMF, hang-up

or host event


or host event

Figure 45. Event flow required to set up a trombone operation.



5. The caller state table uses the WaitEvent state table action to wait for a

hang-up, host event, or caller DTMF keys.

At this point, the caller is connected to the third party using the TDM bus and

the incoming and outgoing channels are waiting for an event.

Terminating a trombone operation using third party hang-up

1. When the third party hangs up, CloseEverything, TerminateCall, or

CloseHostServerLink tells IBM_Trombone_Custom_Server that this has

happened.

2. IBM_Trombone_Custom_Server disconnects the caller and third party from

the TDM bus and sends a HostEvent to the Caller state table to indicate a

third party hang-up.

3. The Caller state table uses CloseHostServerLink to detach from

IBM_Trombone_Custom_Server.

At this point, the caller is connected back to the state table application that

invoked the IBMTromboneCall state table, and the third party has been

disconnected.


or host event

Third party


IBMTromboneCall

CloseHostServerLink

IBMTromboneOut

hangs up

CloseEverything(Implied CloseHostServerLink)Disconnect caller and third

party using

Send host event to caller


or host event

Hang-up event

CA_TDM_Disconnect()

Host event

Clean up connection details

ExitStateTable

Figure 46. Event flow required to terminate a trombone operation when the third party hangs up



Terminating a trombone operation using caller hang-up

1. The caller state table uses CloseHostServerLink, TerminateCall, or

CloseHostServerLink to tell IBM_Trombone_Custom_Server that the caller

has hung up.


the TDM bus and sends a HostEvent to the third party state table to

indicate that the caller has terminated the trombone operation.

3. The third party state table uses CloseEverything, CloseHostServerLink, or

TerminateCall to detach from IBM_Trombone_Custom_Server.

At this point, the caller and the third party have both been disconnected. The

caller state table that invoked the IBMTromboneCall state table is still running

and may perform clean-up operations that don’t involve interacting with the

caller.


or host event


IBMTromboneCall

CloseHostServerLink

IBMTromboneOut

CloseEverything(Implied CloseHostServerLink)

Disconnect caller and thirdParty using



or host event

Hang-up event

CA_TDM_Disconnect()

Host event


ExitStateTable

Callerhangs up

with return code to indicatethat the caller has hung up

Third partydisconnected

Figure 47. Event flow required to terminate a trombone operation when the caller hangs up



Terminating a trombone operation using caller DTMF

1. If the caller state table detects a valid sequence of DTMF keys from the

caller requesting the trombone to terminate, it sends

TromboneDisconnectCall to IBM_Trombone_Custom_Server.


the TDM bus and replies to the TromboneDisconnectCall.

3. The caller state table then uses CloseHostServerLink to inform

IBM_Trombone_Custom_Server that the caller has ended the trombone

operation. (Using TerminateCall or CloseEverything would disconnect the

caller which is probably not what you want at this point.)

4. IBM_Trombone_Custom_Server sends a HostEvent to the third party state

table to indicate that the caller has terminated the trombone operation.

5. The caller state table uses CloseEverything, CloseHostServerLink, or

TerminateCall to detach from IBM_Trombone_Custom_Server (and hang

up on the third party if desired).

At this point, the caller is connected back to the state table application that

invoked the IBMTromboneCall state table, and the third party has been

disconnected.

Voice paths

Although the main aim of a trombone operation is to connect two parties,

WebSphere Voice Response can still make announcements to the two parties

and record their voices during the trombone operation. You will find a


or host event


IBMTromboneCall

CloseHostServerLink

IBMTromboneOut

CloseEverything(Implied CloseHostServerLink)

Disconnect Caller and thirdparty using



or host event

DTMF event

CA_TDM_Disconnect()

Host event


ExitStateTable

Callerdials DTMF

SendData(TromboneDisconnectCall)

ReceiveData(TromboneDisconnectCall)

Send response toTromboneMakeCall request

Third partydisconnected

Figure 48. Event flow required to terminate a trombone operation when the caller requests this by

dialing a DTMF sequence



discussion of the voice paths used in the trombone operation, and problems

that might be caused by echo, see “Voice paths” on page 217.


In this section we describe the five functions supplied with

IBM_Trombone_Custom_Server, and how you can configure the custom server

to meet your own requirements.

v The 14 trombone state tables (“State table definitions” on page 288).


IBM_Trombone_Custom_Server has five functions, which have to be used in

the correct order for a successful trombone operation. (See “How tromboning

works” on page 275 for details of which custom server calls to use.)

There are some configuration options that you can use to fine tune the

operation of the custom server; see “Configuring

IBM_Trombone_Custom_Server” on page 271 for details.

The custom server functions are defined in the following sections:

v “TromboneCall” below

v “TromboneMakeCall” on page 283

v “TromboneMakeCallStatus” on page 285

v “TromboneConnectCall” on page 286

v “TromboneDisconnectCall” on page 287

Note: Throughout the sections that follow, you will find numerous

cross-references in the form “see the definition of....”. All these

references are to sections in the State Tables, Prompts, and Voice Segments

book.

TromboneCall

Description

TromboneCall is called with several parameters, most of them required for the

MakeCall action itself, and to determine which state table to use to make the

call.

Using the data provided by the input parameters, the custom server invokes a

state table (by default IBMTromboneOut) to make a call to the third party. It

then waits for a response in the form of a TromboneMakeCallStatus request

from the invoked state table. If this response indicates that the outbound call

was successful, the custom server requests TDM Manager to connect the caller

and third party using the TDM bus. When this completes successfully, the



TromboneCall request returns a zero response in the make_call_status to

indicate that the trombone is in place and the two parties are connected.

If any of the steps in this process fails, the TromboneCall request returns a

non-zero response in the make_call_status to indicate that the trombone

operation has failed for the given reason.

Input parameters

char phone_number[40]: The number to dial for the outgoing part of the

trombone (see the definition of phone_number in the MakeCall state table

action for details).

char format[50]: The format string for the number to dial for the outgoing

part of the trombone (see the definition of format in the MakeCall state table


char permitted_channel_groups[64]: The permitted channel groups for the

outgoing part of the trombone (see the definition of SV178 for information on

how to use this variable).

char permitted_channels[64]: The permitted channels for the outgoing part

of the trombone (see the definition of SV228 for information on how to use

this variable).

char log_filename[64]: The filename to receive event logging information.

Leave this blank if you want no event logging.

char user_data[64]: Some user-defined data for simple communications from

the IBMTromboneCall state table to the IBMTromboneOut state table.

This may be used, for example, to reference a prompt to be played as an

announcement to the third party before the trombone operation connects them

to the caller.

char outbound_state_table_name[16]: The name of the state table to use for

the outbound part of the trombone operation. If this is blank, the default state

table IBMTromboneOut is used.

char outbound_state_table_entry_point[16]: The entry point to use within

the state table used for the outbound part of the trombone operation. If this is

blank, the default label begin is used.

char additional_call_info1[140]: Reserved for WebSphere Voice Response.






char additional_call_info5[35]: Reserved WebSphere Voice Response.

Output parameters

short trombone_make_call_status: The trombone_make_call_status for the

TromboneCall request indicates the status of the trombone operation. The

trombone_make_call_status falls into various groups defined in Table 15 on

page 282.

Table 15. Return values for the trombone_make_call_status parameter of the

TromboneCall function

Make

Call

Status Error Description

0 The trombone request was successful.

1 - 99 Bad return code from the IBMTromboneOut state table

100 The IBMTromboneOut state table returned a trombone_make_call_status

outside the valid range (0 to 99).

101 The IBMTromboneOut state table performed a CloseHostServerLink while

the custom server was waiting for a response to the TromboneMakeCall

request

102 The custom server request is invalid at this time (probably because of an

error in the sequence of custom server calls).

103 CA_Open_CHP_Link() failed, probably because there are not enough free

CHPs.

104 CA_Execute_State_Table() failed, probably because of an invalid state table

name, entry point, or the state table not being validated.

105 CA_Get_Channel_Info() failed, probably because the outbound call has

been terminated.

106 A TDM connect or disconnect request failed because of an adapter

hardware problem.

107 A TDM connect or disconnect request failed because the requested port is

already connected. This may be caused by other applications running that

can make TDM connect and disconnect requests.

108 A TDM connect or disconnect request failed because there is no call

present. One of the parties has probably hung up.

109 A TDM connect or disconnect request failed because the Timeslot Manager

is not ready. It may be very busy, or not available.




TromboneCall function (continued)

Make

Call


110 A TDM connect or disconnect request failed because of an internal custom

server problem.

111 A TDM connect or disconnect request failed because of an unexpected

return code.

112-199 Spare: may be used for user-defined values.

TromboneMakeCall

Description

TromboneMakeCall is called with several parameters, most of them required

for the MakeCall action and to determine which state table to use to make the

call.

Using the data provided by the input parameters, the custom server invokes a

state table (the default is IBMTromboneOut) to make a call to the third party.

It then waits for a response in the form of a TromboneMakeCallStatus request

from the invoked state table. If this response indicates that the outbound call

was successful, the custom server returns a zero response in the

make_call_status to indicate that the outbound call is in place. The

TromboneConnect function call should be used next to connect the caller and

the third party.

If any of the steps in this process fail, the TromboneMakeCall request returns

a non-zero response in the make_call_status to indicate that the trombone


Input parameters

char phone_number[40]: The number to dial for the outgoing part of the

trombone (see the definition of Phone_Number in the MakeCall state table


char format[50]: The format string for the number to dial for the outgoing

part of the trombone (see the definition of format in the MakeCall state table


char permitted_channel_groups[64]: The permitted channel groups for the

outgoing part of the trombone (see the definition of SV178 for information on

how this variable is used).



char permitted_channels[64]: The permitted channels for the outgoing part

of the trombone (see the definition of SV228 for information on how this

variable is used).

char log_filename[64]: The filename to which to send event logging

information. This should be blank if no event logging is required.

char user_data[64]: Some user-defined data for simple communications from

the IBMTromboneCall state table to the IBMTromboneOut state table.

char outbound_state_table_name[16]: The name of the state table to use for

the outbound part of the trombone operation. If this is blank, the default state

table “IBMTromboneOut” is used.

char outbound_state_table_entry_point[16]: The entry point within the state

table to use for the outbound part of the trombone operation. If this is blank,

the default label begin is used.






Output parameters

short trombone_make_call_status: The trombone_make_call_status for the

TromboneMakeCall request indicates the status of the trombone operation.

The trombone_make_call_status falls into various groups defined in Table 16

on page 285.

long partner_call_id: The Call Reference of the outbound part of the

trombone operation. It is supplied to provide a unique link between the two

halves of the trombone operation, for debug purposes.

string user_status_data[65]: Some user-defined data provided to allow for

simple communications from the outbound state table to the inbound state

table. This may be used, for example, to indicate the response of the third

party to the trombone request (such as a reason code for connection refused).

The inbound state table can then play a prompt to the caller appropriate to

the third party response.




TromboneMakeCall function

Make Call


0 Trombone function request was successful.

1 - 99 Bad return code from the IBMTromboneOut state table.

100 IBMTromboneOut state table returned a trombone_make_call_status

outside the valid range (0 to 99).

101 The IBMTromboneOut state table performed a CloseHostServerLink

while the custom server was waiting for a response to the

TromboneMakeCall request.

102 The custom server request is invalid at this time (probably because of

an error in the sequence of custom server calls).

103 CA_Open_CHP_Link() failed, probably because there were not enough

free CHPs.

104 CA_Execute_State_Table() failed, probably because of an invalid state

table name, entry point, or the state table not being validated.

105 CA_Get_Channel_Info() failed, probably because the outbound call was

terminated.

112-199 Spare

TromboneMakeCallStatus

Description

TromboneMakeCallStatus is called by the IBMTromboneOut state table when

the result of the outbound call part of the trombone function is known, or if

there has been some other error. The values it can return are in the range 0

(success) to 99. Table 17 on page 285 shows the initial meaning of values

between 1 and 99, but you can customize these if you want.

Input parameters

short trombone_make_call_status: The status of the outgoing part of the

trombone. See Table 17 on page 285 for initial values.

Table 17. Status values supplied by the TromboneMakeCallStatus function

Call Status Error Description


The following return codes represent a bad return code from the MakeCall request to

the third party by the IBMTromboneOut state table (assuming that you have not

customized the IBMTromboneOut state table to alter these values)

1 Invalid phone number



Table 17. Status values supplied by the TromboneMakeCallStatus function (continued)

Call Status Error Description

2 Invalid format string

3 Phone busy

4 Network busy

5 No answer

6 Outbound line problem

7 No line available

8 Channel active

9 Unexpected tone

The following return codes represent a bad return code from the IBMTromboneOut

state table, other than from the MakeCall request (assuming that you have not

customized the IBMTromboneOut state table to alter these values)

10 to 99 These values are reserved for user-defined return values.

Output parameters

None.

TromboneConnectCall

Description

TromboneConnectCall is usually used by the originator of the trombone

function (the caller) to connect the two halves of a trombone operation, after

the original state table has set up the outbound part of the trombone using

the TromboneMakeCall custom server. When it receives this request, the

custom server uses TDM Manager to connect the caller and third party using

the TDM bus. When this completes successfully, TromboneConnectCall returns

a zero response in the connect_call_status to indicate that the two trombone

parties are now connected.

If this process fails, TromboneConnectCall returns a non-zero response in

connect_call_status to indicate that the trombone connect operation has failed

for the given reason.

Input parameters

None.

Output parameters

short trombone_connect_call_status: The status of the connect request; zero

means that the operation was successful. Error cases are shown in Table 18 on

page 287 and are a subset of those shown in Table 15 on page 282.





Make Call




terminated.


hardware problem.

107 A TDM connect or disconnect request failed because the requested port

was already connected. This may be caused by other applications

running that can make TDM connect and disconnect requests.

108 A TDM connect or disconnect request failed because there was no call


109 A TDM connect or disconnect request failed because the Timeslot

Manager was not ready. It may be very busy, or not available.

110 A TDM connect or disconnect request failed because of an internal

custom server problem.


return code from the connect or disconnect request.

112-199 Spare

TromboneDisconnectCall

Description

TromboneDisconnectCall is usually used by the caller to terminate the

trombone operation and remain connected to WebSphere Voice Response.

When it receives this request, the custom server asks TDM Manager to

disconnect the caller and third party from the TDM bus. When this completes

successfully, the TromboneDisconnectCall request returns a zero response in

the disconnect_call_status to indicate that the two trombone parties are now

disconnected, and that the caller is connected to WebSphere Voice Response.

If this process fails, the TromboneDisconnectCall request returns a non-zero

response in the disconnect_call_status to indicate that the trombone disconnect


Input parameters

None.



Output parameters

short trombone_disconnect_call_status: The status of the disconnect request,

as shown in Table 19 on page 288.



Make

Call




terminated.


hardware problem.

107 A TDM connect or disconnect request failed because the requested port

was already connected. This may be caused by other applications running

that can make TDM connect and disconnect requests.

108 A TDM connect or disconnect request failed because there was no call


109 A TDM connect or disconnect request failed because the Timeslot Manager

was not ready. It may be very busy, or not available.

110 A TDM connect or disconnect request failed because of an internal custom

server problem.


return code from the request.

112-199 Spare: may be used for user-defined values.


In this section we describe the 14 trombone state tables.

The state tables are provided as compiled state tables and ASCII state table


state table source code.

The state tables fall into three groups:

Example code

To show how to perform a trombone operation with a single

InvokeStateTable call (IBMTromboneXmp, IBMTromboneXmpA, and

IBMTromboneXmpB).



Trombone implementation code

To encapsulate the complexities of the trombone operation

(IBMTromboneCall, IBMTromboneConn, IBMTromboneDisc,

IBMTromboneMake, IBMTromboneOut, IBMTromboneRdy, and

IBMTromboneWait).

Helper state tables

To encapsulate code that is used in various places and to keep the

trombone implementation code simple (IBMTromboneC5,

IBMTromboneC10, IBMTromboneLog, and IBMTromboneMus).

The state tables are described, in alphabetic order, in the following sections:

v “IBMTromboneCall”

v “IBMTromboneConn” on page 295

v “IBMTromboneC5” on page 296

v “IBMTromboneC10” on page 296

v “IBMTromboneDisc” on page 297

v “IBMTromboneLog” on page 298

v “IBMTromboneMake” on page 298

v “IBMTromboneMus” on page 301

v “IBMTromboneOut” on page 301

v “IBMTromboneRdy” on page 303

v “IBMTromboneWait” on page 304

v “IBMTromboneXmp” on page 306

v “IBMTromboneXmpA” on page 306

v “IBMTromboneXmpB” on page 307

IBMTromboneCall

This state table encapsulates the code needed to create the trombone between

a caller and a third party in a single call. This state table is called by the

user’s application, along with a number of parameters using the

InvokeStateTable action. The code is encapsulated in this way to allow it to be

used in a similar way to other telephony actions without having to be

concerned about the details of performing the trombone.

If the trombone is set up successfully, this state table will not return until

either one of the parties hangs up, or the caller terminates the trombone by

dialing a specified number using DTMF keys.

If the trombone operation fails, the state table exits immediately with a status

code (and return edge) that indicates what the problem is.



For details of the communications that this state table performs with

IBM_TromboneCustom_Server, see “How tromboning works” on page 275.

The source code is commented to help make customization easy. The ability to

log data and turn background music on and off has been provided in two

separate state tables (IBMTromboneLog and IBMTromboneMus) that you can

invoke to prevent this state table becoming too complex and cluttered.

Parameters

String phone_number (40 character max): The number to dial for the

outgoing part of the trombone (see the definition of phone_number in the

MakeCall state table action for details).

String format (50 characters max): The format string for the number to dial

for the outgoing part of the trombone (see the definition of format in the


String log_filename (64 characters max): If this is blank, no event logging is

performed. If you supply a filename, the IBMTromboneLog state table logs

trombone calls and their results to an event log with that filename.

String user_data (64 characters max): Some user-defined data for simple

communications from the IBMTromboneCall state table to the

IBMTromboneOut state table.


announcement to the third party before the trombone operation connects the

third party to the caller.

String out_stbl_name (16 characters max): The name of the state table to use

for the outbound part of the trombone operation. If this is blank, the default

state table IBMTromboneOut is used.

String out_stbl_entry (16 characters max): The entry point to use within the

state table used for the outbound part of the trombone operation. If this is

blank, the default label of begin is used.

String end_on_DTMF (64 characters max): If this is blank, the state table

ignores any DTMFs it receives from the caller during the trombone operation.

If this parameter contains a number (one or more digits), it terminates the

trombone operation on receiving the given number from the caller. When the

trombone terminates, the third party is disconnected and the caller remains

connected to WebSphere Voice Response.



If this parameter is set to -, the trombone terminates when it receives any

DTMF from the caller. Valid DTMF digits are 0 to 9, *, and #.

String music_on_hold (64 characters max): If this is blank, the state table

doesn’t play any background music to the caller while the trombone operation

is being set up.

If this parameter contains a string, the state table tries to play background

music (simulating music on hold) to the caller while the trombone is being set

up. This parameter defines the name of the music file to play.

See Chapter 14, “Background music,” on page 193 for details of how to setup

and configure background music.

Note: If background music is not configured on WebSphere Voice Response,

and you try to play background music during the trombone operation,

that operation will fail.

Number call_status (this value is returned): The returned status of the

trombone operation.

If the value is zero, the trombone operation was successful and was

terminated by either the third party hanging up, or the caller requesting a

disconnection by dialling the correct DTMF sequence.

If this value is non-zero, the trombone operation did not complete

successfully. Table 20 on page 291 shows the meanings of the possible

call_status values. Valid values are any given in the table except those

between 221 and 227.

This state table returns different edges depending on where in the range of

possible values the call_status (also defined in Table 20). This allows the

general area of the problem to be determined immediately by the return edge

of the InvokeStateTable action that called IBMTromboneCall.

Table 20. Return values from the IBMTromboneCall state table (call_status)

Return

Edge

Call


0 0 Trombone function request was successful.

1 Bad return code from the MakeCall request to the third party by the

IBMTromboneOut state table (assuming that the IBMTromboneOut and

IBMTromboneCall state tables have not been customized to alter these

values)

1 Invalid phone number

2 Invalid format string



Table 20. Return values from the IBMTromboneCall state table

(call_status) (continued)

Return

Edge

Call


3 Phone busy

4 Network busy

5 No answer

6 Outbound line problem

7 No line available

8 Channel active

9 Unexpected tone

2 Bad return code from the IBMTromboneOut state table, other than from

the MakeCall request (assuming that the IBMTromboneOut and

IBMTromboneCall state tables have not been customized to alter these

values)

10 to 99 These values are reserved for user-defined return values.

3 Bad return code from the IBM_Trombone_Custom_Server (assuming that

the IBMTromboneCall state table has not been customized to alter these

values)

100 IBMTromboneOut state table returned a

trombone_make_call_status outside the valid range (0 to 99).

101 The IBMTromboneOut state table performed a

CloseHostServerLink while the custom server was waiting for a

response to the TromboneMakeCall request

102 The custom server request is invalid at this time (probably

because of an error in the sequence of custom server calls).

103 CA_Open_CHP_Link() failed, probably because there are not

enough free CHPs.

104 CA_Execute_State_Table() failed, probably because of an

invalid state table name, entry point, or the state table not

being validated.

105 CA_Get_Channel_Info() failed, probably because the outbound

call was terminated.

106 A TDM connect or disconnect request failed because of an

adapter hardware problem.

107 A TDM connect or disconnect request failed because the

requested port was already connected. This may be caused by

other applications running that can make TDM connect and

disconnect requests.





Return

Edge

Call


108 A TDM connect or disconnect request failed because there was

no call present. One of the parties has probably hung up.

109 A TDM connect or disconnect request failed because the

Timeslot Manager is not ready. It may be very busy or not

available.


internal custom server problem.


unexpected return code from the connect or disconnect request.

112-199 Spare

4 Bad status returned from the IBMTromboneCall state table itself (assuming

that the IBMTromboneCall state table has not been customized to alter

these values)

200 IBM_Trombone_Custom_Server returned a

trombone_make_call_status outside the valid range (0 to 199).

201 Could not open a server link to the


202 Failed to send the data for the TromboneMakeCall request to

the IBM_Trombone_Custom_Server

203 to

207

Bad return code from the ReceiveData corresponding to the

TromboneMakeCall request. A status of 203 to 207 represents a

return edge of 1 to 5.

208 The caller hung up during the trombone operation.

209 Received a Fax Event during the trombone operation (SV227 is

probably not set to zero).

210 Received a Voice Event during the trombone operation (SV227

is probably not set to zero).

211 Received a Long Silence Event during the trombone operation.

212 Received a Line Problem Event during the trombone operation.

213 Received a Timeout Event during the trombone operation.

214 The timeout specified in the Wait Event was invalid.

215 Failed to send the data for the TromboneDisconnectCall request

to the IBM_Trombone_Custom_Server.

216 to

220


TromboneDisconnectCall request. A status of 216 to 220

represents a return edge of 1 to 5.





Return

Edge

Call


221 Failed to send the data for the TromboneConnectCall request to

the IBM_Trombone_Custom_Server.

222 to

226


TromboneConnectCall request. A status of 222 to 226 represents

a return edge of 1 to 5.

227 The ReceiveData corresponding to the TromboneConnectCall

request timed out.

228 The ReceiveData corresponding to the TromboneDisconnectCall

request timed out.

229 The ReceiveData corresponding to the TromboneCall or

TromboneMakeCall request. timed out.

If you are using the IBMTromboneRdy state table, you

probably specified a fairly short time for the timeout. Call

IBMTromboneRdy again until you are sure that the call has

failed.

230 to

249

Spare: may be used for user-defined values.

5 Bad status returned from the IBMTromboneCall state table itself, caused

by a problem with music on hold. Most of these errors are generated in

the IBMTromboneMus state table, which is invoked by the

IBMTromboneCall state table (assuming that the IBMTromboneCall and

IBMTromboneMus state tables have not been customized to alter these

values)

250 Music on hold was specified, but the IBMTromboneMus state

table was either not available, or not validated. This might

occur if the juke_box application is not installed.

251 The IBMTromboneMus state table returned a status outside the

valid range (> 251).

252 Unrecognized on_or_off value supplied to the

IBMTromboneMus state table.

253 Could not open a server link to the juke_box custom server.

254 Failed to send the data for the juke_box_start_music request to

the juke_box custom server.

255 to

259


juke_box_start_music request. A status of 255 to 259 represents

a return edge of 1 to 5.

260 The status returned by the juke_box_start_music request was

out of range (<1000).





Return

Edge

Call


261 The requested music was not available.

IBMTromboneConn

This state table encapsulates some of the code needed to continue a trombone

operation that is performed in several parts. It connects the caller with a third

party that has already been contacted using the IBMTromboneMake state

table. The call to the third party must have completed successfully for this

state table to work successfully.

IBMTromboneConn uses the TromboneConnectCall function of the

IBM_Trombone_Custom_Server. On successful completion, the caller is

connected to the third party using the TDM bus.

This state table is called by the user’s application, along with a number of

parameters, using the InvokeStateTable action. See “IBMTromboneXmpA” on

page 306 and “IBMTromboneXmpB” on page 307 for examples of how to use

this state table.

The source code is well commented and customization should be easy. The

function to log data has been provided in a separate state table that may be

invoked (IBMTromboneLog) to prevent this state table becoming too complex

and cluttered.

Parameters


performed. If a filename is supplied, event logging of the trombone calls and

the results are logged to an event log with the given filename. The logging is

performed by the IBMTromboneLog state table.


trombone operation.


terminated either by the third party hanging up, or by the caller requesting a




call_status values.



This state table returns different edges depending on which range of possible

values the call_status lies in (also defined in Table 20 on page 291). This

allows the general area of the problem to be determined immediately by the

return edge of the InvokeStateTable action that called IBMTromboneConn.

The IBMTromboneConn state table can return any of the following values:

221, 222 to 206, and 228.

IBMTromboneC5

This state table encapsulates the states needed to concatenate up to five

strings together. It returns the result as a single string.

Parameters

String in0: The 1st string.

String in1: The 2nd string.

String in2: The 3rd string.

String in3: The 4th string.


String out (this value is returned): The concatenation of the input strings

(in0 + in1 + in2 + in3 + in4).

IBMTromboneC10

This state table encapsulates the states needed to concatenate up to 10 strings

together. It returns the result as a single string.

Parameters












String out (this value is returned): The concatenation of the input strings

(in0 + in1 + in2 + in3 + in4 + in5 + in6 + in7 + in8 + in9).

IBMTromboneDisc


operation that is performed in several parts. It disconnects the caller from a

third party that has already been connected using the IBMTromboneMake and

IBMTromboneConn state tables. The call and connection to the third party

must have completed successfully for this state table to work successfully.

IBMTromboneDisc uses the TromboneDisconnectCall function of

IBM_Trombone_Custom_Server. On successful completion, the caller is

disconnected from the third party (the connection on the TDM bus is broken).

If the application allows, the caller can now continue with the application that

was being used before the trombone connection was made.

This state table can be called by the user’s application, along with a number

of parameters using the InvokeStateTable action. This state table is used by

the IBMTromboneWait state table, which can be used as an example of how to

use it.




and cluttered.

Parameters






trombone operation.






call_status values.






return edge of the InvokeStateTable action that called IBMTromboneDisc.

The IBMTromboneDisc state table can return any of the following values: 221,

222 to 206, and 228.

IBMTromboneLog

This state table encapsulates the states needed to log debug data to a file. It

first checks the logging_on flag to see if the supplied data should be sent to

the log file. The data to be logged consists of a header string, followed by six

general strings, which are all concatenated before being logged using a

LogEvent action. The header string should contain the filename to which to

log the data in the format required by the LogEvent action. The state table

always returns edge 0 regardless of any errors.

Parameters

Number logging_on: A value of 1 means perform data logging; otherwise

exit the state table without logging anything.

String header: The header string for the logging function (should contain at

least the filename in a format required by the LogEvent state table action).







IBMTromboneMake

This state table encapsulates the code needed to initiate a trombone operation

that is performed in several parts. It requests an outbound call to be made by

the trombone custom server ready for a trombone operation.

If the wait_time parameter is set to zero, it returns as soon as the request for

an outbound call has been sent. On successful completion, the outbound call

to the third party should be in progress. The IBMTromboneRdy state table can

then be used to determine if the outbound call is successful, has failed, or is

still progressing.



If the wait_time parameter is non-zero, it waits for that amount of time for a

response to the make call request. On successful completion, a third party has

been called, and is connected to WebSphere Voice Response. The caller and

third party are not connected on the TDM bus at this time. The

IBMTromboneConn state table should be used to complete the connection.


parameters using the InvokeStateTable action. See “IBMTromboneXmpA” on

page 306 and “IBMTromboneXmpB” on page 307 for examples of how to use

this state table.


functionality to log data has been provided in a separate state table that may

be invoked (IBMTromboneLog) to prevent this state table becoming too

complex and cluttered.

Parameters


outgoing part of the trombone (see the definition of phone_number in the















String out_stbl_name (16 characters max): The name of the state table to use

for the outbound part of the trombone operation. If this is blank, the default

state table IBMTromboneOut is used.

String out_stbl_entry (16 characters max): The entry point within the state

table to use for the outbound part of the trombone operation. If this is blank,

the default label begin is used.



Number wait_time (value is in seconds): The amount of time to wait for a

response to the MakeCall request that is sent to


If this is set to zero, the state table returns as soon as the MakeCall request

has been sent, without checking to see if the MakeCall has failed or

succeeded.

If this is set to a non-zero value, the state table waits for up to this amount of

time to see if the MakeCall has failed or succeeded. The IBMTromboneRdy

state table is used to perform this test.


trombone operation.






call_status values.




return edge of the InvokeStateTable action that called IBMTromboneMake.

The IBMTromboneMake state table can return any of the following values:

v If wait_time is set to zero: 201, 202, or 229

v If wait_time is non-zero: 0 to 207 or 229

Number partner_call_id (this value is returned).: The Call Reference (SV237)

of the outbound part of the trombone operation. It is supplied to provide a

unique link between the two halves of the trombone operation for debug

purposes. This value is set only if the wait_time is non-zero and the outbound

call is successful within the wait_time specified.

String user_status (this value is returned, up to 64 characters).: Some

user-defined data for simple communications from the outbound state table to

the inbound state table. This may be used, for example, to indicate the

response of the third party to the trombone request (such as a reason code for

connection refused). The inbound state table can then play a prompt to the

caller appropriate to the third party response. This value is set only if the

wait_time is non-zero and the outbound call is successful within the

wait_time specified.



IBMTromboneMus

This state table turns background music on or off, as requested by the

on_or_off parameter, to simulate music on hold. The encapsulation of this

function keeps the IBMTromboneCall state table much simpler.

This state table has to communicate with the juke_box custom server to

provide this function. Any problems encountered with this communication

return a non-zero status (with an exit edge of 1).

The most likely area that might need customizing is the fading in or out of

the music (see the ControlMusic statements in the source code). As a default,

this state table fades the music in over a period of 1 second and out over a

period of 0.1 second.

Parameters

Number on_or_off: A value of 0 means turn music off; a value of 1 means

turn music on; any other value generates a return status of 252.

String music_name: Name of the music file to play to simulate music on

hold.

Number status (this value is returned): The returned status that indicates if

music on hold was provided.

If the value is zero, the “music on hold” operation was successful (and the

State table exits with edge 0).

If the value is non-zero, the music on hold operation failed for some reason

(and the state table exits with edge 1). The possible status codes are given in

Table 20 on page 291 under the definition of the IBMTromboneCall state table

(see status return values greater than 251).

IBMTromboneOut

This state table performs the outbound call part of the trombone operation

and should never called by the user (IBM_Trombone_Custom_Server calls it).

Its job is to perform a MakeCall and return the status of the attempt to

IBM_Trombone_Custom_Server. If the MakeCall is successful, it uses a

WaitEvent action to wait until one of the parties hangs up before exiting. A

third party hang-up is indicated by an EDGE_HUP from the WaitEvent; a

caller hang-up is indicated by an EDGE_EVENT_HOST from the WaitEvent.

The most likely area that may need to be customized is to play an

announcement prompt to the third party before connecting to the caller (look

for the “MakeCall succeeded” comment in the source code for this state table).

A simple PlayPrompt can be inserted here if the prompt is fixed.



If you want to vary the prompt to be played depending on who the caller is,

use the user_data parameter to carry data to specify which prompt to play.

Parameters


outgoing part of the Trombone (see definition of phone_number in the





String permit_ch_grps (64 characters max): The permitted channel groups

for the outgoing part of the trombone. This value should be copied into SV178

(see the definition of SV178 for information on how this variable is used).

String permit_channels (64 characters max): The permitted channels for the

outgoing part of the trombone This value should be copied into SV228 (see

the definition of SV228 for information on how this variable is used).


performed.

If you supply a filename, the IBMTromboneLog state table logs the trombone

calls and their results to an event log with that filename.







String partner_call_id: This is the Call Reference of the inbound part of the

trombone operation. It is supplied to provide a unique link between the two

halves of the trombone operation for debug purposes. It is included in the

header information of any event logging.

String addn_call_info1 (140 characters max): Reserved for WebSphere Voice

Response.


Response.




Response.

String addn_call_info4 (35 characters max): Reserved forWebSphere Voice

Response.


Response.

IBMTromboneRdy


operation that is performed in several parts. It checks to see if an outbound

call, previously requested by the IBMTromboneMake state table, has

completed successfully or with an error.

IBMTromboneRdy uses a ReceiveData action to wait for the amount of time

specified in wait_time for a response to the make call request. On successful

completion, a third party has been called and connected to WebSphere Voice

Response. The caller and third party are connected on the TDM bus at this

time. The IBMTromboneConn state table should be used to complete the

connection. If the ReceiveData action times out, a return code of 229 is

generated.


parameters using the InvokeStateTable action. See “IBMTromboneXmpB” on

page 307 for an examples of how to use this state table.

This state table may also be called by the IBMTromboneMake state table.




and cluttered.

Parameters





Number wait_time (value is in seconds): The amount of time to wait for a

response to the MakeCall request that is sent to the




If this is set to zero, the state table returns as soon as the MakeCall request

has been sent, without checking to see if the MakeCall has failed or

succeeded.

If this is set to a non-zero value, the state table waits for up to this amount of

time to see if the MakeCall has failed or succeeded. The IBMTromboneRdy

state table is used to perform this test.


trombone operation.






call_status values.

This state table will return different edges depending on which range of

possible values the call_status lies in (also defined in Table 20 on page 291).

This allows the general area of the problem to be determined immediately by

the return edge of the InvokeStateTable action that called IBMTromboneRdy.

The IBMTromboneRdy state table can return any of the following values: 0 to

200, 203 to 207, and 229.

Number partner_call_id (this value is returned).: The Call Reference (SV237)

of the outbound part of the trombone operation. It is supplied to provide a

unique link between the two halves of the trombone operation for debug

purposes. This value is set only if the outbound call is successful within the

wait_time specified.

String user_status (this value is returned, up to 64 characters).: Some

user-defined data for simple communications from the outbound state table to

the inbound state table. This may be used, for example, to indicate the

response of the third party to the trombone request (such as a reason code for

connection refused). The inbound state table can then play a prompt to the

caller appropriate to the third party response. This value is set only if the

outbound call is successful within the wait_time specified.

IBMTromboneWait


operation that is performed in several parts. It waits for a trombone

connection to terminate, either by the caller or third party hanging up, or by



the caller dialling a specified DTMF sequence. It requires that a trombone has

already been set up successfully using the IBMTromboneMake and

IBMTromboneConnect state tables.

IBMTromboneWait uses the WaitEvent state table action to wait for either

party to hang-up, or for DTMFs to be sent from the caller. When it detects

trombone termination, it calls the IBMTromboneDisc state table if necessary

and closes the host server link to the IBM_Trombone_Custom_Server. On

successful completion, the trombone operation is terminated, and, if the

application allows, the caller can continue with the application that was being

used before the trombone connection was made (unless a caller hang-up

caused the trombone termination).

This state table can be called by the user’s application, along with a number

of parameters using the InvokeStateTable action. See “IBMTromboneXmpA”

on page 306 and “IBMTromboneXmpB” on page 307 for examples of how to

use this state table.




and cluttered.

Parameters





String end_on_DTMF (64 characters max): If this is blank, the state table

ignores any DTMFs it receives from the caller during the trombone operation.

If this parameter contains a number (one or more digits), it terminates the

trombone operation on receiving the given number from the caller. When the

trombone terminates, the third party is disconnected, and the caller remains

connected to WebSphere Voice Response.

If this parameter is set to -, the trombone terminates on reception of any

DTMF from the caller.

Valid DTMF digits are 0 to 9, *, and #.


trombone operation.








call_status values.




return edge of the InvokeStateTable action that called IBMTromboneWait.

The IBMTromboneWait state table can return any values between 208 and 214.

IBMTromboneXmp

This is an application that can be invoked on an incoming call. We have kept

it intentionally simple to demonstrate the minimum that is required to

perform a trombone operation. It uses the IBMTromboneCall state table to

perform a trombone operation with a single call.

When the application is invoked by an incoming call, it requests a number to

transfer to, and then tries to trombone to that number. If the trombone fails, it

plays the “Technical difficulties...” prompt and exits. If the Trombone is

successful, on termination of the Trombone operation (the third party hangs

up or the caller dials 1234), it asks the caller for another number to which to

transfer.

You can customize this application by altering the variables defined at the

start of the state table, or by adding different prompts and actions on the

various trombone exit conditions near the end of the state table. The variables

at the start of the state table are passed directly to the IBMTromboneCall state

table; their meanings are described in “TromboneCall” on page 280.

The prompts and voice segments for this application are held in directories

called IBM_Trombone.

Parameters

None.

IBMTromboneXmpA

This is an application that can be invoked on an incoming call. The

application has been kept intentionally simple to demonstrate the minimum

that is required to perform a trombone operation. It uses the

IBMTromboneMake, IBMTromboneConn, and IBMTromboneWait state tables

to perform a trombone operation. It allows slightly more control over setting



up the trombone than the example given in the IBMTromboneXmp state table.

It allows a prompt to be played to the caller immediately before the caller is

connected to the third party. In this example we play a long beep to indicate

that the connection is about to be made.


transfer to, and then tries to trombone to that number. If the trombone fails, it

plays the “Technical difficulties...” prompt and exits. If the trombone is

successful, when the trombone operation terminates (the third party hangs up

or the caller dials 1234), it asks the caller for another number to which to

transfer.

This application may be customized by altering the variables defined at the

start of the state table or by adding different prompts and actions on the


at the start of the state table are passed directly to the IBMTromboneMake,

IBMTromboneConn, or IBMTromboneWait state tables and their meanings are

described in the definition of the state tables.

The Prompts and Voice segments for this application are held in directories


Parameters

None.

IBMTromboneXmpB

This is an application that can be invoked on an incoming call. The

application has been kept intentionally simple to demonstrate the minimum

that is required to perform a trombone operation. It uses the

IBMTromboneMake, IBMTromboneRdy, IBMTromboneConn, and

IBMTromboneWait state tables to perform a trombone operation. It allows

slightly more control over setting up the trombone than the examples given in

the IBMTromboneXmp and IBMTromboneXmpA state tables. It allows a

prompt to be repeatedly played to the caller while the outbound call is

progressing and immediately before the caller is connected to the third party.

In this example we play a short beep every 2 seconds to indicate that the

outbound call is progressing and a long beep to indicate that the connection is

about to be made.


which to transfer, and then tries to trombone to that number. If the trombone

fails, it plays the “Technical difficulties...” prompt and exits. If the trombone is

successful, when the trombone operation terminates (the third party hangs up

or the caller dials 1234), it asks the caller for another number to which to

transfer.



This application may be customized by altering the variables defined at the

start of the state table or by adding different prompts and actions on the


at the start of the state table are passed directly to the IBMTromboneMake,

IBMTromboneConn, or IBMTromboneWait state tables and their meanings are

described in the definition of the state tables.

The Prompts and Voice segments for this application are held in directories


Parameters

None.

IBM_Trombone_Custom_Server errors

Red errors are issued for all fatal problems and yellow (warnings) and white

(information) errors for any problems that may cause future failures or for

information purposes.

The errors are issued as standard custom server errors in the range 20500 to

20504. The IBM_Trombone_Custom_Server error title and ID are shown in

parameters 1 and 2 of the standard custom server errors. The error IDs have

the form TROMBONEnnn. The remaining parameters contain information

specific to the particular error.



When you call, have details of any errors, your system setup, and details of

the conditions that cause the problem. An AIX system trace taken when the

problem occurs may also be required. Before taking the trace, set the -d option

in the custom server. For more information on the command line options see

“Configuring IBM_Trombone_Custom_Server” on page 271.

The IBM_Trombone_Custom_Server errors are listed in the WebSphere Voice

Response for AIX: Problem Determination guide.



Chapter 19. Using the VOX_CTI Custom Server

Avaya Interaction Center VOX Connector for WebSphere Voice Response

The Avaya Interaction Center VOX Connector for WebSphere Voice Response

for AIX (VOX_CTI) custom server provides an interface between state tables

and the Quintus VOX Server. A state table sends VOX commands by passing

state table variables into the custom server via the SendData action. VOX

responses are returned via the ReceiveData action. This chapter contains the

following sections:

v “Installation” on page 309

v “VOX_CTI.ini file configuration” on page 309

v “VOX_CTI Custom Server functions” on page 311

v “VOX_CTI function return codes” on page 317

v “General guidelines” on page 318

Installation

Use the following steps to install the VOX_CTI custom server:

1. Import the VOX_CTI.imp file from $VAE/sw/samples.

2. Create the VOX_CTI.ini file in $CUR_DIR/ca/VOX_CTI_dir as detailed in

“VOX_CTI.ini file configuration” below.

3. Make sure all the VOX Servers are set to connect rather than to listen as

the VOX_CTI custom server opens a listening socket.

4. Check that the AIX TCP send and receive buffers are at least 16K by using

the no command:

no -o tcp_sendspace = 16384

no -o tcp_recvspace = 16384

5. Start the VOX_CTI custom server.

VOX_CTI.ini file configuration

The first line of the VOX_CTI.ini file must be [General], and all .ini file items

must be placed under this General section. The only compulsory tag in the

VOX_CTI ini file is the port tag. Here is an example .ini file that sets the

VOX_CTI custom server to listen on port 3000:

[General]

port = 3000

The full list of supported tags is as follows:


port The port tag can be set to a single number or to a list of port

numbers. For example, to start a listening socket for ports 3000 and

3001 the entry in the .ini file would be port = 3000 3001.

dt_children

The dt_children tag specifies the number of child processes to initially

spawn when the VOX_CTI custom server is started. Each WebSphere

Voice Response channel that is using the VOX_CTI custom server

requires one child process to service the requests. Therefore if

dt_children = 20, then 20 channels can simultaneously issue VOX

commands without the VOX_CTI custom server having to spawn

more children.

The dt_children tag is optional and the default value is 0 as the

VOX_CTI custom server will spawn more child processes as they are

needed. The minimum and maximum values are 0 and 480

respectively.

vox_timeout

The vox_timeout tag specifies the number of milliseconds to wait for a

VOX response after issuing a VOX command. If the VOX response

does not arrive before the timeout the VOX_CTI function will return

VOX_TIMED_OUT.

The vox_timeout tag is optional and the default value is 5000. The

minimum and maximum values are 500 and 60000 respectively.

newcall_timeout

The newcall_timeout tag specifies the number of milliseconds to wait

before forcing the association between the state table and the channel

(from the VOX Server point of view). This timeout is only used if a

call arrives at a channel and a Newcall function has been called whilst

an existing channel process or state table is still using the channel

(that is, it has not issued a Gone command). Gone is issued

automatically after the timeout for the existing channel process or

state table, and the Newcall proceeds. The default is to allow the

original state table two seconds to issue a Gone response after it

detects a hang up.

The newcall_timeout tag is optional and has a default value of 2000.

The minimum and maximum values are 500 and 20000 respectively.

send_buffer_size

The send_buffer_size tag specifies the number of VOX commands that

can be buffered in the TCP send buffer. As its default value, the TCP

send buffer uses the size of the AIX TCP send buffer. However, the

default AIX send buffer size is 4096 bytes, which is equivalent to only

four VOX commands (each VOX command requires 1024 bytes). It is

preferable to increase the AIX TCP send buffer size to 16K bytes (to



allow for 16 simultaneous VOX commands) and also to omit the

send_buffer_size tag from the .ini file. This can be achieved by using

the no command no -o tcp_sendspace = 16384.

The send_buffer_size tag is optional and has a default value of -1 (this

means use AIX’s TCP send buffer size). The minimum and maximum

values are 4 and 128 respectively.

recv_buffer_size

The recv_buffer_size tag specifies the number of VOX requests that

can be buffered in the TCP recv buffer. As its default value, the TCP

recv buffer uses the size of the AIX TCP recv buffer. However the

default AIX buffer size is 4096 bytes which is equivalent to only four

VOX responses (each VOX response requires 1024 bytes). It is

preferable to increase the AIX TCP recv buffer size to 16K bytes (to

allow for 16 simultaneous VOX responses) and also to omit the

recv_buffer_size tag from the ini file. This can be achieved by using

the no command no -o tcp_recvspace = 16384.

The recv_buffer_size tag is optional and has a default value of -1 (this

means use AIX’s TCP recv buffer size). The minimum and maximum

values are 4 and 128 respectively.

VOX_CTI Custom Server functions

This section describes the VOX_CTI custom server functions that can be used

from within a state table to access the VOX Server:

v “Alarm” on page 312

v “Getvdu” on page 312

v “Getvox” on page 313

v “Gone” on page 314

v “Newcall” on page 314

v “Ping” on page 314

v “Pseudo_Ani” on page 315

v “Setvdu” on page 315

v “Tr” on page 316

v “Transfer” on page 316

Each function is described using the following headings:

Input The parameters or variables to be passed in the VOX command.

Output

The return values from the VOX response.


Chapter 19. Using the VOX_CTI Custom Server 311

Note: VOX_CTI functions always send back a return code and any

potential VOX error messages.

VOX command

The actual VOX command sent to the VOX Server. All variables in the

VOX command are derived from the input variables except for reqid

and channelnum, which are automatically generated by the VOX_CTI

custom server.

VOX response

The positive response sent back from the VOX Server. All variables in

the VOX response are mapped across to the corresponding output

variables.

Valid An indicator of whether or not the function called is valid. For

example, the Getvdu function is only valid after a Newcall function

and before a Gone.

Note: String variables passed to the VOX Server do not all need to be

enclosed in quotes unless specifically stated. For example, to send a low

priority VOX alarm command to the VOX Server, set the priority

variable to Low from within the state table rather than to "Low".

For more information about each VOX command see the Avaya Interaction

Center VOX Server Programmer’s Guide.

Alarm

Input char alarmname[64]

char priority[16]

char description[128]

Output

long rc

char error_msg[256]

VOX command

[VOX.alarm("alarmname","priority","description")][reqid]

VOX response

[VOX.alarm.response(,"alarmname","priority","description")][reqid]

Valid Any time after a Newcall

Getvdu

Input char name[512]

Output

long rc

char error_msg[256]

char value[1024]

VOX_CTI Custom Server functions


VOX command

[VOX.getvdu(#channelnum,"name1",,"name2",,"name3",)][reqid]

VOX response

[VOX.getvdu.response(,#channelnum,"name1","value1","name2",

""value2",name3","value3")][reqid]

Valid After a Newcall and before a Gone

The name input variable is split into one or more sub strings using the

comma as a delimiter to generate the name1, name2, name3 variables. The

output variable called value is set to the returned set of "name","value" pairs

without the quotes.

For example, to request both a balance and a pin number (on channel 10) the

following variables would be set and VOX commands and requests issued:

Input variable (name)

balance,pin

VOX command sent

[VOX.getvdu(#10,"balance",,"pin",)][0]

VOX response received

[VOX.getvdu.response(,#10,"balance","3000","pin","1234")][0]

Output variable (value)

balance,3000,pin,1234

Note: The maximum size of a VOX response is 1024 bytes so all VOX.getvdu

commands must return less than 1024 bytes. Using the previous

example, if both the balance and pin had returned a character string

great than 512, then the entire response would have exceeded 1024

characters and thus failed. The solution to this is to call the Getvdu

function twice, once with the balance and the other with the pin.

Getvox


Output

long rc

char error_msg[256]

char value[1024]

VOX command

[VOX.getvox(#channelnum,"name",)][reqid]

VOX response

[VOX.getvox.response(,#channelnum,"name","value")][reqid]


Getvdu


Note: The maximum size of a VOX response is 1024 bytes so all VOX.getvox

commands must return less than 1024 bytes.

Gone

Input No input parameters or variables

Output

long rc

char error_msg[256]

VOX command

[VOX.gone(#channelnum)][reqid]

VOX response

[VOX.gone.response(,#channelnum)][reqid]

Valid After a Newcall and only once per CHP/state table

The Gone function must be called immediately after the state table detects

that the call has hung up. The Gone function disassociates the link between

the CHP/state table and the channel from the VOX Server’s point of view.

After the Gone function all subsequent VOX_CTI functions will fail (besides

Alarm and Ping).

If a new call arrives on the channel whilst an existing CHP/state table is

using that channel a VOX.gone command is automatically sent to the VOX

Server for that channel. Preferably, application writers should always call the

Gone function.

Newcall


Output

long rc

char error_msg[256]

VOX command

[VOX.newcall(#channelnum,)][reqid]

VOX response

[VOX.newcall.response(,#channelnum,vdu.id)][reqid]

Valid Only at the start of a call and only once per CHP/state table

The Newcall function should be called once at the beginning of the call. The

Newcall function associates the CHP/state table with the channel from the

VOX Server’s point of view.

Ping


Getvox


Output

long rc

char error_msg[256]

VOX command

[VOX.ping()][reqid]

VOX response

[VOX.ping.response(,)][reqid]

Valid Always

Pseudo_Ani

Input No input or variables

Output

long rc

char error_msg[256]

char ps_ani[32]

VOX command

[VOX.pseudo_ani(#channelnum)][reqid]

VOX response

[VOX.pseudo_ani.response(,#channenum,"ps_ani")][reqid]


Setvdu


Output

long rc

char error_msg[256]

VOX command

[VOX.setvdu(#channelnum,"name1","value1","name2","value2",

"name3","value3")][reqid]

VOX response

[VOX.setvdu.response(,#channelnum,"name1","value1","name2",

"value2","name3","value3")][reqid]


The name input variable is split into one or more sub strings using the

comma as a delimiter to generate the name1, value1, name2, value2, name3,

value3 variables. For example, to set the balance to 3000 and pin number to

1234 (on channel 10) the following variable would be set and VOX commands

and requests issued:

Ping


Input variable (name)

balance,3000,pin,1234

VOX command sent

[VOX.setvdu(#10,"balance","3000","pin","1234")][0]

VOX response received

[VOX.setvdu.response(,#10,"balance","3000","pin","1234")][0]

Tr

Input char op[9]

short output

char arg1[32]

char arg2[32]

char arg3[32]

char arg4[32]

Output

long rc

char error_msg[256]

char output[64]

When the output variable is set to 1 the following VOX command is sent and

VOX response received:

VOX command

[VOX.tr1<op>(#channelnum,"arg1","arg2","arg3","arg4")][reqid]

VOX response

[VOX.tr1<op>.response(,#channelnum,"arg1","arg2","arg3",

"arg4")][reqid]

When the output variable is set to 2 the following VOX command is sent and

VOX response received:

VOX command

[VOX.tr2<op>(#channelnum,"arg1","arg2","arg3","arg4")][reqid]

VOX response

[VOX.tr2<op>.response(,#channelnum,"arg1","arg2","arg3","arg4",

"output")][reqid]


Transfer

Input char destination[32]

Output

long rc

char error_msg[256]

Setvdu


VOX command

[VOX.transfer(#channelnum,"destination")][reqid]

VOX response

[VOX.transfer.response(,#channelnum,"destination")][reqid]


VOX_CTI function return codes

Every VOX_CTI function has an output variable called rc which is used to

return the result of sending the VOX command and receiving the VOX

response (rather than the actual VOX.response result). For example:

v A VOX command that failed to receive a VOX response would set rc to

VOX_TIMED_OUT.

v A VOX command that received a VOX response of "Bad vduid" would set

rc to VOX_OK as the command was successfully sent and a VOX response

successfully received.

The rc variable can take one of the following values:

0 - VOX_OK

The VOX command was successfully sent and a VOX response

successfully received.

1 - VOX_NO_VOX_SERVER

The WebSphere Voice Response channel has no VOX Server registered,

this can be due to several things:

v There is no VOX Server configured for this particular channel.

v The VOX Server has stopped running.

v There is no ″port″ ini item for the VOX Server.

2 - VOX_UNKNOWN

Something unknown went wrong. This return code should never be

returned.

3 - VOX_NO_CHANNEL

The CHP/state table no longer has access to the channel from a VOX

Server point of view. This can be due to several things:

v The VOX Server has stopped running and there is a pending VOX

command.

v Another CHP/state table is currently using this channel. This can

happen if the original call drops and a new call arrives and is answered

by another state table. The second state table will automatically issue a

Gone (see Gone for more information.)

v The Newcall function has not been called.

Transfer


4 - VOX_REQUEST_TOO_LONG

The request is too long (more than 1024 characters). This will occur if the

outcome of the VOX command would be more than 1024 characters long.

5 - VOX_TIMED_OUT

The VOX Server did not respond to the VOX command within the

timeout period specified in the ini file.

6 - VOX_BAD_RESPONSE

The VOX response received by VOX_CTI was not understood. The

response will be stored in the error_msg variable.

General guidelines

Here are some general guidelines for keeping the VOX Server and WebSphere

Voice Response synchronized and improving performance:

v Always call the Newcall function as soon as the call has been answered by


v Always call the Gone function as soon as the state table detects that the call

has been hung up.

v VOX commands and responses must be less than 1024 characters, this is

especially important for Getvdu and Setvdu requests.

v Group the Getvdu and Setvdu requests together rather than making lots of

Getvdu and Setvdu requests for single items. However, the requests can not

contain more than 255 name and value pairs.

v Check the return code from each VOX_CTI function

v As mentioned in the Avaya IC VOX Server Programmer’s Guide hookflash

transfer is not supported.

VOX_CTI function return codes


Appendix A. ID and name limitations

The table below lists the identifiers and names used in WebSphere Voice

Response application development functions and describes the data type

limitations that apply to each ID and name.

ID or Name Data Type Limitations

Application name Up to 15 characters. The first character is limited to

A–Z, a–z, and underscore ( _ ). The second through

fifteenth characters can include alphanumeric (0–9,

A–Z, a–z) and underscore characters.

Application profile ID Up to 20 characters, limited to 0–9, A, B, C, and D.

Application profile name Up to 50 characters.

Administrator profile name Up to eight characters.

Administrator profile

password

Up to eight characters.

Custom server name

Custom server user function

Custom server argument

Up to 63 characters. The first character is limited to


sixty-third characters can include alphanumeric (0–9,


Description (of any object) Up to 255 characters. If you want to use an

apostrophe (’) in the description, you must type two

consecutive apostrophes. For example:

DESCRIPTION("This is Nick''s state table");

Greeting ID A numeric value in the range 1–255.

Input parameters Up to 15 characters, limited to a–z, and A–Z.

Language ID A numeric value in the range 1–255 (as specified in

the WebSphere Voice Response Languages window)

that identifies the default language.

IDs for user-defined languages must be in the range

129-255.

Local variables Up to 15 characters, limited to a–z, and A–Z.

Mailbox ID A numeric value in the range 1–10.

Mailbox password A numeric value up to eight digits in length.



Music title Up to 31 characters. Can include alphabetic

characters (uppercase and lowercase), numeric

characters, #, _, +, -, *, @, (, ), [, ], !, ?, &, <,

>, /, \, ‘, semicolon (;), colon (:), comma (,), period

(.), and space.

Prompt directory name Up to 15 characters. The first character is limited to




Prompt name Up to 15 characters. The first character is limited to




State table entry label/state

label





State table name Up to 15 characters. The first character is limited to




State table variables No more than 4096 local variables, and no more than

4096 parameter variables can be used in each state

table.

Segment ID A numeric value in the range 1–65535.

Subscriber class name Up to 16 characters, limited to alphanumeric (0–9,


3270 server name

3270 server script name

3270 server screen name

3270 server field name

3270 server argument



sixty-third characters can include alphanumeric (0–9,


Transaction ID Up to 16 characters.

Voice directory name Up to 15 characters. The first character is limited to




ID and name limitations



Voice table name Up to 15 characters. The first character is limited to




Voice table entry position A numeric value in the range 0 through 65535.


Appendix A. ID and name limitations 321



Appendix B. Voice interrupt detection: technical

information

Voice interrupt detection is controlled using three system parameters and four

system variables. The system parameters specify default values for the whole

system. These can be overridden for an individual application by using

system variables.

The other system variable turns voice interrupt detection on or off. This

cannot be done on a system-wide basis. Indeed, during the course of an

application, you may turn voice interrupt detection on and off again, perhaps

more than once. For example, when you are using parts of older applications

which were not written to handle voice interrupt detection along with newer

parts which can.

The system parameters and their equivalent system variables are shown in

Table 21.

Table 21. System variables and parameters for voice interrupt detection

System Variable System Parameter

SV217 System : Voice Interrupt Detection : On/Off —

SV218 System : Voice Interrupt Detection Level Voice Interrupt Detection

Level

SV219 System : Voice Interrupt Detection On Time Voice Interrupt Detection

On Time

SV220 System : Voice Interrupt Detection Off Time Voice Interrupt Detection

Off Time

The value of Voice Interrupt Detection Level specifies the minimum energy

level that the voice interrupt detector considers to be an interrupt. That is, any

noises below that level don’t count as interrupts.

Be careful when setting the voice interrupt detection level variable, if it is too

high the caller will be unable to interrupt prompts even by shouting. If the

value is too low, the echo6 from a prompt being played combined with the

6. Echo can be generated by any connectors or switches that have analog circuits. Echo can come from local

equipment, the service provider, or the caller’s equipment.


background noise level from the caller’s telephone may interrupt prompts

unintentionally. If there is a very loud echo on a particular line, it is

recommended that the level is increased.

The value of Voice Interrupt Detection On Time specifies the minimum length

of time for which the audio signal must remain above the minimum energy

level. That is, a very short sound does not count as an interrupt.

After detecting a sound that qualifies as an interrupt (it’s above the minimum

energy level and longer than the minimum on time), the detector must make

sure that the caller has finished speaking the word before starting the next

state table action. This is because the caller may have spoken a multi-syllable

word as the interrupt: for example, “cancel”. If the detector stops as soon as it

has heard “Can”, the rest of the word, “cel” could be taken as another word

and passed to a speech recognizer. If you add a tone between the play and

record actions in the state table, this ensures that the caller’s interrupt

completes before the record action begins. So, the Voice Interrupt Detection

Off Time value is used to make sure that there is a period of silence after the

interrupt-word has been spoken.

This also ensures that a continuous sound picked up by the caller’s telephone

is not assumed to be an interrupt.

There are default values for all of these parameters and variables, which work

in most circumstances. Change these values only if you have a need to, for

example, if levels are set too high or too low for the environments your

applications are used in. See the WebSphere Voice Response for AIX: Problem

Audiosignalenergylevel

Voice Response detectsvoice interrupt

Time

voice interrupt detection levelOn time Off time

Figure 49. WebSphere Voice Response detects a voice interrupt

voice interrupt detection: technical information


Determination guide for examples of problems you may encounter using voice

interrupt detection and suggested solutions.

All you need to do to activate voice interrupt detection is to set SV217 to 1 in

the state table. To turn voice interrupt detection off again, for example, when

invoking a state table that does not have support for voice interrupt detection,

set SV217 to 0 in the state table.

Note: Applications using voice interrupt detection must be able to handle the

voice interrupt detection edges and variable settings when a prompt is

interrupted.

Example of how voice interrupt detection works

Figure 50 shows the audio signal level of the two-syllable word “cancel” being

spoken to a WebSphere Voice Response application. We follow the stages

which WebSphere Voice Response goes through for this word to be

interpreted as a voice interrupt.

1. The energy level of the audio signal exceeds the level set in the voice

interrupt detection level parameter.

2. The value of the voice interrupt detection on time parameter is reached

and the audio signal will qualify as a voice interrupt.

3. The sample energy level of the voice sample falls below the voice interrupt

detection level parameter. WebSphere Voice Response counts (in

milliseconds) until the value of the off time parameter is reached. If the off

time elapses without the audio signal exceeding the voice interrupt

detection level parameter, WebSphere Voice Response interprets this as a

voice Interrupt.

4. The sample energy level rises above the voice interrupt detection level

again. WebSphere Voice Response registers this and the off time is reset

until the level drops below the line again, and no voice interrupt detection

is reported to the application.

Time

Audio

Voice Interrupt Detection Level

Off time

Off time

SignalEnergy

1 2 3 4 5 6

Ontime

Level

7

Figure 50. How voice interrupt detection parameters act on a voice sample

voice interrupt detection: technical information

Appendix B. Voice interrupt detection: technical information 325

5. Again, the sample energy level falls below the threshold. WebSphere Voice

Response begins counting milliseconds for the off time parameter to

expire.

6. If the second peak of the energy level of the sample was not here, the

WebSphere Voice Response would report a voice interrupt at this point.

However, as the peak is there, the off time has not been reached, so

nothing is done here.

7. WebSphere Voice Response registers that the off time has elapsed and the

energy level of the audio signal has remained below the voice interrupt

detection level. A voice interrupt is reported, and the play action stops

(unless the prompt has been force played).

In Figure 50 on page 325, when the off time is less than the difference between

points 3 and 4, the off time criterion is satisfied before point 4, and a voice

interrupt is detected. WebSphere Voice Response acts on the next action in the

state table and if this is a record or speech recognition action, then the second

half of the word in this example may be used.

Similarly, if the voice interrupt detection level is set higher, the time difference

between points 3 and 4 increases. If this time difference exceeds the off time,

then as with the case above, the second half of the word in this example may

be used.

Summary

For a voice interrupt to be detected by WebSphere Voice Response three

criteria must be met:

v The energy level of the audio signal must be equal to or exceed the value

specified in the voice interrupt detection level variable.

v The energy level of the audio signal must remain equal to or above this

level for the time specified in the voice interrupt detection on time variable.

v The energy level of the audio signal must then remain below the value

specified in the voice interrupt detection level variable for the time

specified in the voice interrupt detection off time variable.

example of how voice interrupt detection works


Appendix C. Background music: technical information

This appendix contains the following information:

v “Sound levels” on this page

v “Customizing the Juke Box” on page 330

v “Writing your own background music subsystem” on page 333

Sound levels

When two sounds are added together, the volume increases. Limits must be

set so that the total volume level (measured in dBm) does not exceed the

allowed maximum on a telephone channel. Background music uses the system

variables and system parameters shown in Table 22 to control these levels.

Table 22. System variables and parameters used for background music.

System Variable System Parameter

1 Parameter Group

SV223 System : Prompt volume ceiling Prompt Volume Ceiling

Default

Trunk Interface

SV224 System : Music : Volume ceiling Music Volume Ceiling

Default

Trunk Interface

SV225

System : Music : Automatic fade time

Music Automatic Fade

Time Default

Application

Server Interface

SV226

System : Music : Automatic fade

before actions

Music Automatic Fade

Before Actions

Application

Server Interface

Music Channels

Maximum

Trunk Interface

Music Absolute Silence

Threshold

Trunk Interface

1. For details of system parameters, see the WebSphere Voice Response for AIX:

Configuring the System guide.

To reset the value of a system parameter: Welcome window —>

Configuration —> System Configuration —> Change —> open the

parameter group —> open the system parameter —> click or type in the new

value —> OK. Before closing the System Configuration window, you need to

Save the new value.


Each system parameter has help information which is also listed, in

alphabetical order, in the WebSphere Voice Response for AIX: Configuring the

System guide.

The music volume ceiling and the prompt volume ceiling

The prompt volume ceiling and the music volume ceiling system variables are

defined so that the maximum permissible volume on your telephone system is

not exceeded when a voice sample is played at both volumes and both voice

streams are mixed together. When one volume is high, the other must be low,

as shown in Table 23

Table 23. Music volume and prompt volume ceilings

Music Volume

Ceiling

Prompt Volume

Ceiling

Prompt Volume

Ceiling

Music Volume

Ceiling

0 10 or higher 0 10 or higher








8 or higher 0 8 or higher 0

Figure 51 on page 329 shows a diagrammatic version of events in the

Musical_Welcome state table; shaded areas indicate when prompts or

background music is playing.

sound levels


Figure 52 shows how you would set the prompt volume ceiling and the music

volume ceiling to the same level to play both prompts and tunes at the same

volume.

|a

|b

|c

|d

|e

|f

|g

|h

|i

|j

|k

|l

|m

|n

|o

maximum permissible volumeprompt volume ceiling (SV223)

music volume ceiling (SV224)

voice isplaying

caller hears tunefading in

voice isplaying

prompts play louderthan background music

time

volu

me

background music is playing

Figure 51. Musical welcome state table: volume levels

|b

|a

|c

|d

|e

|f

maximum permissible volume

prompt volume ceiling (SV223)

music volume ceiling (SV224)

background music is playing

voice is playing

time

volu

me

Figure 52. Playing prompts and tunes at the same volume

sound levels

Appendix C. Background music: technical information 329

Customizing the Juke Box

The following information may be useful to you if you change the Juke_Box

custom server or either of the music players (pl_seg and pl_elem).

Source code files for the Juke Box

The following files are supplied in source code form as Restricted Materials,

and are subject to the Licensing Restrictions set out at the top of each file:

Juke Box .h files Juke Box .c files cvelem .c files

jb.h

jb_body.h

jb_cat.h

jb_chp.h

jb_config.h

jb_error.h

jb_list.h

jb_list_types.h

jb_msg.h

jb_pl.h

jb_preg.h

jb_req.h

jb_shared.h

jb_trace.h

jb_utils.h

pl_common.h

pl_elem.h

pl_elem_msg.h

pl_error.h

pl_seg.h

pl_seg_msg.h

jb_body.c

jb_cat.c

jb_chp.c

jb_config.c

jb_list.c

jb_preg.c

jb_req.c

jb_shared.c

jb_utils.c

pl_common.c

pl_elem.c

pl_seg.c

pl_test.c

cvelem.c

customizing the Juke box


Collecting statistics from the Juke_Box custom server

This function is not in the Juke_Box custom server, it is included here as a

suggestion for an extension to the custom server.

When playing music you may want to keep statistics of how often each piece

of music is played.

You can change the Juke_Box custom server to add a record to a file each time

a juke_box_start_music command is received. The file name can be a

parameter sent to the custom server when it starts.

When the custom server starts, it can open the copyright log file.

When the custom server stops, the copyright log file should be closed.

Each time a juke_box_start_music request is received from the state table, the

Juke_Box custom server could do the following:

fprintf(file, music title) - to print the name to the music title into the file.

fflush() - to make sure the music title is sent to the disk.

You can write a script to collect and collate these statistics.

Building music players

The music players pl_elem and pl_seg are built with special options using the

Ld command in the Makefile..., so that the Juke_Box custom server can load()

and call them.

Juke_Box custom server communication with pl_elem and pl_seg

When your state table asks the Juke_Box custom server to start playing a

tune, the Juke_Box custom server starts a process to play the tune to the

music channel until it is told to stop.

The program, or music player, uses the following input parameters:

argv[0] player_program_name

The name used to invoke the music player, for example, pl_elem.

argv[1] pack_number

An ASCII string containing the decimal representation of a number;

the number of the pack where the tune is to be played. This string is

passed to CA_Open_Music_Channel in the vpack field.

argv[2] music_title

An ASCII string giving the music title to the music player. The music

player passes this string to the CA_Open_Music_Channel call in the

music_title field.



argv[3] parameter_string

An ASCII character string specified either in the Juke_Box custom

server configuration file, or passed by the state table when a music

title is added using juke_box_configure_music. This string contains

the information the music player needs to find and access the tune

known as music_title.

Message queue

The music player opens a message queue to communicate with the Juke_Box

custom server using the function in jb_shared.c. The Juke_Box custom server

and the music player can both send messages to, and receive messages from

each other.

When the music player is initialized, either successfully or unsuccessfully, it

sends the message Q_MSG_TYPE_INITIALIZED to the Juke_Box custom

server.

The music player sends the message Q_MSG_TYPE_EXITING to the

Juke_Box custom server before terminating. It sends this message even if

initialization failed, or the rest of the music player process was not executed.

The Juke_Box custom server can send the message

Q_MSG_TYPE_TERMINATE to the music player at any time. The music

player releases any resources it is using and terminates.

When a music player terminates, the Juke_Box custom server receives

SIGCHLD signals. The Juke_Box custom server knows which music player

has terminated, and cleans up its own internal data structures.

Messages sent to the music player by the Juke_Box custom server

Q_MSG_TYPE_TERMINATE

When this message is received, the music player releases any

resources it is using, sends a message Q_MSG_TYPE_EXITING to the

Juke_Box custom server, and terminates.

Messages sent to the Juke_Box custom server by the music player

Q_MSG_TYPE_INITIALIZED

If initialization is successful the code sent with this message is 0, if it

is unsuccessful, the code sent is non-zero.

Q_MSG_TYPE_EXITING

The music player sends this message to the Juke_Box custom server

when it is about to end. This is either in response to a

Q_MSG_TYPE_TERMINATE message from the Juke_Box custom

server or indicates a failure in the music player. A return code is also

sent indicating the reason for the music player ending.



Writing your own background music subsystem

When writing your own background music custom server and music players,

you consider the following:

Passing dynamic voice data to a custom server

For this, you will need a program that accepts data supplied in a

dynamic stream, and uses the custom server API (similar to the

pl_elem music player program). For example, your music data may

come from a line-in on an Ultimedia Audio adapter.

You must set the dBm level in the CA_Play_Voice_Stream custom

server API call. It is your responsibility to ensure that WebSphere

Voice Response never receives audio data which exceeds this peak

dBm level.

To find out this what this level should be, run your program to record

some incoming audio data. Use a sample that contains the loudest

sound the source will send. Use CA_Import_Voice to convert the voice

data to an elements structure, then use CA_Get_Element_Info to find

the dBm level.

Note: If the dBm level is too high you may damage your telephone

provider’s equipment!

When you know what the dBm level is, your music player can pass

this dBm level to CA_Play_Voice_Stream.

Use cvelem off-line to pre-process music into elements more

efficiently than using CA_import() and CA_Play_Voice_Elements()

dynamically.

writing your own background music subsystem


writing your own background music subsystem


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

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

For license inquiries regarding double-byte (DBCS) information, contact the

IBM Intellectual Property Department in your country or send inquiries, in

writing, to:

IBM World Trade Asia Corporation Licensing, 2-31 Roppongi 3-chome

Minato-ku, Tokyo 106, Japan

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, 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 Programming 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 illustrate 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.

For country-specific notes on the use of WebSphere Voice Response, refer to

the README file located in the directory /usr/lpp/dirTalk/homologation.

The file name is in the format README_homologation.xxxx, where xxxx is

the country/region identifier.


Trademarks

The following terms are trademarks of IBM Corporation in the United States

or other countries or both:

AIX AS/400 DB2

DirectTalk IBM NetView

pSeries RS/6000 System/370

System/390 ViaVoice WebSphere

Lotus, Lotus Notes, Domino, and Notes Mail are trademarks of Lotus

Development Corporation in the United States and other countries.

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.

For more information on CallPath products visit the Genesys

Telecommunications Laboratories, Inc website at http://www.genesyslab.com/.

Other company, product or service names may be trademarks or service

marks of others.

Notices 337


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 341

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 343

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


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 345

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 347

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 349

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

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 353

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 355

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 357

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


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 359

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 361

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 363

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.

PDF and HTML versions of the WebSphere Voice Response for AIX

publications are available on the CD-ROM supplied with the product. In

addition, WebSphere Voice Response for AIX, WebSphere Voice Response for

Windows, Unified Messaging, and other WebSphere Voice publications are

available together in PDF and HTML formats on a separately-orderable

CD-ROM (order number SK2T-1787).

Note: To read PDF versions of books you need to have the Adobe Acrobat

Reader (it can also be installed as a plug-in to a Web browser). It is

available from Adobe Systems at http://www.adobe.com .

WebSphere Voice Response software

v WebSphere Voice Response for AIX: General Information and Planning,

GC34-6379

v WebSphere Voice Response for AIX: Installation, GC34-6380

v WebSphere Voice Response for AIX: User Interface Guide, SC34-6386

v WebSphere Voice Response for AIX: Configuring the System, SC34-6381

v WebSphere Voice Response for AIX: Managing and Monitoring the System,

SC34–6384

v WebSphere Voice Response for AIX: Designing and Managing State Table

Applications, SC34–6388

v WebSphere Voice Response for AIX: Application Development using State Tables,

SC34–6387

v WebSphere Voice Response for AIX: Developing Java applications, GC34-6377


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 367

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 369


Index

Numerics3270 field

name limitation 320

3270 host applicationinterfacing with 3270 server 86

3270 screendefinitions used by 3270 application 86

name limitation 320

3270 servername limitation 320

overview 86

purpose 85

requirements 24

sample (3270ServerSample) 130

sample application 129

3270 server scriptname limitation 320

purpose 86

3270ServerSample.imp 129, 130

Aaccess mode

mailbox 171

accessibility xv

Alphabet voice table 83

annotating messages 156

AnswerCall 135

applicationSee ISDN_Call_Transfer application 228

See SSTransfer application 256

Application - Profile ID system variable 138

application folderopening and closing 31

application objectadvantages of creating an application for 29

definition 28

deleting 56

displaying 30

editing and testing 33

exporting 45

importing 47

managing 27

migrating from previous release 51

moving 56

application prerequisitepurpose 37

when to export 54

application profilecreate, how to 90

application profile (continued)create, using command line 94

creating 89

greetings 150

ID limitation 319

mailbox identification 165

name limitation 319

purpose 89

selecting according to call identification 140

subscriber classes 167

voice applicationSee also application profile 89

voice mailbox 149

wvrapplprof 94

application profile IDspecifying 92

Application window 31

Applications window 30

archiving application objects 13

audio namedescription 150

recording 157

Ayavaswitch converse feature 134, 140

Bbackground music

adding to a state table 200

controlling the volume 196

debugging your state table 203

defining a tune 201

defining a tune in the configuration file 199

fading 201

getting music into WebSphere Voice Response 204

Juke_Box custom server 198

overview of a state table 203

playing multiple tunes 194

silence 202

sound levels 327

state table, prerequisites 200

supplied tunes 204

T1 A-law systems 196

the Music Available window 204

tune 193

use by multiple applications 194

uses of 195

with speech recognition 196

with voice interrupt detection 196

writing your own background music

subsystem 333


backup copyvoice application 38

barge-in 121

base applications 101

Bellcore specifications for ADSI telephones 369

blind (immediate) transfer 231

blind transfer 142, 258

bvi_aiff command 110

bvi_wav command 111

Ccalibration of echo cancellation 124

callanswering 135

incomingwriting your own state table to answer 139

Incoming_Callpurpose 135

call info statussystem variable 139

call progress toneshandling in a voice application 133

call transfer 142

call-answer supervision on screened transfer 231

called numberspecifying in an application profile 93

system variable 138

Caller - Profile ID system variable 138

caller variablesmailbox owner status 166

Calling Number system variable 138

CallPath Server 133, 147

CallPath_SigProc 144

changingmessage attributes 156

system voice tables 116

channelidentifying 140

incominganswering 140

invoking an application based on 140

load-balancing 141

channel identificationnumber 140

specifying in an application profile 93

checking voice messages 154

child helper processes,

IBM_Trombone_Custom_Server 272

commandsdtexport 58

dtimport 61

wvrapplprof 94, 175

wvrmailbox 175

common objects 55

compressed voice format 105

compressed voice format (continued)developing

creating prompt directories 113

specifying for prompt directory 113

compression of voice segments 105

configuration file for Juke_Box custom server 198

configurationsVOX_CTI.ini file 309

configuring IBM_Trombone_Custom_Server 271

constantused in State Table Parameters 73

consultation with third party using trombone 269

controlling disk space used for messages 166

coordinated call and data transfer 143

creatingapplication profiles 89

distribution lists 185

multilingual applications 117

prompt directories 113

prompts 112


creating an application 34

Currency system prompt 77, 82

current language variable 117

custom serveraccessing data on other systems 87

argument limitation 319

capabilities 87

initiated explicitly 86

Juke_Box 198

name limitation 319

overview 86

purpose 85

requirements 24


speech recognition 125

text-to-speech 125

waiting to be called 86

custom server functionsISDN_Call_Transfer 243

SSTransfer 258

custom server subroutines, TDD 191

customizing the Juke_Box custom sever 330

CustomServerSample.imp 128

Ddata

returning to a state table 73

date of last updateapplication object 31

Date system prompt 76, 81

Day_Of_Month voice table 83

Day_Of_Week voice table 84

Default applicationmoving objects from 56


Default application (continued)purpose 32, 53

default promptoverview 113

definingmailboxes 168

prompts 113


deletingapplication object 56

voice application 56

voice messages 156

delta export 13

definition 39

purpose 54

dependencyapplication object, purpose 37

descriptionlimitations in 319

designing voice applications 15

dialog design 18

considerations 18

lo-fi prototyping 17

dialog design, user participation 17

dialog stylechoosing 19

digit nameapplication profile, specifying 91

disk spacecontrolling use by messages 166

distributed voice technologies (DVT) 121

distributingupdates to applications 13

voice applications 27

distribution listcreating 185

maximum entries in 184

maximum number of entries 184

maximum number per mailbox 184

Divisor voice table 84

dtexport command 58

dtimport command 61

duplicate objects 54

Eecho cancellation 123

calibration 124


editing system prompts 116

Enter Key system parameter 119

entry pointspecifying in an application profile 91

state table 74

error messagesIBM_Trombone_Custom_Server 308

EuroISDN SST call transferbefore you install 255

components 254

configuring the custom server 257

custom server 255

how to use 258

Incoming_call state table 264

installing 254, 255

ISDN Signaling Process 254

limitations 254

ssct_tag state table 265

ssct_transfer state table 264

export commandSee dtexport 58

export fileformat 39

purpose 38

export report 44

exportingapplication object 45


Fformat of export file 39

forwarding messages 155

frequently asked questions 52

full exportdefinition 39

purpose 54

Ggeneral guidelines

VOX_CTI custom server 318

GetUserStatusISDN_Call_Transfer custom server function 244

TransferTag custom server function 262

global user variables 71

greetingsactive number 171, 178

ID limitation 319

Hhangup detection 134

host application (3270)interfacing with 3270 server 86

host data 86

housekeeping 13

IIBM solutions 5

IBM_Trombone applicationcomponents 269

consulting with third party 269

example state tables 288

helper state tables 289

how it works 275

Index 373

IBM_Trombone application (continued)IBMTromboneC10 state table 296

IBMTromboneC5 state table 296

IBMTromboneCall state table 289

IBMTromboneConn state table 295

IBMTromboneDisc state table 297

IBMTromboneLog state table 298

IBMTromboneMake state table 298

IBMTromboneMus state table 301

IBMTromboneOut state table 301

IBMTromboneRdy state table 303

IBMTromboneWait state table 304

IBMTromboneXmB state table 307

IBMTromboneXmp state table 306

IBMTromboneXmpA state table 306

implementation state tables 289

import file 269

installing 269, 270

prerequisites 270

running the application 271

setting up a trombone operation 275

simulating call transfer 268

starting the custom server 271

state table definitions 288

terminating a trombone operation (caller

DTMF) 279

terminating a trombone operation (caller

hang-up) 278

terminating a trombone operation (third party

hang-up) 277

using 274

voice paths 279

IBM_Trombone_Custom_Server 267

child helper processes 272

command line parameters 271

configuring 271

custom server functions 280

error messages 308

setting configuration options 273

starting 271

TromboneCall function 280

TromboneConnectCall function 286

TromboneDisconnectCall function 287

TromboneMakeCall function 283

TromboneMakeCallStatus function 285



IBMTromboneCall state table 289

IBMTromboneConn state table 295

IBMTromboneDisc state table 297

IBMTromboneLog state table 298

IBMTromboneMake state table 298

IBMTromboneMus state table 301

IBMTromboneOut state table 301

IBMTromboneRdy state table 303

IBMTromboneWait state table 304

IBMTromboneXmp state table 306

IBMTromboneXmpaA state table 306

IBMTromboneXmpB state table 307

identifyingchannels 140

incoming calls 140

import commandSee dtimport 61

import report 49

importingapplication objects 47


incoming callidentifying 140

incoming messagesstatus 153

Incoming_call state table 264

Incoming_Call state tablecustomizing 139

input parametername limitation 319

InstallationVOX_CTI custom server 309

installing IBM_Trombone application 270

interrupting a prompt with speech 24

introduction 3

ISDN call transfer 223

before you install 227

components 226

configuring the custom server 229

custom server 227

helper state tables 247

how to use 231

installing 226, 227

ISDN Signaling Process 225

ISDN_Imm_Xfer state table 247

ISDN_SupA_Xfer state table 248

ISDN_Xfer_C10 state table 250


ISDN_Xfer_Log state table 252

ISDN_Xfer_Stat state table 252

limitations 226

outbound state tables 247

running the application 228, 256

screened transfer (with call answer

supervision) 233

screened transfer (with third party

consultation 237

state table definitions 245, 247, 264

state table ISDN_Xfer_Data 251

state table ssct 265

ISDN RLT call transferNortel DMS-100 224

Nortel DMS-250 224


ISDN single step call transfer custom server 259

ISDN two B-channel transferNortel DMS-100 224

ISDN_Call_Transfer application 228

ISDN_Call_Transfer custom serverconfiguration options 230

definitions 243, 259

GetUserStatus and SetUserData 243

MakeCallStatus 243

functions 243

messages 243

restarting 230

ISDN_Imm_Xfer state table 247

ISDN_SupA_Xfer state table 248



ISDN_Xfer_Data state table 251

ISDN_Xfer_Log state table 252

ISDN_Xfer_Stat state table 252

ISDNSignaling Process, ISDN call transfer 225

ISDNSignaling Process, single step call transfer 254

JJuke_Box custom server 198

configuration file 198

customizing 330

format, configuration file 199

starting and stopping 198

tracing 204

KKey Signals parameter group 119

kry input 119

multiple keys 119

single key 119

Llanguage

current, system variable 117


language-specific promptoverview 113

limitingmessage length 166

number of messages 167

load-balancing across channels 141

local variable 72

name limitation 319

Mmailbox

application profile 149

graphical interface, using the 168

mailbox, voiceaccess mode 171

accessing messaging information 150

mailbox, voice (continued)active greeting number 171, 178

announce and take messages 171

application profile requirement 89

creating 165, 168

ID limitation 319

information in system variables 166

maximum number assigned to guests 184

maximum number of distribution lists 184

maximum number of mailboxes 184

options 170

password 171, 180

password limitation 319

prompt level system variable 172

referral number 174

referral type 174

retrieval order 171


use information 165

MakeCallStatusISDN_Call_Transfer custom server function 245

Transfer custom server function 263

matrix switching 207

messageannotating 156

announce and take messages 171

changing attributes 156

checking 154

controlling 166

deleting 156

forwarding 155

leaving and retrieving 153

limiting length of 166

limiting number of 167

mailboxes required for 165

maximum length 184

maximum number accepted by mailbox 184

playing 155

recording 154

retrieval order 171


saving 156

sending 154

status of incoming and outgoing 153

status variable 153

system parameters 157

message numberusing to retrieve messages 155

Message Waiting Indicator 147

migrating voice application 51

modifying system voice tables 116

Month_Of_Year voice table 84

moving application objects 56

multilingual applicationscreating 117

Index 375

music catalog 198

music playerbuilding 331

Musical_Welcome state table 193

Nname

application profile, specifying 90

name limitationsdescription length limitation 319

Noise voice table 84

Nortel DMS-100ISDN RLT call transfer 224

ISDN two B-channel transfer 224

release level 224

Nortel DMS-250ISDN RLT call transfer 224

release level 224

numberreferral 174

Numbers voice table 84

Oobject

See application object 28

Object Indexpurpose 46

one-call fax 207

Ordinal prompt 76

Ordinal voice table 84

outgoing messagesstatus 153

Pparameter

description 70

passing between state tables 72

used by state table actions 70

parametersstate table action 73

partial exportdefinition 39

purpose 54

passwordapplication profile 171, 175, 180

mailbox 171, 175, 180

Password Minimum Length parameter 171, 180

phone numberreferral 174

Phone prompt 77

Phone system prompt 77

playing voice messages 155

PlayPromptforce played 119

interruptible 119

program data 143

progress tones, callhandling in a voice application 133

promptcreating 112

defining 113

interrupting with speech 24

level heard by callers 172

overview 74

TDD 190

wording 23

prompt directorycreating 113

description 75

name limitation 320

prompt statementsdescription 74

putting applications into production 38

RReal_number system prompt 76

Record Voice Maximum parameter 166, 167

Record_Uncomp voice application 105

RecordAudionameSample application 157

RecordAudionameSample.imp 157

recordingaudio names 157

data for background music 109

voice messages 154

voice segments over the telephone 105

referral number 174

Release Link Trunk (RLT)See also ISDN RLT call transfer 223

remote data 86

removingapplication object 56


reportexport 44

import 49

retrieval ordermessage 171

retrievingmessages, using message number 155

messages, using transaction ID 155

returning data to a state table 73

RLT (Release Link Trunk)See ISDN RLT call transfer 223

Ssample application

3270ServerSample.imp 129

CustomServerSample.imp 128

RecordAudionameSample 157

RecordAudionameSample.imp 157

VoiceMessagingSample 157


sample application (continued)VoiceMessagingSample.imp 158

saving voice messages 156

screened transfer 142

with call_answer supervision 231

with third party consultation 231

script for distributing applications 57

script language3270 server 86

sendingvoice messages 154

setting up a trombone application 275

SetUserDataISDN_Call_Transfer custom server function 245

sharing objects 55

shell script for distributing applications 57

signaling protocolslimitations 133

silencedBm value for background music 202

Simple_record application 105

simulating call transfer using trombone 268

single system imageapplication design considerations 221

configuration, querying 221

Small_number system prompt 75, 81

speech recognitionbarge-in 121

echo cancellation 124

error handling 24

introduction 121

limitations 24

prompt wording 23

voice interrupt detection 123

while a prompt is playing 24

SR-INS-002461 Bellcore specification 369

ssct state table 265

ssct_tag state table 265

ssct_transfer state table 264

SSTransfer application 256

SSTransfer custom serverconfiguration options 257

definitionsTransfer 259

TransferTag 259

functions 258

messages 259

restarting 258

statedescription 63

resulting from actions 73

state label name limitation 320

state tablebackground music, adding 200

design worksheet example 69

state table (continued)Musical_Welcome state table 193

name limitation 320

overview 63

parameters 70

returning data to 73


variables 70

state table actionsdescription 63

resulting states 73

system parameters affecting 143

used to interact with servers 127

voice messaging 152

State Table Name for Incoming Calls parameter 139

statusmessage, system variable 153

subscriber classcreating 183

introduction 167


use in applications 167

subscriber classesspecifying in an application profile 92

switchAyava converse feature 134, 140

switch toneshandling in a voice application 133

System application 32

System Default Application Profile parameterspecifying in an application profile 93

system parametersdial actions 143

ring actions 143

voice messages 157

system promptsCurrency 77, 82

Date 76, 81

description 75

editing 116

in Brazilian Portuguese 80

in French 78

languages other than U.S. English 77, 115

Ordinal 76

Ordinal, date prompt 81

Ordinal, number prompt 80

Phone 80

Real_number 76, 80

Small_number 75, 81

Small_number, number prompt 80

Time 77, 81

translating 114

using translated 117

Whole_number 76

Whole_number, date prompt 81

Index 377

system prompts (continued)Whole_number, number prompt 80

system variables 167

current language 117

description 70

subscriber class limits 167

system voice segments 83

system voice tableslist of 83

modifying 116

overview 83

System_Msgs voice table 84

System/370 applicationinterfacing with 3270 server 86

System/390 applicationinterfacing with 3270 server 86

TTDD

See Telecommunications Device for the Deaf

(TDD) 189

TDMapplication development 215

ASCII state tables 215

cleaning connections 216

concepts 207

port sets 207

ports 207

resource groups 208

connection token 216

custom server main()function 216

custom servers 212

subroutines 212

data structures 215

designing an application 211

echo susceptibility 219

error handling 215

multiprocess custom server, moving to 217

notifying hang-ups 217

port set naming 209


implementation 215

prerequisites 210

sample application, design 212

See time-division multiplex (TDM) 207

state tables 212

TromboneCS state machine 215

voice paths 217

technical difficulties message 138

Telecommunications Device for the Deaf (TDD)control codes 192

custom server subroutines 191

prompts 190

restrictions 191

uncompressed format 192

Telecommunications Device for the Deaf (TDD)

(continued)valid characters 192

voice applications 189

voice segments 190

terminating a trombone operationcaller DTMF 279

caller hang-up 278

third party hang-up 277

third party consultation on screened transfer 231

Time system prompt 77, 81

Time_Of_Day voice table 84

Time_Of_Week voice table 85

time-division multiplex (TDM)TDM connection management 207

time-division multiplex (TDM) bus 207

Tone voice table 85

tones, call progresshandling in a voice application 133

TR-NWT-001273 Bellcore specification 369

Trademarks 337

transaction ID 155, 320

length limitation 320

using to retrieve messages 155

transfer typesblind 258

blind (immediate) 231

screened (with call_answer supervision) 231

screened (with third party consultation) 231

transferring a call 142

transferring voice data 109

analog tape 110

digital audio tape (DAT) 110

diskette 109

from the studio 109

storage device 109

translatingsystem prompts 114

tromboneSee also IBM_Trombone application 267

what is it? 267

trombone connection 207

TromboneCall custom server function 280

TromboneConnectCall custom server function 286

TromboneCS custom server 213

TromboneDisconnectCall custom server function 287

TromboneIn state table 212

TromboneMakeCall custom server function 283

TromboneMakeCallStatus custom server function 285

TromboneMonitor state table 213

TromboneOut state table 212

tunesupplied with WebSphere Voice Response 204

used in background music 193


Uuncompressed voice format 105

specifying for prompt directory 113

updating system voice tables 116

User applicationintroduction 32

moving objects from 56

purpose 53, 90

user function, custom servername limitation 319

user variables, global 71

using command line 94

using the IBM_Trombone application 274

Vvariable

description 70

global 71

local 72

system 70

voice applicationarchiving 13

components 3

creating 34

creating an application profile for 89

deleting 56

design hints 22

designing 15

dialog design 18

dialog design, user participation 17

dialog style 19

exporting 38

finding 30

housekeeping 13

importing 47

including messaging in 149

invoking servers from 63, 127

migrating from previous release 51

opening 30

RecordAudionameSample 157

selecting to answer incoming calls 140

subscriber class limits 167

TDD 189

VoiceMessagingSample 158

voice dataAIFF (Macintosh audio interchange file format 110

converting 110

non-AIX systems 110

raw (unformatted) data 110

WAV (Microsoft Windows format) 111

voice directory name limitation 320

voice interrupt detection 122

interrupting prompts 24

technical information 323


voice messagingaccessing mailbox information 150

audio name 150

distribution list 150

greeting 150

including functions in an application 149

managing resources 165

state table actions 152

voice mailbox 149

voice paths 279

voice promptscreating 112

voice segmentbatch import 111

compression 105

compression type 113

database 112

description 82

dynamic range 106

filters 107

high-quality voice data 106

ID limitation 320

limiting length of 166

planning 103

recording over the telephone 105

recording with a microphone 107

sampling rate 106

saving 111

source format 106

system 83

TDD 190

transferring data 109

using a recording studio 107

window 111

voice signal processingoverview 101

voice tablefor system voice segments 83, 115

name limitation 321

used by the system prompts 115

VoiceMessagingSample application 157

VoiceMessagingSample.imp 158

VOX connectorAvaya 309

Quintus 309

VOX_CTI custom serverAvaya Interaction Center VOX connector 309

configuration 309

functions 311

Alarm 312

Getvdu 312

Getvox 313

Gone 314

Newcall 314

Ping 314

Index 379

VOX_CTI custom server (continued)functions (continued)

Pseudo_Ani 315

Setvdu 315

Tr 316

Transfer 316

general guidelines 318

how to use 309

Installation 309

VOX_CTI funtionreturn codes 317

VOX_CTI.ini fileconfiguration 309

WWebSphere Voice Response

business requirements 4

data requirements 5

external code repository 10

implementation 8

maintenance and support 12

migrating application objects 10

Packaging and distribution 11

programming requirements 5

requirements and planning 4

supplied tunes 204

system design 6

telephony requirements 4

user requirements 4

Welcome state tablecustomizing 139

Incoming_Callcustomizing 139

purpose 139

Welcomecustomizing 139

purpose 139

Whole_number system prompt 76

worksheetsstate table design example 69

wvrapplprof 94, 175

action flags 94

attribute flags 95

examples 96

purpose 94

syntax 94

wvrmailbox 175

action flags 176

attribute flags 176

examples 176

field names 177

prerequisites 175

purpose 175

syntax 176


��

Program Number: 5724-I07

SC34-6388-03

Spin

e in

form

atio

n:

��

�

Web

Sphe

re Vo

ice

Res

pons

e fo

r A

IX w

ith D

irec

tTal

k Te

chno

logy

Des

igni

ng an

d M

anag

ing

Stat

e Ta

ble

Appl

icat

ions

Ve

rsio

n 4.

2

Documents

Designing and Managing State Table Applications...Converting voice data transferred from non-AIX computer systems.....110 Saving voice segments..... 111 The batch voice import utilities