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
Terminating a trombone operation using
caller hang-up . . . . . . . . . . 278
Terminating a trombone operation using
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
40. Event flow for a screened transfer with
call answer supervision (for an
unsuccessful call) . . . . . . . . 236
41. Event flow for a screened transfer with
third party consultation (ending in a
transfer) . . . . . . . . . . . 238
42. Event flow for a screened transfer with
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
47. Event flow required to terminate a
trombone operation when the caller
hangs up . . . . . . . . . . . 278
© Copyright IBM Corp. 1991, 2008 ix
48. Event flow required to terminate a
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
16. Return values for the
trombone_make_call_status parameter
of the TromboneMakeCall function . . 285
17. Status values supplied by the
TromboneMakeCallStatus function . . 285
18. Return values for the
trombone_make_call_status parameter
of the TromboneMakeCall function . . 287
19. Return values for the
trombone_make_call_status parameter
of the TromboneMakeCall function . . 288
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
© Copyright IBM Corp. 1991, 2008 3
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
4 Designing and Managing State Table Applications
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
requirements and planning
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?
Plan DesignImplement
andtest
Maintainand
support
Packageand
distribute
requirements and planning
6 Designing and Managing State Table Applications
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
Chapter 1. Introduction 7
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
Plan DesignImplement
andtest
Maintainand
support
Packageand
distribute
design
8 Designing and Managing State Table Applications
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
Chapter 1. Introduction 9
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
10 Designing and Managing State Table Applications
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
Plan DesignImplement
andtest
Maintainand
support
Packageand
distribute
implementation
Chapter 1. Introduction 11
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
Plan DesignImplement
andtest
Maintainand
support
Packageand
distribute
packaging and distribution
12 Designing and Managing State Table Applications
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
Chapter 1. Introduction 13
maintenance and support
14 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 15
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.
16 Designing and Managing State Table Applications
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.
Chapter 2. Designing a voice application 17
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
18 Designing and Managing State Table Applications
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.
designing the dialog
Chapter 2. Designing a voice application 19
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
designing the dialog
20 Designing and Managing State Table Applications
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
designing the dialog
Chapter 2. Designing a voice application 21
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).
designing the dialog
22 Designing and Managing State Table Applications
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
Chapter 2. Designing a voice application 23
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
24 Designing and Managing State Table 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
Chapter 2. Designing a voice application 25
defining server requirements
26 Designing and Managing State Table Applications
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
© Copyright IBM Corp. 1991, 2008 27
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?
28 Designing and Managing State Table Applications
– 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
30 Designing and Managing State Table Applications
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
Chapter 3. Creating and managing application objects 31
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
32 Designing and Managing State Table Applications
Editing and testing application objects
You can do most of the work involved in implementing a voice response
service from the Application window.
Before you start, see the note on “Using the applications and application
windows” on page 30.
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
Chapter 3. Creating and managing application objects 33
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
Before you start, see the note on “Using the applications and application
windows” on page 30.
1. From the Welcome window, click on Applications —> Applications
Naming the application
2. Click Application —> New.
editing and testing application objects
34 Designing and Managing State Table Applications
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
Chapter 3. Creating and managing application objects 35
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:
creating an application
36 Designing and Managing State Table Applications
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”.
creating an application
Chapter 3. Creating and managing application objects 37
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)
creating an application
38 Designing and Managing State Table Applications
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).
1. From the Welcome window, click on Applications —> Applications
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
Chapter 3. Creating and managing application objects 39
4. Proceed to step 13.
Exporting updated objects only
5. Click Application —> Export —> Delta.
The system displays the Delta Export window:
exporting an application
40 Designing and Managing State Table Applications
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.
exporting an application
Chapter 3. Creating and managing application objects 41
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.
exporting an application
42 Designing and Managing State Table Applications
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:
exporting an application
Chapter 3. Creating and managing application objects 43
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.
exporting an application
44 Designing and Managing State Table Applications
v To save a copy of the Export Report, click Save. The system displays
the Save Report window:
a. Click the directory and select or type in the file name for the export
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.
1. From the Welcome window, click on Applications —> Applications
Displaying the Object Index
2. If the Object Index window is not already displayed, click Options —>
Object Index from the Applications window.
exporting an application
Chapter 3. Creating and managing application objects 45
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
46 Designing and Managing State Table Applications
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.
a. Click the directory and select or type in the file name for the export
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
Chapter 3. Creating and managing application objects 47
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
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.
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.
1. From the Welcome window, click on Applications —> Applications
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
48 Designing and Managing State Table Applications
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.
importing application objects
Chapter 3. Creating and managing application objects 49
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.
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.
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.)
importing application objects
50 Designing and Managing State Table Applications
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.
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.
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.
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.
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:
importing application objects
Chapter 3. Creating and managing application objects 51
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
52 Designing and Managing State Table Applications
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
Chapter 3. Creating and managing application objects 53
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.
frequently asked questions
54 Designing and Managing State Table Applications
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
frequently asked questions
Chapter 3. Creating and managing application objects 55
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.
1. From the Welcome window, click on Applications —> Applications
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.
1. From the Welcome window, click on Applications —> Applications
Removing the objects from the application
moving objects from the default or user applications
56 Designing and Managing State Table 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
Chapter 3. Creating and managing application objects 57
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
58 Designing and Managing State Table Applications
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
exported. This option is not valid if -appl is also specified.
-vtab voicetable...
Specifies a space-delimited list of voice tables that are to be exported.
This option is not valid if -appl is also specified.
-3270 server...
Specifies a space-delimited list of 3270 servers that are to be exported.
This option is not valid if -appl is also specified.
the dtimport and dtexport commands
Chapter 3. Creating and managing application objects 59
-cs server...
Specifies a space-delimited list of custom servers that are to be
exported. This option is not valid if -appl is also specified.
-prof profileID...
Specifies a space-delimited list of application profile IDs that are to be
exported. This option is not valid if -appl is also specified.
-sclass class...
Specifies a space-delimited list of subscriber classes that are to be
exported. This option is not valid if -appl is also specified.
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
operation while another import or export operation is in progress, the
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
the dtimport and dtexport commands
60 Designing and Managing State Table Applications
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
the dtimport and dtexport commands
Chapter 3. Creating and managing application objects 61
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
operation while another import or export operation is in progress, the
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
the dtimport and dtexport commands
62 Designing and Managing State Table Applications
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
© Copyright IBM Corp. 1991, 2008 63
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
64 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 65
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
and assign the result to a variable
AssignData (Length)
Convert all the characters in a string to uppercase,
and assign the result to a variable
AssignData (Uppercase)
Convert all the characters in a string to lowercase,
and assign the result to a variable
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
66 Designing and Managing State Table Applications
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
profile and mailbox ID
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
application profile and mailbox ID
PlayUserGreeting
Remove the greeting specified by system variable
SV102
DeleteUserGreeting
state tables
Chapter 4. Overview of application objects 67
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
68 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 69
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
70 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 71
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
72 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 73
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
74 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 75
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
76 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 77
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
78 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 79
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
80 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 81
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
82 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 83
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
84 Designing and Managing State Table Applications
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
Chapter 4. Overview of application objects 85
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.
3270 and custom servers
86 Designing and Managing State Table Applications
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
3270 and custom servers
Chapter 4. Overview of application objects 87
further information
88 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 89
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
90 Designing and Managing State Table Applications
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
Chapter 5. Creating an application profile 91
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.
how to create an application profile
92 Designing and Managing State Table Applications
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
how to create an application profile
Chapter 5. Creating an application profile 93
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
how to create an application profile
94 Designing and Managing State Table Applications
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
how to create an application profile
Chapter 5. Creating an application profile 95
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
how to create an application profile
96 Designing and Managing State Table Applications
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
how to create an application profile
Chapter 5. Creating an application profile 97
how to create an application profile
98 Designing and Managing State Table Applications
Part 2. Design topics
© Copyright IBM Corp. 1991, 2008 99
100 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 101
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
102 Designing and Managing State Table Applications
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
104 Designing and Managing State Table Applications
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.
planning your voice segments
Chapter 6. Creating the voice output for voice applications 105
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
planning your voice segments
106 Designing and Managing State Table Applications
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.
planning your voice segments
Chapter 6. Creating the voice output for voice applications 107
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
planning your voice segments
108 Designing and Managing State Table Applications
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
planning your voice segments
Chapter 6. Creating the voice output for voice applications 109
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
planning your voice segments
110 Designing and Managing State Table Applications
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.
planning your voice segments
Chapter 6. Creating the voice output for voice applications 111
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
112 Designing and Managing State Table Applications
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
Chapter 6. Creating the voice output for voice applications 113
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
114 Designing and Managing State Table Applications
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
Chapter 6. Creating the voice output for voice applications 115
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
116 Designing and Managing State Table Applications
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
Chapter 6. Creating the voice output for voice applications 117
creating multilingual applications
118 Designing and Managing State Table 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.
© Copyright IBM Corp. 1991, 2008 119
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
120 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 121
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
122 Designing and Managing State Table Applications
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
barge-in, voice interrupt detection, and echo cancellation
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.
barge-in, voice interrupt detection, and echo cancellation
124 Designing and Managing State Table Applications
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
126 Designing and Managing State Table Applications
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)
© Copyright IBM Corp. 1991, 2008 127
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
/usr/lpp/dirTalk/sw/samples directory.
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,
128 Designing and Managing State Table Applications
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
/usr/lpp/dirTalk/sw/samples directory.
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
sample 3270 and custom servers
130 Designing and Managing State Table Applications
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.
sample 3270 and custom servers
Chapter 9. Accessing data with a 3270 or custom server 131
sample 3270 and custom servers
132 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 133
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
134 Designing and Managing State Table Applications
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
136 Designing and Managing State Table Applications
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
Chapter 10. Telephony activity 137
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
138 Designing and Managing State Table Applications
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
Chapter 10. Telephony activity 139
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
140 Designing and Managing State Table Applications
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
Chapter 10. Telephony activity 141
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
142 Designing and Managing State Table Applications
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
Chapter 10. Telephony activity 143
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
WebSphereVoice Response
Figure 18. CallPath Server and WebSphere Voice Response installed in the same pSeries
computer
coordinated call and data transfer
144 Designing and Managing State Table Applications
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.
coordinated call and data transfer
Chapter 10. Telephony activity 145
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
coordinated call and data transfer
146 Designing and Managing State Table Applications
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
OpenHostServerLink to CallPath_SigProc
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
Chapter 10. Telephony activity 147
CloseHostServerLink
OpenHostServerLink to CallPath_SigProc
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
148 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 149
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
150 Designing and Managing State Table Applications
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
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
using state table actions for voice messaging
152 Designing and Managing State Table Applications
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
profile and mailbox ID
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
application profile and mailbox ID
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
Chapter 11. Designing voice messaging applications 153
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
154 Designing and Managing State Table Applications
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.
If the sender requested acknowledgment of the message (using the Receipt
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
interacting with callers and messages
Chapter 11. Designing voice messaging applications 155
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.
If the sender requested acknowledgment of the message (using the Receipt
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
interacting with callers and messages
156 Designing and Managing State Table Applications
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.
interacting with callers and messages
Chapter 11. Designing voice messaging applications 157
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
Invoke VoiceMsgRecord
Figure 22. VoiceMsgMenu and VoiceMsgAnswer
a sample voice message application
158 Designing and Managing State Table Applications
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
Invoke VoiceMsgRecord
Invoke VoiceMsgRecord
Figure 23. VoiceMsgRecord and VoiceMsgListen
a sample voice message application
Chapter 11. Designing voice messaging applications 159
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
a sample voice message application
160 Designing and Managing State Table Applications
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
a sample voice message application
Chapter 11. Designing voice messaging applications 161
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
a sample voice message application
162 Designing and Managing State Table Applications
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.
a sample voice message application
Chapter 11. Designing voice messaging applications 163
Table 7. Fm Variable:Table Sheet Example prompt (continued)
IF SV29 != 0 THEN
SYSPROMPT Whole_number (SV29);
VOICE VoiceMsg (250); # ...saved...
PROMPT Message_s (SV29);
# 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
SYSPROMPT Whole_number (SV31);
VOICE VoiceMsg (270); # ...outgoing...
PROMPT Message_s (SV31);
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”.
a sample voice message application
164 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 165
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
166 Designing and Managing State Table Applications
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
168 Designing and Managing State Table Applications
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
Chapter 12. Managing voice messaging resources 169
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
creating mailboxes for application use
170 Designing and Managing State Table Applications
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
creating mailboxes for application use
Chapter 12. Managing voice messaging resources 171
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
creating mailboxes for application use
172 Designing and Managing State Table Applications
Assistant number
an assistant (also known as deputy ) number is the number of
another person who might be a useful contact for your callers.
creating mailboxes for application use
Chapter 12. Managing voice messaging resources 173
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
creating mailboxes for application use
174 Designing and Managing State Table Applications
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).
creating mailboxes for application use
Chapter 12. Managing voice messaging resources 175
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
creating mailboxes for application use
176 Designing and Managing State Table Applications
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
creating mailboxes for application use
Chapter 12. Managing voice messaging resources 177
Table 8. Mailbox field names used with wvrmailbox command (continued)
Field Name Description Length Field Data
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
2 = Personal greeting 2
3 = Personal greeting 3
4 = Personal greeting 4
5 = Personal greeting 5
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
creating mailboxes for application use
178 Designing and Managing State Table Applications
Table 8. Mailbox field names used with wvrmailbox command (continued)
Field Name Description Length Field Data
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.
This is a mailbox property display-only field
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.
This is a mailbox property display-only field
pager_number
Pager number
Phone number of
your pager
20 numeric string
creating mailboxes for application use
Chapter 12. Managing voice messaging resources 179
Table 8. Mailbox field names used with wvrmailbox command (continued)
Field Name Description Length Field Data
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
creating mailboxes for application use
180 Designing and Managing State Table Applications
Table 8. Mailbox field names used with wvrmailbox command (continued)
Field Name Description Length Field Data
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
creating mailboxes for application use
Chapter 12. Managing voice messaging resources 181
Table 8. Mailbox field names used with wvrmailbox command (continued)
Field Name Description Length Field Data
saved_messages
Saved
Displays how
many saved
messages are in the
mailbox
This is a mailbox property display-only field
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
creating mailboxes for application use
182 Designing and Managing State Table Applications
Table 8. Mailbox field names used with wvrmailbox command (continued)
Field Name Description Length Field Data
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:
creating mailboxes for application use
Chapter 12. Managing voice messaging resources 183
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
184 Designing and Managing State Table Applications
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
Chapter 12. Managing voice messaging resources 185
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
186 Designing and Managing State Table Applications
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:
creating a distribution list
Chapter 12. Managing voice messaging resources 187
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.
creating a distribution list
188 Designing and Managing State Table Applications
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
© Copyright IBM Corp. 1991, 2008 189
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
190 Designing and Managing State Table Applications
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 :
making voice applications available to TDD users
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.
making voice applications available to TDD users
192 Designing and Managing State Table Applications
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
© Copyright IBM Corp. 1991, 2008 193
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?
194 Designing and Managing State Table Applications
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
2 Application A Play
3 Application B Play
4 Application A Play
5 Application A Play
6 Application C Play
1st
Play
2nd
Play
3rd
7 Application B Play
8 Application B Play
9 Application A Play
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?
196 Designing and Managing State Table Applications
Callers interactionwith the application
Caller listensto prompt
Application waitsfor caller’s input
Application waitsfor caller’s input
Application waitsfor caller’s input
Caller listensto background music
while the requestis being processed
Caller listensto background music
while the requestis being processed
Caller listensto prompt
Caller listensto prompt
Caller listensto prompt
What the callerhears on the
music channel
Background musicquieter thanthe prompt
Background musicquieter thanthe prompt
Background musicquieter thanthe prompt
Background music
Background musicquieter thanthe prompt
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
Chapter 14. Background music 197
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
198 Designing and Managing State Table Applications
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.
using the WebSphere Voice Response Juke Box
Chapter 14. Background music 199
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
using the WebSphere Voice Response Juke Box
200 Designing and Managing State Table Applications
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
WebSphere Voice Response for AIX: Application Development using State Tables
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
Chapter 14. Background music 201
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
WebSphere Voice Response for AIX: Application Development using State Tables
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.)
adding background music to a state table
202 Designing and Managing State Table Applications
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
adding background music to a state table
Chapter 14. Background music 203
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
adding background music to a state table
204 Designing and Managing State Table Applications
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
Chapter 14. Background music 205
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
WebSphereVoice Response
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
206 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 207
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
208 Designing and Managing State Table Applications
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
Chapter 15. TDM connection management 209
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
1. From the Welcome window, click on Applications —> Applications
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
210 Designing and Managing State Table Applications
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.
9. Click File —> Save.
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
Chapter 15. TDM connection management 211
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
212 Designing and Managing State Table Applications
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.
designing an application
Chapter 15. TDM connection management 213
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
designing an application
214 Designing and Managing State Table Applications
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
designing an application
Chapter 15. TDM connection management 215
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.
designing an application
216 Designing and Managing State Table Applications
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
designing an application
Chapter 15. TDM connection management 217
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
designing an application
218 Designing and Managing State Table Applications
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
designing an application
Chapter 15. TDM connection management 219
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.
designing an application
220 Designing and Managing State Table Applications
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:
© Copyright IBM Corp. 1991, 2008 221
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
222 Designing and Managing State Table Applications
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
© Copyright IBM Corp. 1991, 2008 223
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?
224 Designing and Managing State Table Applications
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
226 Designing and Managing State Table Applications
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
installing the application
Chapter 17. Using ISDN call transfer 227
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.
Creating an application profile
5. Open the ISDN_Call_Xfer application.
The system displays the Application (ISDN_Call_Xfer) window.
6. Click Object —> New —> Application Profile.
The system displays the Application Profiles window, followed by the
Application Profile window.
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.
10. Click File —> Save.
11. Specify the phone number to be used as the Application Profile ID.
12. Click OK.
13. In the Application (ISDN_Call_Xfer) window, click View —> Refresh.
The system displays the Application Profiles folder, with the new
Application Profile icon inside it.
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.
Running the Application
installing the application
228 Designing and Managing State Table Applications
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.
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 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.
installing the application
Chapter 17. Using ISDN call transfer 229
Table 11. Configuration options for the ISDN_Call_Transfer custom server (continued)
Parameter Default setting Description
-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.
The system displays the available custom servers in a window.
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
230 Designing and Managing State Table Applications
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
application or to the supplied state tables.
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
Chapter 17. Using ISDN call transfer 231
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
application or to the supplied state tables.
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
232 Designing and Managing State Table Applications
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
WebSphere Voice Response for AIX: Application Development using State Tables
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.
how to use ISDN call transfer
Chapter 17. Using ISDN call transfer 233
The sequence of events in Figure 39 is:
1. The Caller state table issues a TransferCall request with the ring_wait and
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
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 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).
4. When the MakeCall action returns, the outbound state table informs the
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
Incoming Channel Outgoing Channel
InvokeStateTable(default = ISDN_SupA_Xfer) ISDN_SupA_Xfer
MakeCall
OpenHostServerLink(ISDN_Call_Transfer)
Return the Success edgeto the TransferCall request
WaitEventWait for DTMF, Hangup
or Host event for up to 30
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.
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)
Success
Wait for response from switch
Return Success edgeto the TerminateCall requestEDGE:
Success
Send Host Event to theoutbound state table EDGE:
HostEvent
TerminateCall
The ISDN SignallingProcess and
ISDN_Call_Transfercustom server
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)
how to use ISDN call transfer
234 Designing and Managing State Table Applications
5. The ISDN Signaling Process sends the result of the transfer to the
incoming state table, which causes the TransferCall action to return.
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.
For most applications, this type of transfer can be used without modification
either to the user application or to the ISDN_SupA_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 the SV178 definition in
the WebSphere Voice Response for AIX: Application Development using State Tables
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.
how to use ISDN call transfer
Chapter 17. Using ISDN call transfer 235
The sequence of events in Figure 40 is:
1. The Caller state table issues a TransferCall request with the ring_wait and
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
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 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).
4. When the MakeCall action returns, the outbound state table informs the
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)
how to use ISDN call transfer
236 Designing and Managing State Table Applications
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.
For most applications, this type of transfer can be used without modification
either to the user application or to the ISDN_SupA_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 the SV178 definition in
the WebSphere Voice Response for AIX: Application Development using State Tables
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.
how to use ISDN call transfer
Chapter 17. Using ISDN call transfer 237
The sequence of events in Figure 41 is:
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
Incoming Channel Outgoing Channel
InvokeStateTable(default = ISDN_SupA_Xfer) ISDN_SupA_Xfer
MakeCall
OpenHostServerLink(ISDN_Call_Transfer)
Return the Success edgeto the TransferCall request
WaitEventWait for DTMF, Hangup
or Host event for up to 30
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.
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)
Success
Wait for response from switch
Return Success edgeto the TerminateCall request
EDGE:Success
Send Host Event to theoutbound state table 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
The ISDN SignallingProcess and
ISDN_Call_Transfercustom server
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)
how to use ISDN call transfer
238 Designing and Managing State Table Applications
Note: A state table called ISDN_Xfer_Data is supplied to help perform
this function.
2. The Caller state table issues a TransferCall request with the ring_wait and
ring_time parameters set to non-zero values to indicate that a screened
transfer is required.
3. The ISDN Signaling Process receives the TransferCall request and initiates
an outbound call to the third party using the ISDN_SupA_Xfer state table
with the aid of the ISDN_Call_Transfer custom server.
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.
7. The ISDN Signaling Process sends the result of the transfer to the
incoming state table, which causes the TransferCall action to return.
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.
12. The ISDN Signaling Process sends Success to the incoming state table,
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
how to use ISDN call transfer
Chapter 17. Using ISDN call transfer 239
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
WebSphere Voice Response for AIX: Application Development using State Tables
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.
how to use ISDN call transfer
240 Designing and Managing State Table Applications
The sequence of events in Figure 42 is:
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
InvokeStateTable(default = ISDN_SupA_Xfer) ISDN_SupA_Xfer
MakeCall
OpenHostServerLink(ISDN_Call_Transfer)
Return the Success edgeto the TransferCall request
WaitEventWait for DTMF, Hangup
or Host event for up to 30
ReconnectCall
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.
SendData(MakeCallStatus)
Returns the edge from theprevious MakeCall action
seconds to allow the transferoperation to complete.
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
ISDN_Call_Transfercustom server
Figure 42. Event flow for a screened transfer with third party consultation (ending up reconnecting
to the original caller)
how to use ISDN call transfer
Chapter 17. Using ISDN call transfer 241
Note: A state table called ISDN_Xfer_Data is supplied to help perform
this function.
2. The Caller state table issues a TransferCall request with the ring_wait and
ring_time parameters set to non-zero values to indicate that a screened
transfer is required.
3. The ISDN Signaling Process receives the TransferCall request and initiates
an outbound call to the third party using the ISDN_SupA_Xfer state table
with the aid of the ISDN_Call_Transfer custom server.
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.
7. The ISDN Signaling Process sends the result of the transfer to the
incoming state table, which causes the TransferCall action to return.
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.
11. The ISDN Signaling Process sends Success to the incoming state table,
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).
how to use ISDN call transfer
242 Designing and Managing State Table Applications
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
WebSphere Voice Response for AIX: Application Development using State Tables
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.
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
how to use ISDN call transfer
Chapter 17. Using ISDN call transfer 243
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.
char user_status2[16]: 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.
char user_status3[16]: 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.
char user_status4[16]: 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.
char user_status5[16]: 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.
custom server functions
244 Designing and Managing State Table Applications
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.
char user_status2[16]: User-defined data field sent to the inbound state table
during a transfer after the outbound call has been made.
char user_status3[16]: User-defined data field sent to the inbound state table
during a transfer after the outbound call has been made.
char user_status4[16]: User-defined data field sent to the inbound state table
during a transfer after the outbound call has been made.
char user_status5[16]: 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.
char user_data_2[16]: User-defined data field sent to the outbound state table
during a transfer.
char user_data_3[16]: User-defined data field sent to the outbound state table
during a transfer.
custom server functions
Chapter 17. Using ISDN call transfer 245
char user_data_4[16]: User-defined data field sent to the outbound state table
during a transfer.
char user_data_5[16]: User-defined data field sent to the outbound state table
during a transfer.
Output parameters: None.
custom server functions
246 Designing and Managing State Table Applications
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
Chapter 17. Using ISDN call transfer 247
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
WebSphere Voice Response for AIX: Application Development using State Tables
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
WebSphere Voice Response for AIX: Application Development using State Tables
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.
String user_data2 (maximum of 16 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.
String user_data3 (maximum of 16 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.
String user_data4 (maximum of 16 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.
String user_data5 (maximum of 16 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.
state table definitions
248 Designing and Managing State Table Applications
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.
You can customize the application, but you must not change the basic
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
WebSphere Voice Response for AIX: Application Development using State Tables
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
WebSphere Voice Response for AIX: Application Development using State Tables
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.
String user_data2 (maximum of 16 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.
String user_data3 (maximum of 16 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.
String user_data4 (maximum of 16 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.
state table definitions
Chapter 17. Using ISDN call transfer 249
String user_data5 (maximum of 16 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_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.
state table definitions
250 Designing and Managing State Table Applications
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.
You can customize the application, but you must not change the basic
functions.
Parameters:
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 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.
String user_data2 (maximum of 16 characters), (this value is returned): User data
supplied to the SetUserData custom server call.
String user_data3 (maximum of 16 characters), (this value is returned): User data
supplied to the SetUserData custom server call.
String user_data4 (maximum of 16 characters), (this value is returned): User data
supplied to the SetUserData custom server call.
String user_data5 (maximum of 16 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.
state table definitions
Chapter 17. Using ISDN call transfer 251
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.
You can customize the application, but you must not change the basic
functions.
Parameters:
String log_filename (maximum of 64 characters): If this parameter is blank, no
event logging is performed.
state table definitions
252 Designing and Managing State Table Applications
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.
char user_status2[16]: User-defined status field that was sent by the outbound
state table during a transfer after the outbound call was made.
char user_status3[16]: User-defined status field that was sent by the outbound
state table during a transfer after the outbound call was made.
char user_status4[16]: User-defined status field that was sent by the outbound
state table during a transfer after the outbound call was made.
char user_status5[16]: 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.
state table definitions
Chapter 17. Using ISDN call transfer 253
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.
Installing the application
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:
state table definitions
254 Designing and Managing State Table Applications
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
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 single step call transfer application.
installing the application
Chapter 17. Using ISDN call transfer 255
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.
Creating an application profile
5. Open the SSTransfer application.
The system displays the Application (SSTransfer) window.
6. Click Object —> New —> Application Profile.
The system displays the Application Profiles window, followed by the
Application Profile window.
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.
10. Click File —> Save.
11. Specify the phone number to be used as the Application Profile ID.
12. Click OK.
13. In the Application (SSTransfer) window, click View —> Refresh.
The system displays the Application Profiles folder, with the new
Application Profile icon inside it.
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 SSTransfer custom server by clicking Run Status —> Start.
The Run Status button displays Waiting after a short while.
Running the Application
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.
installing the application
256 Designing and Managing State Table Applications
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.
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 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
Parameter Default setting Description
-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.
Setting configuration options
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.
3. Click Server —> Open.
The system displays the Custom Server (SSTransfer) window.
4. Click File —> Properties.
The system displays the Properties (SSTransfer) window.
installing the application
Chapter 17. Using ISDN call transfer 257
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.
The system displays the available custom servers in a window.
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.
Custom server functions
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
258 Designing and Managing State Table Applications
accordance with the facility message definition in Single Step Call Transfer
(SSCT) Supplementary Service (ECMA-300, edition 2 Dec 2001)
Custom server function definitions
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.
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 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.
custom server functions
Chapter 17. Using ISDN call transfer 259
Table 13. ISDN single step call transfer return codes (continued)
Error
Code Description Explanation User response
2 Transfer to number
type not valid
The custom server received a
number type 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
type setting to an allowed value.
3 Transfer to number
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
(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 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)
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
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.
Review the Single Step Call Transfer
(SSCT) Supplementary Service
(ECMA-300, edition 2 Dec 2001)
specification and either add a
transferred from number or change
the transfer from number to indicate
that no transfer from number is
required.
7 Transferred number
presentation field not
valid
The custom server received a
transferred number presentation
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
transferred number presentation
setting to an allowed value.
custom server functions
260 Designing and Managing State Table Applications
Table 13. ISDN single step call transfer return codes (continued)
Error
Code Description Explanation User response
8 Transferred number
presentation and
screening fields are
inconsistent.
The custom server received
transferred number presentation
and screening values which did
not conform to the allowed
combinations 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
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
The custom server received tag
data that does not contain or
does not contain a valid number
plan within the
CLGN.NUMBER_PLAN tag
attribute.
Review the tag data that is being
passed into the custom server by
taking a system-level trace. Correct
the tag data as appropriate.
23 Unable to determine
transferred number’s
number type
The custom server received tag
data that does not contain or
does not contain a valid number
type within the
CLGN.NUMBER_TYPE tag
attribute.
Review the tag data that is being
passed into the custom server by
taking a system-level trace. Correct
the tag data as appropriate.
24 Unable to determine
transferred number’s
screening value
The custom server received tag
data that does not contain or
does not contain a valid number
screening value within the
CLGN.NUMBER_SCREEN tag
attribute.
Review the tag data that is being
passed into the custom server by
taking a system-level trace. Correct
the tag data as appropriate.
25 Unable to determine
transferred number’s
presentation value
The custom server received tag
data that does not contain or
does not contain a valid number
presentation value within the
CLGN.NUMBER_PRESENT tag
attribute.
Review the tag data that is being
passed into the custom server by
taking a system-level trace. Correct
the tag data as appropriate.
custom server functions
Chapter 17. Using ISDN call transfer 261
Table 13. ISDN single step call transfer return codes (continued)
Error
Code Description Explanation User response
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
scct_transfer state table error Re-create the problem and take an
AIX system trace, before calling IBM
33 State table receive
data failed with no
more data error
scct_transfer state table error Re-create the problem and take an
AIX system trace, before calling IBM
Support.
34 State table receive
data failed with data
not found
scct_transfer state table error Re-create the problem and take an
AIX system trace, before calling IBM
Support.
35 State table receive
data failed with host
problem
scct_transfer state table error Re-create the problem and take an
AIX system trace, before calling IBM
Support.
36 State table receive
data failed with host
not open
scct_transfer state table error Re-create the problem and take an
AIX system trace, before calling IBM
37 State table receive
data failed with
timeout
scct_transfer state table error Re-create the problem and take an
AIX system trace, before calling IBM
40 State table
TransferCall action
failed
An Edge other than Succeeded
was returned from the
TransferCall action
Re-create the problem and take an
AIX system trace, before calling IBM
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
which the call is to be transferred.
short TransferTag_AwaitConnect: Set to determine when the call should be
disconnected, either as soon as transfer is attempted or only after connection
custom server functions
262 Designing and Managing State Table Applications
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
which the call is to be transferred.
short Transfer_TransfertoNumberType: The number type for the number to
which the call is to be transferred.
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
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).
Output parameters:
short TransferTag_rc: The return code.
custom server functions
Chapter 17. Using ISDN call transfer 263
char TransferTag_data[250]: The ASN1 BER encoding of supplied called and
calling number parameters.
State table definitions
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
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/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.
You can customize the application, but you must not change the basic
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
custom server functions
264 Designing and Managing State Table Applications
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
which the call is to be transferred.
short TransferTag_TransfertoNumberType: The number type for the number to
which the call is to be transferred.
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.
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
state table definitions
Chapter 17. Using ISDN call transfer 265
state table definitions
266 Designing and Managing State Table Applications
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:
© Copyright IBM Corp. 1991, 2008 267
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)?
268 Designing and Managing State Table Applications
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
1. From the Welcome window, click on Applications —> Applications
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.
Creating an application profile
4. Open the Trombone application.
The system displays the Application (IBM_Trombone) window.
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 Example”).
7. Click State Table —> IBMTromboneXmp
installing the IBM_Trombone application
270 Designing and Managing State Table Applications
8. Click OK.
9. Click File —> Save.
10. Specify the phone number to be used as the Application Profile ID.
11. Click OK.
12. In the Application (IBM_Trombone) window, click View —> Refresh.
The system displays the Application Profiles folder, with the new
Application Profile icon inside it.
Starting the custom server
13. Open the Custom Server Manager window: Welcome —> Operations
—> Custom Server Manager
The system displays the available custom servers in a window.
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.
16. Enter Phone B’s number, followed by a # key.
After a short delay, Phone B rings.
17. Pick up Phone B’s handset.
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).
installing the IBM_Trombone application
Chapter 18. Using the IBM_Trombone_Custom_Server 271
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
272 Designing and Managing State Table Applications
-pn < 0
Use the default value of -pn=0.1
Note: Maximum number of trombones = number of channels/2.
Setting configuration options
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
3. Click Server —> Open.
The system displays the Custom Server (IBM_Trombone_Custom_Server)
window.
4. Click File —> Properties.
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.
The system displays the available custom servers in a window.
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
Chapter 18. Using the IBM_Trombone_Custom_Server 273
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
274 Designing and Managing State Table Applications
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
how to use the trombone operation
Chapter 18. Using the IBM_Trombone_Custom_Server 275
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
WaitEventfor DTMF, hang-up
or host event
Figure 45. Event flow required to set up a trombone operation.
how to use the trombone operation
276 Designing and Managing State Table Applications
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.
WaitEventfor DTMF, hang-up
or host event
Third party
Incoming Channel Outgoing ChannelIBM_Trombone_Custom_Server
IBMTromboneCall
CloseHostServerLink
IBMTromboneOut
hangs up
CloseEverything(Implied CloseHostServerLink)Disconnect caller and third
party using
Send host event to caller
WaitEventfor DTMF, hang-up
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
how to use the trombone operation
Chapter 18. Using the IBM_Trombone_Custom_Server 277
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.
2. IBM_Trombone_Custom_Server disconnects the caller and third party from
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.
WaitEventfor DTMF, hang-up
or host event
Incoming Channel Outgoing ChannelIBM_Trombone_Custom_Server
IBMTromboneCall
CloseHostServerLink
IBMTromboneOut
CloseEverything(Implied CloseHostServerLink)
Disconnect caller and thirdParty using
Send host event to caller
WaitEventfor DTMF, hang-up
or host event
Hang-up event
CA_TDM_Disconnect()
Host event
Clean up connection details
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
how to use the trombone operation
278 Designing and Managing State Table Applications
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.
2. IBM_Trombone_Custom_Server disconnects the caller and third party from
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
WaitEventfor DTMF, hang-up
or host event
Incoming Channel Outgoing ChannelIBM_Trombone_Custom_Server
IBMTromboneCall
CloseHostServerLink
IBMTromboneOut
CloseEverything(Implied CloseHostServerLink)
Disconnect Caller and thirdparty using
Send host event to caller
WaitEventfor DTMF, hang-up
or host event
DTMF event
CA_TDM_Disconnect()
Host event
Clean up connection details
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
how to use the trombone operation
Chapter 18. Using the IBM_Trombone_Custom_Server 279
discussion of the voice paths used in the trombone operation, and problems
that might be caused by echo, see “Voice paths” on page 217.
Custom server functions
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).
Custom server function definitions
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
how to use the trombone operation
280 Designing and Managing State Table Applications
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
action for details).
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_info2[35]: Reserved for WebSphere Voice Response.
custom server functions
Chapter 18. Using the IBM_Trombone_Custom_Server 281
char additional_call_info3[35]: Reserved for WebSphere Voice Response.
char additional_call_info4[35]: 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.
custom server functions
282 Designing and Managing State Table Applications
Table 15. Return values for the trombone_make_call_status parameter of the
TromboneCall function (continued)
Make
Call
Status Error Description
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
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
action for details).
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).
custom server functions
Chapter 18. Using the IBM_Trombone_Custom_Server 283
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.
char additional_call_info1[140]: Reserved for WebSphere Voice Response.
char additional_call_info2[35]: Reserved for WebSphere Voice Response.
char additional_call_info3[35]: Reserved for WebSphere Voice Response.
char additional_call_info4[35]: Reserved for WebSphere Voice Response.
char additional_call_info5[35]: Reserved for WebSphere Voice Response.
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.
custom server functions
284 Designing and Managing State Table Applications
Table 16. Return values for the trombone_make_call_status parameter of the
TromboneMakeCall function
Make Call
Status Error Description
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
0 Trombone function request was successful.
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
custom server functions
Chapter 18. Using the IBM_Trombone_Custom_Server 285
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.
custom server functions
286 Designing and Managing State Table Applications
Table 18. Return values for the trombone_make_call_status parameter of the
TromboneMakeCall function
Make Call
Status Error Description
0 Trombone function request was successful.
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.
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 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.
111 A TDM connect or disconnect request failed because of an unexpected
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
operation has failed for the given reason.
Input parameters
None.
custom server functions
Chapter 18. Using the IBM_Trombone_Custom_Server 287
Output parameters
short trombone_disconnect_call_status: The status of the disconnect request,
as shown in Table 19 on page 288.
Table 19. Return values for the trombone_make_call_status parameter of the
TromboneMakeCall function
Make
Call
Status Error Description
0 Trombone function request was successful.
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.
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
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.
111 A TDM connect or disconnect request failed because of an unexpected
return code from the request.
112-199 Spare: may be used for user-defined values.
State table definitions
In this section we describe the 14 trombone state tables.
The 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 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).
custom server functions
288 Designing and Managing State Table Applications
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.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 289
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
MakeCall state table action for details).
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.
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 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.
state table definitions
290 Designing and Managing State Table Applications
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
Status Error Description
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
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 291
Table 20. Return values from the IBMTromboneCall state table
(call_status) (continued)
Return
Edge
Call
Status Error Description
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.
state table definitions
292 Designing and Managing State Table Applications
Table 20. Return values from the IBMTromboneCall state table
(call_status) (continued)
Return
Edge
Call
Status Error Description
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.
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 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
IBM_Trombone_Custom_Server.
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
Bad return code from the ReceiveData corresponding to the
TromboneDisconnectCall request. A status of 216 to 220
represents a return edge of 1 to 5.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 293
Table 20. Return values from the IBMTromboneCall state table
(call_status) (continued)
Return
Edge
Call
Status Error Description
221 Failed to send the data for the TromboneConnectCall request to
the IBM_Trombone_Custom_Server.
222 to
226
Bad return code from the ReceiveData corresponding to the
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
Bad return code from the ReceiveData corresponding to the
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).
state table definitions
294 Designing and Managing State Table Applications
Table 20. Return values from the IBMTromboneCall state table
(call_status) (continued)
Return
Edge
Call
Status Error Description
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
String log_filename (64 characters max): If this is blank, no event logging is
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.
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 either by the third party hanging up, or by 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.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 295
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 in4: The 5th 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 in0: The 1st string.
String in1: The 2nd string.
String in2: The 3rd string.
String in3: The 4th string.
String in4: The 5th string.
String in5: The 6th string.
String in6: The 7th string.
String in8: The 8th string.
state table definitions
296 Designing and Managing State Table Applications
String in9: The 10th string.
String out (this value is returned): The concatenation of the input strings
(in0 + in1 + in2 + in3 + in4 + in5 + in6 + in7 + in8 + in9).
IBMTromboneDisc
This state table encapsulates some of the code needed to continue a trombone
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.
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
String log_filename (64 characters max): If this is blank, no event logging is
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.
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 either by the third party hanging up, or by 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.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 297
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 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).
String in1: The 1st string.
String in2: The 2nd string.
String in3: The 3rd string.
String in4: The 4th string.
String in5: The 5th string.
String in6: The 6th string.
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.
state table definitions
298 Designing and Managing State Table Applications
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.
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
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
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
MakeCall state table action for details).
String log_filename (64 characters max): If this is blank, no event logging is
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.
String user_data (64 characters max): 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 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 within the state
table to use for the outbound part of the trombone operation. If this is blank,
the default label begin is used.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 299
Number wait_time (value is in seconds): The amount of time to wait for a
response to the MakeCall request that is sent to
IBM_Trombone_Custom_Server.
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.
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 either by the third party hanging up, or by 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.
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 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.
state table definitions
300 Designing and Managing State Table Applications
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.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 301
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
String phone_number (40 character max): The number to dial for the
outgoing part of the Trombone (see 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
MakeCall state table action for details).
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).
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 the 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.
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 the
third party to the caller.
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.
String addn_call_info2 (35 characters max): Reserved for WebSphere Voice
Response.
state table definitions
302 Designing and Managing State Table Applications
String addn_call_info3 (35 characters max): Reserved for WebSphere Voice
Response.
String addn_call_info4 (35 characters max): Reserved forWebSphere Voice
Response.
String addn_call_info5 (35 characters max): Reserved for WebSphere Voice
Response.
IBMTromboneRdy
This state table encapsulates some of the code needed to continue a trombone
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.
This state table is called by the user’s application, along with a number of
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.
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
String log_filename (64 characters max): If this is blank, no event logging is
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.
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
IBM_Trombone_Custom_Server.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 303
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.
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 either by the third party hanging up, or by 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.
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
This state table encapsulates some of the code needed to continue a trombone
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
state table definitions
304 Designing and Managing State Table Applications
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.
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
String log_filename (64 characters max): If this is blank, no event logging is
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.
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 #.
Number call_status (this value is returned): The returned status of the
trombone operation.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 305
If the value is zero, the trombone operation was successful and was
terminated either by the third party hanging up, or by 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.
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 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
state table definitions
306 Designing and Managing State Table Applications
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.
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, 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
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 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
called IBM_Trombone.
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.
When the application is invoked by an incoming call, it requests a number to
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.
state table definitions
Chapter 18. Using the IBM_Trombone_Custom_Server 307
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
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 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
called IBM_Trombone.
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.
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, 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.
state table definitions
308 Designing and Managing State Table Applications
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:
© Copyright IBM Corp. 1991, 2008 309
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
VOX_CTI.ini file configuration
310 Designing and Managing State Table Applications
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.
VOX_CTI.ini file configuration
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
312 Designing and Managing State Table Applications
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
Input char name[512]
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]
Valid After a Newcall and before a Gone
Getvdu
Chapter 19. Using the VOX_CTI Custom Server 313
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
Input No input parameters or variables
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
Input No input parameters or variables
Getvox
314 Designing and Managing State Table Applications
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]
Valid After a Newcall and before a Gone
Setvdu
Input char name[1024]
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]
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, 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
Chapter 19. Using the VOX_CTI Custom Server 315
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]
Valid After a Newcall and before a Gone
Transfer
Input char destination[32]
Output
long rc
char error_msg[256]
Setvdu
316 Designing and Managing State Table Applications
VOX command
[VOX.transfer(#channelnum,"destination")][reqid]
VOX response
[VOX.transfer.response(,#channelnum,"destination")][reqid]
Valid After a Newcall and before a Gone
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
Chapter 19. Using the VOX_CTI Custom Server 317
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
WebSphere Voice Response.
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
318 Designing and Managing State Table Applications
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
A–Z, a–z, and underscore ( _ ). The second through
sixty-third characters can include alphanumeric (0–9,
A–Z, a–z) and underscore characters.
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.
© Copyright IBM Corp. 1991, 2008 319
ID or Name Data Type Limitations
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
A–Z, a–z, and underscore ( _ ). The second through
fifteenth characters can include alphanumeric (0–9,
A–Z, a–z) and underscore characters.
Prompt 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.
State table entry label/state
label
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.
State table 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.
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,
A–Z, a–z) and underscore characters.
3270 server name
3270 server script name
3270 server screen name
3270 server field name
3270 server argument
Up to 63 characters. The first character is limited to
A–Z, a–z, and underscore ( _ ). The second through
sixty-third characters can include alphanumeric (0–9,
A–Z, a–z) and underscore characters.
Transaction ID Up to 16 characters.
Voice directory 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.
ID and name limitations
320 Designing and Managing State Table Applications
ID or Name Data Type Limitations
Voice table 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.
Voice table entry position A numeric value in the range 0 through 65535.
ID and name limitations
Appendix A. ID and name limitations 321
ID and name limitations
322 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 323
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
324 Designing and Managing State Table Applications
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
326 Designing and Managing State Table Applications
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.
© Copyright IBM Corp. 1991, 2008 327
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
1 5 or higher 1 5 or higher
2 3 or higher 2 3 or higher
3 3 or higher 3 3 or higher
4 2 or higher 4 2 or higher
5 2 or higher 5 2 or higher
6 1 or higher 6 1 or higher
7 1 or higher 7 1 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
328 Designing and Managing State Table Applications
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
330 Designing and Managing State Table Applications
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.
customizing the Juke box
Appendix C. Background music: technical information 331
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.
customizing the Juke box
332 Designing and Managing State Table Applications
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
Appendix C. Background music: technical information 333
writing your own background music subsystem
334 Designing and Managing State Table Applications
Notices
This information was developed for products and services offered in the
U.S.A.
IBM® may not offer the products, services, or features discussed in this
document in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or
imply that only that IBM product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe
any IBM intellectual property right may be used instead. However, it is the
user’s responsibility to evaluate and verify the operation of any non-IBM
product, program, or service.
IBM may have patents or pending patent applications covering subject matter
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
© Copyright IBM Corp. 1991, 2008 335
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.
336 Designing and Managing State Table Applications
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
338 Designing and Managing State Table Applications
Glossary
The following terms and abbreviations are defined as they are used in the context of
WebSphere Voice Response. If you do not find the term or abbreviation you are looking for,
see IBM Dictionary of Computing, McGraw-Hill, 1994 or the AIX: Topic Index and Glossary,
SC23–2513.
Special Characters
µ-law. The companding algorithm that is used
primarily in North America and Japan when
converting from analog to digital speech data.
(Compand is a contraction of compress and
expand.) Contrast with A-law.
Numerics
2 B-channel transfer feature. See Integrated
Services Digital Network (ISDN) two B-channel
transfer.
3270 host application. An application on the
IBM System/370™ System/390®, or AS/400® that
interacts with terminals that support the 3270
data stream.
3270 script language. See script language.
3270 server. A function of WebSphere Voice
Response that provides a software interface
between WebSphere Voice Response and IBM
System/370, System/390, or AS/400 architecture
business applications that interact with terminals
that support the 3270 data stream. Contrast with
custom server.
5ESS. (1) A Lucent Technologies switch. (2) The
ISDN protocol that is used on the 5ESS switch. It
provides 23 B-channels and a D-channel over a
T1 trunk.
6309 Digital Trunk Quad Adapter. See Digital
Trunk Quad Adapter.
6310 Digital Trunk Extended Adapter (DTXA).
See Digital Trunk Extended Adapter.
6312 Digital Trunk Telephony Adapter
(DTTA). See Digital Trunk Telephony Adapter.
6313 Digital Trunk Telephony Adapter (DTTA)
with Blind Swap Cassette (BSC). See Digital
Trunk Telephony Adapter with Blind Swap
Cassette.
A
A-law. The companding algorithm that is used
in Europe, Latin America, and other countries
when converting from analog to digital speech
data. (Compand is a contraction of compress and
expand.) Contrast with µ-law.
access protocol. A protocol that is used between
an external subscriber and a switch in a
telephone network.
ACD. See automatic call distributor.
ACL. See application connectivity link.
action. See state table action.
Action Palette. An area that contains folders
and icons that can be selected to create state
table actions.
Address Resolution Protocol (ARP). In
HACMP, the Internet communication protocol
that dynamically maps Internet addresses to
physical (hardware) addresses on local area
networks. Limited to networks that support
hardware broadcast.
The usr/sbin/cluster/etc/clinfo.rc script, which is
invoked by the clinfo daemon whenever a
network or node event occurs, updates the
system ARP cache. This ensures that the IP
© Copyright IBM Corp. 1991, 2008 339
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
340 Designing and Managing State Table Applications
ASP. See application server platform.
audio name. The audible name that relates to a
specific application profile ID and mailbox.
auto-attendant. Automated attendant. A voice
application that answers incoming calls and asks
callers which number or other service they
would like.
automatic call distributor (ACD). A telephone
system feature that automatically queues and
processes inbound calls according to predefined
rules. For example, a call might be routed to the
agent whose line has been idle longest.
automatic number identification (ANI). A
service available in the U.S. that provides the
telephone number of the calling party. It is
generated by the caller’s originating central office
switch, sent to a telephone network carrier if
required, then sent directly either to a switch or
to a voice processing system.
autostubbing. A state table icon view utility
that automatically converts lines into stubs when
they cross a specified number of columns.
B
B8ZS. Bipolar with 8-zero substitution. A T1
line code that is required for 64Kb channels such
as ISDN.
B-channel. See bearer channel. See also Integrated
Services Digital Network (ISDN) .
background music. Any audio data that is to be
played on a music channel.
barge-in. The capability that allows a prompt to
be interrupted by an utterance that is then
passed to a speech recognizer. See also
cut-through channel.
baseforms. The set of phonetic pronunciations
that are associated with a grammar. In
WebSphere Voice Server, the IBM dictionary of
pronunciations is used.
basic rate interface (BRI). The means of ISDN
access that is normally used by private
subscribers. It provides two B-channels of 64 Kb
per second and one D-channel of 16 Kb per
second for signaling. This is often known as
2B+D. Contrast with primary rate interface (PRI).
beans. Java beans with which you can build
voice applications to use the services of
WebSphere Voice Response on any platform.
bearer channel. In an ISDN interface, a duplex
channel for transmitting data or digital voice
between the terminal and the network. The
B-channel operates at 64 Kb per second.
bearer service. The type of service that defines
how an ISDN connection will be used. Typical
bearer services are speech telephony, 64 Kb per
second data, and high-quality speech.
blind transfer. A type of call transfer in which
the call is routed to another extension and the
original call is ended. No check is made to
determine whether the transferred call is
answered or if the number is busy. Contrast with
screened transfer.
bnf. Abbreviation for Backus-Naur Form, which
is used to describe the syntax of a given
language and its notation. In speech recognition,
a special adaptation of grammar representation
that is specified by Speech Recognition Control
Language (SRCL) (pronounced “circle”).
bos. Base Operating System.
bps. bits per second.
BRI. See basic rate interface.
bridge. See DVT bridge.
British Approvals Board for
Telecommunications. The British standards
organization that is responsible for approval of
equipment that is to be attached to the PSTN.
C
cadence. The modulated and rhythmic
recurrence of an audio signal. For example, a
series of beeps or a series of rings.
glossary
Glossary 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
342 Designing and Managing State Table Applications
signaling (on-hook and off-hook) and address
signaling on T1 and E1 digital links. The
signaling information for each traffic (voice)
channel is transmitted in a signaling channel that
is permanently associated with the traffic
channel. On T1 links, supervisory signaling is
sent in the traffic channel by using robbed-bit
signaling (RBS). On E1 links, a separate channel is
used to send signaling. Address signaling can be
transmitted either in the signaling channel
(out-of-band) or in the traffic channel (in-band).
Contrast with common channel signaling (CCS).
channel bank. A device that converts an analog
line signal to a digital trunk signal.
channel number. The identifying number that is
assigned to a licensed channel on the T1 or E1
trunk that connects WebSphere Voice Response to
the switch, channel bank, or channel service unit.
channel process (CHP). The AIX process that
runs the logic of the state table; each active caller
session has one active channel process.
channel service unit (CSU). A device that is
used to connect a digital phone line to a
multiplexer, a channel bank, or directly to
another device that generates a digital signal. A
CSU performs specific line-conditioning and
equalization functions, and responds to loopback
commands that are sent from the CO.
CHP. See channel process.
CIC. See circuit identification code.
CICS. See customer information control system.
circuit identification code (CIC). A 12-bit
number that identifies a trunk and channel on
which a call is carried.
clear message. A message that is displayed by
WebSphere Voice Response to tell the operator
that a red or yellow error message has been
cleared.
client node. In a single system image (SSI), a
WebSphere Voice Response system that handles
interactions with callers. A client node must have
a telephony connection. It does not store
application or voice data; it gets data from the
server node of the SSI.
CLIP. See calling line identification presentation.
cluster. Loosely-coupled collection of
independent systems (nodes) that are organized
into a network to share resources and to
communicate with each other. HACMP defines
relationships among cooperating systems where
peer cluster nodes provide the services that a
cluster node offers if that node cannot do so.
cluster configuration. User definition of all
cluster components. Component information is
stored in the Object Data Manager. Components
include cluster name and ID, and information
about member nodes, adapters, and network
modules.
CO. See central office.
codec. Refers to adapters that compress and
decompress video files. The letters ″codec″
represent ″compression/decompression″; in the
past, they represented ″coder/decoder.″
Comité de Coordination de l’Harmonization.
The CEPT committee responsible for standards.
Comitato Elettrotechnico Italiano. The Italian
standards organization responsible for signaling
protocols.
Comité Consultatif International Télégraphique
et Téléphonique (CCITT). This organization
has been renamed and is now known as the
International Telecommunications Union -
Telecommunication Standardization Sector
(ITU-T).
common channel signaling (CCS). A method of
communicating telephony information and line
signaling events (for example, call setup and call
clearing) on a dedicated signaling channel. The
signaling channel is either a predefined channel
on an E1 or T1 digital link, or a completely
separate link between the switch and WebSphere
Voice Response. For data integrity and reliability,
the information is usually communicated using a
data link protocol. The telephone information
glossary
Glossary 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
344 Designing and Managing State Table Applications
customer premises equipment (CPE).
Telephony equipment that is on the premises of a
business or domestic customer of the telephone
company. An example is a private branch
exchange (PBX).
cut-through channel. A channel of voice data
that has been passed through echo-cancellation
algorithms. The channel provides echo-canceled
voice data that can then be used by the engine in
a recognition attempt. This is similar to barge-in.
D
daemon. In the AIX operating system, a
program that runs unattended to perform a
standard service.
database server node. In a single system image
(SSI), a WebSphere Voice Response system that
contains the WebSphere Voice Response DB2®
database. This is usually the same node as the
voice server node.
DBIM. The internal database manager of
WebSphere Voice Response.
DBS. The database server of WebSphere Voice
Response.
DCBU. See D-channel backup.
D-channel. See delta channel.
D-channel backup (DCBU). An ISDN NFAS
configuration where two of the T1 facilities have
a D-channel, one of which is used for signaling,
and the other as a backup if the other fails. See
also non-facility associated signaling.
DDI. See direct inward dialing.
DDS. See production system.
delay start. A procedure that is used with some
channel-associated signaling protocols to indicate
when a switch or PABX is ready to accept
address signaling. After seizure, the switch sends
off-hook until it is ready to accept address
signaling, at which time it sends on-hook.
Contrast with immediate start and wink start.
delta channel. In an ISDN interface, the
D-channel or delta channel carries the signaling
between the terminal and the network. In a basic
rate interface, the D-channel operates at 16 Kb
per second. In a primary rate interface, the
D-channel operates at 64 Kb per second.
destination point code (DPC). A code that
identifies the signaling point to which an MTP
signal unit is to be sent. Unique in a particular
network.
development system. A WebSphere Voice
Response system that is not used to respond to,
or make, “live” calls; it is used only to develop
and test applications. Contrast with production
system.
dial. To start a telephone call. In
telecommunication, this action is performed to
make a connection between a terminal and a
telecommunication device over a switched line.
dial by name. To press the keys that are related
to subscribers’ names instead of to their
telephone numbers or extensions.
dialed number identification service (DNIS). A
number that is supplied by the public telephone
network to identify a logical called party. For
example, two toll-free numbers might both be
translated to a single real number. The DNIS
information distinguishes which of the two
toll-free numbers was dialed.
dialog box. A secondary window that presents
information or requests data for a selected action.
dial tone. An audible signal (call progress tone)
that indicates that a device such as a PABX or
central office switch is ready to accept address
information (DTMF or dial pulses).
DID. See direct inward dialing.
digital signal processing (DSP). A set of
algorithms and procedures that processes
electronic signals after their conversion to digital
format. Because of the specific mathematical
models that are required to perform this
processing, specialized processors are generally
used.
glossary
Glossary 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
346 Designing and Managing State Table Applications
DMS100 switch, providing 23 B-channels and a
D-channel over a T1 trunk.
DNIS. See dialed number identification service.
double-trunking. See trombone.
down. The condition in which a device is
unusable as a result of an internal fault or of an
external condition, such as loss of power.
downstream physical unit (DSPU). Any remote
physical unit (data link, storage, or input/output
device) that is attached to a single network host
system.
DPC. See destination point code.
drop-in grammar. A set of precompiled
grammar rules that can be used by an
application-specific grammar to improve the
recognition performance.
DSP. See digital signal processing.
DSPU. See downstream physical unit.
DSS1. See Digital Subscriber signaling System
Number 1.
DTMF. See dual-tone multifrequency.
DTEA. See Digital Trunk Ethernet Adapter.
DTNA. See Digital Trunk No Adapter.
DTQA. See Digital Trunk Quad Adapter.
dtuser. The name of the AIX account that is set
up during the installation process for the use of
all users of WebSphere Voice Response.
DTTA. See Digital Trunk Telephony Adapter.
DTXA. See Digital Trunk Extended Adapter.
dual-line call transfer. A call transfer method in
which the primary and secondary lines remain
bridged until a call is completed. (Also known as
tromboning: see trombone).
dual-tone multifrequency (DTMF). The signals
are sent when one of the telephone keys is
pressed. Each signal is composed of two different
tones.
DVT. See Distributed Voice Technologies.
DVT bridge. The interface between a voice
technology component (such as a speech
recognizer) and the DVT server. A bridge must
exist for each technology that you want to
integrate with DVT.
DVT_Client2. A WebSphere Voice Response
custom server that passes commands and data to
DVT_Server.
DVT interface. A WebSphere Voice Response
programming interface that is used by a DVT
bridge. It enables integration of voice
applications with Distributed Voice Technologies to
provide functions such as speech recognition.
DVT_Server. A component of DVT that
allocates and manages system resources in
response to requests from DVT_Client2.
DVT service. The combination of a voice
application, a DVT bridge, and a voice
technology that allows a caller to interact with
your business.
dynamic vocabulary. A vocabulary that is
defined while an application is running.
E
E&M. A channel-associated signaling protocol
in which signaling is done using two leads: an
M-lead that transmits battery or ground and an
E-lead that receives open or ground.
E1. A digital trunking facility standard that is
used in Europe and elsewhere. It can transmit
and receive 30 digitized voice or data channels.
Two additional channels are used for
synchronization, framing, and signaling. The
transmission rate is 2048 Kb per second. Contrast
with T1.
glossary
Glossary 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
348 Designing and Managing State Table Applications
... ...
Recursion is not permitted; that is, no contexts of
type FILELIST can be specified in a FILELIST.
When a FILELIST is loaded, all the grammars
that are specified in it are loaded into the engine.
From then on, the grammars that are loaded
when the FILELIST is specified are regarded as a
single context.
Foreign Exchange Subscriber (FXS). A
signaling protocol that links a user’s location to a
remote exchange that would not normally be
serving that user, to provide, for example, calls
to outside the local area at the local rate.
frame. A group of data bits that is surrounded
by a beginning sequence and an ending
sequence.
fsg. Abbreviation for finite state grammar. In
WebSphere Voice Server, the extension of a file
that contains grammar specifications in compiled,
binary form. It is generated from a .bnf file and
is called a .fsg file.
function. In ADSI, an ADSI instruction or group
of instructions.
FXS. See Foreign Exchange Subscriber.
G
gatekeeper. A component of a Voice over Internet
Protocol that provides services such as admission
to the network and address translation.
gateway. A component of Voice over Internet
Protocolthat provides a bridge between VoIP and
circuit-switched environments.
G.711. Specification for uncompressed voice for
PSTN and Voice over Internet Protocol access.
G.723.1. Compressed audio codecs that are used
on Voice over Internet Protocol connection for
voice.
G.729A. Compressed audio codecs that are used
on Voice over Internet Protocol connection for
voice.
glare. A condition that occurs when both ends
of a telephone line or trunk are seized at the
same time.
grammar. A structured collection of words and
phrases that are bound together by rules. A
grammar defines the set of all words, phrases,
and sentences that might be spoken by a caller
and are recognized by the engine. A grammar
differs from a vocabulary in that it provides rules
that govern the sequence in which words and
phrases can be joined together.
greeting. In voice mail, the recording that is
heard by a caller on reaching subscriber’s
mailbox. See also announcement-only greeting.
Contrast with voice message.
greeting header. In voice mail, a recording that
is made by a subscriber and played to callers
either before or instead of a personal greeting.
Groupe Special Mobile (GSM). A CEPT/CCH
standard for mobile telephony.
H
HACMP (High-Availability Cluster
Multi-Processing) for AIX. Licensed Program
Product (LPP) that provides custom software that
recognizes changes in a cluster and coordinates
the use of AIX features to create a
highly-available environment for critical data and
applications.
HACMP/ES. Licensed Program Product (LPP)
that provides Enhanced Scalability to the
HACMP for AIX LPP. An HACMP/ES cluster
can include up to 32 nodes.
hang up. To end a call. See also disconnect.
HDB3. High-density bipolar of order 3. An E1
line coding method in which each block of four
successive zeros is replaced by 000V or B00V, so
that the number of B pulses between consecutive
V pulses is odd. Therefore, successive V pulses
are of alternate polarity so that no dc component
is introduced. Note: B represents an inserted
pulse that observes the alternate mark inversion
glossary
Glossary 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
350 Designing and Managing State Table Applications
(ITU-T). The name of the organization that was
previously known as the CCITT.
IP. See intelligent peripheral.
ISDN. See Integrated Services Digital Network
(ISDN) .
ISDN two B-channel transfer. See Integrated
Services Digital Network (ISDN) two B-channel
transfer.
ISDN-UP. See Integrated Services Digital Network
user part.
ISUP. See Integrated Services Digital Network user
part.
ITU-T. See International Telecommunications
Union – Telecommunication Standardization Sector.
IVR. See interactive voice response.
J
Java Bean. A reusable Java component. See
beans.
jump out. See call transfer.
K
key. (1) One of the pushbuttons on the
telephone handset; sometimes referred to as a
DTMF key. (2) A component of the keyboard that
is attached to the computer system.
key pad. The part of the telephone that contains
the pushbutton keys.
key pad mapping. The process of assigning
special alphanumeric characters to the keys that
are on a telephone key pad, so that the telephone
can be used as a computer-terminal keyboard.
L
LAN. See local area network.
language model. For speech recognition, a set
of acoustic shapes (in binary format) for a given
set of words, in which word-to-word differences
are maximized, but speaker-to-speaker
differences are minimized. See also vocabulary.
LAPD. See link access protocol for the D-channel.
licensed program product (LPP). A
separately-priced program and its associated
materials that bear an IBM copyright and are
offered under the terms and conditions of a
licensing agreement.
license server. A machine on a network that
holds licenses and distributes them on request to
other machines on the network.
line error. An error on the telephone line that
causes the signal to be impaired.
link access protocol for the D-channel. An
HDLC protocol used in ISDN that ensures a
reliable connection between the network and the
user. Often used as another name for Q.921.
local area network (LAN). A network in which
computers are connected to one another in a
limited geographical area. WebSphere Voice
Response communication with WebSphere Voice
Server speech recognition, text-to-speech, and
single system image (SSI) requires a LAN that is
dedicated to that purpose (unless both are
installed on the same system). A token-ring
network is a type of LAN.
local variable. A user-defined temporary
variable that can be accessed only by the
program (state table, prompt, or 3270 script) for
which it is defined. Contrast with input parameter,
system variable.
M
macro. See system prompt.
MAP. See mobile application part.
MB. See megabyte.
megabyte. (1) For processor storage and real
and virtual memory, 1 048 576 bytes. (2) For disk
storage capacity and transmission rates, 1 000
000 bytes.
glossary
Glossary 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
352 Designing and Managing State Table Applications
directories. In a single system image (SSI), NFS is
used to attach the WebSphere Voice Response
DB2 database.
network termination. See NT mode.
NFAS. See non-facility associated signaling.
NFS. See Network File System.
node. In a single system image (SSI), one of the
WebSphere Voice Response systems that are in
the cluster.
non-facility associated signaling (NFAS). An
ISDN configuration where several T1 facilities
can be controlled by a single D-channel, instead
of the normal T1 configuration where each T1
facility has 23 B-channels and a D-channel
(23B+D). With NFAS, all 24 timeslots of the non
signaling trunks are available for voice, whereas
only 23 channels can be used on the trunk that
carries signaling traffic (23B+D+n24B).
NT mode. Attachment to the ISDN network is
asymmetric. The network side of the connection
operates in network termination, or NT, mode.
User equipment operates in terminal equipment,
or TE, mode.
O
ODM. See Object Data Manager.
Object Data Manager (ODM). A data manager
intended for the storage of system data. The
ODM is used for many system management
functions. Information that is used in many
commands and SMIT functions is stored and
maintained in the ODM as objects with
associated characteristics.
off-hook. A telephone line state, usually
induced by lifting a receiver, in which the line is
ready to make a call.
offline. Not attached or known to the existing
system configuration, and therefore not in active
operation.
on-hook. A telephone line state, usually
induced by hanging up a receiver, in which the
line is ready to receive a call.
online. In active operation.
OPC. See originating point code.
Open Systems Interconnection (OSI). (1.) The
interconnection of open systems as specified in
particular ISO standards. (2.) The use of
standardized procedures to enable the
interconnection of data processing systems.
Open Systems Interconnection (OSI)
architecture. Network architecture that observes
the particular set of ISO standards that relate to
Open Systems Interconnection.
Open Systems Interconnection (OSI) Reference
Model. A conceptual model composed of seven
layers, each specifying particular network
functions. Developed by the International
Organization for Standardization (ISO) in 1984, it
is considered to be the primary architectural
model for intercomputer communications
originating point code (OPC). A code that
identifies the signaling Point that originated an
MTP signal unit. Unique in a particular network.
OSI. See Open Systems Interconnection.
outgoing mail. In voice mail, messages that are
sent by a subscriber to another subscriber on the
same system, and have not yet been listened to
by the addressee.
out-of-band. In the telephony signaling channel,
as opposed to the voice channel. Signals are said
to be carried out-of-band. Contrast with in-band.
P
PABX. See private automatic branch exchange .
pack. Each DTTA or DTXA contains the
equivalent of four packs. The pack is a digital
trunk processor built into the digital trunk
adapter, so there is no need for external
hardware. See also XPACK.
glossary
Glossary 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
354 Designing and Managing State Table Applications
prompt. (1) A message that requests input or
provides information. Prompts are seen on the
computer display screen and heard over the
telephone. (2) In WebSphere Voice Response, a
program that uses logic to determine
dynamically the voice segments that are to be
played as a voice prompt.
prompt directory. A list of all the prompts that
are used in a particular voice application. Used
by the state table to play the requested voice
prompts.
pronunciation. The possible phonetic
representations of a word. A word can have
multiple pronunciations; for example, “the” has
at least two pronunciations, “thee” and “thuh”.
pronunciation dictionary. A file that contains
the phonetic representation of all of the words,
phrases, and sentences for an application
grammar.
pronunciation pool. A WebSphere Voice Server
resource that contains the set of all
pronunciations.
protocol. A set of semantic and syntactic rules
that determines the behavior of functional units
when they get communication. Examples of
WebSphere Voice Response protocols are FXS,
RE, and R2.
PSTN. An ITU-T abbreviation for public
switched telephone network.
PTF. See program temporary fix.
Pulse Code Modulation (PCM). Variation of a
digital signal to represent information.
pushbutton. (1) A key that is on a telephone
key pad. (2) A component in a window that
allows the user to start a specific action.
pushbutton telephone. A type of telephone that
has pushbuttons. It might or might not send tone
signals. If it does, each number and symbol on
the key pad has its own specific tone.
Q
Q.921. The ITU-T (formerly CCITT)
recommendation that defines the link layer of the
DSS1 protocol. Q.921 defines an HDLC protocol
that ensures a reliable connection between the
network and the user. Often used as another
name for LAPD.
Q.931. The ITU-T recommendation that defines
the network layer of the DSS1 protocol. This
layer carries the ISDN messages that control the
making and clearing of calls.
quiesce. To shut down a channel, a trunk line,
or the whole system after allowing normal
completion of any active operations. The
shutdown is performed channel-by-channel.
Channels that are in an idle state are shut down
immediately. Channels that are processing calls
are shut down at call completion.
R
RAI. See remote alarm indication.
RBS. See robbed-bit signaling.
RE. See remote extension.
Recognition Engine server. In WebSphere Voice
Server, the software that performs the speech
recognition and sends the results to the client.
This consists of one ‘Tsm router’ and at least one
‘tsmp’ and one ‘engine’.
reduced instruction set computer (RISC). A
computer that uses a small, simplified set of
frequently-used instructions to improve
processing speed.
referral number. The phone number to which
calls are routed, when call forwarding is active.
rejection. The identification of an utterance as
one that is not allowed by a grammar.
release link trunk (RLT). A custom specification
from Nortel for ISDN call transfer.
glossary
Glossary 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
356 Designing and Managing State Table Applications
service information octet (SIO). A field that is
in an MTP message signal unit. It identifies a
higher layer user of MTP, and whether the
message relates to a national or international
network.
service node. An element of an Intelligent
Network. The service node contains the service
logic that controls an intelligent network
application and resources.
service provider. Any company that provides
services for a fee to its customers, such as
telecommunication companies, application
service providers, enterprise IT, and Internet
service providers.
service provider equipment (SPE). The
switching equipment that is owned by the
telephone company.
session. See speech recognition session.
Session Initiation Protocol. A signaling
protocol used for internet conferencing,
telephony, presence, events notification and
instant messaging.
short message service center (SMSC). A
component of the mobile telephony network,
specified by the GSM group of standards, that
provides for exchange of alphanumeric messages
of less than 160 bytes. Messages can be
exchanged between different types of system
such as mobile telephone, alphanumeric pager,
terminal, e-mail, telex, or DTMF telephone.
SIF. See signaling information field.
Signal Computing System Architecture
(SCSA). An architecture that was defined by
Dialogic to support interoperability of software
and hardware components that are developed by
different vendors in the computer telephony
industry.
Signal Computing bus (SCbus). A time
division multiplexed (TDM) hardware bus that
was originated by Dialogic to interconnect
different vendors’ computer telephony adapters.
Specified as part of Signal Computing System
Architecture (SCSA).
signaling. The exchange of control information
between functional parts of the system in a
telecommunications network.
signaling connection control part (SCCP). A
layer 3 protocol that observes OSI.
signaling information field (SIF). The user data
portion of an MTP message signal unit.
signaling link code (SLC). A code that
identifies a particular signaling link that connects
the destination and originating signaling points.
This is used in MTP signaling network
management messages to indicate the signaling
link to which the message relates.
signaling link selection (SLS). A field that is
used to distribute MTP signal units across
multiple signaling links.
signaling mode. The type of signaling protocol,
either channel-associated signaling, or
common-channel signaling.
signaling point. A node in a signaling network
that either originates and receives signaling
messages, or transfers signaling messages from
one signaling link to another, or both.
signaling process. A WebSphere Voice Response
component that controls signaling for an
exchange data link or common-channel signaling
protocol. Some signaling processes are supplied
with WebSphere Voice Response, and others can
be custom-written.
signaling System Number 7 (SS7). The
international high-speed signaling backbone used
for the public-switched telephone network.
silence. A short pause between utterances.
simple mail transfer protocol (SMTP). An
Ethernet protocol that is related to TCP/IP.
simple network management protocol (SNMP).
In the Internet suite of protocols, a network
management protocol that is used to monitor
routers and attached networks. SNMP is an
application layer protocol. Information on
devices managed is defined and stored in the
glossary
Glossary 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
358 Designing and Managing State Table Applications
SS7. See signaling System Number 7.
SSI. See single system image.
SSI-compliant custom server. A custom server
that runs correctly in a single system image. The
custom server observes all the guidelines for the
operation of custom servers in an SSI
environment.
SSI-tolerant custom server. A custom server
that runs in a single system image, but with only
some restrictions.
standalone system. A WebSphere Voice
Response system that is not part of a single
system image (SSI). A standalone system is not
connected to other WebSphere Voice Response
systems, so it contains its own application and
voice data.
state. One step in the logical sequence of actions
that makes a WebSphere Voice Response voice
application.
state table. A list of all the actions that are used
in a particular voice application. A component of
WebSphere Voice Response.
state table action. One instruction in a set of
instructions that is in a WebSphere Voice
Response state table that controls how
WebSphere Voice Response processes various
operations such as playing voice prompts or
recording voice messages. See also state.
stub. A line in a state table that is only partially
displayed.
subscriber. In voice mail, any person who owns
a mailbox.
subscriber class. A named set of variables that
defines a specific level of service available to
telephone subscribers, such as maximum number
of messages per mailbox and maximum number
of members per mailbox distribution list.
subvocabulary. A vocabulary that is called by
another vocabulary.
supplementary service. In Euro-ISDN, a service
outside the minimum service offering that each
signatory is obliged to provide. For example,
calling line identification presentation (CLIP) and
call session.
switch. A generic term that describes a
telecommunications system that provides
connections between telephone lines and trunks.
symmetric multiprocessor (SMP). A system in
which functionally-identical multiple processors
are used in parallel, providing simple and
efficient load-balancing.
Synchronous Data Link Control (SDLC). A
discipline for managing synchronous,
code-transparent, serial-by-bit information
transfer over a link connection. Transmission
exchanges can be duplex or half-duplex over
switched or nonswitched links.
system administrator. The person who controls
and manages the WebSphere Voice Response
system by adding users, assigning account
numbers, and changing authorizations.
system greeting. In voice mail, a default greeting
that is heard by callers to the mailboxes of
subscribers who have not recorded a personal
greeting or who have selected the system
greeting. Contrast with personal greeting.
System Management Interface Tool (SMIT). A
set of utilities that can be used for various
purposes, such as loading WebSphere Voice
Response software, installing the exchange data
link, and configuring SNA.
Systems Network Architecture (SNA). An
architecture that describes the logical structure,
formats, protocols, and operational sequences for
transmitting information units through the
networks and also the operational sequences for
controlling the configuration and operation of
networks.
system parameter. A variable that controls some
of the behavior of WebSphere Voice Response or
applications that are running under WebSphere
Voice Response. System parameters are set
through System Configuration or Pack
glossary
Glossary 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
360 Designing and Managing State Table Applications
token-ring network. A local area network that
connects devices in a ring topology and allows
unidirectional data transmission between devices
by a token-passing procedure. A device must
receive a token before it can transmit data.
tone. An audible signal that is sent across a
telephone network. Single (one-frequency) tones,
tritones (three sequential tones at different
frequencies), dual tones (two simultaneous tones
at different frequencies), and dual sequential
tones exist. Each has a different meaning.
transaction. A specific, related set of tasks in an
application that retrieve information from a file
or database. For example, a request for the
account balance or the available credit limit.
transaction capabilities application part
(TCAP). Part of the SS7 protocol that provides
transactions in the signaling network. A typical
use of TCAP is to verify a card number, for the
credit card calling service.
transaction messaging. The ability to associate
an item of data, such as a transaction identifier,
with a voice message. The voice message can
later be retrieved by referencing the data value.
transfer. See call transfer.
Transmission Control Protocol/Internet Protocol
(TCP/IP). A communication subsystem that is
used to create local area and wide area networks.
trombone. A connected voice path that enters
an IVR from a switch on one circuit, then returns
to the same switch on a parallel circuit. Two IVR
ports and two circuits are consumed, but in some
circumstances this might be the only way to
make a connection between two callers if the
attached switch does not support a Call Transfer
function. Also known as double-trunking.
trunk. A telephone connection between two
central offices or switching devices. In
WebSphere Voice Response, a trunk refers to 24
or 30 channels that are carried on the same T1 or
E1 digital interface.
trunk interface card (TIC). The component of
the pack that manages the trunk connection to
the switch.
Tsm Router. In WebSphere Voice Server, a
process that controls which engine processes are
in use at any time. Requests for an engine by a
WebSphere Voice Server Client are accepted or
rejected depending on whether an engine that
meets the Tsm Client’s requirements is available.
tsmp. In WebSphere Voice Server, a process that
is running on the Recognition engine server
machine that passes messages between an engine
and a Tsm Client. One tsmp exists for every
engine.
TTS. See text-to-speech.
tune. A piece of music or other audio data that
is intended to be played as background music.
U
underrun. To run out of audio data to play,
causing voice or music to be audibly broken up
or cut off.
unified messaging. A messaging system in
which a single copy of a message is stored and
accessed by multiple applications (for example,
voice mail and e-mail). Contrast with integrated
messaging.
Unified Messaging. An IBM product that uses
WebSphere Voice Response’s voice processing
capabilities to provide a wide range of voice
mail, fax, and e-mail functions. Previously
known as Message Center.
user. Someone who uses WebSphere Voice
Response as a system administrator, application
developer, or similar. Contrast with caller.
utterance. A spoken word, phrase, or sentence
that can be preceded and followed by silence.
V
variable. A system or user-defined element that
contains data values that are used by WebSphere
glossary
Glossary 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
362 Designing and Managing State Table Applications
VPIM. See Voice Protocol for Internet Messaging.
VRU. See voice response unit.
W
World Wide Web Consortium (W3C). An
organization that develops interoperable
technologies (specifications, guidelines, software,
and tools) to lead the Web to its full potential.
W3C is a forum for information, commerce,
communication, and collective understanding.
Refer to the web site at http://www.w3.org
WebSphere Voice Response. A voice processing
system, that combines telephone and data
communications networks to use, directly from a
telephone, information that is stored in
databases.
wink start. A procedure that is used with some
channel-associated signaling protocols to indicate
when a switch or PABX is ready to accept
address signaling. After seizure, the switch sends
a short off-hook signal (wink) when it is ready to
accept address information. Contrast with delay
start and immediate start.
word spotting. In speech recognition, the ability
to recognize a single word in a stream of words.
wrap. In ADSI, the concatenation of two
columns of display data to form a single column.
X
XPACK. A digital trunk processor that is
implemented using DSP technology on the
digital trunk adapter without the need for
external hardware. One digital trunk adapter
(DTTA or DTXA) provides up to four XPACKs
on a PCI card.
Y
yellow alarm. See remote alarm indication.
Z
zero code suppression (ZCS). A coding method
that is used with alternate mark inversion to
prevent sending eight successive zeros. If eight
successive zeros occur, the second-least
significant bit (bit 7, with the bits labeled 1
through 8 from the most significant to the least
significant) is changed from a 0 to a 1. AMI with
ZCS does not support clear channel operation.
glossary
Glossary 363
glossary
364 Designing and Managing State Table Applications
List of WebSphere Voice Response and associated
documentation
Here is a list of the documentation for WebSphere Voice Response for AIX and
associated products. PDF and HTML versions of the documentation are
available from the IBM Publications Center at http://www.ibm.com/shop/publications/order. Hardcopy books, where available, can be ordered through
your IBM representative or at this Web site.
WebSphere Voice Response for AIX documentation can also be found by going
to the IBM Pervasive software Web site at http://www.ibm.com/software/pervasive, selecting the WebSphere Voice products link, and then selecting
the library link from the WebSphere Voice Response page.
PDF and HTML versions of the WebSphere Voice Response for AIX
publications are available on the CD-ROM supplied with the product. In
addition, WebSphere Voice Response for AIX, WebSphere Voice Response for
Windows, Unified Messaging, and other WebSphere Voice publications are
available together in PDF and HTML formats on a separately-orderable
CD-ROM (order number SK2T-1787).
Note: To read PDF versions of books you need to have the Adobe Acrobat
Reader (it can also be installed as a plug-in to a Web browser). It is
available from Adobe Systems at http://www.adobe.com .
WebSphere Voice Response software
v WebSphere Voice Response for AIX: General Information and Planning,
GC34-6379
v WebSphere Voice Response for AIX: Installation, GC34-6380
v WebSphere Voice Response for AIX: User Interface Guide, SC34-6386
v WebSphere Voice Response for AIX: Configuring the System, SC34-6381
v WebSphere Voice Response for AIX: Managing and Monitoring the System,
SC34–6384
v WebSphere Voice Response for AIX: Designing and Managing State Table
Applications, SC34–6388
v WebSphere Voice Response for AIX: Application Development using State Tables,
SC34–6387
v WebSphere Voice Response for AIX: Developing Java applications, GC34-6377
© Copyright IBM Corp. 1991, 2008 365
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.
366 Designing and Managing State Table Applications
The documentation for Version 5.1 of WebSphere Voice Server is provided in
the form of an HTML-based information center, and can be found at:
http://publib.boulder.ibm.com/pvc/wvs/51/en/infocenter/index.html
Unified Messaging for WebSphere Voice Response
v Unified Messaging: General Information and Planning, GC34-6398
v Unified Messaging: Subscriber’s Guide (Types 0, 1, 2, 3, 4 and 9), SC34-6403
v Unified Messaging: Subscriber’s Guide (Types 5, 6, 7 and 8), SC34-6400
v Unified Messaging: Administrator’s Guide, SC34-6399
v Unified Messaging: Voice Interface, GC34-6401
v Unified Messaging: Web Services Voicemail API, SC34-6975
Unified Messaging publications can be found by going to the IBM Pervasive
software Web site at http://www.ibm.com/software/pervasive, selecting the
products link, and then selecting the library link from the Unified Messaging
page.
AIX and the IBM pSeries computer
v AIX: Installation Guide, SC23-4112
v AIX: Quick Beginnings, SC23-4114
v AIX: System User’s Guide; Operating System and Devices, SC23-4121
v AIX: System Management Guide; Operating System and Devices, SC23-4126
v AIX: System User’s Guide; Communications and Networks, SC23-4122
v AIX: System Management Guide; Communications and Networks, SC23-4127
v AIX: Topic Index and Glossary, SC23-2513
v RS/6000 and pSeries: Site and Hardware and Planning Information, SA38-0508
HACMP
v HACMP for AIX: Concepts and Facilities, SC23-4864
v HACMP for AIX: Planning Guide, SC23-4277
v HACMP for AIX: Planning and Installation Guide, SC23-4861
v HACMP for AIX: HACMP 5.3 Administration Guide, SC23-4862
v HACMP for AIX: HACMP 5.3 Smart Assist for DB2, SC23-5179
v HACMP for AIX: Enhanced Scalability Installation and Administration Guide,
SC23-4279
SS7
v SS7 Support for WebSphere Voice Response: SS7 User’s Guide, GC34-6613
IBM SS7 Support for WebSphere Voice Response observes the applicable parts
of the following specifications for ISUP:
v CCITT Blue book (1988) Q.701 - Q.707
List of WebSphere Voice Response and associated documentation 367
v ITU-T (formerly CCITT) Recommendations Q.700 - Q.716, Volume VI Fascicle
VI.7
v CCITT Blue book (1988) Q.711 - Q.714
v ITU-T White book (1993) Q.711 - Q.714
v CCITT Blue book (1988) Q.721 - Q.724
v ITU-T (formerly CCITT) Recommendations Q.721 - Q.725, Volume VI Fascicle
VI.8
v ITU-T White book (1992) Q.730 group
v CCITT Blue book (1988) Q.761 - Q.764
v ITU-T White book (1992) Q.761 - Q.764
v CCITT Blue book (1988) Q.771 - Q.775
v ITU-T (formerly CCITT) Recommendations Q.771 - Q.775, Q.791, Volume VI
Fascicle VI.9
ADC
v ADC NewNet AccessMANAGER™: Installation and Maintenance
Manual
v ADC NewNet AccessMANAGER™: User Manual
Integrated Services Digital Network
WebSphere Voice Response ISDN support observes the applicable parts of the
following standards for User Side protocol:
Custom ISDN Standards:
v Northern Telecom DMS/250 Primary Rate Interface NIS A211-4 Release
8, July 1995. (IEC05 level)
v Northern Telecom DMS/100 Primary Rate Interface NIS A211-1 Release
7.05, May 1998. (NA007 & RLT)
v AT&T 5ESS Switch. ISDN Primary Rate Interface Specification. 5E7 and
5E8 Software Release AT&T 235-900-332. Issue 2.00 December 1991
v AT&T 5ESS Switch. ISDN Primary Rate Interface Specification. 5E9
Software Release AT&T 235-900-342. Issue 1.00 November 1993
(National ISDN only)
v Lucent 5ESS-2000 Switch ISDN Primary Rate Interface, Interface
Specification, 5E9(2) and Later Software Releases, 235-900-342. Issue
5.00 January 1997 (National ISDN only)
v AT&T ISDN Primary Rate Specification TR41449 July 1989
v AT&T ISDN Primary Rate Specification TR41459 August 1996
Euro-ISDN
The following documents refer to the specifications required for
observing ISDN:
v TBR4-ISDN; Attachment Requirements For Terminal Equipment To
Connect To An ISDN Using ISDN Primary Rate Access, Edition 1, Nov.
95, English
368 Designing and Managing State Table Applications
v CTR 4 - European Communities Commission Decision 94/796/EC
published in the Official Journal of the European Communities L
329, 20 December 94 (ISDN PRA)
National ISDN
National ISDN is described in the following publications:
v National ISDN, SR-NWT-002006, Issue 1, August 1991, published by
Bellcore
v National ISDN-1, SR-NWT-001937, Issue 1, February 1991, published
by Bellcore
v National ISDN-2, SR-NWT-002120, Issue 1, May 1992, published by
Bellcore
INS Net Service 1500
INS Net Service is described in the following publications:
v Interface for the INS Net Service Volume 1 (Outline), 7th Edition,
published by Nippon Telegraph and Telephone Corporation
v Interface for the INS Net Service Volume 2 (Layer 1 & 2 Specifications),
4th Edition, published by Nippon Telegraph and Telephone
Corporation
v Interface for the INS Net Service Volume 3 (Layer 3 Circuit Switching),
5th Edition, published by Nippon Telegraph and Telephone
Corporation
Bellcore Specifications for ADSI Telephones
The following Bellcore specification documents contain technical details of the
requirements for ADSI telephones, and the interface to voice response systems
such as WebSphere Voice Response:
v SR-INS-002461: CustomerPremises Equipment Compatibility Considerations for
the Analog Display Services Interface
v TR-NWT-001273: Generic Requirements for an SPCS to Customer Premises
Equipment Data Interface for Analog Display Services
List of WebSphere Voice Response and associated documentation 369
370 Designing and Managing State Table Applications
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
© Copyright IBM Corp. 1991, 2008 371
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
subscriber classes 183
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
sample application 128
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
372 Designing and Managing State Table Applications
Default application (continued)purpose 32, 53
default promptoverview 113
definingmailboxes 168
prompts 113
subscriber classes 168
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
with speech recognition 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
voice application 38
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
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
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
voice application 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_C5 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
374 Designing and Managing State Table Applications
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_C10 state table 250
ISDN_Xfer_C5 state table 250
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
specifying in an application profile 92
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
sample application 158
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
sample application 157
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
voice application 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
376 Designing and Managing State Table Applications
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
specifying in an application profile 91
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
specifying in an application profile 92
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
sample application 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
378 Designing and Managing State Table Applications
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
with speech recognition 123
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
380 Designing and Managing State Table Applications
����
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