designing and managing state table applications...websphere voice response software . . . 387 ibm...

WebSphere Voice Response for AIX with DirectTalkTechnology

Designing and Managing State TableApplications

Version 6.1

SC34-7081-02

��

Note

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

This edition applies to Version 6, Release 1 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 neweditions. Make sure you are using the correct edition for the level of the product.

© Copyright IBM Corporation 1991, 2012.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

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

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

About this information. . . . . . . . xiiiWho should use this information. . . . . xiiiHow to use this information . . . . . . xiiiFollowing the procedures in this book . . . xivTypographic conventions . . . . . . . xivAccessibility . . . . . . . . . . . . xvNotes on terminology. . . . . . . . . xvWhere to find more information . . . . . xvi

Useful Web sites . . . . . . . . . xviMaking comments on this book . . . . . xvi

Part 1. The life cycle of a voiceresponse service. . . . . . . . . 1

Chapter 1. Introduction . . . . . . . . 3Requirements and Planning . . . . . . . 3

Business requirements . . . . . . . . 4Telephony requirements . . . . . . . 4User requirements . . . . . . . . . 4Data requirements . . . . . . . . . 5Programming requirements . . . . . . 5IBM solutions . . . . . . . . . . . 5Suggestions . . . . . . . . . . . 5

Design . . . . . . . . . . . . . . 6High-level and low-level design. . . . . 6Design considerations . . . . . . . . 6Suggestions . . . . . . . . . . . 7

Implementation . . . . . . . . . . . 8What does implementation involve? . . . 9System parameters . . . . . . . . . 9Testing the voice response service . . . . 10Migrating application objects . . . . . 10Using an external code repository . . . . 10Suggestions . . . . . . . . . . . 11

Packaging and distribution . . . . . . . 11Distributing an application to otherWebSphere Voice Response systems . . . 12Suggestions . . . . . . . . . . . 12

Maintenance and support . . . . . . . 13Housekeeping . . . . . . . . . . 13

Archiving application objects . . . . . 13Distributing updates . . . . . . . . 13Suggestions . . . . . . . . . . . 14

Chapter 2. Designing a voice application 15User participation in dialog design . . . . 18Designing the dialog . . . . . . . . . 19Good things to do in voice applications . . . 23Wording prompts for speech recognitionapplications . . . . . . . . . . . . 24Defining server requirements . . . . . . 26

Chapter 3. Creating and managingapplication objects . . . . . . . . . 27What are application objects? . . . . . . 28Managing application objects efficiently . . . 29Using the applications and applicationwindows . . . . . . . . . . . . . 30Discovering what applications and objects arein the system. . . . . . . . . . . . 30Editing and testing application objects . . . 33Creating an application . . . . . . . . 34Exporting an application . . . . . . . . 38Exporting one or more objects . . . . . . 44Importing application objects . . . . . . 46Migrating from an earlier release of IBMWebSphere Voice Response for AIX . . . . 50Frequently asked questions . . . . . . . 51

Do you have to create applications? . . . 51What about the integrity of applicationsthat are already in use? . . . . . . . 51Where are newly-created or migratedobjects put? . . . . . . . . . . . 51What happens when you import objectsbelonging to an application that does notexist on the target system? . . . . . . 52When should you use full export, deltaexport, and partial export? . . . . . . 52When should you export prerequisitesalong with an application? . . . . . . 53What happens to “duplicate” objects? . . 53What if more than one application needsto use the same object? . . . . . . . 53

Moving objects from the default or userapplications . . . . . . . . . . . . 54

© Copyright IBM Corp. 1991, 2012 iii

Deleting an application . . . . . . . . 55The dtimport and dtexport commands . . . 55

dtexport command. . . . . . . . . 56dtimport command . . . . . . . . 59

Chapter 4. Overview of application objects 61State tables . . . . . . . . . . . . 61

State table actions . . . . . . . . . 61Example state table . . . . . . . . 68State table variables and parameters . . . 70Returning data to the state table . . . . 73Possible results . . . . . . . . . . 73Entry points . . . . . . . . . . . 74

Prompts . . . . . . . . . . . . . 74System prompts. . . . . . . . . . 75System prompts in languages other thanU.S. English . . . . . . . . . . . 77System prompts in French . . . . . . 78System prompts in Brazilian Portuguese 80Changing the system prompts for yourlanguage . . . . . . . . . . . . 80

Voice segments . . . . . . . . . . . 82Voice directories . . . . . . . . . 82Voice tables . . . . . . . . . . . 83System voice segments . . . . . . . 83System voice tables . . . . . . . . 83

3270 and custom servers . . . . . . . . 853270 servers . . . . . . . . . . . 86Custom servers . . . . . . . . . . 87

Further information . . . . . . . . . 88

Chapter 5. Creating an application profile 89Introduction . . . . . . . . . . . . 89How to create an application profile . . . . 90

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

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

Chapter 6. Creating the voice output forvoice applications . . . . . . . . . 101Overview of voice signal processing . . . 101Planning your voice segments . . . . . 103

Compression . . . . . . . . . . 105Recording voice segments over thetelephone . . . . . . . . . . . 106High-quality voice data . . . . . . . 106Transferring the prerecorded data toWebSphere Voice Response . . . . . 109

Converting voice data transferred fromnon-AIX computer systems . . . . . 110Saving voice segments . . . . . . . 111The batch voice import utilities or theVoice Segments window? . . . . . . 112

The voice segment database . . . . . . 112Creating prompts . . . . . . . . . . 113

About creating prompt directories . . . 113About defining prompts . . . . . . 113Default and language-specific prompts 114Using languages other than U.S. English 115Modifying the system voice tables . . . 116Editing the system prompts . . . . . 117

Creating multilingual applications . . . . 117Using application profiles . . . . . . 117Using the System: Current languagesystem variable . . . . . . . . . 118

Chapter 7. Handling key input fromcallers . . . . . . . . . . . . . 119Making a selection (single key) . . . . . 119Entering data (multiple keys) . . . . . . 119Pressing keys while voice data is beingplayed . . . . . . . . . . . . . 120

Chapter 8. Handling spoken input fromcallers . . . . . . . . . . . . . 121Speech recognition with distributed voicetechnologies . . . . . . . . . . . 121Barge-in, voice interrupt detection, and echocancellation . . . . . . . . . . . . 121

Barge-in . . . . . . . . . . . . 121Voice interrupt detection . . . . . . 122Echo cancellation . . . . . . . . . 123

Writing a custom server to handle speechrecognition . . . . . . . . . . . . 125

Chapter 9. Accessing data with a 3270 orcustom server . . . . . . . . . . 127Sample 3270 and custom servers . . . . . 128

CustomServerSample . . . . . . . 1283270ServerSample. . . . . . . . . 129

Chapter 10. Telephony activity . . . . . 133Handling switch and protocol limitations 133

Handling switch tones . . . . . . . 133Accounting for protocol limitations . . . 133

Answering calls . . . . . . . . . . 135How does WebSphere Voice Responseanswer an incoming call? . . . . . . 136

iv Designing and Managing State Table Applications

Making, transferring, reconnecting, andterminating calls . . . . . . . . . . 142

Call transfer . . . . . . . . . . 142State table actions . . . . . . . . . 143System parameters . . . . . . . . 143

Coordinated call and data transfer . . . . 144What does the state table have to do? . . 144What format must the data be in? . . . 145How much data can you pass? . . . . 145Examples . . . . . . . . . . . 146

Setting the MessageWaiting Indicator usingCallPath Server . . . . . . . . . . 147

Chapter 11. Designing voice messagingapplications . . . . . . . . . . . 149Voice messaging resources . . . . . . . 149Using state table actions for voice messaging 151Interacting with callers and messages . . . 153System parameters that affect voicemessaging . . . . . . . . . . . . 157A sample voice message application . . . 157

Chapter 12. Managing voice messagingresources . . . . . . . . . . . . 167Voice mailboxes . . . . . . . . . . 167

How do I create a mailbox? . . . . . 167How is mailbox information used? . . . 168

Controlling messages . . . . . . . . 168Limiting message length . . . . . . 169Limiting the number of messages . . . 169What are subscriber classes? . . . . . 169How do subscriber classes work? . . . 169When should you define subscriberclasses? . . . . . . . . . . . . 170

Creating mailboxes for application use . . . 170Before you start . . . . . . . . . 170Using the graphical interface . . . . . 170Using the wvrapplprof and wvrmailboxcommands . . . . . . . . . . . 177wvrmailbox command . . . . . . . 177

Creating a subscriber class . . . . . . . 185Creating a distribution list . . . . . . . 187

Chapter 13. Telecommunications Devicesfor the Deaf . . . . . . . . . . . 191Making voice applications available to TDDusers . . . . . . . . . . . . . . 191

Chapter 14. Background music . . . . 195Why use background music? . . . . . . 195

How many tunes can you play at once? . . 196When should you play background music? 197How loud is the background music? . . . 198T1 A-law systems . . . . . . . . . . 198Voice interrupt detection and speechrecognition . . . . . . . . . . . . 198Using the WebSphere Voice Response JukeBox . . . . . . . . . . . . . . 200

The Juke_Box custom server . . . . . 200Starting and stopping the Juke_Boxcustom server . . . . . . . . . . 200The Juke Box configuration file . . . . 200

Adding background music to a state table 202Prerequisites . . . . . . . . . . 202Debugging your state table . . . . . 205

Getting music into WebSphere VoiceResponse . . . . . . . . . . . . 206

Supplied tunes . . . . . . . . . . 206

Chapter 15. TDM connection management 209Concepts. . . . . . . . . . . . . 209

Ports . . . . . . . . . . . . . 209Port sets . . . . . . . . . . . . 209Resource groups . . . . . . . . . 210

Port set naming . . . . . . . . . . 211The TDM sample application . . . . . . 211

Prerequisites . . . . . . . . . . 212Designing an application . . . . . . . 213

State tables . . . . . . . . . . . 213Custom servers . . . . . . . . . 213The design of the sample application . . 214Implementation notes . . . . . . . 217

Chapter 16. Designing for a single systemimage . . . . . . . . . . . . . 223Querying the single system imageconfiguration . . . . . . . . . . . 223

Chapter 17. Using ISDN call transfer . . 225When can I use ISDN Two B-channeltransfer? . . . . . . . . . . . . . 226When can I use ISDN RLT call transfer? . . 226When can I use ISDN single step calltransfer? . . . . . . . . . . . . . 227What the ISDN call transfer application does 227

Limitations of ISDN call transfer . . . . 228Installing the application . . . . . . 228Configuring the ISDN_Call_Transfercustom server . . . . . . . . . . 231How to use ISDN call transfer . . . . 233

Contents v

Custom server functions . . . . . . 245State table definitions . . . . . . . 249

What the ISDN single step call transferapplication does . . . . . . . . . . 258

Limitations of ISDN single step calltransfer . . . . . . . . . . . . 259Installing the application . . . . . . 259Configuring the SSTransfer custom server 261How to use ISDN single step call transfer 262Custom server functions . . . . . . 263State table definitions . . . . . . . 269

Chapter 18. Using theIBM_Trombone_Custom_Server . . . . 273What is a trombone (in telephony terms)? 273

What you can use a trombone for . . . 274Installing the IBM_Trombone application . . 275

Components of the IBM_Tromboneapplication . . . . . . . . . . . 275Installing the IBM_Trombone application 276

Configuring IBM_Trombone_Custom_Server 277About child helper processes . . . . . 278Setting configuration options . . . . . 279

How to use the trombone operation. . . . 280How tromboning works . . . . . . 281Setting up a trombone operation . . . . 282Terminating a trombone operation usingthird party hang-up . . . . . . . . 283Terminating a trombone operation usingcaller hang-up . . . . . . . . . . 283Terminating a trombone operation usingcaller DTMF . . . . . . . . . . 284Voice paths . . . . . . . . . . . 285

Custom server functions . . . . . . . 286Custom server function definitions . . . 286TromboneCall . . . . . . . . . . 286TromboneMakeCall . . . . . . . . 289TromboneMakeCallStatus . . . . . . 292TromboneConnectCall . . . . . . . 293TromboneTerminationValue . . . . . 295TromboneDisconnectCall . . . . . . 295

State table definitions . . . . . . . . 296IBMTromboneCall. . . . . . . . . 297IBMTromboneConn . . . . . . . . 304IBMTromboneC5 . . . . . . . . . 305IBMTromboneC10. . . . . . . . . 306IBMTromboneDisc . . . . . . . . 307IBMTromboneLog. . . . . . . . . 308IBMTromboneMake . . . . . . . . 309IBMTromboneMus . . . . . . . . 312

IBMTromboneOut. . . . . . . . . 312IBMTromboneRdy . . . . . . . . 314IBMTromboneWait . . . . . . . . 316IBMTromboneXmp . . . . . . . . 318IBMTromboneXmpA . . . . . . . . 318IBMTromboneXmpB . . . . . . . . 319

IBM_Trombone_Custom_Server errors . . . 320

Chapter 19. Using the VOX_CTI CustomServer . . . . . . . . . . . . . 321Avaya Interaction Center VOX Connector forWebSphere Voice Response . . . . . . 321Installation . . . . . . . . . . . . 321VOX_CTI.ini file configuration . . . . . 321VOX_CTI Custom Server functions . . . . 323VOX_CTI function return codes . . . . . 329General guidelines . . . . . . . . . 330

Part 3. Appendixes . . . . . . . 331

Appendix A. ID and name limitations . . 333

Appendix B. Voice interrupt detection:technical information . . . . . . . . 337Example of how voice interrupt detectionworks. . . . . . . . . . . . . . 339Summary . . . . . . . . . . . . 340

Appendix C. Background music: technicalinformation . . . . . . . . . . . 341Sound levels . . . . . . . . . . . 341

The music volume ceiling and the promptvolume ceiling . . . . . . . . . . 342

Customizing the Juke Box . . . . . . . 344Source code files for the Juke Box . . . 344Collecting statistics from the Juke_Boxcustom server . . . . . . . . . . 345Building music players . . . . . . . 346Juke_Box custom server communicationwith pl_elem and pl_seg . . . . . . 346Message queue . . . . . . . . . 347

Writing your own background musicsubsystem . . . . . . . . . . . . 348

Notices . . . . . . . . . . . . . 349Trademarks . . . . . . . . . . . . 351

Glossary . . . . . . . . . . . . 353

vi Designing and Managing State Table Applications

List of WebSphere Voice Response andassociated documentation . . . . . . 387WebSphere Voice Response software . . . 387IBM hardware for use with WebSphere VoiceResponse . . . . . . . . . . . . 388WebSphere Voice Response related products 388

WebSphere Voice Server. . . . . . . 388Unified Messaging for WebSphere VoiceResponse . . . . . . . . . . . 388

AIX and the IBM pSeries computer . . . 389HACMP . . . . . . . . . . . . 389SS7 . . . . . . . . . . . . . 389Integrated Services Digital Network. . . 390

Bellcore Specifications for ADSI Telephones 391

Index . . . . . . . . . . . . . 393

Contents vii

viii Designing and Managing State Table Applications

Figures

1. The life cycle of a voice response service 32. Example of main activities to be

performed by a voice application. . . . 163. Voice application objects . . . . . . 284. The Application window . . . . . . 315. Two applications, one of which contains

commonly-used objects . . . . . . 546. System variables. . . . . . . . . 717. A list of parameters to be passed to a

prompt . . . . . . . . . . . . 738. Barge-in . . . . . . . . . . . 1229. Voice interrupt detection . . . . . 122

10. Voice interrupt detection with speechrecognition . . . . . . . . . . 123

11. Calibrating the echo canceller . . . . 12512. External speech recognition overview 12613. Accessing data using custom servers

and 3270 servers (for example, asystem/390 server) . . . . . . . 127

14. How WebSphere Voice Response findsthe state table to handle an incomingcall . . . . . . . . . . . . . 137

15. Application profile needed with onestate table for all . . . . . . . . 141

16. Application profiles needed whenusing called number . . . . . . . 141

17. Application profiles needed whenusing channel identification . . . . 142

18. CallPath Server and WebSphere VoiceResponse installed in the same pSeriescomputer . . . . . . . . . . . 144

19. Receiving a call and data transferredby CallPath Server. . . . . . . . 146

20. Transferring a call and data to anothernumber using CallPath Server . . . . 147

21. Using CallPath Server to set themessage waiting indication . . . . . 148

22. VoiceMsgMenu and VoiceMsgAnswer 15923. VoiceMsgRecord and VoiceMsgListen 16024. VoiceMsgOptions . . . . . . . . 16125. Example listing of the first two states

in a state table . . . . . . . . . 16226. Two people communicating using TDD 19127. How WebSphere Voice Response

interacts with a TDD . . . . . . . 192

28. Using background music . . . . . 19629. What the caller hears at each stage in

the interaction . . . . . . . . . 19930. Example of a configuration file for the

Juke_Box custom server . . . . . . 20131. Schematic overview of part of a state

table using background music . . . 20532. Getting tunes into WebSphere Voice

Response for background music . . . 20833. Ports, port sets, sources, and sinks 21034. Making and breaking a trombone

connection . . . . . . . . . . 21635. The TromboneCS state machine 21736. Voice paths in a trombone connection 22037. Voice paths when the switch is in TDM

position . . . . . . . . . . . 22138. Voice paths when the switch is in host

position . . . . . . . . . . . 22139. Event flow for a blind (immediate)

transfer . . . . . . . . . . . 23440. Event flow for a screened transfer with

call answer supervision (for asuccessful call) . . . . . . . . . 236

41. Event flow for a screened transfer withcall answer supervision (for anunsuccessful call) . . . . . . . . 238

42. Event flow for a screened transfer withthird party consultation (ending in atransfer) . . . . . . . . . . . 240

43. Event flow for a screened transfer withthird party consultation (ending upreconnecting to the original caller) . . 243

44. Voice path between caller and thirdparty during a trombone operation . . 274

45. High-level flow chart for theIBMTromboneXmp state table . . . . 281

46. Event flow required to set up atrombone operation. . . . . . . . 282

47. Event flow required to terminate atrombone operation when the thirdparty hangs up . . . . . . . . . 283

48. Event flow required to terminate atrombone operation when the callerhangs up . . . . . . . . . . . 284

© Copyright IBM Corp. 1991, 2012 ix

49. Event flow required to terminate atrombone operation when the callerrequests this by dialing a DTMFsequence . . . . . . . . . . . 285

50. WebSphere Voice Response detects avoice interrupt . . . . . . . . . 338

51. How voice interrupt detectionparameters act on a voice sample. . . 339

52. Musical welcome state table: volumelevels . . . . . . . . . . . . 343

53. Playing prompts and tunes at the samevolume . . . . . . . . . . . 344

x Designing and Managing State Table Applications

Tables

1. Example dialog segments. . . . . . 162. Where To find newly-created objects 523. Example state table . . . . . . . . 684. Creating voice segments for WebSphere

Voice Response . . . . . . . . . 1045. Responses for spot frequencies 1096. Application profile examples . . . . 1387. Mailbox field names used with

wvrmailbox command . . . . . . 1798. Applications simultaneously playing

tunes from music channels . . . . . 1979. Configuration options for the

ISDN_Call_Transfer custom server . . 23110. Configuration options for the

SSTransfer custom server . . . . . 26211. ISDN single step call transfer return

codes . . . . . . . . . . . . 26412. Configuration options for

IBM_Trombone_Custom_Server. . . . 27713. Return values for the

trombone_make_call_status parameterof the TromboneCall function . . . . 288

14. Return values for thetrombone_make_call_status parameterof the TromboneMakeCall function . . 292

15. Status values supplied by theTromboneMakeCallStatus function . . 293



18. Return values from theIBMTromboneCall state table(call_status) . . . . . . . . . . 300

19. System variables and parameters forvoice interrupt detection. . . . . . 337

20. System variables and parameters usedfor background music. . . . . . . 341

21. Music volume and prompt volumeceilings . . . . . . . . . . . 342

© Copyright IBM Corp. 1991, 2012 xi

xii Designing and Managing State Table Applications

About this information

This information tells you how to design voice applications to suit yourrequirements for voice response services, and then provides guidance forimplementing them with IBM® WebSphere® Voice Response for AIX® withDirectTalk® Technology.

This book also tells you how to put applications into production on one ormore WebSphere Voice Response systems, and keep your applications runningsmoothly.

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

Who should use this information

This book is for anyone involved in designing, implementing, or managing avoice response service with WebSphere Voice Response. Knowledge of howthe voice response service fits into your business would be valuable for allreaders.

Before starting to read this book, you should be familiar with the first fewchapters of the WebSphere Voice Response for AIX: General Information andPlanning book.

How to use this information

If you are commissioning a voice response service, you will find guidance onhow to specify and plan for it in Chapter 1, “Introduction,” on page 3 andChapter 2, “Designing a voice application,” on page 15.

If you are implementing an application, you should read this book to getbackground information, before using the reference and proceduralinformation in the WebSphere Voice Response for AIX: Application Developmentusing State Tables book, the WebSphere Voice Response for AIX: Custom Serversbook, or the WebSphere Voice Response for AIX: 3270 Servers book. This bookprovides specific guidance about implementing various types of applicationand including different voice processing functions in your applications,whereas the procedural information in the other book is more generic. Thebackground information in this book is organized by function, whereas thereference information in the other information is organized alphabetically.

© Copyright IBM Corp. 1991, 2012 xiii

If you are responsible for managing voice response services running inproduction, use the information in Chapter 3, “Creating and managingapplication objects,” on page 27, Chapter 5, “Creating an application profile,”on page 89, and Chapter 12, “Managing voice messaging resources,” on page167, as necessary.

This book contains background information and some procedural information,with step-by-step instructions. The procedures explain how to complete thetasks using the WebSphere Voice Response windows.

Following the procedures in this book

The procedures assume that you are already familiar with using a mouse andwindow environment and that you know how to use the common actionssuch as Save to work with information. If you are new to WebSphere VoiceResponse, have a look at the WebSphere Voice Response for AIX: User InterfaceGuide book, which tells you how to log on and log off, and use the WebSphereVoice Response windows efficiently.

Typographic conventions

This book uses the following typographic conventions:

boldfaceIdentifies an item that is in a WebSphere Voice Response window. Theitem might be a keyword, an action, a field label, or a pushbutton.Whenever one of the steps in a procedure includes a word inboldface, look in the window for an item that is labeled with thatword.

boldface italicsAre 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 itsdefinition.

v Parameters for which you supply the actual names or values.v References to other books.

monospaceIdentifies 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 exactlyas shown.

v Names of files and directories (path names).

xiv Designing and Managing State Table Applications

Accessibility

WebSphere Voice Response for AIX is a voice application enabler. Theapplications that are developed to run on WebSphere Voice Response providetelephone access to business data and services. In this way, WebSphere VoiceResponse provides accessibility for people who cannot access the data andservices by using regular Web pages or traditional graphic interfaces. Thesetelephone user interfaces are fully accessible to people who are blind or havelow vision and, if speech recognition is used, to people with mobilityimpairments or limited hand use. Speech recognition capability can beprovided by IBM WebSphere Voice Server, or other MRCP-V1.0-compliantspeech recognition products. In addition, support for users of TelephonyDevices for the Deaf (TDD) is provided as part of the WebSphere VoiceResponse product.

With WebSphere Voice Response you can perform many applicationdevelopment and system administration tasks with a text editor or linecommands—these are accessible if you use a screen reader product tointerface with them. Also, the default settings of the WebSphere VoiceResponse graphical user interface can be changed to produce large fonts andhigh contrast colors. Details of how to use these accessibility features can befound in the WebSphere Voice Response for AIX: User Interface Guide book.Alternatively, application development can be done with Java or VoiceXMLdevelopment tools that are supplied by IBM and third parties.

You can also use a screen-reader product to access the WebSphere VoiceResponse publications in HTML format (for details of their availability see“List of WebSphere Voice Response and associated documentation” on page387).

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® andpSeries ranges. (Consult your IBM representative for details of models thatare supported for use with WebSphere Voice Response.) RS/6000 computerswith an MCA bus are not supported.

v The IBM Quad Digital Trunk Telephony PCI Adapter is generally referred to inthis book by its abbreviation DTTA. This adapter is a replacement for theIBM ARTIC960RxD Quad Digital Trunk PCI Adapter, which is generallyreferred to by the abbreviation DTXA. The DTXA is not supported withWebSphere Voice Response Version 6.1.

About this information xv

v References made to the VoiceXML 2.1 specification are intended to includeVoiceXML 2.0 unless otherwise specified.

Where to find more information

The information provided in the WebSphere Voice Response library will helpyou complete WebSphere Voice Response tasks more quickly. A complete listof the available publications and where you can obtain them is shown in “Listof WebSphere Voice Response and associated documentation” on page 387.

Useful Web sites

The following Web sites are useful sources of information about WebSphereVoice Response and related products:

WebSphere Voice Responsehttp://www.ibm.com/software/pervasive/voice_response_aix/

IBM WebSphere developerWorks resources (including WebSphere Voiceproducts)

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

VoiceXML Version 2.0 and 2.1 specificationshttp://www.w3.org/TR/voicexml21/

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

CCXML Version 1.0 specificationhttp://www.w3.org/TR/2011/PR-ccxml-20110510/

GenesysFor more information on Genesys products go to the Genesys Website at http://www.genesyslab.com

Making comments on this book

If you especially like or dislike anything about this book, feel free to send usyour comments.

You can comment on what you regard as specific errors or omissions, and onthe accuracy, organization, subject matter, or completeness of this book. Pleaselimit your comments to the information that is in this book and to the way inwhich the information is presented. Speak to your IBM representative if youhave suggestions about the product itself.

When you send us comments, you grant to IBM a nonexclusive right to use ordistribute the information in any way it believes appropriate withoutincurring any obligation to you.

xvi Designing and Managing State Table Applications

http://www.ibm.com/software/pervasive/voice_response_aix/

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



http://www.w3.org/TR/2011/PR-ccxml-20110510/

http://www.genesyslab.com

You can get your comments to us quickly by sending an e-mail [email protected]. Alternatively, you can mail your comments to:

User Technologies,IBM United Kingdom Laboratories,Mail Point 095, Hursley Park,Winchester, Hampshire,SO21 2JN, United Kingdom

Please ensure that you include the book title, order number, and edition date.

About this information xvii

xviii Designing and Managing State Table Applications

Part 1. The life cycle of a voice response service

© Copyright IBM Corp. 1991, 2012 1

2 Designing and Managing State Table Applications

Chapter 1. Introduction

This chapter begins with an overview of the process of providing a voiceresponse service by means of a WebSphere Voice Response application, andthe components that comprise an application. Subsequent chapters elaborateon the steps in the process, introducing the components involved. These arefollowed by chapters that give more information about implementing specifictypes of service, using specific techniques and technologies.

The process is assumed to be top-down, though iterative (as shown inFigure 1), and throughout the book, the organizing principle is to start withthe high-level, broad view and progress through lower-level views to thedetails of individual elements.

Requirements and Planning

The WebSphere Voice Response for AIX: General Information and Planning bookdescribes the kind of services that WebSphere Voice Response can support,and the facilities it uses to support them. Use this information to guide you inthe planning phase.

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


A voice response service typically handles information requests fromtelephone callers.1

You design and develop voice applications to satisfy your businessrequirements: the voice application can make calls, answer calls, performcomputations, pass information from local or remote databases, communicateinformation to a caller by speaking it back over the telephone, let callers leaveand retrieve messages, transfer calls to other applications, connect callers to ahuman operator, and so on.

Business requirementsYou need to establish how the proposed service fits in with your business ororganization goals. What is the purpose of the service and is an automatedvoice response service the best way of achieving this? What are the benefits ofautomating the service to your organization and to the target population? Isan automated voice response service likely to be accepted by the targetpopulation and generate business or cut costs?

Telephony requirementsHow does the new service fit into existing services? Is it going to be asingle-purpose or multi-purpose service in its own right? Or is it just going tobe a new part of an existing service? Does the telephony equipment you usesupport this kind of service, or are you going to have to make changes there?

User requirementsWhat are the characteristics of the target population? What kind of output isgoing to be acceptable to them? What kind of input mode are they going toprefer? How big is the target population? How frequently are they likely touse the service? Is the service likely to be frequently used or rarely used?

1. Voice response services can also make outbound calls. However, throughout this book, the word “caller” refers tothe 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


Data requirementsWhat data is to be provided by the service, where is it stored (currently or inthe 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 touse other software or write new programs to access data if necessary?

Programming requirementsWho is going to implement the components of the voice response service? Isthe department who understands the business and the callers going todevelop the application themselves? Or do you have professionalprogrammers or a service bureau that you can call upon? Even if you useprofessional programmers or a service bureau, the business departments andthe callers themselves should be involved too. Conversely, even if the businessdepartments are comfortable with implementing small and medium-scalesystems, it may be advisable to involve system integrators if you are scalingup to something large.

IBM solutionsCan your requirements be satisfied by an IBM solution? For example, beforestarting to develop your own voice mail system, consider the advantages ofbuying IBM’s Unified Messaging program offering. This is very much easierthan writing your own system: Unified Messaging comes with additionalsystem administration utilities and, if it does not fit your requirements exactly,you can tailor just about every aspect of it. For more information, see yourIBM representative.

SuggestionsUse existing services as a model

Start planning an application by surveying the requests for information thatyour company currently receives. Repetitive requests that are time-consumingfor your personnel to satisfy are good candidates for voice applications.

Start small

Begin by serving your most important customers, or set up an application toservice a pilot group. Provide a feedback mechanism to measure how thesystem is meeting your customers’ and employees’ needs. Encouragecomplaints.

Prioritize your applications

Don’t expect the system to solve every problem from the first day. It’simportant to set fairly easy and reasonable objectives which can be metduring the initial phase of use, and then move on to more sophisticated

Chapter 1. Introduction 5

applications as your staff and customers become better acquainted with thesystem.

Design

High-level design consists of analyzing your requirements, both businessgoals and caller needs, decomposing the functions of the service, anddetermining what application components are required to perform eachfunction. Low-level design then involves examining how WebSphere VoiceResponse facilities and the facilities of other hardware and software (such asthe telephone switch and database access) are to be used to accomplish thegoals of each component. You need to prototype and document, visually, ateach stage in the design process.

High-level and low-level design

Design considerationsIn designing the voice response service, you need to consider telephonyactivities 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 dataintegrity implications?

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

speech or a mixture of the two?v How will the application handle situations such as the caller hanging up in

mid-transaction or the database link failing?


andtest

Maintainand

support

Packageand

distribute


For more information, see Chapter 2, “Designing a voice application,” on page15. To design your application, you need to understand the facilities andprogramming interfaces that will be used to implement it, as well as therequirements for it, so you’ll also need to read the appropriate chapters onimplementation before you start designing your own applications to run withWebSphere Voice Response.

SuggestionsFlowchart applications

Draw step-by-step flowcharts of specific applications both before and after thesystem is installed. This will help you to catch duplications or redundancies inprocedure that existed in the past and that might occur again in newapplications. Are there paper documents that need to be maintained? Arethere ways to simplify your business operations before or during yourconversion 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 willsurely confuse them. Offer callers just what they need in order to get to theinformation they want. If there are many options, and you want to make themall available, create a series of branched prompts that break the options intosmall 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 tooverride 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 allowfor 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 orplay a prompt that tells the caller to call back and start again.

Develop design documentation

Applications should be clearly documented. Provide the name of theapplication, its purpose and benefits, how to access the system for theapplication, and the specific steps involved. Include the commands to beentered via the telephone keypad, the specific actions or results of eachcommand, what to do in case something goes wrong, and the correct way tosign off the system.


Develop a draft set of voice segments

Don’t have your voice segments recorded professionally right at thebeginning: record them yourself to begin with, because they are sure tochange before the voice response service is put into production, and you don’twant 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 debuggingstatements by setting variables at the beginning of the state table, or you caninclude parameters in a command file that is read by a custom server.

Implementation

To implement your design, you need to understand how to create andmanage 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 27v Chapter 4, “Overview of application objects,” on page 61v 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 101v Chapter 7, “Handling key input from callers,” on page 119v Chapter 8, “Handling spoken input from callers,” on page 121v Chapter 9, “Accessing data with a 3270 or custom server,” on page 127v Chapter 10, “Telephony activity,” on page 133v Chapter 11, “Designing voice messaging applications,” on page 149


andtest

Maintainand

support

Packageand

distribute


v Chapter 12, “Managing voice messaging resources,” on page 167v Chapter 13, “Telecommunications Devices for the Deaf,” on page 191v Chapter 14, “Background music,” on page 195v Chapter 15, “TDM connection management,” on page 209

What does implementation involve?Implementation of a voice response service involves:v Recording voice segmentsv Designing and building promptsv Designing and building state tablesv Designing and building 3270 server scriptsv Designing, coding, and building custom server programsv Testing and debugging components separately and together

We cannot stress too much that testing is vital to the success of your voiceresponse service. Not only functional testing, but also getting users involvedin early trials, and evaluating their experiences. Early user involvement indesign should ensure that you don’t find reach the beta-test stage beforefinding too many usability problems that are costly to fix, but you should alsoensure 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 responseservice into production. You may think of the following tasks as belonging toimplementation, as you will certainly need some resources with which to test.However, you should consider these to be administration tasks that belong tothe packaging and distribution or maintenance and support phases:v Creating application definitionsv Exporting application packagesv Importing application packagesv Creating application profilesv Defining mailboxes, distribution lists, and subscriber classesv Ensuring that system parameters are appropriately defined

System parametersAmong the many parameters that control the way the WebSphere VoiceResponse system works are two groups of particular importance toapplications:v Application Server Interface parameter groupv General parameter group

See the WebSphere Voice Response for AIX: Configuring the System book fordetails of each parameter in these groups.


Testing the voice response serviceTest phases

Testing should be performed in distinct phases, in which you are checking fordifferent kinds of problem:1. Logical or unit test, to test the basic logical flow2. Functional test, to test the interaction with the caller3. 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 anAnswerCall state in the state table. When using the debugger, this isconverted into a MakeCall. Using the debugger, you can step through theactions, modifying the values of variables to test different paths through thestate table.

It’s useful if a voice application can output its own trace data, using theLogEvent action or a custom server. You should design this so that tracing canbe switched on or off when the application is in production.

Migrating application objectsIf you are migrating to WebSphere Voice Response Version 6.1 fromWebSphere Voice Response Version 4.2, use the restoreDT utility to bring yourapplication objects and data into the new system (refer to the WebSphere VoiceResponse for AIX: Installation book for more information on using restoreDT).When you do this, all your application objects are placed in the Defaultapplication. You can either leave them there or, if you want to manageapplication objects efficiently (see “Managing application objects efficiently”on page 29), you can create your own applications (see “Creating anapplication” on page 34) and move objects into them from the Defaultapplication.

If you export applications from IBM WebSphere Voice Response for AIX, youneed to import them (see “Importing application objects” on page 46).

Using an external code repositoryIf you develop applications using a text editor, and store them in a coderepository 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 VoiceResponse with a user-specified version ID, which makes synchronization with


external code control systems possible. Optionally, you can make the importedobject read-only, which prevents it from being modified and saved using theWebSphere Voice Response windows. The read-only property (if set) isdisplayed in the object’s container window.

SuggestionsModularity

For maintainability, you are recommended to implement applications asmultiple state tables rather than one large state table.

Encapsulation

Consider implementing some parts of the application as common state tablesthat 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 handleincoming 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 yourapplication into production (see Chapter 12, “Managing voice messagingresources,” on page 167).

Packaging involves creating an application definition, which specifies whichcomponents are required to run the voice response service. If you have only


andtest

Maintainand

support

Packageand

distribute


one WebSphere Voice Response system, you don’t need to package yourapplications, although creating an application definition can help you keep thecomponents organized.

To distribute the components of an application, you then use the applicationdefinition to create a package: this is known as exporting. You then send thepackage you created using the application definition to whichever systems aregoing to run it. The package is simply a file that you can send using anysuitable file transfer method to another pSeries computer. After transferringthe package, you import it into the WebSphere Voice Response system on theother pSeries computer and install its contents: the original applicationcomponents.

Distributing an application to other WebSphere Voice Response systemsYou may develop the components of a voice application on a system reservedfor development, or you may want to run the same voice response service onmultiple systems. In either case, you need to be able to transport applicationobjects from one system to another. To do this, you export the applicationfrom WebSphere Voice Response. This creates a single AIX file that you cantransport to another system. The file must then be imported into WebSphereVoice Response. See “Exporting an application” on page 38 and “Importingapplication objects” on page 46.

SuggestionsSpread the word

Send a memo around your site announcing the planned installation date of anew voice application and describe clearly how the system works and whatthe benefits are to the staff. Conduct a promotional campaign for yourcustomers explaining your new service and educate them in the use of thesystem by flowcharting the application for them. Also select a staff personwho 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 thesystem administrator is to configure the system as required by your voiceapplications, establish the data interface between the system and your hostcomputer, set up controls and authorizations, monitor system performance,and take whatever action is necessary to manage and keep the system up andrunning.


Maintenance and support

Once the application is in production, new requirements may arise, orproblems occur. These can result in a re-iteration of any of the precedingsteps. Requirements for important new function will cause you to go back tothe requirements phase. Major usability issues may return you to therequirements or the design phase. Performance problems may return you todesign or implementation, as will failure to handle every situation that arisesor provide correct output.

HousekeepingSome application objects, such as voice segments, take up a lot of storage, soyou need to attend to the housekeeping regularly. Before deleting an objectyou think might no longer be used, check its dependencies, to make sure thatno other object uses it. See What is a dependency? for more information.

Archiving application objectsTo archive the application objects necessary for a voice response service, youexport the application from WebSphere Voice Response. This creates a singleAIX file that you can store on disk, tape, or other media. When theapplication is required again, the file can be imported into WebSphere VoiceResponse. See “Exporting an application” on page 38 and “Importingapplication objects” on page 46.

Distributing updatesUpdates to some of the objects in the application can easily be distributedusing delta export: exporting only those objects that have changed since the lastfull export, delta export, or since a specified date. See “Exporting anapplication” on page 38.


andtest

Maintainand

support

Packageand

distribute


SuggestionsConduct system user surveys

Gather feedback both before and after system installation. This will help youto diffuse any fears or misunderstandings and to compare expected and actualreactions to the system.


Chapter 2. Designing a voice application

When you understand the requirements for the voice response service, thebusiness goals and callers’ needs, you can begin designing your application.You may not yet know which WebSphere Voice Response facilities and othersoftware and hardware you will use to implement it. Part of the designprocess will be to decide on the implementation of the high-level activities.

This process will be iterative, as you create prototypes and learn more aboutboth requirements and ways of implementation. Always involve users, bothcallers and the departments commissioning the voice response service, in thedesign process. However, there will be work you need to do without them.


1. Before the first meeting with users, identify the main activities to beperformed by the application. An example is shown in Figure 2.

2. Together with users, design the dialog for each activity, concentrating oneverything 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 respondwith.

Table 1. Example dialog segments

ID Words

1 Thank you for calling the WebSphere Voice Response Automated AccountInquiry Service.

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.


Table 1. Example dialog segments (continued)

ID Words

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 on page 16 shows examples of punctuation conventions that youcan use in the text versions of voice segments:An initial capital letter at the beginning of a voice segment indicates thebeginning of a prompt.Ellipsis (...) at the beginning of a voice segment indicates the continuationof a prompt.Ellipsis (...) at the end of a voice segment indicates that further voicesegments 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 speechthroughout the call, keys for some parts and speech for others, or whetheryou are going to restrict the caller to either keys or speech. You maydecide on two versions of the service: one for callers who have pushbuttonphones, and one for callers with rotary phones, who have to use speech.

4. As your dialog design progresses, make sure you document each of thebranches of the application. You can use the WebSphere Voice ResponseState Tables window to create a graphical representation of the state table,filling in the details later.

Chapter 2. Designing a voice application 17

5. Before the next meeting, identify all the things that could go wrong: forexample, the caller could hang up in the middle of the call, the connectionwith a host computer could fail. Again, you can use the WebSphere VoiceResponse State Tables window, this time looking at the possible results forthe actions and filling in the details.

6. Again, with users, refine the dialog, taking into consideration all the thingsyou have identified that could go wrong. The business departments willwant to be assured that the caller is going to hear the right thing whateverhappens. They do not want to lose business through a badly designedvoice application. If the voice application itself cannot continue, ideally, thecaller should be transferred to a human agent.

User participation in dialog design

The words used in the dialog must satisfy both the business goals (includingthe company or organization image) and be meaningful and unambiguous tocallers, so you need participation from business people and representativecallers.

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 ofsight (say behind a screen or curtain), and another person acting the part of acaller. This avoids the need to write prompts and state tables before you haverefined the design. Recording voice segments and writing code increases yourreluctance to make changes, so try the live Wizard-of-Oz prototypingtechnique first.

When you are fairly happy with the dialog design, record the voice segmentsusing the telephone, or synthesize them using text-to-speech. Recording overthe telephone is easily done with either of two sample programs suppliedwith WebSphere Voice Response. To test the dialog, you’ll need to writeprompts and a simple state table too. Start with company employees as thecallers, and, when you are happy with the dialog, try it on potentialcustomers or clients. If the service is aimed at company employees, start withexperienced employees, but don’t forget to try it out on newcomers.

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


Designing the dialog

Customer satisfaction with your voice response service will depend on anumber of factors, including the voice you choose, the information youprovide, 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 andfeel of a visual computer application. With careful design, the caller’sexperience will be pleasurable; with lack of attention to dialog design, thecaller will get frustrated and hang up. At best this will result in your peoplehandling just as many calls as they ever did; at worst it may mean loss ofbusiness.

You’re already considering a voice response service, so you’re aware of thestrengths of voice response: telephones are ubiquitous, familiar, andeasy-to-use and an automated system can provide more speed, privacy,efficiency, availability, and accuracy than some human operators, and at lowercost.

Nevertheless, when designing the dialog, you need to be aware of some of thelimitations of the medium. Compared with people, automated systems areinflexible, demanding, and intolerant of deviations from the expectedconversation. They are best at handling very routine calls. Almost withoutexception, all voice response services should offer help in some way, forexample by offering the choice of transferring to an operator (if call transfer isprovided by the switch) or calling another number to speak to an operator. Ifcall transfer is provided by the switch, the application can automaticallytransfer the caller to a human agent in some circumstances.

You should give human factors and usability a high priority when designingvoice response services, in addition to testing the usability of the serviceslater.

Design considerations

Compared with today’s multiwindowed screen-based computer applications,voice response applications have a number of potential limitations. Withcareful design, you can overcome the limitations and make your application adelight 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 aslittle time as possible: again, the prompts need to be worded carefully sothat they convey the greatest amount of information, unambiguously, andin the shortest amount of time.


v The very ubiquity and availability of telephones means that callers don’thave access to manuals and other supporting materials: the whole point isthat the voice response service can be used from anywhere, so theapplication itself must be completely self-documenting.

v Voice data takes up a lot of storage space (one second of voice occupies8000 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 inferiordevice 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 transmitdual-tone multifrequency (DTMF) tones. If the caller is able to transmitthese tones, keys are the most accurate and efficient method of input.

v Bear in mind that many callers may be using phones with an integralkeypad and handset: they will take longer to press the keys than callersusing traditional phones with a separate keypad.

v Compared with the 100 or so keys on a computer keyboard, the standardtelephone has twelve keys (WebSphere Voice Response supports up tosixteen: 0 through 9, *, #, A, B, C, and D).

v The standard keypad is fine for numeric input, making simple choices, andanswering yes-no questions, but what about alphabetic input? In somecountries, there are no alphabetic characters on the keys at all; even incountries where telephones still have the alphabetic characters on thenumber keys, people don’t use them enough to be familiar with theirpositions. (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 portablephones often suffer from noise interference; some equipment sends tones offixed duration or cannot send tones at all during a call. In these cases, theonly reasonable input device is voice, and for that, you require access tospeech recognition hardware or software.

Faced with all these challenges, you have a number of design decisions tomake. First you need to determine the right dialog style or styles and thenyou need to attend to the detail of each interaction, or task, within theapplication. If you design your application well, callers will prefer it to thehuman 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 anapplication, or for all callers:


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

v Callers may be familiar or unfamiliar with other voice response services.v Callers may use the service frequently (and therefore acquire expertise with

the mechanics, or the content, over time) or infrequently (never acquiringexpertise).

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, forexample, if callers are employee or students, but it is unreasonable to baseyour design on the assumption that documentation will be read or trainingsessions attended.

There is a far greater choice of dialog designs for voice response services thanyou might imagine. Some less common designs overcome the problemsencountered by callers in using traditional voice response services. Differentstyles of dialog may be appropriate in different parts of the service,depending on the task being performed: after all, these days one expects tosee pull-down menus, radio buttons, check boxes, and so on, used in visualapplications, so it’s not surprising that there might be a variety of techniquesyou can use in voice response dialogs.

There are three basic styles of voice response dialog, suited to different typesof 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 providerules for good dialog design, but you need to classify your application andyour 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 areunlikely to use the application often, give them composite actions thataccomplish the most with the fewest keystrokes. If callers are likely to usethe application often, however, they may want to combine actions indifferent ways.

2. Keys or speech recognition? The application is using speech tocommunicate with the caller, but should the caller be using speech orkeys? Remember it takes longer to speak a command and have it


recognized than it does to press a key. Also, people are better at pressingkeys accurately than speaking clearly enough to be recognized accurately.

3. A mixture of key and speech input? You can mix key input and speechinput in a single application (though you are not recommended to allowboth at the same time). For example, entering a Personal IdentificationNumber (PIN) is easier using keys, whereas recording a street address iseasier with speech.

4. Command-driven or prompted? You need to make a decision aboutwhether to let callers interrupt the prompts or not. In general, you shouldlet them interrupt. Once they learn the choices at each point, they can keyahead (or speak ahead), without waiting for the prompt to finish. Theremay, 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 tobe force played.The type of dialog that allows key-ahead or speak-ahead is sometimesknown as a command-driven dialog, but you still need to play theprompts in a voice application, because of the absence of documentation.

5. A single selection key or option-specific selection keys? With a singleselection key, you play each choice to the caller and give them a fewseconds to press the nominated key (for example, 1); if they do not press akey, you play the next choice, and so on. The caller always presses 1 toselect 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 tothe 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 abilityto key ahead and bypass menus.With option-specific selection keys, you allocate a different key to eachoption. This has the advantage of allowing callers to key ahead, but limitsthe options available at any one time. It can also be difficult to ensureconsistency of key-allocation throughout the application (for example, onone menu, 3 may be “Delete message” while on another menu, it issomething less destructive). Again, infrequent use may indicate the singleselection key and frequent use the option-specific selection keys.

6. Passive or active advance through menus? Should each option “dropthrough” to the next option, or should the caller have to press a key toproceed? This becomes an issue if you provide a single selection key.Again, passive advance is probably most suitable for callers who use theapplication infrequently but, to avoid the problem of callers selecting anoption just after the menu has moved on to the next option, you need toinclude 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 morelikely the caller is to learn how to drive the application. However, longprompts slow down callers, particularly experienced ones. A choice ofnovice and expert prompts can help. The difference between them is notnecessarily verbose versus terse: you could actually leave someinformation out of the expert prompts altogether.Always provide essential information before information that is merelyhelpful. Provide “Next” and “Previous” keys, so that callers can skip overinformation they don’t want to hear.

Good things to do in voice applications

Correct wording of your prompts is particularly critical when you are usingspeech recognition. Your prompts must tell the caller what to say, when to sayit, and how to say it. Here are several considerations for wording prompts: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 mentionthe key first, the caller may forget which one it was before realizing that itwas they one they wanted.

v Use questions and commands rather than statements, to encourage callersto 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 smallpizza?” 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 withthe command, for example, 7 for back, 8 for pause, and 9 for forward).

v Try to limit menus to about four options, with a fifth option (“for morechoices”) if necessary; this adheres to the “magic number 7 plus or minus2” items that people can hold in short-term memory; also it won’t take toolong to play.

v The order in which you play the options depends on the application: youmight choose to start with most frequently used, or least-frequently used, orplay them in ascending numerical sequence.

v Use simple, explicit language, for example: “Press” for single key entry (nodelimiter) 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 timeat 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 andvoice B for data retrieved for playback to the caller). For this reason, youshould get the system voice segments recorded by the same professional asyour other voice segments.

Wording prompts for speech recognition applications

Like DTMF applications, your instructions to the caller must be brief. Thecaller cannot be expected to remember more than two or three instructionsbefore making a response. Here are some hints and tips.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 apizza, say YES now” rather than “Do you want a pizza?”

v To encourage the caller to speak digits rather than whole numbers, youmight provide an example. Your recorded voice segment must speak indigits. “How many bottles of item one seven five do you want?” is betterthan “How many bottles of item one hundred and seventy five do youwant?”


v It is useful to include directions such as “say YES or NO now” in theprompt. This helps callers understand that they must wait for the promptto be over before they can speak.

v Your prompts are models for the caller. That is, the caller is likely to mimicthe volume, pace, enunciation, and terseness of the recorded speech.

Handling all responses

When designing a speech-recognition application, you must decide when torepeat a prompt, request verification, or transfer to a human operator. Yourdecisions are based on confidence factors.

Ask for the same information not more than twice, to avoid irritating thecaller and jeopardizing the business transaction. The second prompt shouldapologize to the caller, accept responsibility for the communication error, andrepeat the request. You might change the wording in the second request togive 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 stillplaying. See “Barge-in” on page 121.

Interrupting prompts

To enable callers without DTMF phones to interrupt a prompt with a shortspeech utterance (for example “stop!”), you need to enable voice interruptdetection. See “Voice interrupt detection” on page 122.

Limitations

Speech-recognition applications work best when there is a high signal-to-noiseratio. The speech recognition process can fail when background noise, such astraffic, 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. Forexample, 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 tablecould branch to a TransferCall action to transfer the call.


Defining server requirements

Before you create a 3270 server or custom server to access businessinformation, you need to perform an analysis of your requirements, todetermine how you can most effectively use a server.

The analysis involves identifying information such as:v Remote data required by a voice applicationv Where the required data residesv Existing applications that access the datav Data the server needs to satisfy a requestv Processes required (both new and existing) to satisfy a requestv Whether voice data is to played or recorded on multiple channels at the

same time: a multiprocess custom server makes this easier to managev 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 serverneeds 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 informationv Considering custom server resource requirements, things such as CPU,

memory and page spacev 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 activitystatistics).

When you have identified the information that defines the requirements for aserver, you can determine whether a 3270 server or custom server best suitsyour needs.


Chapter 3. Creating and managing application objects

To implement a voice response service using WebSphere Voice Response, youneed to create a number of objects. This chapter introduces the concept of avoice 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 moredetail in Chapter 4, “Overview of application objects,” on page 61.)

This chapter contains the following sections:v “What are application objects?” on page 28v “Using the applications and application windows” on page 30v “Managing application objects efficiently” on page 29v “Discovering what applications and objects are in the system” on page 30v “Editing and testing application objects” on page 33v “Creating an application” on page 34v “Exporting an application” on page 38v “Exporting one or more objects” on page 44v “Importing application objects” on page 46v “Migrating from an earlier release of IBM WebSphere Voice Response for

AIX” on page 50v “Frequently asked questions” on page 51v “Moving objects from the default or user applications” on page 54v “Deleting an application” on page 55v “The dtimport and dtexport commands” on page 55


What are application objects?

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

v The heart of the voice application is the state table, which provides the logic(see “State tables” on page 61).

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 text-to-speech.– 3270 servers, to provide access to data on host computers, via existing

applications that use the 3270 data stream. (See “3270 and customservers” on page 85.)

v The state table can invoke prompts, which are specialized programs thatcontrol 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 voicesegments. Although these can be played directly by the state table, it ismuch more efficient to play each voice segment from a prompt. (See “Voicesegments” on page 82). Voice segments are collected together in a voicedirectory, 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 profileshave several functions. Each application profile specifies a main (or initial)state table which:

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


– Can be invoked in response to incoming calls if the application profile IDmatches the called number or channel identification.

– Can be invoked by other state tables (but note that you can invoke astate table from another state table without an application profile).

– Uses the specified language database to play prompts and voicesegments. Thus you can have the same state table to handle calls indifferent languages; only the application profiles need to be different.

– Can access up to ten voice mailboxes, together with associated voicemessaging resources, such as distribution lists, for use by the state tabledescribed 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 customserver.

All these objects comprise the voice response service, or voice application. To helpyou manage these objects in an application-oriented way, WebSphere VoiceResponse includes an Applications window in which you can see all theapplications in the system, and an Application window for each application,which shows all the objects in the application, grouped into folders: one folderfor each type of object in the application.

Managing application objects efficiently

All application objects in the WebSphere Voice Response system must be inone 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 developmentThis enables you to:– Find objects easily– Open objects for browsing or editing– Delete objects from the system

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

Chapter 3. Creating and managing application objects 29

– Importing the application package

You can move objects into and out of an application.

You can copy objects, with the restriction that you must provide a new namefor the copied object, whether or not it has been copied to a differentapplication.

Using the applications and application windows

There are several ways of doing many of the tasks described in the followingsections. The procedures describe the simplest way, using the mouse tosingle-click, double-click, or drag-and-drop. Most tasks are also available fromone of the pulldown menus on the menu bar, and from the object popupmenu.

To use the pulldown menu, select the object first and then select the menuoption using mouse button 1. To use the popup menu, select the object firstand then press mouse button 3. Alternatively, all tasks can be done usingkeyboard keys. See “wvrapplprof command” on page 94 and the WebSphereVoice Response for AIX: User Interface Guide book for more information.

Discovering what applications and objects are in the system

Before you start, see the note on “Using the applications and applicationwindows.”

From the Welcome window click on, Applications —> Applications

The Applications window shows all the applications in the system.


1. Opening an application: To display the objects in each application,double-click on the line that represents the application.The Application window shows a folder for each type of object in theapplication:

2. Opening a folder and displaying information about objects: Single-clickon 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


You can select the names of the objects in this view.

About the supplied applications: When you install WebSphere VoiceResponse, three applications are supplied:

The Default applicationThe Welcome, Incoming_Call, Record_Comp, and Record_Uncompstate tables, and other objects they need are in the Default application.If you migrated your own application objects from IBM WebSphereVoice Response for AIX Version 4.2, they are also placed in theDefault application.

The User applicationFor information about the User application, see Table 2 on page 52.

The System applicationThe 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 ownapplications and move your objects into them (see “Creating an application”on page 34 and “Moving objects from the default or user applications” onpage 54).


Editing and testing application objects

You can do most of the work involved in implementing a voice responseservice from the Application window.

Before you start, see the note on “Using the applications and applicationwindows” on page 30.1. From the Welcome window, click on Applications —> Applications

2. Opening an object: Open the application. In the Application window,open the appropriate folder. (See “Discovering what applications andobjects 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 containerwindow listing all the objects of that type appears, followed by the editingwindow 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 youwhich application was selected when the container window opened. However,the container window lists all the objects of that type in the system.

You can use the container window to find objects, using the Search popupwindow (mouse button 3). (For information about using the containerwindows and about searching for information, see the WebSphere VoiceResponse for AIX: User Interface Guide book.)


To open objects such as prompts and voice segments, which are contained inprompt directories and voice directories respectively, double-click on thedirectory name in the container window. This displays all the objects in thatdirectory. 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 customservers, 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 importthe ASCII code into the appropriate editing window, by clicking Utilities —>Import. Or, you can import ASCII state tables and prompts using a commandthat can be issued from the command line or from a script.

For more information

See the appropriate book for all the detailed information you need aboutcreating, editing, and testing these objects (and importing ASCII code forthem):v WebSphere Voice Response for AIX: Application Development using State Tables

bookv WebSphere Voice Response for AIX: 3270 Servers bookv WebSphere Voice Response for AIX: Custom Servers book

The remainder of this chapter tells you about creating the application as acontainer for your objects, managing the objects within the application, andexporting and importing whole applications and individual objects.

Creating an application

Before you start, see the note on “Using the applications and applicationwindows” on page 30.1. From the Welcome window, click on Applications —> Applications

2. Naming the application: Click Application —> New.The system displays the New Application window.

3. Type in the name (up to 15 characters) and, optionally, a description (upto 255 characters). The name must be unique.

4. Click Create.The name of the new application is displayed in the Applicationswindow and a new Application window opens automatically.


5. You can now either move or copy existing objects into the application, orcreate new objects within it.

6. Moving an object: Open both the source and target Applicationwindows.

Note: It does not matter whether there is a folder for the type of object inthe Application window, because folders are created automatically by thesystem; 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, usingmouse button 2, to the target Application window.The object is moved to the target Application window, and displayed inthe appropriate folder.

Note: If you drag an object from the Object Index window into anApplication window, the object is not removed from the Object Indexwindow, but the application name is changed. The object appears in thetarget Application window.

8. Moving multiple objects: Click multiple objects of the same type (in thesame folder): you can either select adjacent objects by dragging downthem using mouse button 1, or you can add objects to the selection byholding 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 displayedin the appropriate folder.

10. Copying an object: Click the object in the source Application windowand drag it, using mouse button 2 + Ctrl, to the target Applicationwindow.Because you cannot have two objects with the same name, the systemasks you for a new name.

11. Type in the name. The name must be unique.12. Click Copy.

The new object is displayed in the Application window.13. Creating a new object: 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. Referto the WebSphere Voice Response for AIX: Application Development usingState Tables book for detailed procedural and reference information, or usethe online help.


When you click View —> Refresh Now, the new object is displayed inthe Application window.

Note: If you create a new object within the Object Index window, theobject is stored in the Default application and displayed in theApplication (Default) window.

16. Creating more objects: You can create further objects of the same type byrepeating steps 13 on page 35 and 14 on page 35, or by clicking Newfrom the appropriate menu in the container window.

17. Displaying dependent objects: Click an object and then clickDependencies from the object's popup menu.The system displays the Dependencies window:

What is a dependency?: A dependency is an object that is necessary foranother object to run correctly.

For example, prompt directory B becomes a dependency of state table Awhen you specify it as the prompt directory in state table A. WebSphereVoice Response cannot find all of the dependencies if variables are usedto name them (for example, InvokeStateTable by variable).

To run a state table on a development system, it is not necessary toinclude all dependencies in the same application. Provided that all thedependencies are actually present, the state table can be run. But, beforeyou export the state table to another system, you should check that thestate table and all its dependencies (other state tables, prompts, voicesegments, and so on) are present on the target system, whether in thisapplication or in another one, for example, a common application.

18. Adding application prerequisites: Click Application Prerequisites fromthe application's popup menu.


The system displays the Application Prerequisites window.

What is an application prerequisite?:

An application prerequisite is another application that contains objectsthat are necessary for the application to run. After you've traced all thedependencies of the objects in your application, you can add theapplications that contain them to the Application Prerequisites list. (Whenyou export the application, the system asks you if you want to export theprerequisite applications too.)

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.


22. Deleting application prerequisites: Click the applications that are nolonger required.

23. Click Delete.The system removes the applications from the list in the Add ApplicationPrerequisites 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 copyof the application, you need to export all the objects that comprise theapplication. The export process involves the creation of an export file, in whichall the objects in the application are packaged. It is then up to you to send thefile to another system by any suitable method.

You can export an application from:v The Applications window (from the Application menu or from the

applications’s popup menu)v The Application window (from the Application menu)v The AIX command line (see “dtexport command” on page 56)v A script (see “dtexport command” on page 56).

You can export a complete application (full export) or only those objects whichhave 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). Inaddition, you can choose to export only binary objects. These choices areexplained further in Choosing objects to export and What are text and binaryObjects?.

Multiple simultaneous import or export operations using dtimport or dtexportfrom the command line, or using import or export functions from theApplication Manager are not allowed. If you attempt to start an exportoperation while another import or export operation is in progress, theApplication Manager will display a warning dialog notifying you that anotherimport or export operation is already in progress.


Note: The export process uses the AIX tar command to create a file in UnitedStates Tape Archiver (USTAR) format. This supports file path names with amaximum of 155 characters for the prefix part (the directory name) and amaximum of 100 characters for the name part (the file name itself).1. From the Welcome window, click on Applications —> Applications

2. Selecting the application: Either click the application name in the mainApplications window, or click the Application window, if it is displayed.

3. Exporting the complete application: Click Application —> Export —>Full.The system displays the Full Export window:

4. Proceed to step 13 on page 42.5. Exporting updated objects only: Click Application —> Export —>

Delta.The system displays the Delta Export window:


6. Click the appropriate radio button for objects changed since Last FullExport, Last Delta Export, or a Specific Date, and if necessary fill in thedate fields.

7. Proceed to step 13 on page 42.8. Choosing objects to export: Click Application —> Export —> Partial.

The system displays the Partial Export Preview window.If the application has prerequisite applications, a window is displayed foreach of the applications. You don’t have to export them all. If you aresure that a prerequisite application is already on the target system, clickExport —> Cancel.All the objects in the application are listed:


This window allows you to drag in any objects that you want to add tothe export file, from any other applications.It also allows you to exclude objects from the list, to prevent them frombeing exported.

9. To remove an object from the list, click it and click Exclude from thepopup menu.

10. To add all the objects that are used by an object in the list, click the objectand then click Include Dependencies from the popup menu.

11. To add an object from another application to the list, open the otherapplication. Then click the object in the Application window and drag itinto the Partial Export window.

12. Exporting: Select Export —> Confirm on the Partial Export Previewwindow to display the Partial Export window.Click the appropriate radio button for Text and Binary objects, or BinaryOnly.


What are text and binary Objects?:

Each state table, prompt, and 3270 script comprises a text file and abinary (executable or “runtime”) file. You need both files fordevelopment, but only the binary file for running applications inproduction.

Select Text and Binary if:v You are exporting to another development system

orv 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

andv You don't want anyone else to see or modify the code.

Note: The Object Settings window for each object has a radio buttonfor Do not export when "Binary Only" is selected. Selecting thismeans that when you select Binary Only, the object is not exported.

13. Specifying where to put the export file: Click the appropriate radiobutton for media type.If you click File, the system displays the Export File window:


a. Click the directory and select or type in the file name for the exportfile.

b. Click OK.The “working” dialog is displayed. The progress of the export isdisplayed on the status line in the Applications window.When the export is completed, the system displays the Export Reportwindow, giving details of what was exported:

14. Saving or printing the export report: If you want to keep the ExportReport 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 theWebSphere Voice Response parameter group.


v To save a copy of the Export Report, click Save. The system displaysthe Save Report window:

a. Click the directory and select or type in the file name for the exportreport file.

b. Click OK.

Next Step

The export file is now ready to be transported to another system. Usewhichever method you normally use for this (for example, file transferprotocol (ftp)).

Exporting one or more objects

Although the recommended methods of export are full export and delta exportof an application (see “Exporting an application” on page 38), partial export ofone or more objects is also available if necessary. To preserve the integrity ofyour applications, however, partial export is not recommended.1. From the Welcome window, click on Applications —> Applications

2. Displaying the Object Index: If the Object Index window is not alreadydisplayed, click Options —> Object Index from the Applicationswindow.


The Object Index window shows a folder for each type of object in thesystem:

The Object Index shows you all the application-related objects in thesystem, organized into folders. It’s another view of the objects in thesystem, each of which is contained in a single application. In otherwords, you cannot move objects out of the Object Index into anapplication: all objects are shown in the Object Index.

3. Opening a folder: Single-click on the folder icon to open it.The folder contains all the objects of that type in the system.

4. Selecting the objects to export: Click one or more objects in the ObjectIndex 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 Removefrom thepopup menu.

7. To add all the objects that are used by an object in the list, click the objectand then click Get Dependencies from the popup menu. For guidance,see Choosing objects to export.

8. To add an object from another application to the list, open the otherapplication. Then click the object in the Application window and drag itinto the Partial Export window.

9. Exporting binary objects only: Click the appropriate radio button forText and Binary (executable) objects, or Binary only. For guidance, seeExporting.


10. Specifying where to put the export file: Click the appropriate radiobutton 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 isdisplayed on the status line in the Applications window. Once theexport 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 systemparameter 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. Usewhichever method you normally use for this (for example, file transferprotocol (ftp)).

Importing application objects

You can import any file that was exported from a WebSphere Voice Responsesystem using any of the following methods. You can also import all the filesthat are supplied with WebSphere Voice Response as import files (file namesending in .imp).v The procedure described in “Exporting an application” on page 38v The procedure described in “Exporting one or more objects” on page 44v Using the dtexport command (see “dtexport command” on page 56)

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)v The AIX command line (see “dtimport command” on page 59)v A script (see “dtimport command” on page 59)


When you import voice prompts or voice directories, you can choose either toreplace existing objects of the same name, or to merge them with existingobjects. When you choose to merge objects, the objects are replaced if theyalready exist, and they are added if they do not. For objects other than voiceprompts and voice directories, you can only replace them.

Multiple simultaneous import or export operations using dtimport or dtexportfrom the command line, or using import or export functions from theApplication Manager are not allowed. If you attempt to start an importoperation while another import or export operation is in progress, theApplication Manager will display a warning dialog notifying you that anotherimport or export operation is already in progress.

Attention: If the imported object belongs to a different application, it is putinto an application of that name on the target system, even if the replacedobject was in a different application.1. From the Welcome window, click on Applications —> Applications

2. Simply importing a file: 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.

5. Click OK.The “working” dialog is displayed. The progress of the import isdisplayed on the status line in the Applications window. When the


import has completed, the system displays the Import Report window:

6. Printing or Saving a Report: If you want to keep a the Import Reportyou can print it or save it in a file. Click Print. The report is printed onthe printer specified by the Printer Queue system parameter in theWebSphere Voice Response parameter group.To keep a record of the import, click Save. The system displays the SaveReport window.a. Click the directory and select or type in the file name for the import

report file.b. Click OK.

7. Simply importing from tape or diskette: Ensure that the Default TapeDrive or the Default Diskette Drive system parameter in the Generalparameter group is set as appropriate.

8. Click Application —> Import —> Merge —> Tape or Diskette.The “working” dialog is displayed. The progress of the import isdisplayed on the status line in the Applications window. When theimport has completed, the system displays the Import Report window.

9. To keep a record of the import, click Save or Print.10. Checking the objects you are importing from a file: 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 donot want to install all objects, click any object not required, and then clickExclude from the popup menu.The selected objects are removed from the list. (If you remove one bymistake, click Cancel and start over.)

Note: For the most efficient application distribution, you arerecommended to ensure that the export file contains the correct set ofobjects and then import all of them, rather than exporting more than youneed and then picking the ones you don’t want. See “Exporting anapplication” on page 38.

15. Click OK.The “working” dialog is displayed. The progress of the import isdisplayed on the status line in the Applications window. When theimport 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 thePrinter Queue system parameter in the WebSphere Voice Responseparameter 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.


17. Checking the objects you are importing from tape or diskette: Ensurethat the Default Tape Drive or the Default Diskette Drive systemparameter in the General parameter group is set as appropriate.

18. Click Application —> Import with Preview —> Merge —> TapeorDiskette.The system displays the objects included in the file.

19. Open and close the folders by single-clicking on the folder icon. Clickany objects you do not want to import.

20. Click Exclude.The selected objects are removed from the list. (If you remove one bymistake, click Cancel and start over.)

21. Click Import —> Confirm.The “working” dialog is displayed. The progress of the import isdisplayed on the status line in the Applications window. When theimport 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 book, thereare two methods of migrating applications:v If you used the saveDT command to save your WebSphere Voice Response

application objects and data before installing WebSphere Voice Response,you must use the restoreDT command to bring them into WebSphere VoiceResponse (see the WebSphere Voice Response for AIX: Installation book fordetails).

v If you exported application objects from IBM WebSphere Voice Response forAIX Version 4.2, you must import them into WebSphere Voice ResponseVersion 6.1, as described in “Importing application objects” on page 46.

In both cases, objects created using IBM WebSphere Voice Response for AIXVersion 4.2 arev Automatically migrated into the WebSphere Voice Response Version 6.1

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 ownapplications and move your objects into them (see “Creating an application”on page 34 and “Moving objects from the default or user applications” onpage 54).


Frequently asked questions

Here are some frequently-asked questions:v “Do you have to create applications?”v “Where are newly-created or migrated objects put?”v “What happens when you import objects belonging to an application that

does not exist on the target system?” on page 52v “What about the integrity of applications that are already in use?”v “When should you use full export, delta export, and partial export?” on

page 52v “When should you export prerequisites along with an application?” on

page 53v “What happens to “duplicate” objects?” on page 53v “What if more than one application needs to use the same object?” on page

53.

Do you have to create applications?Your state tables will run successfully, whether or not you create your ownapplications to put the objects in2. In other words, you can develop and run avoice response service without creating your own application containers.Nevertheless, you will find that applications make management anddistribution of objects easier. If you decide to create your own applicationsafter all, follow the instructions in “Moving objects from the default or userapplications” on page 54.

What about the integrity of applications that are already in use?Moving objects between applications has no effect on any objects that are inuse. However, if you choose to delete an object, you really will be deleting itfrom the system, and a dialog will ask you to confirm your decision, even ifthe object is not in use.

Similarly, if you import a new version of a state table when that state table isalready running (and so is already cached), the running state table is notchanged. 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 inone and only one application. However, objects can “arrive” in a WebSphereVoice Response system in a variety of ways. Table 2 on page 52 shows whichapplications these objects are put into.

2. When you put the application into production, it is the application profile that defines the main state table andentry point to the runtime WebSphere Voice Response system. (See Chapter 5, “Creating an application profile,” onpage 89 for more information.)


Table 2. Where To find newly-created objects

Method of Creating the Object Application

Migrated from IBM WebSphere Voice ResponseVersion 4.2

Default

Imported from another WebSphere Voice ResponseVersion 6.1 system (including application objectssupplied with the WebSphere Voice Responseproduct or its features)

The application that containedthe object in the other system

Created by clicking Object "> New in anApplication window

The current application

Created by clicking the object type (for example,State Tables, from the Applications menu in theWelcome window and then File "> New

User

Created by clicking Object "> New from the ObjectIndex window

Default

What happens when you import objects belonging to an application thatdoes not exist on the target system?

Whether you’re importing an application into a system for the first time, or ifyou have deleted the application and are importing it again, the answer tothis question depends on whether you are importing a file that was the resultof:v A full or delta exportv A partial export

With full or delta export, the application is created in the target system and allthe objects are placed within it.

With partial export, when the file is imported into another system, WebSphereVoice Response attempts to place each object into the application to which itbelonged on the system from which it was exported. If an application withthat name does not exist on the target system, the object is not created, and anerror 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 anothersystem. After the first time, delta export is recommended, because it includesonly the objects that have been changed, and therefore reduces the size of thefile.

Use full export for a complete backup of an application.


Partial export is recommended only for exporting one or a few individualobjects. It’s not recommended as the normal method of exporting voiceapplication objects: to ensure the integrity of your applications, use deltaexport 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 manyapplications. It’s not necessary to export those prerequisite applications unlessyou know they don’t exist on the target system or you know that some of theobjects have changed.

What happens to “duplicate” objects?Each object name must be unique across all the applications in a system. Thismeans that you have to be careful when importing an application for the firsttime. The same applies to using the restoreDT command when migrating froma release of IBM WebSphere Voice Response for AIX. Any object already in thetarget system, with the same name as an object being imported, will beoverwritten.

What if more than one application needs to use the same object?The application is a “container” of application objects, which means that eachobject must be specified in one, and only one, application. In addition, eachobject must have a unique name, within that type of object, across allapplications.

It is very likely that some objects will be useful in more than one voiceresponse service: for example, voice segments for commonly-used phrases.Copying them has two disadvantages: storage is used unnecessarily and youhave to rename each copy. Instead of copying, you can make an objectavailable to be used by more than one application, by putting it into a commonapplication.A common application is just an ordinary application whose objectsare to be used by more than one other application.

You then add the common application to the list of application prerequisitesfor any application that is to use it. When you export any of theseapplications, the system gives you the opportunity to export the commonapplication at the same time.

For example, the cemg application in Figure 5 on page 54 includes all the statetables, and the specific prompts, voice segments, and voice tables used bythose state tables; while the common application includes prompts, voicesegments, and voice tables that might be used by other applications too.


Moving objects from the default or user applications

If you have just migrated from IBM WebSphere Voice Response for AIXVersion 4.2, or for some other reason all your objects are in either the Defaultapplication or the User application, you may find it more convenient to sortthem out into application “packages” (for reasons, see “Managing applicationobjects efficiently” on page 29).

The following instructions assume that the source application is the Defaultapplication, but they work just as well for the User application or any otherapplication.1. From the Welcome window, click on Applications —> Applications

2. Displaying the Default application: Find the object named Default anddouble-click on it to open it.The Application (Default) window is displayed.

3. In the Applications window, create your own application, and moveobjects 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 1and drag across the object names.

Figure 5. Two applications, one of which contains commonly-used objects


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 theCtrl 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 Applicationwindow, but it's harder to keep track of what you've done, because theobjects 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 anyother application, and make sure that the objects in the application are notused by any other objects. You must first delete or move all the objects froman 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

2. Removing the objects from the application: Double-click on the name ofthe 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.

7. Removing the application: Click Application —> Delete.

Note: If the application still contains any objects, the system does notallow 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 Importand Export options in the windows, but also enable you to:


v Distribute the applications to multiple systems using shell scripts. This canautomate 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 andexamine or debug it at your location.

The dtexport and dtimport commands perform most of the same functions asthe Export and Import options. The following functions are not supported bythe 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.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 thecommands directly on the AIX command line. Starting the programs fromwithin shell scripts gives a lot of power to the user because they can have theprograms executed on remote machines and as a part of more complexoperations.

Because the command-line utilities are fully compatible with the options inthe windows, you can use the dtimport command to import files that wereexported by the Export option, and you can use the Import option to importfiles that were exported by the dtexport command.

dtexport command

Purpose

Exports application objects into application or partial-export packages.

Prerequisitesv You must be logged onto AIX as dtuser.v WebSphere Voice Response must be running.


Syntaxdtexport [-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 deviceExport on to the specified device. The device can be either afully-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 notbe longer than 100 characters.

You can also specify the path to the file. The path name must not belonger than 155 characters.

-t Export on to the tape drive specified in the Default Tape Drive systemparameter.

-D Export on to the diskette drive specified in the Default Diskette Drivesystem parameter.

-x Extract all dependencies of the selected objects, and add them to thepackage. 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 thecommand are included in the package.

-b Export only the binary format of those objects that have both a textand a binary form (that is, state tables, prompts, and 3270 scripts).

-appl applicationSpecifies the name of the application to be exported. This optioncannot be specified in conjunction with the object type optionsdescribed below.

-delta The application objects to be exported are only those that have beenmodified 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 onlyyou also specify the -appl option.

-since yyyymmddhhmmssOnly those objects in the specified application that have beenmodified since the time yyyymmddhhmmss are to be exported. Thisoption 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 beexported. This option is not valid if -appl is also specified.

-vdir voicedir...Specifies a space-delimited list of voice directories that are to beexported. 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.

-cs server...Specifies a space-delimited list of custom servers that are to beexported. This option is not valid if -appl is also specified.

-prof profileID...Specifies a space-delimited list of application profile IDs that are to beexported. This option is not valid if -appl is also specified.

-sclass class...Specifies a space-delimited list of subscriber classes that are to beexported. This option is not valid if -appl is also specified.

Return values

0 Success

< >0 Failure

Usage notesv Multiple simultaneous import or export operations using dtimport or

dtexport from the command line, or using import or export functions fromthe Application Manager are not allowed. If you attempt to start an export


operation while another import or export operation is in progress, thedtexport command will return an error message notifying you that anotherimport or export operation is already in progress, and the command willreturn 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 havechanged since the last export:dtexport -dev /tmp/sports.imp -appl Sports_Results -delta

To export only those objects in the “Proto” application that have changedsince a specific date:dtexport -dev /tmp/proto.imp -appl Proto -delta -since 19970620000000

dtimport commandPurpose

Imports application or partial export packages

Prerequisitesv You must be logged on to AIX as dtuser.v WebSphere Voice Response must be running.

Syntaxdtimport [-dev device | -f filename | -t | -D]

[-mp] [-mv]


Flags

-dev deviceImport from the specified device, which either be a fully-qualified AIXfile 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 systemparameter.

-D Import from the diskette drive specified in the Default Diskette Drivesystem parameter.

-mp Specifies that any prompt directories in the export package will bemerged into the corresponding prompt directory on the target system(if it exists). This means that prompts will be replaced if they alreadyexist, and added if they do not.

-mv Specifies that any voice directories in the export package will bemerged into the corresponding voice directory on the target system (ifit exists). This means that voice segments will be replaced if theyalready exist, and will be added if they do not.

Return values

0 Success

< >0 Failure

Usage notesv Multiple simultaneous import or export operations using dtimport or

dtexport from the command line, or using import or export functions fromthe Application Manager are not allowed. If you attempt to start an importoperation while another import or export operation is in progress, thedtimport command will return an error message notifying you that anotherimport or export operation is already in progress, and the command willreturn 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 voicedirectories and prompt directories:dtimport -D -mp -mv


Chapter 4. Overview of application objects

Application objects were introduced briefly in the WebSphere Voice Response forAIX: General Information and Planning book, and are described in more detailin the following sections.

You'll need the procedural and reference information in the WebSphere VoiceResponse for AIX: Application Development using State Tables; WebSphere VoiceResponse for AIX: 3270 Servers; and WebSphere Voice Response for AIX: CustomServers books when you come to create your own objects to implement a voiceresponse 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, thevoice 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 onpage 68 for an example of a state table.

A state table can invoke a nested state table to perform a set of actions beforereturning control to the invoking state table. The state table can invokedifferent state tables depending on a condition, such as the response of thecaller to a previous prompt.

State table actionsThere is a range of state table actions, from very general (such as AssignData,which performs a variety of computational functions) to very specific (likeControlMusic, which is used to turn up or down the volume of backgroundmusic). Because the general actions can be combined in so many ways, thefollowing list may not be exhaustive, but it does give a goal-orientedoverview of which action to choose to perform application functions.

Telephony activity

Task State Table Action

Respond to a ringing line (incoming call) AnswerCall

Make an outbound call MakeCall

Send a set of numbers, a hook flash, or a ground keysignal 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 (forexample, if a TransferCall failed)

ReconnectCall

Disconnect a caller TerminateCall

Voice segments


Record a segment of voice data RecordVoiceSegment

Store a segment of voice data in a voice directory SaveVoiceSegment

Remove a segment of voice data DeleteVoiceSegment

Play a prompt, which may include one or moreprerecorded voice segments

PlayPrompt

Play a single segment of prerecorded voice data PlayVoiceSegment

Output to the caller


Play a prompt, which may include one or moreprerecorded voice segments

PlayPrompt

Play a single segment of prerecorded voice data PlayVoiceSegment

Play speech from a text-to-speech server, databaseserver, or another WebSphere Voice Response system

PlayVoiceFromHost

Play voice data sent from another WebSphere VoiceResponse 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 a3270 server or custom server

GetFindData

Retrieve an application profile, using keys pressed bythe caller

GetFindName

Check the password keyed by the caller with thepassword defined in the application profile specifiedby SV20 for the mailbox ID specified by SV32

GetPassword

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 valueof a character variable

Case

Invoke another state table InvokeStateTable

Chapter 4. Overview of application objects 63


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 customserver

ReceiveData

Receive data items and return codes, from a 3270server

ReceiveData

Find out it there is enough storage available in theWebSphere Voice Response file system for anapplication 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 theresult to a variable

AssignData (Subtract)

Multiply one number by another and assign the resultto a variable

AssignData (Multiply)

Divide one number by another and assign the resultto a variable

AssignData (Divide)

Divide one number by another and assign theremainder to a variable

AssignData (Modulus)

Assign the absolute value of a number to anothervariable

AssignData (Absolute Value)



Truncate one number by the length specified byanother and assign the result to a variable

AssignData (Truncate)

Round one number at the digit specified by anotherand assign the result to a variable

AssignData (Round)

Concatenate one character string to another andassign the result to a variable

AssignData (Concatenate)

Take a specified number of characters from thebeginning of one character string and assign them toa variable

AssignData (Left)

Take a specified number of characters from the end ofone character string and assign them to a variable

AssignData (Right)

Take the character that occurs in a specified positionof one character string and assign it to a variable

AssignData (Index)

Search for a specified character string in anothercharacter string and assign the position of it in thesecond string to a variable

AssignData (Search String)

Count the number of characters in a character stringand 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)

Remove a tag string designated by a tag label AssignData(RemoveTag)

Remove the attribute substring AssignData(RemoveAttribute)

Find a tag label and append the corresponding tagstring to the result

AssignData(GetTag)

Find a tag and attribute substring and assign theattribute value to a variable

AssignData(GetAttributeValue)

Find a tag label and assign its value to a variable AssignData(GetTagValue)



Build a tag string and assign it to a variable AssignData(PutTag)

Build an attribute and assign it to a variable AssignData(PutAttribute)

Find and replace a tag value AssignData(ChangeTagValue)

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 theapplication profile ID and mailbox ID

SendVoiceMessage

Retrieve all voice messages of a specified type for theapplication profile specified by SV20 and mailbox IDspecified by SV32

CheckVoiceMessages

Play a voice message from a mailbox PlayVoiceMessage

Save a voice message, which has been retrieved usingCheckVoiceMessages, in the mailbox for later retrieval

SaveVoiceMessage

Play back a voice message which has just beenrecorded

PlayVoiceMessage

Remove a voice message previously retrieved usingCheckVoiceMessages

DeleteVoiceMessage


Distribution lists


Retrieve names of all recipients on a specifieddistribution list for a specified application profile andmailbox ID

GetDistributionList

Retrieve names of all distribution lists for a specifiedapplication 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 andmailbox ID

SaveAudioName

Play the audio name of the specified applicationprofile and mailbox ID

PlayAudioName

Remove the audio name of the specified applicationprofile and mailbox ID

DeleteAudioName

Greetings


Record a greeting RecordUserGreeting



Store the greeting for the specified application profileand mailbox ID

SaveUserGreeting

Play the greeting associated with the specifiedapplication profile and mailbox ID

PlayUserGreeting

Remove the greeting specified by system variableSV102

DeleteUserGreeting

Endings


Terminate a nested state table and return to theinvoking state table

ExitStateTable

Terminate a link with a custom server CloseHostServerLink

Disconnect a caller TerminateCall

Terminate an application and clean up all resources CloseEverything

Example state table

Table 3. Example state table.

State Table Name: Simple_Sample

Prompt Directory: Simple_PromptsDescription: Accountbalances and interest rates

StateLabel

Action Parameter Description Possible Results NextState

Start AnswerCall 1 None Succeeded

Not ringing

Welcome

Exit


Table 3. Example state table (continued).



Welcome PlayPrompt Prompt name (playssegment 1)

Succeeded

Line Problem

Nothing Played

Caller Hung Up

Options

Exit

Thanks

Exit

Options PlayPrompt Prompt name (playssegment 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 (playssegment 15)

Succeeded

Line Problem

Nothing Played

Caller Hung Up

Exit

Exit

HangUp

Exit

Error PlayPrompt Prompt name (playssegment 16)

Succeeded

Line Problem

Nothing Played

Caller Hung Up

Options

Exit

HangUp

Exit


Table 3. Example state table (continued).



HangUp TerminateCall Succeed Exit

Exit CloseEverything

1. The AnswerCall statement is required only for using the Debug option in thestate table window. The call has already been answered by the Incoming_Callstate table: see “How does WebSphere Voice Response answer an incoming call?”on page 136.

State table variables and parametersWebSphere Voice Response includes three types of variable:v System variablesv Local variablesv Input parameters

Use the AssignData action to set the value of a variable and the EvaluateDataaction to check the value.

System variables

System variables are global variables predefined by WebSphere VoiceResponse; they are available to any WebSphere Voice Response state table orprompt, but not to 3270 servers or custom servers. There are a large numberof system variables, and they are documented in the WebSphere Voice Responsefor AIX: Application Development using State Tables book.


In the window for selecting system variables (shown in Figure 6), thevariables are organized into groups, and listed by names that reflect thosegroupings. Each system variable also has a shorter numeric identifierpreceded by “SV”. For example, the System : Call Info : Called numbersystem variable (SV185) holds the number dialed by the caller (the callednumber passed by the switch), and the System : Call : Channel numbersystem variable (SV165) holds the logical channel number of the channelcurrently in use by the application.

The values of some system variables are read-only (RO) and cannot bechanged by an application; other system variables are read-write (RW) andtheir values can be set using the AssignData action.

Global user variables

WebSphere Voice Response supplies 60 read-write system variables for youruse. These include 45 string variables (SV51 through SV80 and SV82 throughSV96), each of which can contain up to 3583 characters, and 58 numericvariables (SV241 through SV298), which are implemented as 32-bit signedintegers. These variables, like other system variables, are global within a statetable and all the state tables nested within it. They are not accessible by statetables running on other channels. When the main state table starts, the stringvariables are initialized to null and the numeric variables are set to 0.

Figure 6. System variables


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 ofthe variable as a string of characters or as a number.

Local variables are not permanent. When the application is finished using astate table, it destroys the local variables you defined for that state table. Thenext time the application is invoked and uses the state table, it recreates thelocal variables.

The information the local variable contains is accessible to any action in thestate table in which you defined the variable. But only that state table canaccess or alter the contents of the variable. If you use an InvokeStateTableaction to call another state table, the local variables defined for the invokingstate table are not available to the invoked state table, unless they are passedas parameters.

Input parameters

Input parameters are used to define variables received by programs, includingprompts, 3270 scripts, custom servers, or state tables, from the invoking statetable. 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 invokingand invoked state tables.

To pass parameters from a state table to another state table, prompt, customserver or 3270 server, click the Parameters pushbutton in the InvokeStateTablewindow, the PlayPrompt window, or the SendData and ReceiveData windows.This displays a window that lists the parameters required by the invokedstate table, prompt, custom server or 3270 server, as shown in Figure 7 onpage 73. Parameters are passed by value to prompts, custom servers, and 3270servers.


Note: No parameters can be passed from an application profile to a statetable.

State table action parameters

Some state table actions require parameters to tell them what to do. Forexample, the PlayPrompt has a Force Play parameter that specifies that theprompt must be played through to the end. Some parameters can be constantvalues or variables.

Returning data to the state tableAn invoked state table can return data to the invoking state table by assigninga new value to an “input” parameter. Because parameters are passed byreference to state tables, the new value will be available to the invoking statetable.

A prompt cannot return data to the state table, but the RETURN and ABORTstatements 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 usingparameters on the ReceiveData action.

Possible resultsEach state table action can have one or more possible results. The possibleresults of each action are predefined by WebSphere Voice Response. Forexample, the PlayPrompt action has four possible results:v Succeededv Line problemv Nothing playedv Caller hung up

Figure 7. A list of parameters to be passed to a prompt


For each result, the state table needs to know what to do next. For eachpossible result, of each state in your state table, you have two choices:1. “Fall through” to the next state in the state table2. “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 forAIX: Application Development using State Tables to make sure that your designaccounts for all possible results. You may need to modify your design if youfind you have not allowed for some possible results. Decide how you wantthe 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 thesystem variables, such as the System : Action additional informationsystem variable (SV180), which gives you additional information about someactions. (And note that SV180 is reset after every action, including DoNothing,so you should check its value immediately following the action.)

Entry pointsYou must define at least one entry point at which execution of the state tablebegins. If the state table always starts at the first state and executes through tothe last state, there will be only one entry point. However, you can startexecution at any state by defining entry points where applicable. When youcall a state table from an application profile or another state table, you specifythe entry point at which execution is to start.

Prompts

Prompts are used in state tables to define what a caller hears. A prompt notonly identifies the words the caller hears, but also defines the logic of whenand how the words are played.

A prompt can be simple or complex, depending on whether the promptalways plays the same words or whether the prompt logic defines conditionsfor playing different phrases. For example, you may want an application torepeat the items that the caller has ordered, so the prompt would constructthe utterance with phrases representing those items: “you ordered a bagel withsour cream and lox, and a croissant with Canadian ham and salad ”.

Prompts are constructed using the prompt statements described in theWebSphere Voice Response for AIX: Application Development using State Tables.The variables used by prompt statements work exactly the same way as statetable variables. Generally, a state table passes input parameters to a promptwhich it then uses to select the voice segments to play to the caller.


The set of prompts that are used by a particular state table are grouped in aprompt directory. All prompts used by a state table must be in the same promptdirectory. Multiple state tables can use the same prompt directory.

System promptsThe System prompt directory contains the system prompts, which are includedwith WebSphere Voice Response when the system is installed. The systemprompts do not operate any differently from the prompts you create. The onlydifference between system prompts and the prompts you write is that thesystem prompts are already written for you.

If a state table uses the System prompt directory, the state table can call asystem prompt by supplying the prompt name to the state table action thatplays the prompt as a parameter. If a state table uses its own promptdirectory, you can create new prompts that call the system prompts (using theSYSPROMPT prompt statement). Each system prompt accepts a number asinput and plays a prompt that speaks the number as one of the following:v An integer between -999 and 999v An integer between -999 999 999 999 and 999 999 999 999v A real numberv An ordinal numberv 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 Currencyprompt, the phrase that results is “twelve dollars and thirty-four cents.”However, passing the same number to the Real_number prompt results in thephrase “twelve and thirty-four hundredths.”

Note that although very large numbers can be stored and used by WebSphereVoice Response (using multiple precision format to store large numbers andfloating point numbers), the system prompts cannot play numbers larger thanthe maximum size defined by the prompts. To play very large numbers, youmay need to create your own system prompts.

The Small_number prompt

The Small_number system prompt plays an integer between -999 and 999 asa numeric quantity. Numbers larger than 100 are played without “and”between the word “hundred” and any of the digits. For example, an input of123 produces the phrase “one hundred twenty-three.”


The small number prompt includes prompt statements that reference theNumbers and the Divisor voice tables.

The Whole_number prompt

The Whole_number system prompt plays a positive or negative integer of upto 12 digits as a numeric quantity. The prompt does not insert “and” betweenany of the units of measure or digits. For example, an input of 1103294produces the phrase “one million one hundred three thousand two hundredninety-four.”

Whole_number includes a prompt statement that references the Divisor voicetable.

The Real_number prompt

The Real_number system prompt plays a positive or negative real number asa numeric quantity. The prompt expresses fractional amounts in one of twoways, 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 playedas “(digit) point (digit) (digit) (digit) (digit).” For example, an input of1.2345 produces the phrase “one point two three four five.”

Note that you can change the character to be used for the decimal place bymodifying 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 anordinal number. For example, an input of 256 produces the phrase “twohundred fifty-sixth.”

Ordinal includes prompt statements that reference the Numbers, Divisor, andOrdinal 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. Forexample, an input of 19930113 produces the phrase “January thirteenth,nineteen ninety-three.”

Date includes a prompt statement that references the Month of Year voicetable.

The Time prompt

The Time system prompt plays 6-digit input (hhmmss) as two numbersfollowed by AM or PM. The seconds value is not played. If the minutes inputis 00, Time plays “o’clock” following the hours value.

Although the input to Time is in 24-hour clock time, Time plays the timeusing a 12-hour clock. Noon is 12 PM and midnight is 12 AM (both 000000and 240000 are interpreted as midnight).

For example, an input of 160100 produces the phrase “four oh one PM.” Aninput of 110000 produces the phrase “eleven o’clock AM.”

Time includes prompt statements that reference the Numbers and Time ofDay voice tables.

The Currency prompt

The Currency system prompt plays an input string as an amount of dollarsand cents. For example, an input of 123.45 produces the phrase “one hundredtwenty-three dollars and forty-five cents.”

Note that you can change the character to be used for the decimal place bymodifying 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. Forexample, an input of 5551212 produces the phrase “five five five one two onetwo.”

System prompts in languages other than U.S. EnglishThe system prompts supplied with WebSphere Voice Response producephrases that are spoken in U.S. English. In addition, system prompts for othernational languages are supplied in the /usr/lpp/dirTalk/sw/samples directory(if you install the appropriate optional filesets, which are listed in theWebSphere Voice Response for AIX: Installation book):v Belgian Dutch


v Brazilian Portuguese (for more information, see “System prompts inBrazilian Portuguese” on page 80)

v French (for more information, see “System prompts in French”)v Germanv U.K. English

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 samplesinclude: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 promptthat speaks the number as one of the following :v An integer between 1 and 100 000 000 000v A real numberv 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 specificFrench system prompts (Small_number_frs, Whole_number_frs, andReal_number_frs) are not removed. You must remove each promptindividually.

The standard French system prompts are :

Small_numberPlays an integer between -999 and 999.

For example, 121 is spoken as "cent ... vingt et un." Small_numberincludes prompt statements that reference the Numbers and theNumbers_c voice tables.

Whole_numberPlays a positive or negative integer.


For example, 12345 is spoken as "douze mille ... trois cent ... quarantecinq."

Whole_number includes prompt statements that reference the Numbers,the Numbers_c, and the Numbers_m voice tables.

Real_numberPlays 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 andthe 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 voicetable

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 thatreference the Telephone voice table.

CurrencyPlays input as Francs and Centimes associated with the followingspecific French system prompts.

The French system prompts called by the Currency prompt are:

Small_number_frsPlays 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 theNumbers the Numbers_c, the Numbers_frs and the Numbers_cfrs voicetables.

Whole_number_frsPlays a positive or negative currency integer.

For example, 12345 is spoken as "douze mille ... trois cent ... quarantecinq francs."


Whole_number_frs includes prompt statements that reference theNumbers, the Numbers_c, the Numbers_m, the Numbers_frs, theNumbers_cfrs, and the Numbers_mfrs voice tables.

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

v 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 PortugueseBrazilian Portuguese is a user-defined language, so before importing theBrazilian Portuguese samples you must define a language called BrazilianPortuguese with the language code 213. For information on definingadditional languages, see the WebSphere Voice Response for AIX: Configuring theSystem book.

Changing the system prompts for your languageFor voice response services in languages other than those described in thisbook, you may need to modify the system prompts to use the correct syntaxand conventions. The information in the following sections should help youdetermine whether you need to change the prompts.

The number prompts

The English language constructs numbers by concatenating words for smallernumbers and units of measure, as appropriate. All of the number prompts(Small_number, Whole_number, Real_number, Ordinal, and Phone) create thenumber to be spoken by analyzing the input for the components and thenconcatenating the voice segments that play each component.


For example, the number 81 is determined to be “eighty” and “one” andspoken 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.”

If the language spoken in your location does not construct numbers byfollowing a concatenation pattern similar to the pattern in U.S. English, youmay 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 numbers0 (as both “zero” and “oh”) through 31, 40, 50, 60, 70, 80, 90, and 100. TheSystem voice directory also includes the word “point” for use in decimalnumbers, and the units of measure “hundred,” “thousand,” “million,” and“billion.”

Besides recording the voice segments that play these numbers in a differentlanguage, you may need to record some additional voice segments.

All of the number prompts use Small_number to play numbers from -999through 999.

The Date prompt

Date plays the month first. However, the convention in many other languagesis 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 theconvention in your location is to play the day of the month as a cardinalnumber (for example, “one,” “sixteen,” “twenty-two”), consider usingSmall_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 inyour location is to express the year in a different format, consider using asystem prompt such as Whole_number to play the year. You will also need tochange 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 a12-hour clock. In addition, the logic in Time divides the day into two parts:morning (AM) and afternoon-evening (PM). The convention at your locationmay 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 needto modify Time. You will also need to modify the prompt if your day hasmore (or less) than two parts. And since the System voice directory onlyincludes four voice segments for expressing the time of day (“AM”, “PM”,“hours”, and “o'clock”), you may need to record some additional voicesegments. Note that Time does not play seconds, although they are requiredas input.

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 ofcents. In addition to rerecording the units of currency, you may need tomodify the prompt to play smaller units first.

Voice segments

A voice segment defines the spoken words (for example, “hello” or “goodmorning”) or sounds (for example, music) available to WebSphere VoiceResponse voice applications. A segment can be a single word, a sound, aphrase, one or more sentences, or a combination of words and sounds. Asegment can also be silence.

System voice segments in several languages, including U.S. English, areprovided with WebSphere Voice Response, and listed in the WebSphere VoiceResponse 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 aproduction environment is specified in an application profile, and you canhave one application profile for each language.

Voice directoriesVoice segments are stored in voice directories. Prompts can use segments fromany voice directory.

Note: You are recommended to specify the voice directory name in state tableactions, rather than the voice directory ID, which is retained only forcompatibility. If you use don’t use the name, WebSphere Voice Responsecannot identify a voice directory as a dependent object for export.


Voice tablesSegments can also be logically grouped in a voice table, so that you canreference the segments using an indexing mechanism. For example, you canuse the numbers 1 through 12 to index the months of the year, and thenumbers 1 through 7 to index the days of the week. Voice tables can help youfind out what segments have been recorded and where they are stored. Thesegments in a voice table can be stored in the same voice directory or indifferent directories. Voice tables include a description of each voice segmentand indicate where each segment is stored.

System voice segmentsThe system voice segments are a group of voice segments that are deliveredwith WebSphere Voice Response. They include all of the voice segmentsneeded by the system prompts to play numbers, letters, days of the week, andother common terms. The system voice segments are stored in the Systemvoice directory and should be recorded again to match the voice used in thevoice segments that you create.

Some of the system prompts reference the system voice segments using theVoice prompt statement. Others use the Table prompt statement. The voicetables referenced are all system voice tables.

System voice tablesThe system voice tables catalog the system voice segments in groups such asall the letters of the alphabet, numbers, and days of the week. You can createadditional voice tables as you need them, or as you record more voicesegments, you can add them to the existing voice tables.

The names of several of the system voice tables are referenced by otherWebSphere Voice Response objects. For example, the DIGITS promptstatement uses the Numbers Voice Table Name system parameter, which has adefault value of “Numbers”. If you decide to change the names of the systemvoice tables, you need to make the corresponding changes wherever the tablesare referenced.

The Alphabet voice table

The Alphabet voice table contains the voice segments that play the letters ofthe alphabet (“A” through “Z”). Alphabet is the value of the Alphabet VoiceTable Name system parameter, which is part of the Application ServerInterface parameter group.

The Alphabet Voice Table Name parameter in the Application ServerInterface group specifies the name of the voice table that the CHARACTERSprompt statement uses to play alphabetic characters. The default value isAlphabet.


You can create additional voice tables for the CHARACTERS promptstatement 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 segmentsthat play the days of the month as ordinal quantities (“first” through“thirty-first”).

The day of week voice table

The day of week voice table (Day_Of_Week) contains the voice segments thatplay 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 segmentsthat 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 warningtone.

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 ServerInterface group specifies the name of the voice table that the DIGITS promptstatement 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 asordinal 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 segmentthat plays the system messages. For example, “We are experiencing technicaldifficulties.”

The time of day voice table

The time of day voice table (Time_Of_Day) contains the voice segments thatplay time quantities (“AM,” “PM,” “O’Clock,” “hours,” “oh,” “minutes,”“seconds”).

The time of week voice table

The time of week voice table (Time_Of_Week) contains the voice segments thatplay “yesterday,” “today,” and “tomorrow.”

The tone voice table

The tone voice table contains the voice segments for ringback tone, busybacktone, and fast busyback tone.

3270 and custom servers

Custom servers and 3270 servers are programs that provide a bridge betweenWebSphere Voice Response and data that resides outside WebSphere VoiceResponse. The data can be on a remote host computer or on the same pSeriescomputer workstation as your WebSphere Voice Response software. The datacan 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 WebSphereVoice Response, or performs other processes, such as speech recognitionand text-to-speech, generation of fax output, or coordinated call and datatransfer.A custom server that uses the signaling interface, a specialized library of Csubroutines, is known as a signaling process. This is used to manage anexternal signaling device that controls or monitors telephony channels. Formore information, see the WebSphere Voice Response for AIX: Programming forthe Signaling Interface book.


v A 3270 server lets you access data on remote 3270 host computers. If youhave existing 3270 host applications that retrieve data needed by yourWebSphere Voice Response applications, you can create a 3270 server toobtain this data.

Access to remote data means that your voice applications can use this data toperform a variety of tasks, such as:v Read a file or database to retrieve information that a caller needsv Maintain or manipulate files based on a caller's requestv Obtain information from a combination of sources and business

applications on other host computersv Call another program to perform any predefined processv Perform calculations and return the result to the state tablev Generate business statistics based on telephony activityv Recognize spoken words using an external speech recognition serverv Speak words created by an external text-to-speech server or sent from

another WebSphere Voice Response systemv Generate fax output.

Both 3270 servers and custom servers must be invoked from a state table,which controls the dialog with the caller.

3270 serversA 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. A3270 server uses these screen images to interact with the host application bysending data to the application in screen input fields, and reading the dataretrieved by the application from screen output fields. When a voiceapplication sends a request to a 3270 server, the 3270 server sends theappropriate screen definitions to the host application to start the application,provide input data, and retrieve output data. It then sends the output to thecalling voice application.

3270 scripts

The logic of a 3270 server is defined in script language, a set of statements thatinstructs the server what to do. The WebSphere Voice Response for AIX: 3270Servers book contains descriptions of each WebSphere Voice Response scriptlanguage statement. The statements can accept parameters, check certainconditions, use the screen definitions to retrieve data from the hostapplications, and send the data back to your WebSphere Voice Response voice


application. A set of script language statements is commonly referred to as ascript. A 3270 server may consist of one or more scripts, depending on thecomplexity of the required host interaction.

The script uses the screen definition to ensure that the correct screen isdisplayed and then retrieves the data.

Scripts interface with WebSphere Voice Response state tables and other scriptsby passing input and output parameters. The input parameters receive thedata from the calling state table or script. The output parameters contain thedata to be returned to the calling state table or script.

Refer to the WebSphere Voice Response for AIX: 3270 Servers book for guidanceabout creating a 3270 server and for language reference information.

Custom serversCustom 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 requestedfrom incoming calls.

v Applications that are initiated by other means under your control, such asanother program or a timed event. This type is useful for processes likeoutbound calling, invoking a state table which might then call other customservers and state tables.

A custom server consists of a main function 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 serversubroutines. If the main function is system-generated, you must develop userfunctions to support your WebSphere Voice Response application. The mainfunction that the system generates can pass required information betweenuser functions and WebSphere Voice Response and perform other processes. Ifyou create the main function yourself, user functions are optional, dependingon the requirements of your custom server.

The capabilities of a custom server are limited only by the resources of thepSeries computer and the connectivity options at your site. You cancommunicate with other systems such as the IBM System/36, or the AppleMacintosh, Hewlett Packard, or DEC personal computers, using anycommunications protocol supported by the pSeries computer (refer to the AIX:Communications Programming Concepts for RISC System/6000 manual forinformation about communications protocols).


Refer to the WebSphere Voice Response for AIX: Custom Servers book forguidance about creating a custom server and for language referenceinformation.

Further information

For procedural and language reference information, see the followingmanuals: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


Chapter 5. Creating an application profile

You need to create an application profile for any state table that is to beinvoked in response to an incoming call or by another state table specifyingthe profile name, or to define one or more mailboxes for an application.

This chapter introduces application profiles and describes how to create them.

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 ameaningful string of characters.

v A unique digit name, which can be used by callers and applications toidentify the profile. WebSphere Voice Response creates the digit name bytranslating the application profile name into digits.

v A unique application profile ID, which is used by WebSphere VoiceResponse to find the state table to answer an incoming call. You specify theID, 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 invokedonly 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 (forexample, specifying different entry points, languages, or mailbox details).

v The language in which prompts are initially to be played. You can specifydifferent application profiles for each language, each specifying the samestate table. Because the state table uses the language specified by theapplication profile, this makes your state tables potentially multilingual. Todo this, you have to provide different variants of the prompts andtranslations of the voice segments, but the state table can be identical for alllanguages.


v Mailbox definitions and other voice messaging information, describedfurther in “What mailbox information does the application profile include?”on page 167. This information defines voice mailboxes for voice messagingapplications that require them.

An application profile is required for a state table that is to respond toincoming calls, and is required for voice messaging. Application profiles arenot required for other state tables.

How to create an application profile

The three methods for creating application profiles are described.v Start from the Application window (see Figure 4 on page 31), which

displays the other objects in your application (see Chapter 3, “Creating andmanaging application objects,” on page 27). In the Application windowclick Object —> New —> Application Profile . The advantage of thismethod is that the resulting application profile is created in the sameapplication. 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 Userapplication and can then be moved to the appropriate application, ifnecessary.


1. Naming the profile : Type a unique name in the Name field. The namecan be up to 50 characters long, including blanks.As you type, you’ll see digits appearing in the Digit Name field. This isthe numeric equivalent of the name. The digit name is used by theGetFindName action to find an application profile that matches digitskeyed in by the caller. You need to be aware that the digit name is usedin this way, to help you determine what profile names should beallowed. You can’t have two profile names whose corresponding digitnames are the same, because each digit name must be unique.For example, if you have a profile called AAA, you cannot have a profilecalled BBB unless A and B are mapped to different keys on the telephonekeypad. (For more information, see “Entering data (multiple keys)” onpage 119.)

2. Specifying the initial state table for the application : Click the StateTable pushbutton.The system lists all validated state tables.

3. Click the appropriate state table. If you have implemented yourapplication as a set of state tables, click the main state table that includesthe first part of the interaction with the caller.

4. Click OK.5. 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 statetable has more than one entry point, the Entry Point is Undefined, inwhich case you must specify one. 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.

Chapter 5. Creating an application profile 91

7. Click OK.8. Changing the language (optional): The language listed is the language

identified as the language specified in the administrator profile for the IDyou used to log on. The language specifies which language database touse. The state table can be the same for all languages: only theapplication profiles, prompts, and voice segments arelanguage-specific.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.11. Specifying subscriber classes (optional): Subscriber classes are used for

controlling the use of mailboxes.Click the Subscriber Classes pushbutton.The system lists the subscriber classes.

12. Click a subscriber class.13. Click OK.14. Entering the profile ID: Click File —> Save.

The system prompts you for a profile ID.

The profile ID can be up to 20 characters long and can include anycharacters valid for a telephone number (the digits 0 through 9 and theletters A, B, C, and D). WebSphere Voice Response does not accept blanksor special characters as part of the profile ID.The profile ID depends on how you intend the application profile to beused: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 reachthis application (the called number).


v For a state table to be used to handle all incoming calls on a specificchannel, or channels, when the called number is unavailable, it shouldbe the channel identification, as specified in the Pack Configurationwindow.

v For a state table to be used if an application profile matching the callednumber or the channel identification cannot be found, it should be thevalue of the System Default Application Profile parameter.

v If the application profile is not to be used to identify a state table tohandle incoming calls, you can choose any valid value to identify it.

Note: In a voice mail system, the profile ID is typically the extensionnumber of the subscriber, and the state table is the main state table ofthe 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 ApplicationProfiles window. If you have more this number, use the command linetool wvrapplprof to manage the application profiles, as described in“wvrapplprof command” on page 94.


The Application Profile window is still open, so that you can createfurther application profiles or, if necessary, continue with the procedurein “Creating mailboxes for application use” on page 170. (If you prefer,you can add mailboxes later.)

Note: You can create a profile to use as a template, editing it and savingit as a new profile when necessary.

Using the command lineYou can perform the same functions of managing profiles and mailboxes asthe graphical user interface, by using the wvrapplprof and wvrmailboxcommands. Refer to the WebSphere Voice Response for AIX: User Interface Guidebook.

wvrapplprof command

Purpose

List application profiles, or view details of, add, change, delete, or copy, anapplication profile. Note that this command does not allow you to modify anyof the mailbox properties or options.

Syntaxwvrapplprof

{ -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 anidentical profile identified by -O target_profile_ID.

-d Delete the application profile identified by profile_ID. The -N flag can


optionally be specified to help prevent inadvertent deletion of thewrong profile. Both profile_ID and profile_name must match those ofthe profile for it to be deleted.

-h Display help for the command

-l List all the application profiles whose profile IDs match theprofile_ID_spec, or the profile_name_spec. These specifications caninclude percent (%) signs to indicate zero or more characters, orunderscore to specify a single character. To list all application profileson the system, use wvrapplprof -l -I all

-m Modify the application profile identified by profile_ID, as specified bythe other parameters.

-n Create a new application profile identified by profile_ID.

-v View the details of the application profile identified by profile_ID orprofile_name.

-? Display syntax of the command

Attribute flags

All attribute flags are uppercase.

-B The number of active mailboxes to be initially associated with thisapplication profile. Mailboxes are numbered sequentially from 1 up toa maximum of 10. For example, if you specify -B5, mailboxes from 1to 5 are created and activated. Mailboxes from 6 to 10 will not exist.See “wvrmailbox command” on page 177 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, tobe used by the active mailboxes associated with this applicationprofile.

-I The profile ID of the application profile.

-L The language in which the state table is to be run. A number in therange 1 to 255. Here is a list of example language numbers:

1 = US English2 = Belgian Dutch3 = Belgian French4 = Canadian French5 = Danish6 = Finnish7 = Swedish


8 = French9 = German10 = Italian11 = Netherlands Dutch12 = Norwegian13 = Portuguese14 = Spanish15 = Swiss French16 = Swiss German17 = UK English18 = Icelandic19 = Greek20 = Turkish101 = US English TDD

Other numbers can be created by the user. To find out what thenumbers of the installed languages are, click Languages in theConfiguration window.

-N The name of the application profile.

-O The output profile ID when copying an application profile (this is theletter '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, witha profile name "newapp":wvrapplprof -c -I 123456 -O 998877 -N newapp

Delete the application profile 123456:wvrapplprof -d -I 123456

List all application profiles:wvrapplprof -l -I all

List all application profiles whose profile IDs begin 9988:wvrapplprof -l -I 9988%

List all application profiles whose names contain Saver:wvrapplprof -l -N %Saver%

Modify the application profile 123456, changing its language to French:wvrapplprof -m -I 123456 -L 8


Create a new application profile 665123, specifying only the mandatoryparameters:wvrapplprof -n -I 665123 -N accounts -S AVF_Main -E start

View the details of application profile whose name is Banking:wvrapplprof -v -N Banking

View the details of application profile 123456:wvrapplprof -v -I 123456


Part 2. Design topics


Chapter 6. Creating the voice output for voice applications

How to create voice output for voice applications and an overview of voicesignal processing.

This chapter provides information about:v “Overview of voice signal processing”v “Planning your voice segments” on page 103v “The voice segment database” on page 112v “Creating prompts” on page 113v “Creating multilingual applications” on page 117

Overview of voice signal processing

Normally, voice is transmitted to the human ear by means of an acousticwave travelling through the air at the speed of sound. A conventional analogtelephone transmits sound through a wire as an electrical signal which travelsat close to the speed of light. To do this, the acoustic signal generated by thehuman vocal chords must first be converted to an electrical signal, and thenconverted back to an acoustic form before it can be heard by the human ear.These two conversions are done by a telephone mouthpiece and earpiecerespectively.

The electrical signal sent over the telephone wire for a conventional telephoneis of an analog form. That is, it is represented as a voltage which variescontinuously in a given range (for example, 0 to 1 volt) where the louder thesignal, the higher the voltage. The normal electrical signal is described asanalog because the voltage can take any value in the possible range, that is aninfinite number of possible values. As well as the signal varying continuouslyin the voltage limits, an analog signal is able to vary continuously over timewith no requirement to change only at fixed time intervals.

Although analog signals are the easiest to handle in a simple telephonesystem, they give rise to a number of problems if they are to be stored orprocessed by computer or if they are to be sent over a long distance. Sendingan analog signal over long distances rapidly decreases the signal strength, andcan increase background noise level, both of which lead to severe qualitydegradation. For these reasons, almost all modern telephone systems arebased on the concept of digital processing of voice, where the signal isconverted to a form which can be handled by standard digital computers as asequence 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 tomultiplying every number in a spreadsheet by a certain value.

To convert an analog signal into a digital form two steps are needed:

First, the analog signal is sampled at a fixed rate to break it into a sequence ofanalog samples which can be handled individually. For the highest possibleaudio quality (such as CD audio), the sampling rate is usually very high, thatis 44,000 times per second (44 kHz), whereas for the telephone, where a muchlower voice quality is acceptable, the sampling rate is only 8,000 times persecond (8 kHz). This is a fixed sampling rate now used by all telephonesystems of the world.

Note: The sampling rate is one factor limiting the voice quality that can beachieved over a telephone link as it limits the frequency response (the highestaudio signal that can be carried) to one half of the sampling rate, that is4 kHz. The human ear can detect frequencies up to about 18 kHz; dogs andbats can detect even higher frequencies.

Second, each analog sample is converted to a number to allow it be handledby the digital computer. For example, if the input signal has a range of 0 to 1volt and 16-bit numbers are used to represent the digital form of each signalsample, the digital value 0 would represent 0 volts, the digital value 65535would represent 1 volt with a linear sliding scale for intermediate values (forexample, 32767 = 0.5 volt).

Note: Analog voltages are more usually transmitted with a center value ofzero and, say, maximum and minimum values of +0.5 volt and -0.5 voltrespectively. This corresponds with a two's complement digital numberingsystem which can, for 16-bit values, range from +32767 down to -32768 with acenter value of zero.

A special technique known as companding is used to reduce the number of bitsfor each voice sample from 16 to 8 bits. This halves the amount of data to beprocessed and stored. Companding applies a logarithmic conversion to eachsample, 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, transmittedand processed, and a reverse (anti-log) process applied to the signal at thereceiver 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 notcompatible, they must be converted to move from one to the other.


When WebSphere Voice Response plays voice to, or records voice from, thetelephone line, it is at the standard 8 kHz 8-bit rate (µ-law for T1, A-law forE1). 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 VoiceResponse applies a compression algorithm to the signal to reduce its size by afactor of five. When compressed voice is played to the line, WebSphere VoiceResponse 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 verygood quality at a compression ratio of five to one, that is the data rate isreduced to 1600 bytes per second. Other compression techniques, such asADPCM, are also used in the voice processing industry to reduce the size ofvoice data. WebSphere Voice Response uses only the five to one GSMcompression 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. Thedisadvantage of compressed voice is that the quality of voice is slightlyreduced. 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 isas high as possible (see the WebSphere Voice Response for AIX: ApplicationDevelopment using State Tables book).

Planning your voice segments

Step-by-step instructions on how to create voice segments are given later inthis chapter, but there are different approaches to this, so it is worthwhiletaking 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 amicrophone and an audio adapter such as the Ultimedia AudioAdapter 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 toconvert the format of the voice data after transfer.

Chapter 6. Creating the voice output for voice applications 103

4. If using a microphone directly or transferring voice data from a recordingstudio, decide how to import segments into the WebSphere Voice Responsevoice segment database. There are two methods:v The Voice Segments window (select the voice segment in the

Application window and open it)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 VoiceImport (BVI) utility to import voice data created on another system. The voicesegment editor supports only raw unformatted voice data files, the BVI utilitysupports .wav files and audio interchange file format (AIFF) files. Table 4shows you which tool to use.

Table 4. Creating voice segments for WebSphere Voice Response

Source ToolUltimedia AudioAdapter 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 audiofile

Voice segment editor No

Windows .wav file BVI utility No

Apple Macintosh AIFF file BVI utility No

Other file format Custom server you havewritten. (Not supplied withWebSphere Voice Response)

No

Note:

1. Although the voice segment editor can be used to import multiple voicesegments, depending on the number of voice segments, you might find itquicker to use the BVI utility.

2. The voice segment editor and the BVI utility both support only IBM audioadapters for direct input of voice from microphone, tape recorder, and soon. For PCI pSeries computers, you might or might not have the audiofunction available on the planar (there is currently no PCI plug-in audioboard).If you do not have audio on your PCI pSeries computer, you can recordvoice segments in one of the following ways:


v Using the telephonev Using another pSeries computer with a Ultimedia Audio Adapter

installedv Using a separate personal computer with an industry audio adapter,

and import standard audio files (such as .wav) using Batch VoiceImport.

3. To import audio files from other computers, use either the TCP/IP filetransfer program (FTP) over a LAN or other network, or use a removablestorage device, such as a tape. You might find tape more convenient tomove bulk voice data to your pSeries computer.

4. For top-quality audio segments, we recommend that you record your voicesegments in a professional recording studio, then either import a digitalfile (.wav or .aiff) or use digital audio tape.

CompressionWhen you store a voice segment in the database, you can save it incompressed format, uncompressed format, or both. WebSphere Voice Responseuses a compression algorithm derived from the Groupe Speciale Mobile(GSM) digital mobile phone system, which gives high-quality voice suitablefor telephony applications. Saving voice segments in a compressed formatsaves disk space and bus bandwidth (the compression ratio is 5:1), but tendsto cause a slight loss of sound quality. If you compress a voice segment, thenuncompress it, the sound quality of the resulting voice segment will not beequivalent 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 soundquality, choose uncompressed format.

You can mix compressed and uncompressed voice segments in the sameapplication using the System : PlayPrompt voice compression type systemvariable (SV182) to specify the compression type (or the System : Voicesegment compression type system variable (SV50) if you are using thePlayVoiceSegment action). You might, for example, use uncompressedsegments in the opening dialog and most frequently used menus, to give agood impression, but use compressed segments for less frequently used, orless essential, information.

Note: If you use uncompressed voice segments with the PlayVoiceSegmentaction, this produces more network traffic when your WebSphere VoiceResponse system is part of a single system image. This is because thePlayVoiceSegment action has to retrieve the segment from the database everytime it plays the segment.


Recording voice segments over the telephoneThis does not always give the highest quality sound, and should be used forprototyping and testing rather than for production applications. To record viathe telephone you use the Record_Comp or the Record_Uncomp voiceapplications supplied with the base WebSphere Voice Response system.

The segments recorded using Record_Comp are stored by default ascompressed voice segments. The segments recorded using Record_Uncomp arestored by default as uncompressed voice segments.

The files for the applications are automatically imported into a directory atinstallation time, but, if they get corrupted by mistake, you can reimport themfrom /usr/lpp/dirTalk/sw/samples/BaseData.imp.

Before anyone can use either application, you must create an applicationprofile that allows people to access it over the telephone. In the profile,specify the language in which you intend to record segments. Otherwise, thevoice segments are stored in the wrong database. You can create anapplication 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 systemdirectory. The WebSphere Voice Response for AIX: Application Development usingState 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 8kHz 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 samplingrates other than 8 kHz when recording new voice segments using the VoiceSegment 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 intoWebSphere Voice Response in 16-bit PCM (linear) format at an 8 kHzsampling rate. To do this, use studio-quality DAT tape through the line-in ofthe Ultimedia adapter with the Ultimedia format set to 16-bit PCM.Alternatively, you may already have 16-bit PCM voice segments as files thatcan be imported directly into the Voice Segment Editor. The editor can changesampling rates are required, although slight distortion will usually result from


a change in sampling rate. You should therefore always use an 8 kHzsampling rate for imported voice data if possible.

Dynamic range

When using the voice segment editor or the batch voice input utility to recordvoice segments via the Ultimedia adapter with an audio source connected tothe its line input, you may find that the audio signal is relatively smallcompared to the available ‘dynamic range’. 16-bit PCM allows signal levels ofup to 32K, whereas typical input signals from the Ultimedia adapter mayhave an amplitude of around 2K. When using 5:1 compression, the bestquality is obtained if the input signal occupies as much of the 32K range aspossible without signal peaks exceeding the available limits. This can be donewith an external preamplifier or by using the MAXIMIZE option of the voicesegment editor or batch voice input utility which digitally scales the inputsignal to occupy 90% of the full range.

Note that the maximize button of the voice segment editor is only enabledwhen operating in 16-bit PCM mode.

Filters

When you record a high-quality input signal for use over the telephone, it isnecessary to filter out all frequencies above 4 kHz to allow transmission at thedigital 8 kHz rate. (The voice segment editor does this automatically when itstores the segment in the database.) Loss of these high frequencies can makethe signal sound relatively dull. You can improve this by using the Boostbutton of the voice segment editor before saving the recorded segment. Thisincreases 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 2dB. An identical effect can be achieved with the “Boost” option of the batchvoice 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 whenoperating in 16-bit PCM mode.

Recording directly using a microphone

A direct microphone input can provide excellent quality input. However, thepSeries computer must be within 10-15 feet (maximum) of the microphone inorder to minimize electrical noise pick-up. This may be difficult to achieve ina studio environment because fan and disk noise prohibit the pSeriescomputer from being in the same room as the microphone.


Using a recording studio

For the best results when recording voice segments, keep to the followingrules: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 thehighest 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 noisegenerated by cooling fans in machines such as personal computers, shouldbe avoided.

v If you are editing segments in the studio, do not put absolute silencebetween segments, as this sounds unnatural. Instead, insert room-tonesilence breaks (background studio ambient sound).

v Half a second of silence at the beginning and end of each segment isrecommended.

v Record segments as a continuous stream of audio with a silence gapbetween consecutive segments. The recommended silence gap is fiveseconds, because this allows the batch voice import utility to distinguish thesilence gaps between segments from the natural gaps that occur withinsegments.

v If a mistake is made during the recording of a segment, just stop, wait forfive seconds (or whatever inter-segment gap you have decided to use) andthen re-record the segment. Bad segments can be removed by the voicesegment editor or the batch voice import utility.

If you are working with a studio which has reasonably sophisticated audioprocessing capabilities, it is wise to apply the audio boost function at sourcerather than with batch voice import utility. The best frequency-shapingfunction to apply is defined in the ITU P-Series Blue Book (Volume 5 1988) inSupplement No. 10 (P332). This is the preferred response for a telephonemicrophone as determined by user trials, and can be applied to flat-spectrumaudio, achieving the same results as if the voice was being spoken through atelephone.

The frequency shaping function recommended by the ITU boosts the trebleand cuts the bass in a signal in order to restore some of the brightness lostwhen a full-bandwidth audio signal is low-pass filtered at 3400 Hz prior tosampling at 8 kHz and is similar to the BOOST option of the voice segmenteditor or the batch voice import utility. Be sure that the shaping is not doneboth in the studio and by one or other of WebSphere Voice Response’s voiceutilities.

The ITU-recommended frequency response characteristic is as follows:


v 0 dB reference at 1kHzv Under 1kHz, 4 dB/octave roll-off to 200 Hzv Below 200 Hz, 8 dB/octave roll-offv Above 1kHz, smooth increase to +7 dB peak at 2600 Hz.v Sharp cutoff at 3.4kHz

Responses for spot frequencies are shown in Table 5.

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 utilityv Filter the signal using a graphic equalizer before the it reaches the

Ultimedia adapter.

Transferring the prerecorded data to WebSphere Voice Responsev Direct transfer from the studiov Diskette or other removable storage devicev Digital Audio Tape (DAT)v Analog Tapev Microphone

Direct transfer from the studio

Most recording studios use specialized voice processing systems forprocessing audio data. The best possible method for moving this data from


the studio system to the WebSphere Voice Response system is direct filetransfer across a network (for example, using TCP/IP FTP). If you transferdigital data directly, when using the batch voice import utility, you shouldbypass 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 is100% digital. If the recording studio uses Apple Macintosh basedsound-processing applications, you can use Apple’s system extension,Macintosh PC Exchange, or an equivalent product, to format a Macintoshdiskette so that it can be read by a pSeries computer. Write a diskette in aDOS 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 astudio to the pSeries computer. However, there is currently no method oftaking a digital output from a DAT player and transferring it directly into thepSeries computer without translating to analog and back again, using theUltimedia Audio Adapter. The digital-to-analog and analog-to-digitalconversions always introduce some low-level noise and distortion, but theseare usually negligible for a system with optimum input level.

Analog tape

This is not recommended, because analog tape, even of the highest quality onthe best audio equipment, can introduce low-level noise that can cause voicequality problems especially with compressed data. The compression algorithmoperates best with a noise-free input signal. However, if you have noalternative, write a tape in AIX format and then copy data directly from it intothe AIX file system.

Converting voice data transferred from non-AIX computer systemsYou can transfer audio data from other systems provided that you can get theaudio data into the AIX file system. The audio data can be in one of thefollowing formats:

“Raw” (unformatted) data

The data must be stored in the file in the following format:v Single channelv Linearly encoded PCM 16-bit samples (two’s complement)


v 8 kHz sampling ratev 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 requiredformat for processing by bvi_seg. It takes an input file specified as aparameter and generates a file whose name is specified in the bvi.control fileby the VOICE_FILE_NAME parameter. The AIFF file must be written in thefollowing format:v Single channelv 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 withan extension of .wav) into the required format for processing by bvi_seg. Ittakes an input file specified as a parameter and generates a file whose name isspecified in the bvi.control file using the VOICE_FILE_NAME parameter. TheWAV file must be written in the following format:v Single channelv 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 segmentsThe WebSphere Voice Response database only allows voice data to be storedat 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 doneautomatically when you save a segment as either uncompressed orcompressed. Note that converting from 16-bit PCM to 8-bit A-law or µ-lawand back will degrade voice quality, as will compressing and uncompressingvoice data. To save voice data for future use, always save it in 16-bit mode toan AIX file using the voice segment editor Export function. Don’t just save itin the WebSphere Voice Response voice segment database.


To find out more about the batch voice import process, see the WebSphereVoice Response for AIX: Application Development using State Tables. If you haveonly a few voice segments to record, use the Voice Segments window (alsodocumented in the WebSphere Voice Response for AIX: Application Developmentusing 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 VoiceSegments window convenient, but if you are dealing with many voicesegments, you will probably find it worthwhile to use the batch voice importprocess. Both processes allow you a choice of different input media.

The voice segment database

There is a voice segment database for each language. By creating anapplication profile for each language, you can make the same applicationwork with different languages.

Each voice segment has:

v A segment ID

v A description

v Digitized audio data in eithercompressed or uncompressedformat, or both.

Each voice segment is stored in avoice directory, and can also bereferenced by one or more voicetables.

A voice directory has:

v A name

v A voice directory ID (retainedonly for compatibility withearlier releases)

The voice directory must existbefore you create the voicesegment.

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. Voicetables are particularly useful if you have applications that use voicesegments which can be referenced using an index value, such as thespoken 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 aprompt directory. All prompts used by a state table must be in the same promptdirectory. Different state tables can use the same prompt directory.

If a state table uses its own prompt directory, you can use the system promptsby creating new prompts that call the system prompts (using the SYSPROMPTprompt statement).

Note: System prompts cannot be exported as a dependency of anotherapplication object (for example, a state table), so we recommend that youdon’t use the System_Macros prompt directory for application specific, oruser, prompts. You can distribute changes to system prompts only byexplicitly exporting them and importing them to another system.

If you want to store the prompts in a new, rather than an existing, promptdirectory, the first step is to create the new prompt directory. Then, you createthe prompts by defining new prompts, copying existing prompts, orimporting prompts. You can edit the prompt statements that comprise theprompts that you create.

About creating prompt directoriesBefore you can save a prompt, the prompt directory to which it belongs mustexist. A prompt directory is referred to by a prompt directory name. You mustspecify a default compression type for playing the voice segments included inthe 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 thePlayPrompt action. A value of 0 specifies that the clear channel version of thesegments is to be played; a value of 2 specifies that the compressed version isto be played; and a value of -1 indicates that the default compression type isto be used.

A prompt can play audio names and greetings.

About defining promptsPrompts are constructed using the prompt statements described in theWebSphere Voice Response for AIX: Application Development using State Tables. Aprompt statement can use any of the following elements to define what acaller will hear:v Voice segments (stored in voice directories or voice tables)v Greetings


v Audio namesv Other promptsv Parameters passed from the calling state tablev System variables or local variablesv Conditional tests that determine what should happen in different cases

For examples of prompts, look at the system prompts that are delivered withWebSphere Voice Response in the System prompt directory. For moreinformation about the system prompts, see “System prompts” on page 75.

Default and language-specific promptsEach new prompt that you create is called a default prompt. A default promptis language-independent. If the logic of a particular prompt does not changefrom 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 theprompt, but you will not need to alter the prompt itself.

Only one language can be active at any one point during the execution of avoice application. The active language is identified by the value inthe System : Current language system variable (SV39). When the promptreferences a voice segment, it uses the segment ID and voice directory nameto locate the required segment in the active language. As long as the ID for aparticular voice segment is not changed when the segment is translated intoother 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 specificlanguage. For example, the system prompt that speaks the date (Date) usesU.S. English syntax to play the month, followed by the day spoken as anordinal quantity, followed by the year. In other languages, the date syntaxmay be different. For example, the German version of Date will need to playthe day, followed by the month, followed by the year. In such cases, you willneed to create a language-specific version of the default prompt. Thelanguage-specific prompt for a particular language will be used instead of thedefault prompt when that language is the active language for the currentlyexecuting voice application. The inputs to the language-specific and defaultversions of a prompt, if any, must match exactly in number and type. Refer to“Using languages other than U.S. English” on page 115 for information aboutmodifying the system prompts for other languages.

All default and corresponding language-specific prompts for a state table arestored in the same prompt directory. When a state table encounters aPlayPrompt action, the system searches the specified prompt directory for theprompt to be played. If a language-specific version of the prompt exists forthe active language, that version is played; otherwise, the default version ofthe prompt is played.


Using languages other than U.S. EnglishWhen it has been installed, WebSphere Voice Response is ready to work inU.S. English. If you want to use other languages in your voice responseservices, 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 AIXInstallation Guide).

2. Install the optional fileset that contains the system prompts and voicesegments for the languages you need (see the WebSphere Voice Response forAIX: Installation book). If the system prompts are not supplied in thelanguages you require, you may have to select one of the suppliedlanguages, and then make modifications to suit your language (see“Modifying the system prompts for other languages”).

3. Establish a database for the new language (refer to the WebSphere VoiceResponse for AIX: Configuring the System book)

4. If your language was supplied in an optional fileset, import theappropriate 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 promptsv The System voice directory containing language-specific voice segmentsv Language-specific voice tables

Modifying the system prompts for other languages

The prompts that are supplied in the System prompt directory are describedin “System prompts” on page 75. To modify the system prompts, you must befamiliar with programming logic and with the prompt statements described inthe WebSphere Voice Response for AIX: Application Development using State Tablesbook.

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 Numbersv Divisorv Ordinalv Time_Of_Dayv Month_Of_Year

7. Make a list of the voice segments that will need to be changed or addedto each of the voice tables. Make sure all of these voice segments are onthe list you made in Step 5 on page 115.

8. Record the voice segments for the system prompts in the new languageand also record any new segments (see the WebSphere Voice Response forAIX: Application Development using State Tables).

9. Modify the system voice tables to include any new voice segments (seethe WebSphere Voice Response for AIX: Application Development using StateTables book).

10. Edit the system prompts to play voice segments using the correct syntax(see the WebSphere Voice Response for AIX: Application Development usingState Tables book).

Refer to “Creating multilingual applications” on page 117 for informationabout using the system prompts that you have created for the new language.

Modifying the system voice tablesSome of the system prompts invoke voice segments using the Table promptstatement. One of the parameters of the Table statement identifies the table inwhich the required segments are cataloged. For example, Small_number callsthe voice segments that play numbers using the Table statement, with theNumbers table as a parameter. If you record a new number for Small_numberto play and do not add it to the Numbers table, Small_number fails when ittries to play it. In this case, you must either add the new voice segment to theNumbers table or edit Small_number so that it no longer uses the Tablestatement.

The other system prompts invoke voice segments using the Voice promptstatement. One of the parameters of the Voice statement identifies thedirectory (in this case, the System voice directory) in which the requiredsegments are stored. As long as the voice segments you record are stored inthe System voice directory for the language specified in the applicationprofile, these prompts will be able to locate them.

If you create additional voice segments for use by one of the prompts thatincludes a Table statement, either catalog it in the voice table that is theparameter for the statement, or edit the prompt to use the Voice statement


instead. The WebSphere Voice Response for AIX: Application Development usingState 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 addvoice segments to the table.

Editing the system promptsIn some languages, the logic of a system prompt may need to be altered, forexample, the Date system prompt which plays the date using U.S. Englishsyntax. Before you start editing the system prompts, make sure you arefamiliar with the information in “System prompts” on page 75.

Some of the system prompts rely on other system prompts, so make sure youedit the prompts in the following order:1. Small_number2. Whole_number3. Real_number4. Ordinal5. Date6. Time7. Currency

The Phone prompt does not rely on any other prompts.

Refer to the procedures in the WebSphere Voice Response for AIX: ApplicationDevelopment using State Tables for instructions about defining alanguage-specific prompt.

Creating multilingual applications

You can create a voice database for each language, dialect, or regional accentyou want to use for voice output. You can even use different voice databasesfor different voices speaking the same voice segments in the same language.You also create a voice database for each TDD language to be used fortelephony devices for the deaf.

Using application profilesTypically, multilingual applications are set up by defining a differentapplication profile for each language. Thus, callers dial different numbersaccording to the language to be used, or you can call the state table byapplication profile, depending on a choice that the caller has made. Eachprofile refers to the same state table, but a different language is specified. TheApplication : Language system variable (SV142) contains the code for thelanguage specified in the application profile. The System : Current languagesystem variable (SV39) is also initially set to this value.


Using the System: Current language system variableIf the language defined for the application profile does not specify therequired language, you can change the value of the System : Currentlanguage 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 torequest a specific language (“Por español, prensa el uno... ...for English, presstwo... ...pour Français, appuyez sur trois... ...Für Deutsch, bitte drücken Sie aufdie Vier.”) Then set the System : Current language system variable (SV39) tothe code for the language chosen (the codes are listed in the Languageswindow (Configuration —> Languages). The value of SV39 specifies whichlanguage database is to be used for prompts.


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 multiplekeys (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. Toindicate that the caller has finished entering data, the last key pressed must bethe key specified by the Enter Key system parameter in the Application ServerInterface parameter group. The default is # (pound or hash).

The GetFindName action allows you retrieve an application profile whosedigit name matches a sequence of key presses from the caller. The digit nameis the numeric equivalent of the application profile ID. Again, the Enter Key isused to indicate the end of the data entry, and the Stop Key allows the callerto cancel the entry and start again. The default value for the Stop Key systemparameter is * (star).

The GetFindData action allows you to pass a sequence of key presses from thecaller to a custom server or 3270 server, to retrieve information. Again, theEnter Key is used to indicate the end of the data entry, and the Stop Keyallows the caller to cancel the entry and start again. The default value for theStop Key system parameter is * (star).

Alphabetic to numeric key mapping

Alphabetic characters are assigned to the keys on the keypad, so that callerscan enter alphabetic data if necessary. You can change the character-to-keyassignments 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 meansthe prompt is always played through to the end. If you do not specify forceplay, the caller can interrupt the prompt by pressing a DTMF key. You canspecify that the caller can use any DTMF key to interrupt the prompt, or thatthey can use only one of a set of keys that you define.

The caller can also interrupt the prompt by speaking. For more information onthis, see “Voice interrupt detection” on page 122.

The PlayVoiceFromHost action can also be interruptible or force played. Inaddition, you can specify that it can either be interrupted by any key or onlyby the Pause and Stop Keys.

During the PlayAudioName, PlayUserGreeting, PlayVoiceSegment, andPlayVoiceMessage, 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 thesystem parameters in the Application Server Interface parameter group.


Chapter 8. Handling spoken input from callers

Speech recognition means that you can write voice applications that take actionbased on spoken input from the caller.

You can implement speech recognition in your applications in two ways:v By sending commands from the state table to a custom server that

interfaces with a speech recognizer. As an example, the custom server couldbe a DVT_Client—see “Speech recognition with distributed voicetechnologies” below.

v By using a VoiceXML application—refer to the WebSphere Voice Response forAIX: VoiceXML Programmer's Guide for further information.

Speech recognition with distributed voice technologies

The distributed voice technologies (DVT) subsystem provides support forcommunication with speech recognition technologies. The DVT subsystemincludes a fully functional custom server that passes data from your statetable to a speech recognizer.

Using the DVT subsystem, WebSphere Voice Response can be integrated withTDM-based DSP or software-based speech recognition products. For moreinformation, ask your IBM representative for the WebSphere Voice Response forAIX: Distributed Voice Technologies Integrator’s Guide.

Barge-in, voice interrupt detection, and echo cancellation

When handling spoken input, it is important to understand these threeconcepts:v “Barge-in”v “Voice interrupt detection” on page 122v “Echo cancellation” on page 123

Barge-inBarge-in, properly referred to as full-duplex barge-in, allows voice data to berecorded from the voice channel at the same time as voice data is beingplayed in the opposite direction; voice data is going both ways at the sametime, just as it is when two people are having a conversation and both arespeaking at once. The most important use of barge-in is to allow spoken inputto be sent to a speech recognizer while a prompt is being played.


Essentially, to implement barge-in, you start a recognition session beforebeginning to play the prompt. You can use barge-in either with or withoutvoice interrupt detection, depending on the needs of your application. Withvoice interrupt detection, the prompt stops as soon as the caller speaks, evenif the word is not in the expected vocabulary. Without voice interruptdetection, the prompt continues until a custom server event happens (forexample, when an utterance is recognized) or to the end.

Voice interrupt detectionVoice interrupt detection allows a caller to interrupt the playing of a prompt ora voice segment by speaking. This can be used in an application with speechrecognition or it can be used on its own.

If callers are using speech recognition rather than key input to interact withthe voice application, voice interrupt detection is particularly useful. It can,however be used independently of speech recognition; you do not have toimplement speech recognition to enable voice interrupt detection. And, ofcourse, you can use voice interrupt detection, and speech recognition, in anycombination along with DTMF-key input.

With DTMF-keys, the application can allow callers to interrupt prompts orvoice segments while they are being played. On the PlayPrompt andPlayVoiceFromHost actions, if you don’t select Force Play when you definethe 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


In the same way, if you enable voice interrupt detection in an application, thecaller 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. Beaware that one of the drawbacks of using voice interrupt detection is that notall sounds picked up by the caller’s phone are intended to be interruptions. Innoisy environments it can be difficult to use an application that has voiceinterrupt detection enabled.

To turn on voice interrupt detection, set the System : Voice interruptdetection On/Off system variable (SV217) to 1. To turn it off (the default), setSV217 to 0.

For more information about voice interrupt detection, see Appendix B, “Voiceinterrupt detection: technical information,” on page 337.

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 isthrown away and is not passed on to the recognizer. Without barge-in, youcan let the caller stop the prompt and then start speaking the words to berecognized. Start the recognition session after the prompt has beeninterrupted. Play a pacing tone to let the caller know when the recognitionsession is ready to accept input.

In most applications, however, callers find this unnatural: they expect to beable to speak-ahead, in the same way that they can key-ahead in a key-basedapplication, with the word they utter during the prompt being passed on tothe recognizer. Voice interrupt detection is probably better used with barge-in,in speech recognition applications.

Echo cancellationBoth barge-in and voice interrupt detection are enhanced by echo cancellation,which filters out any echo of the prompt from the spoken input. Echocancellation is available to any custom server that records voice data from theline: it is not directly available to a state table.

Time

Prompt is playing

An utterance from thecaller stops the prompt,but is then discarded

Voice data can now besent to a speech recognizer

Figure 10. Voice interrupt detection with speech recognition

Chapter 8. Handling spoken input from callers 123

Calibration

Before using echo cancellation in a state table, you need to instruct WebSphereVoice Response to calibrate the echo canceller for the line being used. Theecho cancellation for DTTAs continues to monitor and reduce the echo whenany prompt or voice segment is played. It is therefore particularly suitable forsituations where the echo path is likely to change, for example when a call istransferred or when call tromboning is used.

The calibration is requested by the state table, before invoking a custom serverto begin recording voice data. Set the System : Echo Cancellation :Calibration system variable (SV231) to 1 and then use a PlayPrompt orPlayVoiceFromHost action to force play some uncompressed voice data. Theoutcome of the calibration is indicated by the value of SV231 following thePlay action; if the value is 2, the calibration was successful. If calibration wasunsuccessful, echo cancellation will not be used.

To ensure that the initial calibration of the echo cancellation for DTTAs willalways be successful, the duration of the uncompressed voice data used forcalibration must be at least 0.5 seconds, With DTTAs, echo cancellation isrecalibrated 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 calibrationwas successful, echo cancellation will be used.


Writing a custom server to handle speech recognition

If none of the speech recognition implementations offered with WebSphereVoice Response satisfy your requirements, you can write your own customserver to pass voice data to an external voice services system for speechrecognition. The custom server subroutines for voice handling aredocumented in the Custom Serversbook.

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

Chapter 8. Handling spoken input from callers 125

Contact your IBM representative for more information if you plan toimplement your own custom server for speech recognition.

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


Chapter 9. Accessing data with a 3270 or custom server

How to use WebSphere Voice Response state tables and state table actions toget a server to access data.

To invoke a server to access data, you must set up one or more WebSphereVoice 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.

Caller

LocalDatabase

TelephoneNetwork

VoiceProcessing

DataCommunications

Network

LocalArea

Network

Sun

HP

Macintosh

IBM PersonalComputer

CommunicationsFacility

3270Server

CustomServer

TCP/IPOSI

SNAASYNC

APPCX.25EthernetToken ring

Caller

TelephoneNetwork Caller

TelephoneNetwork

Caller

TelephoneNetwork

Caller

TelephoneNetwork

System/390

WebSphereVoice

Response

pSeries

Figure 13. Accessing data using custom servers and 3270 servers (for example, a system/390 server)


v GetFindData: Requests a list of items that match or begin with a specifiedgeneric key.

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 usingState Tables book for information about these actions.

Sample 3270 and custom servers

WebSphere Voice Response includes many custom servers, which performservices for state tables. The following are supplied in object code only:v DVT_Client: to send requests to speech recognition serversv CallPath_SigProc: to send requests to CallPath Server

The following are supplied in source form as well, so you can use them asexamples:v SpeechServer: to send requests to speech recognition serversv CustomServerSample.

In addition, the 3270ServerSample is also supplied in source form.

CustomServerSampleThe application called CustomServerSample contains two sample customservers. 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 book).3. Create an application profile for the SrvrSamp_Main state table with Start

as the entry point (see Chapter 5, “Creating an application profile,” onpage 89).

The CustomServerSample application comprises six state tables and twocustom 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 deletescheduled wakeup calls.

2. From the caller's input, the SrvrSamp_Main state table then invokes theSrvrSamp_Write, SrvrSamp_Read, SrvrSamp_Update, or


SrvrSamp_Delete state table to perform the appropriate function. Thecaller is prompted to input the phone number to make the wakeup call,the time to call (in 24 hour format), and an indication of whether this is aone-time call or a daily call. The CS_Request_Call custom server is usedto manipulate the corresponding database, based on the user inputs.

3. Whenever the database is modified, the CS_Wakeup_Call custom serverchecks it to determine the time of the next call. When it is time to makethe wakeup call, CS_Wakeup_Call opens a channel process link andrequests that the SrvrSamp_Wakeup state table be executed, which willmake the actual wakeup call. The SrvrSamp_Wakeup state table will playa wakeup greeting, then prompt the called party whether or not to use thesnooze feature to call again in 10 minutes.

3270ServerSampleThe application called 3270ServerSample contains a sample 3270 server. Beforeyou can use 3270ServerSample you must do the following:1. From the Welcome window, click on Configuration —> System

Configuration

2. Select Virtual Mode.

The sample server is just that, a sample. Unless your environment isidentical to the environment in which the sample was constructed, thesample can run only if you reconfigure the 3270 host connection tovirtual mode.If you try to run the sample server in a different environment in realmode, you will disable the 3270 sessions defined for it. Therefore, werecommend that you run the sample only in virtual mode or use it as anexample of the types of scripts and the kinds of logic you can include inthe 3270 servers you write.

3. Open Application Server Interface

4. Open 3270 Mode

5. Click Virtual Mode

6. Click OK.7. Before closing the System Configuration window, you need to Save the

new value.8. Finally, you must stop WebSphere Voice Response and start it again to

make the new value take effect.9. Import and install: Import the 3270ServerSample.imp file. The import file

is located in the /usr/lpp/dirTalk/sw/samples directory.10. Configure a session for use by the server. Use the instructions in

WebSphere Voice Response for AIX: Configuring the System to configure a3270 terminal session for use by the 3270ServerSample server.

11. Create an application profile for the SrvrSample_3270 state table (seeChapter 5, “Creating an application profile,” on page 89).

Chapter 9. Accessing data with a 3270 or custom server 129

Done: You can now run the 3270ServerSample application in virtual mode.

3270ServerSample is an example of a 3270 server that performs a simplequery of an account balance based on a 6-digit account number. The sampleincludes script language statements that facilitate operation of the script invirtual mode.

The SrvrSample_3270 state table

The state table SrvrSample_3270 plays the initial greeting and prompts thecaller to enter a 4-digit ID that identifies a valid application profile. The calleris allowed three attempts to enter a valid ID before the state table terminatesthe application with a good-bye message.

Upon registering a valid ID, the state table uses the OpenHostServerLink statetable action to call the 3270 server, SrvrSample_3270. The caller is thenprompted to enter the 6-digit account number of the account to be queried. Ifthe sample is run in virtual mode, interaction is not with real host screens butwith screens stored in the WebSphere Voice Response database. Consequently,the list of valid account numbers in virtual mode is limited to those presenton the abrw screen. These valid account numbers are:v 006006v 006016v 006670v 006968

If the account number that the caller enters is valid, the account balance isplayed to the caller; otherwise, the caller is advised that the account numberentered 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 thelogin and those called from the state table.

The scripts that are used for the login navigate to the amnu screen, which isthe main menu screen of the host application. These scripts are:v login_amnu

v login_blank

v login_cics

v login_unformatted


v login_samon

The main login script is login_amnu, which calls the other scripts, dependingon the screen encountered. The remaining scripts are used to navigate to thescreen containing the account information, namely abrw.

Review the scripts themselves for a more detailed description of theirbehavior.

Chapter 9. Accessing data with a 3270 or custom server 131

Chapter 10. Telephony activity

How WebSphere Voice Response interacts with the telephony network.

This chapter contains the following sections:v “Handling switch and protocol limitations”v “Answering calls” on page 135v “Making, transferring, reconnecting, and terminating calls” on page 142v “Coordinated call and data transfer” on page 144v “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 thelimitations and operation of the signaling protocol and switch you are using.For example, some switches and signaling protocols do not allow WebSphereVoice Response to initiate a call transfer.

Handling switch tonesA switch issues different tones, to indicate the current activity on the phoneline. However, any one activity, for example, ringing, is indicated differentlyby each switch; the tones may be switch-specific or defined by nationalstandards. In addition, some switches send different tones depending onwhether the target number is internal or external to the switch.

For example, when a ROLM switch receives a signal that the telephonereceiver is off-hook, it generates a dial tone for a set number of seconds whilewaiting for dialing to begin, followed by a beep tone if the telephone is notdialed, followed by a howl tone after a set period of no activity.

For more information about all progress tones, see the WebSphere VoiceResponse for AIX: Configuring the System book.

Accounting for protocol limitationsYou need to be aware of the operation of the signaling protocol your systemuses and design your state table accordingly. In general, trunk protocolsprovide call information (called and calling numbers) but not call transfer,while line-side (station) protocols provide call transfer but not callinformation. To get both call information and call transfer, you may need touse an exchange data link. For example, the exchange data link using CallPathServer provides call information.


Far-end hangup detection is another function that is not supported by someprotocols. Again, if you use an exchange data link that uses CallPath Server,far-end hangup detection is supported. (See “Coordinated call and datatransfer” on page 144.)

Getting call information when answering a call

The best way of choosing a state table to handle an incoming call is to use thecalled number (appearing to callers that they have “gone straight through to”the voice response service). However, if the called number is unavailable thereare two other options: see “Handling incoming calls in your productionsystem” on page 140.

Ayava switches with the converse feature cannot send DNIS informationusing the incoming address signaling options, and therefore cannot beretrieved by the WebSphere Voice Response system variable SV185. Suchswitches send DNIS information as DTMF keys after WebSphere VoiceResponse answers the call. To handle this, you need to modify the state tableidentified by the system parameter: State Table Name for Incoming Calls(the default is Incoming_Call). See “Can you write your own state table toanswer 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 arerecommended to use dial tone detection when making outbound calls and calltransfers (see the information about MakeCall in the WebSphere Voice Responsefor AIX: Application Development using State Tables book).

Detecting far-end hangup

You need to be aware that some protocols, generally loop start protocols suchas FXS, do not include positive hangup detection.

In the absence of any indication from the switch, when a caller hangs up, thestate table continues to run until a CloseEverything action. To avoid executinga 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 aCloseEverything action, low timeout and repeat count values will end thestate table execution soon after a caller hangs up.

v After a Record... action or a speech recognition request, evaluate theSystem : Action additional information system variable (SV180), which


may indicate that the recording was terminated because the time limitspecified by the Maximum Silence Duration system parameter wasexceeded.

Example:

Here's an example that highlights the potential for various problems you mayencounter based on your specific configuration. Suppose your system isconnected to a ROLM 9751 switch that is configured to use the FXS Loop Startprotocol. When a caller hangs up before a voice application has completedexecution, 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 errortone that alternates between the tones for the * and # keys.

3. The voice application state table encounters a GetData action and waits forcaller 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 againencounters the GetData action to wait for caller input.

5. Assuming a high time-out value, the repeat count value (the maximumnumber of timeouts allowed before branching to the state specified in thelast timeout result field) may not be reached before the ROLM switchissues the second error tone.

6. GetData recognizes the # key in the error tone as “end of input,” but doesnot recognize the * key.

7. GetData exits with a result of “Input Too Short,” and branches to the statespecified for this result.

8. If the state that is branched to is not CloseEverything, the state tablecontinues to execute.

9. If the execution again encounters the GetData action, and the switchcontinues to issue the second error tone, the state table loops indefinitely.

The problem in this example could have been eliminated by reducing thetimeout and repeat count values so that the voice application timed out beforethe switch issued the second error tone.

Answering calls

AnswerCall is the state table action that answers an incoming call.

Chapter 10. Telephony activity 135

An AnswerCall action in every state table is not mandatory, but it is useful fordebugging. (See the WebSphere Voice Response for AIX: Application Developmentusing State Tables book for information about using the debug option in theState Table window.)

How does WebSphere Voice Response answer an incoming call?When WebSphere Voice Response receives an incoming call it uses the call'sapplication profile ID to determine how it should be answered.

Initially, control of the call is always passed to the Incoming_Call state table.Incoming_Call issues the AnswerCall action then the InvokeStateTable actionto invoke the state table specified in the application profile.

If the application profile specifies a state table called JavaApplication and theJava and VoiceXML environment is installed and running, control of the callpasses to a Java application. The JavaApplication state table needs to beavailable in case the Java and VoiceXML environment is not running. Formore information on configuring your system to answer incoming calls withJava applications, see WebSphere Voice Response for AIX: Deploying andManaging VoiceXML and Java Applications.

Each state table that is designed to handle incoming calls therefore requires anapplication profile, and WebSphere Voice Response must find the appropriateapplication profile before Incoming_Call can invoke the right state table tohandle the call.


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


How does WebSphere Voice Response find the applicationprofile?

Incoming_Call works on the basis that an application profile specifying a statetable has been found. Figure 14 on page 137 shows how WebSphere VoiceResponse finds the application profile. When a call comes in and the callednumber is available, WebSphere Voice Response looks for an applicationprofile whose ID matches the called number. (If the called number wasreceived on an exchange data link, the area code specified in the channelgroup is concatenated to the beginning of the number before the search.) Ifthe called number is unavailable for any reason, WebSphere Voice Responselooks for an application profile whose ID matches the channel identification (fordetails, see the WebSphere Voice Response for AIX: Configuring the System book).If no profile is found, WebSphere Voice Response looks for an applicationprofile whose ID matches the value of the System Default Application Profilesystem parameter (whose supplied value is 0000000000).

If there is no qualifying application profile ID, the call is not answered.3

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 thestate table specified in the application profile. Because it invokes the statetable by application profile, Incoming_Call cannot pass any parameters to thestate table. The following system variables are, however, available for the statetable 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 channelidentification.

3. If WebSphere Voice Response is configured to go off hook in order to receive DNIS information, the system playsthe caller a message saying that there are technical difficulties, and then hangs up.


Caller - Profile ID (SV20)The calling number (if available).

System : Call Info : Calling Number (SV186)The calling number (if available).

System : Call Info : Call info status (SV129)Indicates whether call information (called number and callingnumber) 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 anothersupplied state table, Welcome, which greets the caller and hangs up. Welcomeis also invoked during the installation test described in the WebSphere VoiceResponse for AIX: Installation book: WebSphere Voice Response finds theapplication profile whose ID is 0000000000, and this application profilespecifies 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 anew voice segment for Welcome to play, perhaps explaining to the caller thatthe system is experiencing technical difficulties.

Both of these applications are imported into WebSphere Voice Response aspart of the installation process.

Do not delete the state table specified in the State Table Name for IncomingCalls parameter (Incoming_Call), because WebSphere Voice Response cannotanswer calls without it. Do not delete the application profile specified in theSystem Default Application Profile parameter (0000000000), becauseWebSphere Voice Response may need it to answer a call if no otherapplication 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 Namefor Incoming Calls parameter in the Application Server Interface parameter


group (after you've done this, you need to stop WebSphere Voice Responseand 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 VoiceResponse answers the call, instead of using the incoming address signalingoptions. To use such switches with WebSphere Voice Response you musteither customize the state table identified by the system parameter: StateTable Name for Incoming Calls (the default is Incoming_Call) or substituteone of your own.

The customized state table must include the GetData action immediately afterthe AnswerCall action. The KeyBuffer, Minimum, Maximum, and Timeoutparameters for the GetData action should be set according to the length of theDNIS digits and the expected time to receive all digits.

If you want to use the received digits to select the application profile, add anAssignData action to set SV22 with the received digits before calling theInvokeStateTable action.

Handling incoming calls in your production system

Even if you do not change Incoming_Call, there are several method ofhandling incoming calls, and your decision partly depends on the capabilitiesof the switch to pass the called number on to WebSphere Voice Response. Youneed to decide whether to:v Have one state table to handle all incoming callsv Choose the state table on the basis of the called numberv 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 tomake 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 groupv 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 theappropriate voice response service for each caller. Each caller dials a differentnumber depending on which service they require, and gets straight through tothat service. In the example shown in Table 6 on page 138, callers dial 1234567for the accounts application (Accounts_Main) or 1238800 for the interest ratesapplication (Interest_Main).

You should have one application profile for each state table that might beinvoked in this way. You also need a default application profile and statetable. Typically, the default state table would ask the caller which service theyrequire, in the event that the called number is, for some reason outside yourcontrol4, unavailable.

This is the most efficient method. However, if your switch is unable to passthe 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 basisof called number. The disadvantage of this method is that it ties channels tospecific applications, which is inefficient if all the calls at one time are for oneof the applications: it makes load-balancing difficult. If it's possible to get thecalled number from the switch, you should use that method.

4. The called number may be unavailable if, for example, the switch did not receive the full information, or becausethe task the switch uses to send the information is busy.

0000000000

Figure 15. Application profile needed with one state table for all

0000000000

1238800

1234567

Figure 16. Application profiles needed when using called number


Again, you need one application profile for each state table that might beinvoked in this way.

Making, transferring, reconnecting, and terminating calls

How WebSphere Voice Response makes, transfers, reconnects, and terminatestelephone calls.

Call transferMost voice response services offer the caller the opportunity to transfer a call.Call transfer can be provided in several ways, although the only standardmethod uses PABX station or Centrex line features. Other methods of transferinclude a release link trunk, unique T1 or E1 protocols, or exchange data link.

There are two types of call transfer:v Screened (or supervised) transferv Blind transfer

Screened transfer is usually preferable, but a blind transfer does reduce theduration of a successful transfer process and may be acceptable.

Screened transfer

With a screened transfer, the state table places the caller on hold (suspendingthe call) and completes the transfer only if the call to the third party isanswered. If the state table detects busy tone while transferring a call, or if thethird party does not answer, the state table can take one of the followingactions:v Reconnect to the original caller and offer another optionv Dial an alternate numberv 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 theaddress of the third party, and then disconnects from the call. If the transfer is

1238800

1234567

Figure 17. Application profiles needed when using channel identification


unsuccessful, the switch usually places a new call to the party that originallyinitiated the transfer request.

Implementing call transfer with WebSphere Voice Response

With channel associated signaling (CAS), WebSphere Voice Response cangenerate call transfer request signals using feature codes (character stringsconsisting of 0 through 9, *, and #) with or without hook or ground flash. Totransfer a call, invoke the TransferCall action. With the Transfer Call RequestSignal parameter (in the Signaling Type parameter group) set to Feature Code,the Transfer Call Feature Code (in the same group) identifies the characterstring recognized by the switch as a call transfer request.

If the CAS protocol being used does not support call transfer, but the switchhas a host access control link that does support it, a custom-written signalingprocess (see the WebSphere Voice Response for AIX: Programming for the SignalingInterface book for details).

State table actionsRefer to the WebSphere Voice Response for AIX: Application Development usingState Tables book for information about the following state table actions:v MakeCallv Dialv TransferCallv ReconnectCallv TerminateCall

System parametersTelephony activity is defined by a number of system parameters; those thatare of interest to you when designing a state table to make outbound callsinclude: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 theWebSphere Voice Response for AIX: Configuring the System book.


Coordinated call and data transfer

Coordinated call and data transfer is the process of transferring a caller toanother phone number together with some data. Typically, an account numberor some other identifier is passed, to allow the receiving agent to find detailsabout 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, youneed 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 areanetwork (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.

What does the state table have to do?The CallPath_SigProc commands are documented in the WebSphere VoiceResponse for AIX: Application Development using State Tables book. The

DataCommunications

Network

Information

Caller

Switch

TelephoneNetwork

VoiceProcessing

LocalArea

Network

CallPath_SigProcCustom Server

CallPath Server

State Table

pSeries


Figure 18. CallPath Server and WebSphere Voice Response installed in the same pSeries computer


commands are used to read or set the program data. In addition, the statetable also has access to information about an incoming call in the followingsystem variables:

System : Call Info : Called Number (SV185)The called number (the number to which the call has beentransferred).

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 systemvariable (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 toCallPath_SigProc, followed by a ReceiveData to receive two parameters: theprogram data itself and the length of the string. These steps are shown inFigure 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 whenyou use the SendData action to send the Set_Program_Data command toCallPath_SigProc. Use a ReceiveData action following the SendData, andcheck the return code. If the Set_Program_Data appears to have beensuccessful, use the TransferCall action to make the call transfer. These stepsare 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 controlcharacters are allowed in the string.

How much data can you pass?WebSphere Voice Response has a limit of 512 bytes, but your switch may havea smaller limit. If so, it is your responsibility to ensure that you do not send alonger string.


Examples

If the value of SV188 is not 0,there is program data to be

read.

CloseHostServerLink

OpenHostServerLink to CallPath_SigProc

SendData Read_Program_Data

ReceiveData Read_Program_Data

EvaluateData SV188

Read the program data

Call transferred by CallPath Server andanswered by WebSphere Voice Response

Application can use the information itreceived in the program data.

Figure 19. Receiving a call and data transferred by CallPath Server


Setting the MessageWaiting Indicator using CallPath Server

You can use CallPath Server to set the message waiting indicator on anyphone, for example, when virtual mailboxes are in use.

To do this, you need the following:v A switch that supports message waiting indicationv CallPath Server installed, either on the same pSeries computer or on

another pSeries computer or a personal computer connected by a local areanetwork (LAN)

v The CallPath_SigProc custom server imported into your WebSphere VoiceResponse system.

TransferCall

CloseHostServerLink


SendData Set_Program_Data

ReceiveData Set_Program_Data

Set the program data. Thismight be an account

identifier or any other data.

Transfer the call. The datais set along with the call.

A call is in progress; the caller wants to betransferred, or the application decides to

transfer them

Figure 20. Transferring a call and data to another number using CallPath Server


A single-system installation is shown in Figure 18 on page 144. The steps thatthe state table performs are shown in Figure 21. For details about theCallPath_SigProc Set_MWI command and its parameters, see the WebSphereVoice Response for AIX: Application Development using State Tables book.

CloseHostServerLink


SendData Set_MWI

ReceiveData Set_MWI

Set the message waitingindicator on or off at thespecified phone number.

Optionally, you can set theduration that the MWI is to

be on for, and the LEDfrequency.

A call is in progress

Figure 21. Using CallPath Server to set the message waiting indication


Chapter 11. Designing voice messaging applications

You can create your own voice messaging applications or add voicemessaging to existing applications. For example, in an ordering application,you may choose to let people leave a voice message to be associated with anorder. 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 whetherIBM’s Unified Messaging program offering would satisfy your needs. UnifiedMessaging is a fully functional voice mail application that can be extensivelytailored. For more information, see your IBM representative.

Voice messaging resources

This section describes the resources used for voice messaging:v Voice Mailboxesv Greetingsv Audio Namesv Distribution lists

Voice mailboxes

Voice messages are stored in mailboxes. To define mailboxes, you need anapplication profile. You can define up to ten mailboxes in one applicationprofile, or you can give each mailbox its own profile. The application profileID can be any value you want, but, for a voice mail application, the phonenumber or extension number of the subscriber who owns the mailbox isprobably most convenient. In transaction messaging, you can use the differentmailboxes in an application profile to store different categories of voicemessage.

In this case, each subscriber has an application profile, each of which specifiesthe name of your voice mail application's initial state table.

For more information about creating and maintaining mailboxes, seeChapter 12, “Managing voice messaging resources,” on page 167.


Greetings

An application profile can define up to 255 greetings. Each mailbox definedfor the profile can use one or more greetings; a mailbox can play differentgreetings depending on the value of the Caller : Mailbox : Owner Statussystem variable (SV102). Each greeting is identified by a greeting ID.

The administrator of a WebSphere Voice Response system can specify that allnew greetings recorded using state table actions are compressed, or that theyare all not compressed. The administrator specifies this using the UserGreeting Compression Type system parameter.

Audio names

Each mailbox can also have an associated audio name that is normally used tocontain the digitized voice data that identifies the owner of a mailbox. Theaudio name can be played to callers who leave and retrieve messages toidentify the owner of a mailbox. Audio names are stored in compressedformat only.

The administrator of a WebSphere Voice Response system can specify that allnew audio names recorded using state table actions are compressed, or thatthey are all not compressed. The administrator specifies this using the AudioName Compression Type system parameter.

Distribution lists

A distribution list is a list of application profile IDs and mailbox IDs or otherdistribution list IDs, to which a message can be sent. There is no limit to thenumber of members in each distribution list. The distribution list is identifiedby a four-digit ID. A distribution list can be public or private to the mailboxfor which it is defined. There are state table actions to manipulate distributionlists and distribution list editing functions available to the systemadministrator. For more information about creating distribution lists, seeChapter 12, “Managing voice messaging resources,” on page 167.

Accessing mailbox information

To access mailbox information, the state table must set the Caller - ProfileID system variable (SV20). To access information about a specific mailbox inthe application profile, the state table must set the Caller : Mailbox - IDsystem variable (SV32). The rest of the Caller system variables are initializedwith appropriate values when SV20 and SV32 are set.

SV20 can be set in the following ways:


v When WebSphere Voice Response automatically loads it with the callingnumber information. In this case, the profile data is not retrieved from thedatabase until the state table writes to SV20 (use AssignData to setSV20=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 fromthe database when the state table writes to SV20.

Using state table actions for voice messaging

This section lists the 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 theapplication profile ID and mailbox ID

SendVoiceMessage

Retrieve all voice messages of a specified type for theapplication profile specified by SV20 and mailbox IDspecified by SV32

CheckVoiceMessages

Play a voice message from a mailbox PlayVoiceMessage

Save a voice message, which has been retrieved usingCheckVoiceMessages, in the mailbox for later retrieval

SaveVoiceMessage

Play back a voice message which has just beenrecorded

PlayVoiceMessage

Chapter 11. Designing voice messaging applications 151


Remove a voice message previously retrieved usingCheckVoiceMessages

DeleteVoiceMessage

Distribution lists


Retrieve names of all recipients on a specifieddistribution list for a specified application profile andmailbox ID

GetDistributionList

Retrieve names of all distribution lists for a specifiedapplication 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 andmailbox ID

SaveAudioName

Play the audio name of the specified applicationprofile and mailbox ID

PlayAudioName

Remove the audio name of the specified applicationprofile and mailbox ID

DeleteAudioName


Greetings


Record a greeting RecordUserGreeting

Store the greeting for the specified application profileand mailbox ID

SaveUserGreeting

Play the greeting associated with the specifiedapplication profile and mailbox ID

PlayUserGreeting

Remove the greeting specified by system variableSV102

DeleteUserGreeting

Interacting with callers and messages

A caller is anyone who dials or calls into the system, for example, to record amessage or greeting or listen to a voice message. This caller is represented bythe Caller : Profile - ID system variable (SV20), and the mailbox fromwhich voice messages are sent or retrieved for listening is represented by theCaller : Mailbox - ID system variable (SV32). Each voice message is alwaysassociated with the Profile ID and Mailbox ID from which it was sent and theProfile ID and Mailbox ID from which it is to be retrieved.

Recorded voice messages are stored in temporary workspace until they aresent to a mailbox. Voice messages can be retrieved from mailboxes to beplayed, annotated (repeatedly, if required), sent, deleted, saved, or theirattributes can be changed before sending them to a specified mailbox. Theattributes of a message in a mailbox are defined by the Message systemvariables, described in the WebSphere Voice Response for AIX: ApplicationDevelopment using State Tables book. The status of a message is stored in theMessage : Status system variable (SV47).

Incoming messages are received messages in the recipient's mailbox; the statusof incoming messages can be New, Checked, Listened, Saved, orUndeliverable. Outgoing messages are sent messages in the sender's mailbox;the status of outgoing messages can be New or Future.

Recording messages

The RecordVoiceMessage state table action records a message in theworkspace. Recording a new message clears the workspace of any existingvoice 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 theSendVoiceMessage state table action.

Sending messages

The SendVoiceMessage state table action sends a message to a mailbox. Themessage is stored in the recipient's mailbox as a New message, and is addedto the sender's outgoing messages. If sent to someone else's mailbox, themessage will be kept in the sender's outgoing messages until the recipientchecks the message. If the message is future dated (status is Future), themessage is not sent to the recipient's mailbox until the specified date andtime. SendVoiceMessage is also used to forward messages from one mailboxto another, as described in “Forwarding messages” on page 155.

If the sender requested acknowledgment of the message (using the ReceiptAcknowledgment parameter of ChangeMessageAttributes), the message willbe sent to the sender's mailbox as a New message when the recipient plays ordeletes the message. The Message : Receipt acknowledgment status systemvariable (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 amailbox. Before a message in a mailbox can be played, forwarded, annotated,saved, deleted, or the attributes changed, it must be retrieved from themailbox by CheckVoiceMessages. When a message is retrieved, the Messagesystem variables are initialized with the message information. Whenever themailbox is accessed and a New message is counted, SV32 is set and the statusof the message is changed to Checked . A retrieved message remains Checkeduntil 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 checkedby the recipient).

v First Outgoing To Selected Recipient. Includes outgoing messages sent to aspecific recipient (the messages that have a status of New or Future thathave not been checked by the recipient).

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 currentmessage, 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 thelist. The Message system variables are always initialized with the currentmessage information.

To select a specific message in the list, you can use the AssignData state tableaction to assign a value to a Message system variable that defines the messageyou want. For example, to select the third message in a list retrieved byCheckVoiceMessages, you can assign the Message : Message number systemvariable (SV21) a value of 3. This automatically updates the current messageto the third message in the CheckVoiceMessages list.

You can also select a specific message based on the transaction ID of themessage. By setting the Message : Transaction ID system variable (SV126) toa value, the list is searched for a message with a transaction ID that matchesthe value. If the first message in a newly retrieved list matches, that messageremains the current message. Subsequent AssignData actions select andrefresh the workspace information with subsequent matching messages in thelist. In other words, subsequent checks for matches with the same transactionID begin following the current message, not starting with the current message.

If the sender requested acknowledgment of the message (using the ReceiptAcknowledgment 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 actionplays it from the workspace; if the voice message is the current message in thelist of retrieved messages, the PlayVoiceMessage action plays it from themailbox. As soon as the mailbox is accessed, the status of all messageschanges from New to Checked. When a message has been played successfullyall the way through to the end, the status changes to Listened.

If the sender requested acknowledgment of the message, (using the ReceiptAcknowledgment parameter of ChangeMessageAttributes), the message issent to the sender's mailbox as a New message when the recipient plays themessage 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 SendVoiceMessagestate table action can be used to forward the message from one mailbox toanother. The recipient of a message can forward the message directly toanother mailbox or can first change the attributes of a message or annotate the


message before forwarding. In all cases, the sender information of theforwarded message reflects the forwarder. The sender information of theoriginal message remains unchanged.

For example, if Jay sends a message to Nick's mailbox, and Nick thenforwards it to Daisy, the message in Daisy's mailbox will indicate Nick as thesender. Nick can also record an annotation to the message before sending it toDaisy. Jay's outgoing messages include the original message sent to Nick, butnot the annotated message sent by Nick to Daisy. Nick's incoming messagesinclude the original message sent by Jay; his outgoing messages include themessage sent to Daisy. Daisy's incoming messages include the message sentby Nick.

Annotating messages

The RecordVoiceMessage state table action can use the options Add ToBeginning and Add To End to annotate the message. The message can be anewly recorded message in the workspace or the current message retrieved byCheckVoiceMessages. The same message can be annotated multiple times.

Changing message attributes

The ChangeMessageAttributes state table action sets and changes theattributes of the message in the workspace. The attributes that can be changedare the date it is to be delivered, the security level, urgency level, whether toacknowledge receipt of the message, or transaction ID.

Deleting messages

After a voice message has been retrieved from a mailbox, theDeleteVoiceMessage state table action can be used to change the status of themessage in the list to Deleted and clears the Message system variables.

If the sender requested acknowledgment of the message (using the ReceiptAcknowledgment parameter of ChangeMessageAttributes), and the recipientdid not play the message before deleting it, the message is sent to the sender'smailbox as a New message and the Message : Receipt acknowledgmentstatus system variable (SV161) has a value of 3, which indicates that themessage was received but not listened to.

Saving messages

After a voice message has been retrieved from a mailbox, theSaveVoiceMessage state table action can be used to change the status of themessage in the mailbox from Checked, Listened, or Undeliverable to Saved.


If you make any changes to a voice message (by usingChangeMessageAttributes or RecordVoiceMessage), you have created a newmessage, which must be sent to a mailbox. The mailbox can be the sender'sown mailbox, or a different mailbox. If sent to the sender's mailbox, themessage 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 recipientchecks the message. Whether a message is sent to the sender's own mailbox orto another mailbox, the message is always added to the sender's outgoingmessages list.

System parameters that affect voice messaging

The following parameters in the Application Server Interface parameter groupaffect voice applications that include messaging or use mailboxes:v Password Minimum Lengthv Play Skipv User Identifier Minimum Digits

The following parameters in the General parameter group control the lengthof each voice message:v Record Voice Maximum Pausev Record Voice Maximum

A sample voice message application

The sample called VoiceMessagingSample is a voice application that includesmessaging. The sample called RecordAudionameSample allows you to recordthe 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/samplesdirectory.

2. Create an application profile for it (see Chapter 5, “Creating an applicationprofile,” on page 89).

3. Create the mailboxes for which you plan to record the audio names (see“Creating mailboxes for application use” on page 170).

4. Use RecordAudionameSample to record some audio names.

RecordAudionameSample

RecordAudionameSample enables you to record an audio name for anapplication profile mailbox.


Note: This sample includes a state table and a prompt that are both namedRecordAudioName. 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, youmust rename them.

VoiceMessagingSample

VoiceMessagingSample is an example of a messaging application that allowscallers to:v Record messagesv Listen to messagesv Send messages (to individuals or to a distribution list)v Annotate (add to) messagesv Save messagesv Forward messagesv Change personal options such as distribution lists, passwords, and greetings

The flow of control in VoiceMessagingSample is illustrated in FiguresFigure 22 on page 159 through Figure 24 on page 161. The application ismodular, with the state table VoiceMsgMenu as the main controlling loop thatcalls the other state tables according to the caller’s input.


Answer the call Answer the call

Get the profile ID

Get the password

Home state

Invoke VoiceMsgListen

Invoke VoiceMsgOptions

Play the greeting

Invoke VoiceMsgRecord

Exit

VoiceMsgMenu VoiceMsgAnswer

1

2

3

9

0

Record a message

Listen to your messages

Personal options

Help

Exit


Figure 22. VoiceMsgMenu and VoiceMsgAnswer


VoiceMsgListen

Listen

Play the message

Check next message

Summary

Message type

1

2

3

New

Saved

Outgoing

Message options

1

2

3

5

7

9

Reply

Next message

Save

Delete

Listen

Forward

VoiceMsgRecord

Record the message

Send

Annotate the message

1

2

3

5

7

Append

Prefix

Re-record

Send

Listen

Special delivery

1

2

5

Acknowledgement

Future delivery

Send

Destination

1

2

To single recipient

To distribution list

Resend

1

2

Send again

Finished



Figure 23. VoiceMsgRecord and VoiceMsgListen


An example state table

Figure 25 on page 162 shows an example of the listing you get when youprint a state table from WebSphere Voice Response. For each state, the listinghas 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, itsaction is a PlayPrompt, and its description is Play summary of messagesprompt. The second state is unlabeled, it is also a PlayPrompt, and itsdescription is Play message type selection prompt.

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


2. TRANSITIONS

This section tells you the possible results that can be returned by theaction, with the label of the state specified as the Goto State (the nextstate for that result). A blank in the Goto State column indicates that thestate 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 firstaction (summary), the Prompt parameter specifies the name of the prompt(in this case, the Summary prompt) and the Force Play parameter, which isset to False, specifies that the prompt can be interrupted by the caller.

State Table - VoiceMsgListenVoice Messaging Sample - "Listen"

State Label Action Description=============== ==================== ======================================summary PlayPrompt Play summary of messages prompt

TRANSITIONSResult Goto State------------------------------ ---------------SucceededLine Problem errorNothing Played errorCaller Hung Up end

PARAMETER VALUESParameter Value------------------------------ ------------------------------Prompt SummaryForce Play False

Figure 25. Example listing of the first two states in a state table


An example prompt

The prompt for VoiceMsgSummary is typical of those you will write whencreating a WebSphere Voice Response application.

IF SV28 = 0 AND SV29 = 0 AND SV31 =0 THENVOICE VoiceMsg (200); # You have no...VOICE VoiceMsg (220); # ...messages

If the caller’s mailboxcontains no new messages(SV28), saved messages(SV29), or outgoingmessages (SV31), thissection plays “You have nomessages” (voice segment200 followed by voicesegment 220 in theVoiceMsg voice directory).

State Label Action Description=============== ==================== ======================================

PlayPrompt Play message type selection prompt

TRANSITIONSResult Goto State------------------------------ ---------------SucceededLine Problem errorNothing Played returnCaller Hung Up end

PARAMETER VALUESParameter Value------------------------------ ------------------------------Prompt MessageTypeForce Play False


ELSEVOICE VoiceMsg (210); # You have...IF SV28 != 0 THEN

SYSPROMPT Whole_number (SV28);VOICE VoiceMsg (250); # ...new...PROMPT Message_s (SV28);

This section plays “Youhave” (voice segment 210).It then checks SV28 to see ifthe caller has any newmessages. If there are newmessages, theWhole_number systemprompt plays the value ofSV28.

This is followed by voicesegment 250, which playsthe word “new” and thenthe Message_s prompt.Message_s is a subroutinethat determines whether thevalue passed as aparameter is 1, or >1. If thisvalue 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 (savedmessages) and SV31(outgoing messages) arechecked. If either variablecontains a number otherthan 0, the system prompt301, which contains theword “and”, is played.


IF SV29 != 0 THENSYSPROMPT 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 todetermine if the caller hassaved messages. If so, itcalls the system promptWhole_number to play thevalue in SV29, followed byvoice segment 250, whichplays the word “saved”.The prompt Message_sagain determines whetherto play the work “message”or the word “messages”.

Next, SV31 (outgoingmessages) is checked. If itcontains a number otherthan 0, the system prompt301, which contains theword “and”, is played.

IF SV31 != 0 THENSYSPROMPT Whole_number (SV31);VOICE VoiceMsg (270); # ...outgoing...PROMPT Message_s (SV31);

ENDIF

This section checks SV31 todetermine if the caller hasoutgoing messages. If so, itcalls the system promptWhole_number to play thevalue in SV31, followed byvoice segment 270, whichplays the word “outgoing”.The prompt Message_sagain determines whetherto play the word “message”or the word “messages”.


Chapter 12. Managing voice messaging resources

This chapter describes how to create and maintain mailboxes, subscriberclasses 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 andassigning mailboxes to them. This can be done at any time, either when youfirst create the application profile, or later.

The system administrator creates mailboxes for new users, removes unwantedmailboxes, and can also create, update, and remove distribution lists forgeneral use or as required by subscribers. The system administrator can alsoview the number and status of messages in the mailboxes (the content of themessages cannot be accessed by the system administrator).

If you are implementing a large-scale voice messaging application, you shouldalso read about supporting applications that require a large amount of voicedata in the WebSphere Voice Response for AIX: Installation book.

Voice mailboxes

Voice mailboxes are required for voice messaging. They are logical mailboxes, notphysical ones: the system does not reserve space on the disk for each mailbox.When you “define mailboxes” for an application to use, you are reallyactivating a mechanism that enables the state table messaging actions to workproperly. If no mailboxes have been created, the messaging actions cannotwork correctly.

How do I create a mailbox?Mailboxes always belong to an application profile. Up to 10 mailboxes can beactivated on any one application profile. You can do this either in theApplication Profile window or by using the wvrapplprof and wvrmailboxcommands. See “Creating mailboxes for application use” on page 170

What mailbox information does the application profileinclude?

The application profile includes information that the voice application and thesystem administrator can use to control the usage of the mailboxes. Theprofile specifies, for example:v How many mailboxes the application can use.


v What greeting the application plays to callers by default.v A password for each mailbox.v A referral telephone number at which the mailbox owner can be reached.v What greeting the owner of a mailbox wants played to callers who reach

the mailbox when the owner has recorded more than one greeting.v A status for the owner, which can also control which greeting is played.v Whether a mailbox takes messages or only plays the owner’s greeting.v The order in which messages are retrieved.v Whether callers can leave and retrieve messages in any mailbox controlled

by the application or only in the current mailbox.v Which set of prompts a caller accessing the mailbox should hear when the

application includes more than one set of prompts.

How is mailbox information used?When the Caller - Profile ID system variable (SV20) and Caller - MailboxID system variable (SV32) have been set by an AssignData action, causing theprofile information to be retrieved, the system loads each item of the mailboxinformation into a separate system variable. For example, if the applicationprofile includes information about the owner’s status, WebSphere VoiceResponse loads the information into the Caller: Mailbox: Owner statussystem variable (SV102).

Voice applications can make control decisions based on the value of avariable. In this example, assuming the owner had recorded alternativegreetings to be played when he was out of town or sick, the messagingapplication could use the value of SV102, Caller : Mailbox: Owner status todetermine which greeting to play.

Whether an application checks the value of the system variable that holdsprofile information is up to the application developer.

Controlling messages

All messages assigned to a mailbox are stored on the hard disk in the pSeriescomputer. If one mailbox accumulates a lot of messages (or even a few verylong messages), the messages can take up a large amount of disk space.

WebSphere Voice Response includes two tools to help you control how muchdisk space messages can use. One controls the maximum length of a message.The other controls how many messages an application can store in a singlemailbox.


Limiting message lengthThe maximum length of a message is controlled by the Record VoiceMaximum system parameter in the General parameters group. This controlsthe length of any voice data that is recorded over the telephone, bothmessages and voice segments. If you change the value of Record VoiceMaximum, you will have to stop WebSphere Voice Response and start itagain, for the new value to take effect.

When the system is delivered, the parameter is set at 120 seconds. You canreset it to limit recorded voice to any number of seconds between 30 and3600.

In a state table, you can override the value of the Record Voice Maximumsystem parameter, by setting the System : Maximum record time systemvariable (SV179).

Limiting the number of messagesThe object that controls the maximum number of messages in a single mailboxis 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 theuse of mailboxes. Each subscriber class can specify different value for:v The maximum number of mailboxes that can be assigned to guest usersv The maximum number of messages that a mailbox can acceptv The maximum number of distribution lists that can be constructed for each

mailboxv The maximum number of entries in a distribution list constructed for any

mailboxv The maximum record time per messagev 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 mailboxesat once. Using subscriber classes, you can also specify limits other than thesystem limits to a group of mailboxes. To use a subscriber class, specify it inan application profile. Specifying a subscriber class in an application profileindicates that you want the limits included in the definition of that subscriberclass 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 asubscriber class has been retrieved, the system loads the values specified inthe subscriber class definition into the appropriate Caller : Subclass system

Chapter 12. Managing voice messaging resources 169

variables . (For more information on the system variables, see the WebSphereVoice Response for AIX: Application Development using State Tables book.) Oncethe values have been loaded into the variables, the voice application can checkthem and enforce the limits.

WebSphere Voice Response does not automatically enforce the limits in asubscriber class definition. The voice application itself must include state tableactions 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 applicationprofiles, or after your system has been operating for a while.

You may find that you never need subscriber classes. Remember, subscriberclasses only specify limits on the use of mailboxes. The voice application thatis written to access the mailboxes must check these limits and then enforcethem.

Creating mailboxes for application use

You can create mailboxes in two ways, using either the graphical userinterface (GUI), or the wvrapplprof and wvrmailbox commands.

Before you startWebSphere Voice Response does not automatically check mailbox definitions:only the messaging application can check to make sure mailboxes are beingused properly. Therefore, the application designer must tell you whatinformation is necessary.

The application designer can interpret the system variables in any way that isappropriate. For example, value 0 for the Caller : Mailbox : Access modesystem variable (SV106) is documented as meaning “Global”, but yourapplication may use it to mean “Read-only”. To make it easier to use suchMailbox Options in the Application Profile window, you could edit thedisplay text in the language database (see the WebSphere Voice Response forAIX: Configuring the System book for details).

Using the graphical interface1. In the Welcome window, click on Configuration —> Application Profiles

2. Activating mailboxes : Open the application profile. If you haven't yetcreated it, follow the instructions in Chapter 5, “Creating an applicationprofile,” on page 89.


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 anapplication uses more than one mailbox, callers can enter this mailbox IDto select a mailbox to access. The selected mailbox then becomes thecurrent 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 themailbox 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.


7. Defining options for a mailbox : Click the mailbox from the Mailboxdrop 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 WebSphereVoice Response itself does not use this information: it passes the


information on to the state table, without any validation. The followingtext describes each field name displayed in the Mailbox Options . Similarfield names are used in the wvrmailbox command prompt as shown inTable 7 on page 179, where the corresponding GUI field names are shownin italics.

Active Greeting Numberidentifies which greeting an application should play to callerswhen the owner has recorded more than one greeting.

Announce anddetermines whether a caller who reaches the mailbox can leave amessage. The default is Announce and Take Messages.

Application Statusindicates whether the owner of the mailbox is In, Out, Sick,Busy,or Traveling.

Access Modespecifies how callers can use any mailboxes created for use by theapplication. Global access means that a caller can retrieve orleave messages in any mailbox. Read All access means that acaller can retrieve a message from any mailbox but only leavemessages in the current mailbox. Read Write means that a callercan access only the current mailbox. The default is Global.

Mailbox Busyindicates whether the mailbox is currently being used.

Passwordidentifies a password that “opens” the mailbox for the caller toretrieve messages. Password use is optional: you can create amailbox without a password. It is up to the application to checksuch things as the length against the Password Minimum Lengthparameter in the Application Server Interface parameter group.The default value for this is four digits. The maximum length ofa password is always eight digits. Again, it is up to theapplication to check this.

Password change datedate after which password must be changed.

Email addressaddress for e-mail notification.

Retrieval Orderspecifies how messages are ordered in the message selection listsyou can use to maintain the contents of a mailbox. It also definesthe order in which messages are retrieved for a caller. (For moreinformation on mailbox maintenance, see the information in the


WebSphere Voice Response for AIX: Managing and Monitoring theSystem book.) Messages are grouped first by priority. Allmessages of the same priority are then sorted into chronologicalorder: first in, first out (FIFO), or last in, first out (LIFO). Thedefault is FIFO (the system lists the earliest message receivedfirst).

Prompt Levelspecifies whether callers should hear Normal prompts, Noviceprompts, or Expert prompts. If voice application developers havewritten three different sets of prompts and the applicationincludes logic to check which set to use, this informationdetermines which prompts the caller hears. The default isNormal.

Play headersplays message header, before listening to each message: Playmessage headers, or Don't play message headers.

New message deleteallows subscribers to elect to delete new messages withoutlistening to the whole message. The default is Don't deletemessages without listening.

Save messages automaticallyallows subscribers to elect to save new messages automaticallyafter listening. The default is Only save when requested.

Send messageallows subscribers to select when to specify the address of themessage: before, or after, recording the message. The default isAddress after recording the message.

Clock preferenceclock preference used by notification schedules, either 12-hourclock or 24-hour clock.

Bilingual greeting userspecifies whether to play bilingual greetings.

First time userindicates the status of the subscriber: Yes: mailbox has neverbeen entered or No: the user has listened to the tutorial already.

Use the scroll bar to reveal more fields in the Mailbox Options


Assistant numberan assistant (also known as deputy ) number is the number ofanother person who might be a useful contact for your callers.


Temporary assistant numberspecifies a temporary alternative number for your assistantnumber.

Reach-Me numberReachMe number.

Temporary Reach-Me numberPIN to be used when receiving calls transferred via the reach-mefacility.

Operator numberOperator number.

Referral Numberspecifies a number at which the mailbox owner can be reached.The number must be a string of up to 20 digits (no hyphens orparentheses).

Temporary referral numbertemporary call-forwarding number.

Referral Typespecifies whether the referral number is a telephone number or abeeper number. The default is Telephone.

Pager numberpaging bureau number.

Pager referencepager reference number.

Temporary pager numbertemporary paging bureau number.

Temporary pager referencetemporary pager reference number.

Default fax numberspecifies fax number; a 20-character numeric string.

Temporary fax numberspecifies temporary fax number

VPIM addressaddress for SMTP/MIME delivery

VPIM MDPspecifies the message delivery preference for VPIM. It can beLocal, Remote, or Local and Remote. The default is Local.

VPIM voice formatVPIM voice format


Notification schedule statusspecifies whether all notification schedules are turned On or Off.

10. To set the options for another mailbox, click on the Mailbox drop downbutton, which reveals the mailbox ids 1 through 10. Select the mailboxnumber you want to activate.The window changes to display the properties and options of the selectedmailbox.

11. Click File —> Save. The mailboxes are defined and ready for use.

Using the wvrapplprof and wvrmailbox commandsBefore you can use the wvrmailbox command, you must import the admincustom server (see “Importing application objects” on page 46) and make surethat it is running (see WebSphere Voice Response for AIX: Managing andMonitoring 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. Forexample, if you want to allow five mailboxes to be associated with theapplication 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 wvrmailboxcommand. 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 commandwith the -F and -V flags as described in “wvrmailbox command.”

wvrmailbox commandPurpose

List mailboxes associated with an application profile, or change, or viewdetails of mailboxes associated with an application profile. Note that theapplication profile must already exist (see “wvrapplprof command” on page94).

Prerequisites

Before you can use the wvrmailbox command, you must import the admincustom server (see “Importing application objects” on page 46) and make surethat it is running (see WebSphere Voice Response for AIX: Managing andMonitoring the System).


Syntaxwvrmailbox

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

-m Modify the mailbox identified by profile_ID and mailbox_ID, asspecified by the other parameters.

-v View the details of the mailbox identified by profile_ID andmailbox_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 mustspecify a -V flag and value for each -F flag and field name.

Examples

List all mailboxes of application profile 123456:wvrmailbox -l -I 123456

Activate mailbox 1 for application profile 123456:wvrmailbox -m -I 123456 -M 1 -F mailbox_status -V 1

Modify some details of mailbox 2 for application profile 123456:


wvrmailbox -m -I 123456 -M 2 -F deputy_number -V 123333 -F email_address-V [email protected]

View some details of mailbox 1 for application profile 123456:wvrmailbox -v -I 123456 -M 1 -F mailbox_status -F clock_pref

View all the details of mailbox 1 for application profile 123456:wvrmailbox -v -I 123456 -M 1 -F all

Field names

For an alphabetical list of field names that are valid with the -F attribute flag,see the table that follows. All of these fields are user-modifiable except thosemarked as display-only in the Field Data column. Corresponding fields namesused in the GUI are shown in italics.

Table 7. Mailbox field names used with wvrmailbox command

Field Name Description Length Field Data

access_mode

Access Mode

This specifies howcallers can use anymailboxes createdfor use by theapplication. Globalaccess means that acaller can retrieveor leave messagesin any mailbox.Read All accessmeans that a callercan retrieve amessage from anymailbox but onlyleave messages inthe currentmailbox.Read Write meansthat a caller canonly access thecurrent mailbox.

1 0 = Global (default)1 = Read All2 = Read/Write

announce_only

Announce and

Determineswhether a callerwho reaches themailbox can leave amessage.

1 0 = take messages (default)1 = don't


Table 7. Mailbox field names used with wvrmailbox command (continued)


autosave_new_msgs

Save messages automatically

Allows subscribersto elect to savenew messagesautomically afterlistening.

1 0 = no (default)1 = yes

bilingual_grt

Bilingual greeting user

Bilingual greetinguser.

1 1 = play0 = don't play

box_id

Mailbox

Indicates themailbox number.

2 From 1 to 10This is a mailbox property display-onlyfield

clock_pref

Clock preference

Clock preferenceused bynotificationschedules.

1 0 = 12-hour (default)1 = 24-hour

delete_new_msgs

New message delete

Let subscribersdelete newmessages withoutlistening to thewhole message.

1 0 = no (default)1 = yes

deputy_number

Assistant number

Assistant number 20 numeric string

email_address

Email address

Address for e-mailnotification

255 text

fax_number

Default fax number

Fax number; atwenty-characternumeric string

20 numeric string

first_time_user

First time user

First time userstatus

1 0 = New mailbox (default)1 = Tutorial has been used




mailbox_active_grt

Active Greeting Number

Identifies whichgreeting anapplication shouldplay to callerswhen the ownerhas recorded morethan one greeting.

3 0 = Default1 = Personal greeting 12 = Personal greeting 23 = Personal greeting 34 = Personal greeting 45 = Personal greeting 57 = Announcement-only greeting9 = System default10 = System default announcement-only11 = Alternative system announcement-only12 = Alternative announcement-only

mailbox_busy

Mailbox Busy

Is the mailboxcurrently busy on acall.

1 0 = no1 = yes

mail_status

Active

Indicates whethermailbox is active orinactive

1 0 = inactive1 = active

new_messages

New

Displays howmany newmessages are in themailbox

This is a mailbox property display-only field

notif_sched_status

Notification schedule status

This specifieswhether allnotificationschedules areturned On or Off.

1 0 = All off1 = Active on

number_of_mailboxes

Total Active Mailboxes

The number ofmailboxes whichare active.


operator_number

Operator number

The number of theswitchboardoperator at yourlocation. This is thedefault number towhich a call istransferred if acaller chooses thatoption whenleaving a message.Subscribers can settheir own operatornumber to overridethe system default.

20 numeric string




outgoing_messages

Outgoing

Displays howmany outgoingmessages are in themailbox.


pager_number

Pager number

Phone number ofyour pager

20 numeric string

pager_ref

Pager reference

Some pagers areidentified by aunique referencenumber. If yourpager uses areference number,you can set this byentering it in thisfield.

20 numeric string

password

Password

This identifies apassword that“opens” themailbox for thecaller to retrievemessages.Password use isoptional. You cancreate a mailboxwithout apassword. It is upto the applicationto check suchthings as the lengthagainst thePasswordMinimum Lengthparameter in theApplication ServerInterface parametergroup. The defaultvalue for this isfour digits. Themaximum length ofa password isalways eight digits.Again, it is up tothe application tocheck this.

8 max numeric string




password_change_date

Password change date

Date after whichpassword must bechanged

8 YYYYMMDD

play_headers

Play headers

Play header beforemessage.

1 0 = no (default) - never play header1 = yes

profile_active_grt

Profile Active Greeting

Specifies theidentifier of theactive greeting thatwill be playedwhen a callerreaches thismailbox.

Reserved for use by Unified Messaging

prompt_level

Prompt Level

Verbosity level forprompts thesubscriber hears.

1 0 = Normal prompts (default)1 = Novice prompts2 = Expert prompts

reachme_number

Reach-Me number

A number wherethe subscriber canbe reached. Callscan be forwardedto this number

20 numeric string

referral_number

Referral Number

This specifies anumber at whichthe mailbox ownercan be reached.

20 numeric string

referral_type

Referral Type

This specifieswhether thereferral number isa telephonenumber or a beepernumber.

1 0 = Telephone1 = Beeper




retrieval_order

Retrieval Order

Indicates the orderin which to retrievemessages from themailbox. Anapplication canretrieve messagesin the order thatthey arrived, or itcan retrieve themost recentmessages first. Thepossible values are:First in first out(the order in whichthe messagesarrived), Last infirst out (the mostrecently receivedmessage first).

1 0 = FIFO (default)1 = LIFO

saved_messages

Saved

Displays howmany savedmessages are in themailbox


send_msg_address

Send message

Indicates that youwill specify themessage addressbefore or afterrecording themessage.

1 0 = Message first, address after (default)1 = Address first, message after

temp_deputy_number

Temporary assistant number

Temporaryassistant number

20 numeric string

temp_fax_number

Temporary fax number

Temporary faxnumber

20 numeric string

temp_pager_number

Temporary pager number

Temporary pagingbureau number

20 numeric string

temp_pager_ref

Temporary pager reference

Temporary pagerreference number

20 numeric string




temp_reachme_number

Temporary Reach-Menumber

The PIN to be usedwhen receivingcalls transferred viathe reach-mefacility.

20 numeric string

temp_referral_number

Temporary referral number

Temporarycall-forwardingnumber

20 numeric string

user_status

Application Status

Indicates whetherthe subscriber is in,out, sick, travelingor busy

1 0 = in (default)1 = out2 = sick3 = busy4 = traveling

vpim_address

VPIM address

Address forSMTP/MIMEdelivery

255 text

vpim_msg_del_pref

VPIM MDP

Message deliverypreference forVPIM

1 0 = Local1 = Remote2 = Local and remote

vpim_voice_type

VPIM voice format

VPIM voice format 1 0 = wav1 = au2 = 32KADPCM3 = DT6 elements4 = 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 anycombination of 15 characters.

From the Welcome window, click on Configuration —> Subscriber Classes

1. Defining a subscriber class : Click File —> New.The system displays the Subscriber Class window:


2. Type in the limits to be used for all mailboxes defined by applicationprofiles that are assigned to this subscriber class.

Maximum number of guest mailboxesspecifies the number of mailboxes that can be assigned to guestusers. For example, if one of your customers runs a messagingapplication for which they “buy” 10 mailboxes, but then subleasefive of those mailboxes to other people, those five mailboxesbecome guest mailboxes. This limit can be any number between 1and 9 (the system limit).

Maximum number of messages per mailboxspecifies how many messages an application can accept and storein one mailbox: any number between 0 and 999 (the system limit).

Maximum distribution lists per mailboxspecifies how many distribution lists can be created for onemailbox. When a voice application includes the logic for it, callerscan use the telephone to create distribution lists to distributemessages from a mailbox. You can also use WebSphere VoiceResponse to create distribution lists for a mailbox, as explained in“Creating a distribution list” on page 187). This limit can be anynumber between 0 and 90 (the system limit).


Maximum distribution list entriesspecifies how many members a single mailbox distribution list canhave. A member can be a mailbox or another distribution list. Thislimit can be any number between 0 and 90 (the system limit).

Maximum record time per messagespecifies the length of the messages that can be recorded. Don’t setthis higher than the value of the Record Voice Maximum systemparameter in the General parameter group.

Maximum number of greetings per mailboxspecifies how many different greetings the mailbox owner canrecord for a mailbox. The maximum number of greetings can beany number between 0 and 20. The system limit is 20.

3. Identifying the subscriber class : 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 theSubscriber Class window, you will see the new class listed.

Done

After you have created a new subscriber class, you must shutdown andrestart WebSphere Voice Response to make the subscriber class available.

To assign a subscriber class to an application, specify the subscriber class inthe application profile (see Specifying subscriber classes (optional)).

Creating a distribution list

Use this procedure to create a distribution list for a mailbox. This procedureassumes that you have already created an application profile that includesmailbox definitions and saved the profile. However, you can combine thisprocedure with the procedures in Chapter 5, “Creating an application profile,”on page 89


on page 89 and “Creating mailboxes for application use” on page 170 andcreate a distribution list for each mailbox after you define the mailbox andsave the definition.

Each distribution list is identified by a four-digit number. The number can beany combination of the digits 0 through 9.

A distribution list can be public or private. A private distribution list isreserved for the use of the mailbox owner. A public list can be used byanyone. 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 isno limit to the number of members on each distribution list. However, if theapplication profile is assigned to a subscriber class, the limitations defined bythe subscriber class may apply. (For more information on subscriber classes,see “What are subscriber classes?” on page 169.)

To create a distribution list for a mailbox:1. From the Welcome window, click on Configuration —> Application

Profiles

2. Selecting the mailbox : Open the application profile that defines themailbox.The system displays the profile information in the Application Profilewindow.

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 forwhich you are creating the list.

5. Naming the list : 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.


9. Classifying the list : Click the button next to Private or Public.10. Adding a mailbox to the list : To add a mailbox to the list, click Add

Box to List.The system displays a list of application profiles.

11. Click the application profile that you want to add to the distribution list.12. Click the button next to the mailbox that you want to put on the

distribution list.13. Click OK.


The system adds the mailbox to the distribution list and displays it as amember.

14. To add more mailboxes, repeat steps 10 on page 189 through 13 on page189.

15. Adding a distribution list to the list: 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 ofApplication 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 selectedmailbox:

17. Click the distribution list that you want to add to the current distributionlist.

18. Click OK.The system adds the distribution list as a member of the currentdistribution list.

19. To add more distribution lists, repeat steps 15 through 18.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 themailbox and saved it.


Chapter 13. Telecommunications Devices for the Deaf

The Telecommunications Device for the Deaf (TDD) is a telephony devicewith a QWERTY keyboard and a small display and, optionally, a printer.Instead of speaking into a mouthpiece, the caller types messages on thekeyboard; instead of hearing a voice from the receiver, the caller views themessages on the screen, and can print them for later reading. Usually, at bothends of the conversation, TDDs are being used.

Although the TDD itself does not generate DTMF tones, most users use aTDD in conjunction with a telephone that generates tones, and probably thinkof the whole thing as a TDD.

TDD support can be ordered as an optional feature of WebSphere VoiceResponse.

WebSphere Voice Response’s support is designed to operate with devicesmeeting the EIA Standard Project PN-1663 TDD Draft, 9 June 1986specification.

Making voice applications available to TDD users

Enabling your WebSphere Voice Response applications to communicate withTDDs makes your services and information available to callers who areunable to use an ordinary telephone.

WebSphere Voice Response can send characters as if it were another TDD. Thevoice application can recognize and generate TDD characters dynamically.

Figure 26. Two people communicating using TDD


TDD voice segments and prompts

To make a voice application available to TDD users, you have to add a newlanguage 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-onlylanguage, containing only voice segments, prompts, and voice tables. It doesnot contain any window text.

Voice segments? Yes, the signals that are transmitted along the voice channelto 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 usedfor converting text to speech, but TDD characters are generated instead ofspoken words. Voice segments are played to the caller using the PlayPromptaction, just as spoken voice segments are.

To add a TDD language to the system, see the WebSphere Voice Response forAIX: Configuring the System book.

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

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


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 systemprompts tailored in this way

To create tailored versions of prompts, you must create language-specificprompts, in the same way as you would for any other language, as describedin the WebSphere Voice Response for AIX: Application Development using StateTables reference manual.

TDD custom server subroutines

There is a set of custom server subroutines for use in applications that workwith 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 fromdigitized voice data.

v CA_TDD_Play_String() works like CA_Play_Voice_Stream(), taking anASCII string and playing it as TDD characters directly on a voice channel.

v CA_TDD_Get_String() works like CA_Record_Voice_Stream(), decodingthe 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.alibrary 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 usethe subroutines. The sample is called TDD_sample; it is supplied as an importfile, TDDSample.imp in the samples directory /usr/lpp/dirTalk/sw/samples,and must be imported as described in “Importing application objects” on page46. The sample application uses a shell script, TDD_talk, which is alsosupplied.

You can make many of your voice applications enabled for TDD users, but theTDD technology imposes some restrictions :v TDD segments are stored in uncompressed format, because the data would

not meet TDD specifications after compression and decompression. So thereis no support for voice messages, audio names, or user greetings.

Chapter 13. Telecommunications Devices for the Deaf 193

Note: When playing TDD segments or using a custom server to receiveTDD input ensure that you set the System : Voice Compression Typesystem variable (SV50) to 1, and the System : PlayPrompt CompressionType system variable (SV182) to 0.

v In addition, uncompressed segments are sensitive to the voice encodingscheme used on the trunk interface. The supplied U.S. English TDDsegments are only suitable for T1 trunk interfaces. If you create your ownsegments using CA_TDD_Create_Segment(), the appropriate encoding, forE1 or T1, is automatically selected.

v A TDD cannot generate DTMF tones. You need to adapt your existingDTMF-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 alsosupports the following control codes :

BACKSPACE <BS>

LINEFEED <LF>

CARRIAGE RETURN <CR>

It is recommended that your application inserts a <CR><LF> sequence after atmost 68 printable characters, to help the TDD printer to display the messagesproperly.


Chapter 14. Background music

WebSphere Voice Response includes a background music subsystem called thejuke box, which you can use to play background music in your applications.This chapter tells you how to implement background music using the jukebox:v “Why use background music?”v “Using the WebSphere Voice Response Juke Box” on page 200v “Adding background music to a state table” on page 202v “Getting music into WebSphere Voice Response” on page 206

To hear what background music sounds like, import the /usr/lpp/dirTalk/sw/samples/juke_box.imp, and then run the sample state tableMusical_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 cancustomize it, or you can write your own background music subsystem. Detailsare available on request: contact your IBM representative.

Why use background music?

Some requests take a while to process: playing background music during suchperiods can help to indicate to the caller that the application is still workingon the request. Your organization may already play music on hold , and yourdecision to play music during voice applications, and your choice of music,should take this into consideration. You may decide to play neutraleasy-listening music that suits the image of your organization, or you maydecide to play something related to your latest advertising campaign. Your“background music” does not have to be musical: it could be spokeninformation 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 beingprocessed by a person!

In this chapter, the word tune is used to mean a piece of music or otheruncompressed audio data saved in a format that WebSphere Voice Responsecan play on a music channel. Tunes are held as voice segments or in elementfiles.

Note: It is your responsibility to obtain the necessary permission from theowner of any rights to the music you intend to use, such as copyright in themusic 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 channelsper telephony trunk, while the prompts are played on the regular telephonychannels (as shown in Figure 28). Any application can use any one of themusic channels, so you can have all applications playing the same tune or upto eight applications can be playing different tunes; one application can playonly 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 thetelephony channels.

In the example shown in Table 8 on page 197, the applications on channels 1,2, 4, 5, and 9 are playing Tune 1, while the applications on channels 3, 7, and8 are playing Tune 2. At the same time, on channel 6, an application playsTune 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


Table 8. Applications simultaneously playing tunes from music channels

Telephony Channels

Music Channels

Tune1

Tune2

Tune3

Tune4

Tune5

Tune6

Tune7

Tune8

1 Application A Play


3 Application B Play



6 Application C Play1st

Play2nd

Play3rd




up to 24 T1 or 30 E1

The applications determine when to turn music on and off, and what music toplay. However, the application cannot control the point at which the musicstarts and stops, it can only control the volume. It’s as if the application wastuning into a radio station that is already broadcasting music. A musicchannel 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 thecaller is waiting for something to happen. Playing background music duringprompts is not recommended.

The background music is effectively mixed in with the prompts: the callershould be able to hear both if both are playing at once. Figure 29 on page 199

Chapter 14. Background music 197

shows what the caller is hearing at each stage in the interaction, on thetelephony channel and on the music channel. If required, you can turn downthe music during prompts.

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 ofprompts and background music does not exceed the maximum volume foryour telephone network.)

The volume of the prompts can be changed during the course of theapplication, and can fade in and out gradually. While the music is fading in orout, the application can either wait or continue with the next action. If theapplication continues with the next action, and the next action is aPlayPrompt, the prompt will start while the music is fading out, giving avoice-over effect.

The action of one application using a music channel does not affect the wayother 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 convertedby WebSphere Voice Response to µ-law. If you are using such as system,provided you obey the rule that music segments, elements, or data must usethe same encoding law as the other output (voice segments and so on) fromWebSphere 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 interruptdetection algorithm or the speech recognition algorithm, causingunpredictable results. For this reason we recommend that you do not usebackground music with either voice interrupt detection enabled or duringspeech recognition.

If you want to use background music with voice interrupt detection, eitherlower the volume of the background music to suit the current voice interruptdetection threshold, or raise the voice interrupt detection threshold. Thisshould result in a level of echo which is ignored by the voice interruptdetection algorithm. When testing your application, use the loudest music youhave, or a peak in the background music volume may cause problems later.


Callers interactionwith the application

Caller listensto prompt

Application waitsfor caller’s input



Caller listensto background music

while the requestis being processed

Caller listensto background music

while the requestis being processed




What the callerhears on the

music channel

Background musicquieter thanthe prompt



Background music


Background music

What the callerhears on the

telephony channel

Prompt

Prompt

PromptPrompt

Prompt

Figure 29. What the caller hears at each stage in the interaction


Using the WebSphere Voice Response Juke Box

The Juke Box is comprised of the Juke_Box custom server and two musicplayer 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 staticvoice file to an elements file (that can be used by WebSphere Voice Response)are also supplied.

The Juke_Box custom serverUsing the Juke_Box custom server your state table can start and stop a tunebeing played and add tunes to the music catalog dynamically.

The Juke_Box custom server maintains a music catalog of tunes. This catalogcontains entries from a configuration file and entries added dynamically bystate 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 atune, it starts a music player process which remains active until your statetable tells the Juke_Box custom server to terminate it.

The Juke_Box custom server handles requests from all state tables for allpacks on a WebSphere Voice Response system, so you need only one copy ofthe custom server running.

Starting and stopping the Juke_Box custom serverEach time WebSphere Voice Response starts, the Juke_Box custom server isstarted automatically. If you need to stop and restart the Juke_Box customserver, for example, to use a different configuration file, follow theinstructions for starting and stopping custom servers in the WebSphere VoiceResponse for AIX: Configuring the System book.

Stopping the Juke_Box custom server stops all music players, and releases anyresources used by them. Note that callers may hear their tunes cut off whenthis happens.

The Juke Box configuration fileWhen the Juke_Box custom server starts, it reads a configuration file to buildthe music catalog. The supplied music_catalog configuration file is ready touse 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, andcopy the music_catalog_a_law file:cp music_catalog_a_law music_catalog


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 customserver reads the configuration file only when it starts, so to make changeseffective 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'smain() function as a parameter. If you want to use a configuration file otherthan the default (music_catalog), you must change the properties on theJuke_Box custom server and restart it.

Note: If you are using the Juke_Box custom server on a cluster of WebSphereVoice Response systems that are configured as a single system image, filesthat 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, theJuke_Box custom server generates a yellow alarm. The Juke_Box customserver continues without a configuration file, that is, it starts with an emptymusic catalog. You can still use background music in your application byconfiguring tunes dynamically from your state table.

Configuration file format

Each tune in the configuration file has three fields; each field is surrounded bydouble quotation marks, as shown in Figure 30. Lines starting with # aretreated as comments; blank lines are ignored. For an explanation of the musictitle, music player name, and parameters, see the parameter descriptions forthe juke_box_configure_music custom server command in the WebSphereVoice Response for AIX: Application Development using State Tables book.

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

Figure 30. Example of a configuration file for the Juke_Box custom server


Adding background music to a state table

Figure 31 on page 205 shows a simplified overview of the actions involved inusing background music in a state table.

Use pairs of SendData and ReceiveData commands to send commands to thecustom 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, andReceiveData to check return codes.

Use the ControlMusic command to increase or decrease the volume of thetune that is playing.

Prerequisites1. 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 bepackaged to be imported and exported with the state table.

2. Unless you want to define tunes dynamically in the state table, you candefine your tunes in the configuration file. However, you should alwaysdefine a default tune in the configuration file, so that if an application failsto dynamically configure a tune, there is always a tune configured andavailable to be played by the application.

3. Ensure that a call has already been connected. The Juke_Box custom serverrejects SendData requests unless a call is already established or connected.

State table1. Start: Use the OpenHostServerLink action to set up a link between the

state table and the Juke_Box custom server. Check that the actionsucceeds. If it fails, let your application continue without usingbackground music.

2. If the tune you want to play is in the configuration file, go to step 5 onpage 203.

3. Define a tune dynamically: Use the SendData action, specifying thejuke_box_configure_music command. For details, see the WebSphere VoiceResponse for AIX: Application Development using State Tables.

4. Use the ReceiveData action and then check the return code. If theJuke_Box custom server was unable to configure the tune, don't ask theJuke_Box custom server to play it. Instead, either use a tune that youknow 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. Makeyour application as robust and forgiving as you can.

5. Start playing a tune: Use the SendData action, specifying thejuke_box_start_music command to tell the Juke_Box custom serverwhich tune to play. For details, see the WebSphere Voice Response for AIX:Application Development using State Tables book.

6. Use ReceiveData to get the return code and check that the tune starts toplay.

7. If the tune doesn't start playing, set up alternative paths for your statetable to follow. For example, if all the music channels are in use, you maywant your state table to use a “music-of-the-day” default tune (if yoursystem has this set up).

8. Take appropriate action for all possible results from the SendData andReceiveData actions.

9. Fade the tune in: Use the ControlMusic action to increase the volume ofthe tune while it is playing. The initial volume is low: increase it so thatthe tune can be heard.

Smooth Volume ChangeIf you want the background music in your application to fadesmoothly, use ControlMusic with a non-zero value for the FadeTime 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.

Instant Volume ChangeTo change the volume instantly, use ControlMusic with the FadeTime 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 ControlMusicaction.

11. Change Smoothly from One Tune to Another: If you want to changefrom one tune to another smoothly, use two ControlMusic actions in yourstate table. In the first action, fade out the current tune by setting the fadeoption 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 fadeactions complete or not, as you want).

12. Take appropriate action for all possible results from the ControlMusicaction.

13. Perform normal application activities: Some actions work withbackground music playing to the caller, some fade out background music


before the action starts, and fade in the music when it is complete. Youcan override the automatic fading using the system variables (seeTable 20 on page 341).

14. Fade the tune out: When your state table has finished with the tune, usethe ControlMusic action to fade the music to silence. Use a value of 80dBm for silence.

15. Stop playing a tune: If the tune plays successfully, make sure that yourstate table stops it playing (to release resources) before closing the hostserver link.

16. Use the SendData action, specifying the juke_box_stop_music commandto 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 theWebSphere Voice Response for AIX: Application Development using State Tablesbook.

17. Use ReceiveData to get the return code and check thatjuke_box_stop_music command was successful.

Note: The tune does not stop if it is still playing on another channel. Inthis situation, it stops when a juke_box_stop_music command has beenreceived by the custom server from each of the channels on which thetune is playing. (In effect, the custom server needs to receive ajuke_box_stop_music command for every juke_box_start_musiccommand that was issued.)

18. Cleaning up: Use the CloseHostServerLink action, specifying theJuke_Box custom server.

19. End the call, free any resources that the application used, and terminate.


Debugging your state tableTo debug your state table, use the state table debugger. You may also need totrace the custom server, and you will probably find it useful to monitor thebackground music channels.

Errors generated by the Juke_Box custom server are listed in the WebSphereVoice Response for AIX: Problem Determination book.

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 31. Schematic overview of part of a state table using background music


Tracing the custom server

Use custom server trace to capture information about how your custom serveris working with your state table. See the WebSphere Voice Response for AIX:Custom Servers book for details.

You can select entries for the Juke_Box custom server only from the customserver 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 book for moreinformation.

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 formatthat WebSphere Voice Response can use. Figure 32 on page 208 shows somepossible sources of music and how to convert your source.

Supplied tunesTwo 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 1v WebSphere Voice Response theme 2

A music_a_law voice directory is supplied for use on A-law systems (E1).


The same tunes are in the $DB/current_dir/ca/juke_box_dir/ directory aselement 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)


Follow the batch voice import processdescribed in the State Tables, Prompts,and Voice Segments reference manual.When converting tunes, edit the ASCIIindex file to check that the tune does notspread over several segments. Alsocheck that there is only one tune persegment. When you make the ASCIIdescription file (using bvi_desc) provide atitle for the music.

ElementFile

.WAV file


database segment

music player(not supplied)

bulk voice import utility

CA_Play_Voice_Stream()custom server routine

CA_Play_Voice_Elements()custom server routine

music channel on WebSphere Voice Response

cvelem utility

dynamic blocks ofaudio data

(uncompressedm-law or A-law)

bvi_rec utility bvi_aiffbvi_wav

.AIFF file

Ultimedia Audioadapter from DAT,microphone, tape,

CD, or line-in

static voice file8kHz,16-bitbig-endian

pl_elem (music player)called by the Juke_Box

custom server

linear audio datafile from another

system

pl_seg (music player)called by the Juke_Box

custom server

Figure 32. Getting tunes into WebSphere Voice Response for background music


Chapter 15. TDM connection management

TDM connection management helps to coordinate the making and breaking oftime-division multiplex (TDM) connections between resources such as channelson packs, and channels on digital signal processor (DSP) adapters. Customserver subroutines allow you to write applications that exploitindustry-standard time-division multiplex (TDM) bus (TDM bus) capabilitiessuch as matrix switching, one-call fax, speech recognition, and text-to-speech.

In addition, TDM connection management also enables you to implementfacilities such as tromboning: connecting a caller to an agent or other service,via WebSphere Voice Response. This type of connection can be used evenwhen the switch does not support call transfer.

WebSphere Voice Response supports the TDM bus, through the Digital TrunkTelephony Adapter (DTTA). Support for other adapters can be added bywriting a connection server.

Concepts

This section introduces the concepts of TDM connection management.

PortsA port is one end of a 64 kbps unidirectional stream, which can be attached tothe TDM bus. Ports can be seen as sources, which put voice on to the TDMbus, or sinks which take voice data from the TDM bus. Examples of sourceports are:v The stream received from a caller via a telephony channel and placed on

the TDM bus by the DTTA.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 setsOften, an application needs to connect multiple streams. For example, acustom server for matrix switching must connect caller A's transmit stream tocaller B's receive stream and vice versa. For this reason the concept of a portset is useful. A port set is a set of one or more ports which may need to beconnected to a complementary port set as a single operation. Examples of portsets containing more than one port are:v The transmit-receive pair of a telephony channel on a DTTA.


v For speech recognition with barge-in and the ability to play beeps as aprompt 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 thesoftware support for an adapter. You do not need to modify this file, but youmay need to refer to it to understand what port sets have been defined. Thecustom server subroutines accept port set names as parameters. A port setmay consist of a single port. A port can be a member of several port sets as itmay need to be used in different combinations by different applications. Portsets to be connected must be compatible, that is they must contain acomplementary number of sources and sinks.

Resource groupsA 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 portsets. In a running system, there may be multiple instances of each definedresource group. TDM connection management will create multiple instances ofthe resource group, depending on how many adapters, E1 or T1 interfaces orDSPs are installed.

For example, a fax adapter may support 12 fax channels. This would bedefined as one resource group containing 12 port sets. If two fax adapters areinstalled, 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 33. Ports, port sets, sources, and sinks


The main benefit of the resource group concept is that a resource group isonly defined once when a new resource group type is configured, and theactual number of resource groups in the system can be discovereddynamically at system startup. No configuration changes are needed just toadd a new instance of an existing resource group.

Port set naming

The custom server subroutines relating to TDM connection managementrequire port set names as parameters. A standard naming scheme is adopted:

ResourceGroupName.N.PortSetName.M

ResourceGroupNameis the name of the resource group type, as specified in aresource_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)

PortSetNameis the name of the port set type, as specified in a port_set= keywordentry 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. Theresource group name for all of these port sets is dtpack. A port set calledchannel consists of two ports: a sink port (raw_out) which takes speech fromthe TDM bus and plays it to a caller, and a source port (raw_in1) which putsa caller’s voice onto the TDM bus. This port set can be used in applicationssuch as matrix switching, or one-call fax. The first channel on the first digitaltrunk 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 demonstrateshow you can use TDM connection management to implement your ownapplications.

This application is similar to the calling card service provided by manytelephone companies. A customer dials in to the calling card application, andenters the telephone number to which they wish to connect. In a real callingcard service, the customer would also provide card details and a personalidentification number, but these are omitted from the sample application.

Chapter 15. TDM connection management 211

After the customer has entered a phone number, WebSphere Voice Responseplaces a second call to the specified number, and as soon as this call isanswered, the two calls are connected via the TDM bus. The customer cannow talk to the called party.

This arrangement is sometimes called a trombone, or hairpin, a reference tothe shape of the voice path between the two parties; from the switch to theIVR 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 canmonitor DTMF key presses made by either party. This feature is not used inthe sample application, but in a real service, DTMF keys could be used torequest additional services, such as conference calling, or putting a caller onhold.

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

Prerequisitesv A PCI WebSphere Voice Response system with one or two DTTA adapters.

If two adapters are installed they should be connected using the suppliedH.100 ribbon cable. If only one is installed, an H.100 cable is not needed.

v A connection to a switch or public network using a trunk that supportsboth 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.

Procedure1. From the Welcome window, click on Applications —> Applications

2. Importing the application : Click Application —> Import.3. Click the /usr/lpp/dirTalk/sw/samples/IBM_Trombone.imp file.4. Creating an application profile: Open the Trombone application.

The system displays the Application (Trombone) window.5. Click Object —> New —> Application Profile.

The system displays the Application Profiles window followed by theApplication 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 newApplication Profile icon inside it.

13. Building and installing the custom server: Open the TromboneCScustom server.

14. Click Utilities —> Build.15. Click Utilities —> Install.

Note: Full instructions for building and installing custom servers areincluded in the WebSphere Voice Response for AIX: Custom Servers book.

16. Running the ApplicationPick up Phone A's handset and dial theapplication profile ID.WebSphere Voice Response answers the call and prompts you to input atelephone 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 pathbetween the two telephones.

Designing an application

A TDM application consists of State tables and Custom servers. This sectiondescribes how they are used in designing a TDM application.

State tablesState tables manage the interaction with callers. State table actions are used toanswer calls, and to place outgoing calls. They may send requests to customservers to invoke additional facilities, such as TDM connections.

Custom serversTDM port sets are connected and disconnected by custom server librarysubroutines, CA_TDM_Connect() and CA_TDM_Disconnect(), therefore anapplication using TDM connection management must contain at least onecustom server. The custom server is responsible for connecting TDM port setsin response to requests from state tables, and for disconnecting port sets onrequest from an state table, or cleaning up TDM connections in errorconditions.


Custom server subroutines

WebSphere Voice Response provides two custom server subroutines forconnecting 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 applicationThe TDM sample application uses three different state tables, and one customserver.

TromboneIn state table

TromboneIn answers the customer’s call and prompts the customer to enter atelephone number. When the customer has entered the number, TromboneInmakes 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 twochannels. 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) tomonitor activities of the calling party.

TromboneOut state table

TromboneOut is invoked by the custom server dial the telephone numberspecified by the customer. The number is passed to TromboneOut byparameter. TromboneOut uses a MakeCall action to select a free outgoingchannel and dial the telephone number. The MakeCall action completes eitherwhen the call is answered by the called party, or when the call fails, forexample because the number is invalid or busy, or there are no outboundlines available. On completion of the MakeCall action, TromboneOut notifiesthe custom server of the outcome of the call attempt, and then invokes theTromboneMonitor state table to monitor subsequent activities of the calledparty.

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 aDTMF key, the name of the key is announced to the caller; this feature doesnot serve any real purpose, but demonstrates how a real application could useDTMF keys to invoke service features. In this application, custom serverchannel 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 calleron this channel, then exits. If the party on this channel hangs up, the statetable exits.

TromboneCS custom server

TromboneCS is a custom server which manages the relationships betweendifferent channels, including making and breaking TDM connections betweenthem. TromboneCS provides two user functions which may be used by statetables, and one system function:

t_outdial()This function represents a request to allocate a new channel and dial aspecified phone number on that channel. TromboneCS executes thisby allocating a new channel process (CHP) and executing theTromboneOut state table with that new CHP. t_outdial() sends aresponse to the calling state table when the outbound call attempt iscomplete, indicating whether the attempt succeeded or failed.

t_outdial_complete()This function represents an indication from a state table that anoutbound call attempt has been completed, and whether the attemptsucceeded or failed. There is no response to this user function.

t_chsl()This is a CloseHostServerLink function, which is invokedautomatically 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 whichcoordinates the making of the trombone connection between the two parties,and breaking that connection when one of the parties hangs up. Figure 34 onpage 216 summarises the steps involved in making and breaking theconnection.


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 34. Making and breaking a trombone connection


Implementation notesThis section provides more detailed information about the implementation ofthe sample application, and suggestions for developing your own applicationswhich use TDM connection management.

Error handling

Error handling in the sample application is simplified to make the code easyto understand. Errors in the custom server are treated as fatal and the customserver will exit. Errors in the state tables cause a “technical difficulties”announcement to be played to the caller and the call terminates. If youdevelop a production application based on this sample, you should enhancethe error handling to improve reliability and usability.

ASCII state tables

TromboneIn, TromboneOut and TromboneMonitor were written as ASCII statetables. 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 easierto understand how the application works. If you want to change the statetables, you may find it easier to change the ASCII versions, and import themodified state tables, rather than making changes using the State Tablewindow.

TromboneCS state machine

Each “trombone”, that is, connection between a calling and a called party, isdescribed by a state machine, so that the trombone moves between variousstates according to events, which are the custom server user functions.Figure 35 shows the states and events in this state machine.

Data structures

TromboneCS uses two main data structures:

tromboneA structure which holds the status of one trombone, including the

t_idle

t_chsl() t_chsl()

t_outdial()

t_outdial_complete()

t_dialing

t_connectedt_disconnected

Figure 35. The TromboneCS state machine


link_id of each of the two channel processes involved, theconnection_id returned from CA_TDM_Connect(), the current state ofthe connection, and a copy of the t_outdial() request which initiatedthis trombone, and which is modified to become the t_outdial()response when the trombone is connected.

t_arrayAn array of pointers to trombone structures, one for each channelprocess in the system. This provides a way to access the trombonedata structure for a particular channel process, by using the link_id asan index into the array. A null pointer in this array means that thecorresponding channel process is not involved in a tromboneconnection.

Custom server main() function

When you develop a custom server, you can choose to have WebSphere VoiceResponse create the main() function, or provide your own. TromboneCSprovides its own main() function, because the system generated main()assumes that each user function will return a response to the state table whenthe user function returns. TromboneCS cannot return a response to the statetable as the t_outdial() function returns, because it must wait for thet_outdial_complete() message from TromboneOut to discover whether theoutdial attempt was successful. The main() function is modified compared tothe system-generated main() to take account of this.

TDM connection token

When you make a TDM connection using CA_TDM_Connect(), you have tosupply an unsigned integer as a token for that connection. The same tokenmust be supplied when the connection is broken, either byCA_TDM_Disconnect() or by making a new connection involving the sameports. This simple security mechanism prevents unauthorized custom serversfrom breaking your connections. As a custom server writer, it is yourresponsibility to choose a token for your connections. The sample applicationuses a four character string, “TROM”, and casts this into an unsigned integerfor use as a token.

Cleaning up TDM connections

TDM connection management is designed to break TDM connectionsautomatically when a caller involved in the connection hangs up. Thisprotects against callers hearing spurious speech when a call ends and thetelephony channel is reused. However, resources associated with theconnection remain allocated until the connection has been explicitlydisconnected by a call to CA_TDM_Disconnect(). So it is your responsibility as


a custom server writer to disconnect any TDM connections you establish. Agood way is to keep track of connections made by each channel process, andto provide a CloseHostServerLink function. When the custom server isnotified via this function that a channel process has detached from the customserver, it can disconnect all TDM connections associated with that channelprocess. This technique is illustrated by TromboneCS.

Notifying hang-ups to the partner channel process

When one of the parties connected by a trombone hangs up, theTromboneMonitor state table interacting with this party detects the hangupevent and exits. But the application must also provide a way for this hangupto be notified to the state table interacting with the other party. There are twosteps 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 anasynchronous notification from custom server to a state table. A channelevent 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 beconfigured to detect voice energy or fax tones if you wish, by settingsystem variables, as described in the WebSphere Voice Response for AIX:Application Development using State Tables book. Each channel eventcontains an event type and an information field, which can be used toprovide different types of notifications from custom servers to state tables.The sample application uses only one type of event, so the event andinformation fields are set to zero. When TromboneMonitor receives achannel event, it makes a short announcement to the attached party andthen terminates the call.

Moving to a multiprocess custom server

The CA_TDM_Connect() and CA_TDM_Disconnect() custom serversubroutines will block your custom server process while waiting for aresponse from TDM connection management. This means that a single-processcustom server design, as implemented in the sample, may not be suitable fora production environment where high throughput is required. This issue isdiscussed in “Designing a multiprocess custom server” in the WebSphere VoiceResponse for AIX: Custom Servers reference manual.

A multiprocess non-associated design would be a good choice for thisapplication. You could fork() several identical copies of the custom serverprocess to increase throughput, and place t_array, the array of trombone data


structures in shared memory to allow access from any of the processes. Youshould allocate storage for the trombone data structures statically in sharedmemory, instead of using malloc() as in the sample, because storage allocatedby malloc() is not accessible outside the process which allocated it.

Voice paths

The main purpose of the trombone application is to allow the two partiescarry out a conversation. However, one of the benefits of using WebSphereVoice Response to provide this service is that your application can also makeannouncements to the parties, record their voices or allow them to use DTMFkeys to invoke features of the service. In general, you can use Play, Recordand GetKey actions freely in your state tables, and they will behave as youexpect. But it is useful to have a clear understanding of the voice paths in thesystem so that you understand WebSphere Voice Response's capabilities andlimitations.

Figure 36 shows the voice paths which are in effect while a tromboneconnection is established. State table A can always record the spoken voice ofparty A, Tom for example, or detect Tom's DTMF keys. Likewise, state table Bcan 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.

State Table A

State Table B

TDM bus

Tom

Daisy

Figure 36. Voice paths in a trombone connection


Figure 37 and Figure 38 show the switches that control what each party canhear. Your application does not need to do anything to control the position ofthese switches: they are manipulated automatically by WebSphere VoiceResponse. 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 37). In this example, Daisy can hear Tom'svoice.

v But when state table B plays an announcement, WebSphere Voice Responsethrows the switch into the host position (as shown in Figure 38), so thatDaisy can hear the announcement. Tom does not hear this announcement.The switch remains in the host position for the duration of theannouncement, during which time Daisy cannot hear Tom's voice. At theend of the announcement, the switch reverts to the TDM position so thatTom and Daisy can resume their conversation.

Echo susceptibility

“Voice paths ” on page 220 stated that state table A cannot hear Daisy's voiceand state table B cannot hear Tom. This rule may not hold true if the circuit

State Table B

Daisy

From Tom

Daisy can hear Tom

Record

Play

Switch inTDM position

Figure 37. 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 38. Voice paths when the switch is in host position


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'svoice circuit or handset. The echo cancellation feature of the digital trunkadapters cannot be used to reduce these echoes, because the output from theTDM bus by-passes the digital signal processors in the pack.

If your customers use echo-prone telephone connections, you should take thisinto account in your application design. For example, it may be better to offerDTMF facilities to the calling party but not to the called party. If you disableDTMF detection in one of the state tables, you avoid the risk that a DTMFdetector may be triggered by an echoed DTMF tone.


Chapter 16. Designing for a single system image

Most voice applications will run without any changes on WebSphere VoiceResponse systems that are configured as a single system image. State tables,prompts, or custom servers that use application data (by, for example, playingor recording voice segments) do not need to be aware of whether or not theyare running on a single system image: they will access that data in exactly thesame way whether they are running on a stand-alone WebSphere VoiceResponse system, on a client node, or on a database server node. However,you should consider the following points when you design a voice applicationthat 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 inthe single system image, so an application that processes this data for thewhole single system image will have to collect data from the log files oneach node.

v If your voice application uses custom servers to access hardware orsoftware resources that cannot be made available in exactly the same wayon all client nodes of the single system image, your application must beable to handle any differences. For example, if a telephone call cannot bedirected to the particular node that is known to have the resource requiredto process it, the voice application may need to transfer the call to thatnode.

v Applications that play voice segments using prompts will perform better ina single system image because such voice data may be cached locally on theclient nodes, and will not require voice data to be accessed using thenetwork.

v Using uncompressed voice segments instead of compressed voice segmentswill increase the network bandwidth required by a factor of 5, unless suchdata has been cached using the prompt mechanisms and the segments areplayed using prompts.

Querying the single system image configuration

An application may need to determine whether it is running on a client nodeor a server node of a single system image, or if it is running on a stand-alonesystem. It may need to do this, for example, to restrict the running ofhousekeeping processes to one machine.

The application can find this information like this:


v In a state table, test the value of SV540 (System : SSI (Single System Image): State). This numeric system variable represents the mode in which thenode has been configured. For more information, see the description of thissystem variable in WebSphere Voice Response for AIX: Application Developmentusing State Tables.

v In a custom server, call the CA_Get_DT_Info() subroutine. TheDT_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 WebSphereVoice Response for AIX: Custom Servers.

To find from the command line the type of system you are logged on to, usethe ssistatus command. For more information, see the description of thiscommand in WebSphere Voice Response for AIX: Configuring the System.


Chapter 17. Using ISDN call transfer

This chapter describes how to transfer calls on WebSphere Voice Responseusing ISDN. WebSphere Voice Response supports four protocols, EuroISDNand E1 QSIG Single Step Transfer Supplementary Service protocols, the ISDNtwo B-channel transfer protocol, and the Nortel proprietary Release LinkTrunk (RLT) call transfer protocol.

The ISDN call transfer application works with the two B-channel transfer andthe Nortel RLT protocols, and where there are differences between the twothese are noted, otherwise the information in the following section applies toboth protocols.

The ISDN single step call transfer works in a different way, and uses adifferent 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 226v “When can I use ISDN RLT call transfer?” on page 226v “When can I use ISDN single step call transfer?” on page 227v “What the ISDN call transfer application does” on page 227

– “Limitations of ISDN call transfer” on page 228– “Installing the application” on page 228– “Configuring the ISDN_Call_Transfer custom server” on page 231– “How to use ISDN call transfer” on page 233– “Custom server functions” on page 245– “State table definitions” on page 249

v “What the ISDN single step call transfer application does” on page 258– “Limitations of ISDN single step call transfer” on page 259– “Installing the application” on page 259– “Configuring the SSTransfer custom server” on page 261– “How to use ISDN single step call transfer” on page 262– “Custom server functions” on page 263– “State table definitions” on page 269


When can I use ISDN Two B-channel transfer?

WebSphere Voice Response implements the ISDN Two B-channel transferprotocol that is defined in the Bellcore document Generic Requirements forISDN PRI Two B-Channel Transfer, GR-2865-CORE Issue 2.

WebSphere Voice Response supports one specific version of ISDN TwoB-channel transfer:v Nortel DMS-100 at release level NA012.

This version is described in the document NT - NI Primary Rate UserNetwork Interface Specification,publication number NIS-A233-1, standardrelease 05.03, issue date 3rd August 1999.

Blind ISDN Two B-channel transfer is also supported by WebSphere VoiceResponse.

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 ISDNRLT call transfer protocol as defined in the Nortel document ISDN PrimaryRate 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 UserNetwork Interface Specification,publication number NIS-A211-1, standardrelease 07.05, issue date May 1997.

v Nortel DMS-250 at release level IEC05.This version is described in the Nortel document PRI RLT FeatureApplication 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 single step call transfer?

WebSphere Voice Response implements the Euro ISDN single step transferprotocol 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 tableso that the contents of SV542 (call data) are saved into SV51 before the callis answered and the call data lost.

v From the Welcome window, click Configuration -> Systemconfiguration->Change->Application server interface.

v In the Application Server Interface window displayed, set State table namefor 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 ofcall-transfer operation uses the same channel as the incoming call when itmakes the call to the third party to prepare for a transfer. However, ISDN calltransfer requires that the call to the third party is made on a different channelfrom that used for the original call. To match these two requirements, theISDN call transfer application of WebSphere Voice Response for AIX modifiesthe ISDN Signaling Process and provides a custom server that performs thecall to the third party when a TransferCall request is received.

WebSphere Voice Response implements ISDN call transfer in the followingway: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 usesthe TransferCall state table action to initiate the transfer.

2. The ISDN Signaling Process makes an outgoing call using the customserver and an outbound state table on another channel. When you createyour voice application, you may have to modify the supplied outboundstate tables, depending on the needs of your application (for example, theRing Time parameter of MakeCall can be changed).

3. When the third party has answered, the outbound state table informs theISDN Signaling Process using the custom server.

4. For a blind transfer, the ISDN Signalling Process then asks the switch tocomplete the transfer using a request and then ends the TransferCall actionin the incoming state table. For screened transfer, the ISDN Signalling

Chapter 17. Using ISDN call transfer 227

Process ends the TransferCall action in the incoming state tablestraightaway. 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 asksthe switch to complete the transfer using a request.

7. The caller and third party should now be connected within the switch. Thetwo call stubs connected to WebSphere Voice Response (the inbound callfrom the original caller and the outbound call to the third party) areterminated 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 transferThere are some limitations associated with using ISDN call transfer withWebSphere 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 VoiceResponse from the same switch. The Bellcore specifications allow the twocalls to be on different trunks, provided that both trunks support ISDN TwoB-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 ISDNtrunks, the user application should ensure that the outbound call is madeon the correct trunk for an ISDN call transfer to be successful.

Note: The Nortel DMS-100 switch at release level NA008 permits a transferonly if the two calls (inbound and outbound) are on the same trunk. Thismust 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 whenporting applications that involve transfer operations from differenttelephony configurations. This applies mainly if you want to perform athird party consultation during a screened transfer operation.

v ISDN RLT blind transfer is not supported.

Installing the applicationThe ISDN call transfer application is supplied as an installp image that youinstall using the System Management Interface Tool (SMIT). The applicationcontains three components, including some source code to help you customizethe ISDN call transfer capability to your specific needs. For a straightforwarduse of the ISDN call transfer capability, no customizing should be required.

The components of the application are:v Updated ISDN support.


v State tables (including source code):The following state tables are provided (for definitions for these state tables,see “State table definitions” on page 249):– ISDN_Imm_Xfer– ISDN_SupA_Xfer– ISDN_Xfer_C5– ISDN_Xfer_C10– ISDN_Xfer_Data– ISDN_Xfer_Stat– ISDN_Xfer_LogThe source code for these state tables is supplied in an ASCII file in thesame 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 thelow-level functionality of the trombone operation (for details of theavailable calls, see “Custom server function definitions” on page 245).

Note: Only the executable version (not the source code) of this customserver 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 6.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 book.v Sufficient disk space for the components you are installing (the WebSphere

Voice Response for AIX: Installation book explains how to check this; see thesection “Ensuring you have enough disk space for the new software”).


Installing1. Installing the application: Follow the instructions in “Installing the

WebSphere Voice Response software” in the WebSphere Voice Response forAIX: Installation book to use the System Management Interface Tool(SMIT) to install the PTF that contains the ISDN call transfer application.

2. Starting WebSphere Voice Response: Start WebSphere Voice Responseand log in to the user account you use for WebSphere Voice Responseadministration.

3. Importing the custom server and state tables: In the WebSphere VoiceResponse Welcome window, click Applications —> Application —>Import—> Replace—> File.

4. Select the file /usr/lpp/dirTalk/sw/isdn/call_transfer/ISDN_Call_Xfer.imp.

5. Creating an application profile: 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 theApplication 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.


14. Starting the custom server: 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

Note: The exact sequence here depends on your application. Assumingyour 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 thetransfer to a third party. It answers the call and prompts you to input thetelephone number that you want to transfer to, followed by a # key.


18. Pick up Phone B's handset.The application completes the transfer when Phone B is answered andthe voice path for the two calls is connected within the switch.

19. The two remaining connections to WebSphere Voice Response (originallyconnected to Phones A and B) are disconnected shortly after the transferis completed.

Configuring the ISDN_Call_Transfer custom serverThe ISDN_Call_Transfer custom server has some command line parametersthat you can set to help you debug problems, or to fine-tune the operation ofthe custom server.

The parameters are defined in Table 9. For information on how to set theparameters, see “Setting configuration options” on page 232.

Table 9. 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 tothe information that always gets sent). Valid valuesare 0 (none) to 4 (everything). To set the logginglevel to 3, specify –d3 . Level 4 traces Protocol DataUnit creation, and is always written toDTstatus.out. Normally level 3 tracing should besufficient for problem determination.

-en n=0 The event data (n) sent by the custom server if thethird party hangs up (seeCA_Report_Channel_Event() in the WebSphere VoiceResponse for AIX: Custom Servers book).

-in n=0 The information field (n) sent by the custom serverif the 3rd party hangs up (seeCA_Report_Channel_Event() in the WebSphere VoiceResponse for AIX: Custom Servers book).

-s off Print debugging information to stdout, as well as toAIX system trace.


Table 9. Configuration options for the ISDN_Call_Transfer custom server (continued)


-z off This parameter is for test purposes only. It causesthe custom server to enrol one of each type of errorpossible 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 theoutbound state table. This must be the same for allof the outbound state tables used in ISDN transferoperations.

-Lfile_name file_name = null Name of the log file to be used for logging debuginformation. If this is blank, no logging informationwill be sent.

-Ssttbl_name sttbl_name =ISDN_SupA_Xfer

Name of the state table to use for screened transfers(that follow the WebSphere Voice Responsesignaling 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

2. Setting a command line parameter for the custom server: Highlight theISDN_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.

8. Restarting the custom server: Open the Custom Server Manager windowby 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.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. Thenew command line parameters are now in effect. If the Run Statusremains at None, there is probably an error with one of the commandline parameters. Check the error log for details.

How to use ISDN call transferThis chapter describes how to perform a transfer operation using the ISDNcall transfer mechanism.

If your requirements for transfer are fairly simple, you should not have tochange your applications or the supplied state tables.

The description in the WebSphere Voice Response for AIX: ApplicationDevelopment using State Tables book of how the TransferCall state table actionworks gives general information on how to perform a transfer. Transfer usingISDN works in generally the same manner, and differs significantly onlywhere 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 hassuccessfully contacted the third party.This type of transfer should require little or no modification to yourapplication 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 thirdparty has answered. If the third party did not answer, the application cancontinue interacting with the caller.This type of transfer should require little or no modification to yourapplication 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, duringthe transfer. The transfer can then be completed, or the application canreconnect to the original caller and continue.The outbound call state table application performs the interaction with thethird party.


This type of transfer requires modifications to your application and to thesupplied state tables. The supplied state tables have been written to makethis as easy as possible.

The type of transfer you use will depend on your application requirements.The following sections describe how to implement the various types oftransfer and highlight any changes that you may have to make to yourapplication or to the supplied state tables.

Blind (immediate) transfer

Blind (immediate) transfer is a transfer that completes before knowing if thecaller has successfully contacted the third party.

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 zero to indicate that a blind transfer isrequired.

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 39. Event flow for a blind (immediate) transfer


2. The ISDN Signalling Process receives the TransferCall request and initiatesan outbound call to the third party using the ISDN_Imm_Xfer state tablewith 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 setto zero to indicate that a blind make call is required. The make call returnsas soon as the call is underway, or if there is a problem with the suppliedparameters (for example, the phone number contains invalid characters).

4. When the MakeCall action returns, the outbound state table informs theISDN_Call_Transfer custom server (and so the ISDN Signalling Process) ofthe result and enters into a WaitEvent. It should not hang up at this stagebecause this may interfere with the completion of the transfer.

5. The ISDN Signalling Process sends a message to the switch to request thatthe caller and third party are connected together (the actual transfer) andwaits for the switch to confirm this.

6. The ISDN Signalling Process sends the result of the transfer to theincoming state table, which causes the TransferCall action to return.

Soon after step 5, the switch hangs up both the incoming and outgoing callsconnected to WebSphere Voice Response. If these calls are not disconnected bythe switch within a reasonable time, the WebSphere Voice Responseapplications 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 modificationto either the user application or to the ISDN_Imm_Xfer state table. The mostlikely modification that may have to be made though, is to specify whichchannels may be used to make the outbound call (see SV178 definition in theWebSphere Voice Response for AIX: Application Development using State Tablesbook). This modification should be made in the ISDN_Imm_Xfer state tablebefore the MakeCall action is performed.

Screened transfer (with call answer supervision)

Screened transfer (with call answer supervision) is a transfer that completesafter knowing whether or not the third party has answered. If the third partydoes not answer, the application can continue interacting with the caller.These two scenarios are described in the following sections:v Figure 40 on page 236 shows what happens when the third party answers

and the transfer completes.v Figure 41 on page 238 shows what happens when the third party is not

contactable and the transfer is abandoned so that the incoming applicationcan continue interacting with the original caller.



ring_time parameters set to non-zero values to indicate that a screenedtransfer is required.

2. The ISDN Signaling Process receives the TransferCall request and initiatesan outbound call to the third party using the ISDN_SupA_Xfer state tablewith 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 setto non-zero values to indicate that a screened make call is required. Themake call returns as soon as the call is answered (because this is asuccessful transfer).

4. When the MakeCall action returns, the outbound state table informs theISDN_Call_Transfer custom server (and so the ISDN Signaling Process) of

Caller

Third Party


InvokeStateTable(default = ISDN_SupA_Xfer) ISDN_SupA_Xfer

MakeCall


Return the Success edgeto the TransferCall request

WaitEventWait for DTMF, Hangup


TerminateCall

TransferCallring_wait > 0ring_time > 0

User Incomingapplication

EDGE:

ring_wait > 0ring_time > 0

Note the OHSL

MakeCall returns as soon asthe result of the call is known.Since the result was success,

third party phone will beanswered at this stage.


Returns the edge from theprevious MakeCall action.




Success

Wait for response from switch

Return Success edgeto the TerminateCall requestEDGE:

Success

Send Host Event to theoutbound state table EDGE:

HostEvent

TerminateCall



At this time, the caller is connected to the third party within theswitch and the incoming and outgoing channels will be hung up.

Figure 40. Event flow for a screened transfer with call answer supervision (for a successful call)


the result and enters into a WaitEvent. It should not hang up at this stagebecause this will interfere with the completion of the transfer.

5. The ISDN Signaling Process sends the result of the transfer to theincoming state table, which causes the TransferCall action to return.

6. The incoming state table should then perform a TerminateCall to completethe transfer.

7. On receiving the TerminateCall from the incoming state table, the ISDNSignaling Process sends a message to the switch to request that the Callerand third party are connected together (the actual transfer), and waits forthe switch to confirm this.

8. The ISDN Signaling Process sends a HostEvent to the outbound statetable, 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 modificationeither to the user application or to the ISDN_SupA_Xfer state table. The mostlikely modification that may have to be made though, is to specify whichchannels may be used to make the outbound call (see the SV178 definition inthe WebSphere Voice Response for AIX: Application Development using State Tablesbook), or to modify the ring_wait and ring_time parameters used in theMakeCall state table action. Modifications to system variables should be madein the ISDN_SupA_Xfer state table before the MakeCall action is performed.



ring_time parameters set to non-zero values to indicate that a screenedtransfer is required.


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 setto non-zero values to indicate that a screened make call is required. Themake 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 theISDN_Call_Transfer custom server (and hence the ISDN Signaling Process)of the result and terminates the call.

Figure 41. Event flow for a screened transfer with call answer supervision (for an unsuccessful 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 TransferCallaction to return.

6. The incoming call state table performs a ReconnectCall.7. The ISDN Signaling Process returns Success or CallerHungUp, depending

on the current state of the call. This causes the ReconnectCall action toreturn.

8. If the edge returned from the ReconnectCall action was Success, theincoming application can continue to interact with the caller; otherwise itmust hang up.

For most applications, this type of transfer can be used without modificationeither to the user application or to the ISDN_SupA_Xfer state table. The mostlikely modification that may have to be made though, is to specify whichchannels may be used to make the outbound call (see the SV178 definition inthe WebSphere Voice Response for AIX: Application Development using State Tablesbook), or to modify the ring_time and ring_wait parameters used in theMakeCall state table action. Modifications to the system variables should bemade in the ISDN_SupA_Xfer state table before the MakeCall action isperformed.

Screened transfer (with third party consultation)

Screened transfer (with third party consultation) is a transfer that can interactwith the third party, if it answers, during the transfer. The transfer can then becompleted, or the application can reconnect to the original caller and continue.

Due to limitations with the WebSphere Voice Response hardware, the originalcaller state table cannot perform the third party interaction, and so theWebSphere Voice Response signaling model for a transfer operation cannot befollowed precisely. Instead, the outbound state table must perform the thirdparty interaction. Two custom server calls (and associated state tables) havebeen added to allow the inbound and outbound state tables to perform somebasic communications during the transfer. This should keep any changes toyour application to a minimum.

Figure 42 on page 240 shows a third party consultation that ends with atransfer, and Figure 43 on page 243 shows a third party consultation that endswith a reconnection to the original caller.


The sequence of events in Figure 42 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

Caller

Third Party



MakeCall





TerminateCall



EDGE:


Note the OHSL




Returns the edge from theprevious MakeCall action




Success

Wait for response from switch

Return Success edgeto the TerminateCall request

EDGE:Success

Send Host Event to theoutbound state table EDGE:

HostEvent

TerminateCall


Note the OHSL

SendData(SetUserData)

Sets up user_data passedto the outbound. state table

Record the user data to bepassed to the outbound state

table when it is invoked.

Interact with the third partyand gather responses

and the third party response.and record third partyresponses for later

SendData +

(GetUserStatus)Retrieves the third party

response gathered by the

Return the third partyresponse that was stored.

ReceiveData

outbound state table

Process the third partyresponse



At this time, the caller is connected to the third party within the switchand the incoming and outgoing channels will be hung up.

Figure 42. Event flow for a screened transfer with third party consultation (ending in a transfer)


table what needs to be done on the consultation. This data is set up byan OpenHostServerLink to the ISDN_Call_Transfer custom server and aSendData using the SetUserData function.

Note: A state table called ISDN_Xfer_Data is supplied to help performthis function.

2. The Caller state table issues a TransferCall request with the ring_wait andring_time parameters set to non-zero values to indicate that a screenedtransfer is required.


4. The outgoing state table connects to the ISDN_Call_Transfer customserver. It then issues a MakeCall with the ring_wait and ring_timeparameters set to non-zero values to indicate that a screened make call isrequired. The make call returns as soon as the call is answered (becausethis is a successful transfer).

5. When the MakeCall action returns, the outbound state table can interactwith the third party (for example, to ask if the third party wants toaccept a call at this time). The third party responses are gathered.

6. The outbound state table then informs the ISDN_Call_Transfer customserver (and so the ISDN Signaling Process) of the result of the MakeCalland the third party responses to the consultation, and enters into aWaitEvent. It should not hang up at this stage because this wouldinterfere with the completion of the transfer.


8. The incoming state table should then use a SendData/ReceiveData pairof actions calling the GetUserStatus function to determine the responsefrom the third party. This example assumes that the response is tocontinue with the transfer operation.

Note: A state table called ISDN_Xfer_Stat is supplied to help performthis function.

9. The incoming state table should then perform a TerminateCall tocomplete the transfer.

10. On receiving the TerminateCall from the incoming state table, the ISDNSignaling Process sends a message to the switch to request that the Callerand third party are connected together (the actual transfer), and waits forthe switch to confirm this.

11. The ISDN Signaling Process sends a HostEvent to the outbound statetable, 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 madeto both the user application and to the ISDN_SupA_Xfer state table. Thechanges involve moving the third party consultation logic to the outboundstate table (this would normally be performed in the inbound state table).Another modification that may have to be made is to specify which channelsmay be used to make the outbound call (see the SV178 definition in theWebSphere Voice Response for AIX: Application Development using State Tablesbook), or to modify the ring_wait and ring_time parameters used in theMakeCall state table action. Modifications to system variables should be madein the ISDN_SupA_Xfer state table before the MakeCall action is performed.


The sequence of events in Figure 43 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 statetable what needs to be done on the consultation. This data is set up by

Caller

Third Party

Outgoing Channel


MakeCall





ReconnectCall



EDGE:


Note the OHSL




Returns the edge from theprevious MakeCall action


Send a host event to theoutbound state table to tellit to hang up the third party

Success

Return Success edgeto the ReconnectCall requestEDGE:

Success

EDGE:HostEvent

TerminateCall

OpenHostServerLink(ISDN_Call_Transfer) Note the OHSL

SendData(SetUserData)

Sets up user_data passedto the outbound. state table

Record the user data to bepassed to the outbound state

table when it is invoked.

Interact with the third partyand gather responses

and the third party response.and record third partyresponses for later

SendData +

(GetUserStatus)Retrieves the third party

response gathered by the

Return the third partyresponse that was stored.

ReceiveData

outbound state table

Process the third partyresponse

At this time, the caller is connected to the third party within the switchand the incoming and outgoing channels will be hung up.

Incoming Channel The ISDN SignallingProcess and


Figure 43. Event flow for a screened transfer with third party consultation (ending up reconnecting to the original caller)


an OpenHostServerLink to the ISDN_Call_Transfer custom server and aSendData using the SetUserData function.

Note: A state table called ISDN_Xfer_Data is supplied to help performthis function.

2. The Caller state table issues a TransferCall request with the ring_wait andring_time parameters set to non-zero values to indicate that a screenedtransfer is required.


4. The outgoing state table connects to the ISDN_Call_Transfer customserver. It then issues a MakeCall with the ring_wait and ring_timeparameters set to non-zero values to indicate that a screened make call isrequired. The make call returns as soon as the call is answered (becausethis is a successful transfer).

5. When the MakeCall action returns, the outbound state table can interactwith the third party (for example, to ask if the third party wants toaccept a call at this time). The third party responses are gathered.

6. The outbound state table then informs the ISDN_Call_Transfer customserver (and so the ISDN Signaling Process) of the result of the MakeCalland the third party responses to the consultation, and enters into aWaitEvent. It should not hang up at this stage because this wouldinterfere with the completion of the transfer.


8. The incoming state table should then use a SendData/ReceiveData pairof actions calling the GetUserStatus function to determine the responsefrom the third party. This example assumes that the response is toabandon the transfer operation and connect back to the original caller.

Note: A state table called ISDN_Xfer_Stat is supplied to help perform thisfunction.

9. The incoming state table should then perform a ReconnectCall toabandon and tidy up the abandoned transfer.

10. On receiving the ReconnectCall from the incoming state table, the ISDNSignaling Process sends a host event message to the outbound state tableto 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 madeto both the user application and to the ISDN_SupA_Xfer state table. Thechanges involve moving the third party consultation logic to the outboundstate table (this would normally be performed in the inbound state table).Another modification that may have to be made is to specify which channelsmay be used to make the outbound call (see the SV178 definition in theWebSphere Voice Response for AIX: Application Development using State Tablesbook), or to modify the ring_wait and ring_time parameters used in theMakeCall state table action. Modifications to system variables should be madein the ISDN_SupA_Xfer state table before the MakeCall action is performed.

Custom server functionsThis section describes the custom server functions supplied with the ISDN calltransfer application.

Custom server function definitions

Three functions are provided with the ISDN_Call_Transfer custom server:

MakeCallStatusThe outbound state table uses this function to return informationabout the success of the outbound call to the third party.MakeCallStatus is described in “MakeCallStatus” on page 247.

GetUserStatus and SetUserDataUse these functions only if you need a method of communicationbetween the inbound and outbound state tables during a transferoperation that uses ISDN call transfer. For example, you might wantto specify the prompts played to the third party during consultation,and to gather the third party responses and return them to the callerstate table. The caller state table could then decide either to completethe transfer or to reconnect to the original caller. GetUserStatus isdescribed in “GetUserStatus” on page 246, and SetUserData isdescribed in “SetUserData” on page 248.

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. TheISDN_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 formISDN_XFERnnn. The remaining parameters contain information specific to theparticular error.

With any of these errors, if you have followed the suggestions in the UserResponse, and you are unable to solve the problem, contact IBM Support.When you call, you will need details of any errors, your system setup, anddetails of the conditions that cause the problem. You may also require an AIXsystem trace taken when the problem occurs. Before taking the trace, set the-d option in the custom server. For more information on the command lineoptions see “Configuring the ISDN_Call_Transfer custom server” on page 231.

Error messages generated by the ISDN_Call_Transfer custom server, togetherwith explanations and suggested responses, are listed in the WebSphere VoiceResponse for AIX: Problem Determination book.

GetUserStatus

Description:

The GetUserStatus function is called by the inbound state table after atransfer. Use it to retrieve any user data set by the outbound state tableduring the transfer operation. This call must be made after the TransferCallaction 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 valuesare:

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 statetable during a transfer after the outbound call has been made.










MakeCallStatus

Description:

The MakeCallStatus function is called by the outbound state table after theoutbound 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_statusparameters.

Input parameters:

short call_status

The return code from the MakeCall state table action.


User-defined data field sent to the inbound state table during a transfer afterthe outbound call has been made.










Output parameters:

None.

SetUserData

Description:

The SetUserData function is called with several parameters to sendinformation 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 thestrings is user defined.

Input parameters:

char user_data_1[64]

User-defined data field sent to the outbound state table during a transfer.










Output parameters:

None.

State table definitionsThis section describes the state tables supplied with the ISDN call transferapplication.

Six state tables are provided as compiled state tables and ASCII state tablesource code. The compiled state tables are compiled directly from the ASCIIstate table source code. The source code for the state tables is provided in thedirectory $CUR_DIR/ca/ISDN_Call_Transfer_dir.

The state tables fall into two groups:

Outbound state tablesAn outbound state table provides functions to make the outbound callfor the transfer operation:v “ISDN_Imm_Xfer”v “ISDN_SupA_Xfer” on page 251

Helper state tables:The helper state tables encapsulate code that is used to provideinteraction between the inbound and outbound state tables during thetransfer, and other utility functions:v “ISDN_Xfer_C5” on page 253v “ISDN_Xfer_C10” on page 253v “ISDN_Xfer_Data” on page 254v “ISDN_Xfer_Log” on page 256v “ISDN_Xfer_Stat” on page 257

The following sections describe the state tables.

ISDN_Imm_Xfer

The ISDN_Imm_Xfer state table is used as the default outbound state table forblind transfers. It attempts to perform a blind make call and returns thesuccess or failure to the ISDN Signalling Process using the ISDN_Call_Transfercustom server.


After the results of the MakeCall have been reported, it enters into aWaitEvent for up to 30 seconds to allow the transfer to complete. When theswitch completes, the transfer channel is hung up and the WaitEvent exited. Ifthe switch does not hangup, the WaitEvent times out and the state tableterminates, which hangs up the call.

You can customize the application, but you must not change the basicfunctions.

Parameters:

String phone_number (maximum of 40 characters)

The number to dial for the outgoing part of the transfer. For moreinformation, see the definition of phone_number in the description of theMakeCall state table action in the WebSphere Voice Response for AIX: ApplicationDevelopment 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 theMakeCall state table action in the WebSphere Voice Response for AIX: ApplicationDevelopment 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 andthe results are logged in the file you specify. The logging is performed by theISDN_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 254, which is a state table that can set this data foryou.










ISDN_SupA_Xfer

The ISDN_SupA_Xfer state table is used as the default outbound state tablefor screened transfers when not using DTTA hardware.

The state table attempts to perform a make call and returns the success orfailure to the ISDN Signaling Process using the ISDN_Call_Transfer customserver.

After the results of the MakeCall have been reported, if the make call wassuccessful, it enters into a WaitEvent for up to 30 seconds to allow the transferto complete. When the switch completes, the transfer channel is hung up andthe WaitEvent exited. If the switch does not hang up, the WaitEvent times outand the state table terminates, which hangs up the call. If the make call wasnot successful, it hangs up immediately.

You can customize the application, but you must not change the basicfunctions. Comments in the source code show where you can insert code toperform 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 moreinformation, see the definition of phone_number in the description of theMakeCall state table action in the WebSphere Voice Response for AIX: ApplicationDevelopment 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 theMakeCall state table action in the WebSphere Voice Response for AIX: ApplicationDevelopment using State Tables book.



If you specify a file name, event logging of the transfer calls is performed andthe results are logged in the file you specify. The logging is performed by theISDN_Xfer_Log state table.












ISDN_Xfer_C5

The ISDN_Xfer_C5 state table encapsulates the states needed to concatenateup 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 concatenateup to 10 strings. It returns the result as a single string.

Parameters:

String in0

The first string.

String in1

The second string.


String in2

The third string.

String in3

The fourth string.

String in4

The fifth string.

String in5

The sixth string.

String in6

The seventh string.

String in7

The eighth string.

String in8

The ninth string.

String in9

The tenth string.

String out (this value is returned)

The concatenation of the input strings (in0 + in1 + in2 + in3 + in4 + in5 + in6+ in7 + in8 + in9).

ISDN_Xfer_Data

The ISDN_Xfer_Data state table encapsulates the actions necessary to use theSetUserData custom server function. It is called by the incoming state table toset up some user-defined data to be supplied to the outbound state tableduring a transfer. This call must be made before the TransferCall action isperformed.



Parameters:



If you specify a file name, event logging of the supplied data is performedand the results are logged in the file you specify. The logging is performed bythe ISDN_Xfer_Log state table.

String user_data1 (maximum of 64 characters), (this value is returned)

User data supplied to the SetUserData custom server call.









Number return_code, (this value is returned)

This value is returned to indicate whether or not the call to theISDN_Xfer_Data state table was successful. The possible return values are:

0 The state table ran successfully

1 The OHSL to the ISDN_Call_Transfer custom server failed.

2 The SendData to the ISDN_Call_Transfer custom server failed.


ISDN_Xfer_Log

The ISDN_Xfer_Log state table encapsulates the actions needed to log debugdata in a file.

The state table first checks the logging_on flag to see if the supplied datashould be sent to the log file. The data to be logged consists of a headerstring, followed by six general strings; these are concatenated before beinglogged 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 statetable to exit without logging anything.

String header

The header string for the logging function. This must contain at least the filename, 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 theGetUserStatus custom server function. It is used by the incoming state table toreceive the user-specified status values returned by the outbound state tableafter the make call. This call must be made after the TransferCall action andbefore the TerminateCall or ReconnectCall actions.


Parameters:



If you specify a file name, event logging of the supplied data is performedand the results are logged in the file you specify. The logging is performed bythe ISDN_Xfer_Log state table.

Number user_status

The status of the call to get the user status information. The possible valuesare:

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.


User-defined status field that was sent by the outbound state table during atransfer 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 theISDN_Xfer_Data state table was successful. The possible return values are:

0 The state table ran successfully

1 The OHSL to the ISDN_Call_Transfer custom server failed.

2 The SendData to the ISDN_Call_Transfer custom server failed.

3 The ReceiveData failed with a Timeout edge.

4 The ReceiveData failed with a No More Data edge.

5 The ReceiveData failed with a Data Not Found edge.

6 The ReceiveData failed with a Host Problem edge.

7 The ReceiveData failed with a Host Not Open edge.

What the ISDN single step call transfer application does

The SSTransfer custom server generates the ASN1 encoding data for thefacility message. Your application invokes the ssct_transfer state table to createa facility message and send it to the network, which then connects theexisting incoming call with a new party.

The process does not involve using the ISDN_Call_Transfer custom server. Formore information, refer to the supplied ssct_tag example state table, whichdemonstrates how to use the ssct_transfer state table.

The TIncoming_Call state table is used in place of the default Incoming_Callstate table. It is exactly the same as the Incoming_Call state table but savescall data to a global variable before answering the call. The saved call data isused to extract the calling party number when transfer is requested. The ssctexample state table demonstrates how to use SSTransfer custom serveralternative function call. Use this when the calling number is available to yourapplication.


Limitations of ISDN single step call transferThere are some limitations associated with using ISDN single step call transferwith 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 VoiceResponse from the same switch. The specifications allow the two calls to beon different trunks, provided that both trunks support ISDN single step calltransfer.If the WebSphere Voice Response system has a mixture of CAS, SS7, andISDN trunks, the user application should ensure that the outbound call ismade on the correct trunk for a ISDN single step call transfer to besuccessful.

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 requiredwhen porting applications that involve transfer operations from differenttelephony configurations.

Installing the applicationThe ISDN single step call transfer application is supplied as an installp imagethat you install using the System Management Interface Tool (SMIT). Theapplication contains three components, including some source code to helpyou customize the ISDN single step call transfer capability to your specificneeds. For a straightforward use of the ISDN single step call transfercapability, no customizing should be required.

The components of the application are:v Updated ISDN support.v State tables (including source code):

The following state tables are provided (for definitions for these state tables,see “State table definitions” on page 269):– ssct_transfer– ssct_tag– TIncoming_Call– ssctThe source code for these state tables is supplied in an ASCII file in thesame directory as the custom server: $CUR_DIR/ca/SSTransfer_dir

v Custom server:A custom server, named SSTransfer, is supplied to perform the low-levelfunctionality of the transfer operation (for details of the available functioncalls, see “Custom server function definitions” on page 263).


Note: Only the executable version (not the source code) of this customserver is supplied.

Before you install

Before you can install the ISDN single step call transfer application, you musthave:v A WebSphere Voice Response system running Version 6.1 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 book.v Sufficient disk space for the components you are installing (the WebSphere

Voice Response for AIX: Installation book explains how to check this; see thesection “Ensuring you have enough disk space for the new software”).

Installing1. Installing the application: Follow the instructions in “Installing the

WebSphere Voice Response software” in the WebSphere Voice Response forAIX: Installation book to use the System Management Interface Tool(SMIT) to install the PTF that contains the ISDN single step call transferapplication.

2. Starting WebSphere Voice Response: Start WebSphere Voice Responseand log in to the user account you use for WebSphere Voice Responseadministration.

3. Importing the custom server and state tables: In the WebSphere VoiceResponse Welcome window, click Applications —> Application —>Import—> Replace—> File.

4. Select the file /usr/lpp/dirTalk/sw/SST/SSTransfer.imp.5. Creating an application profile: 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 theApplication 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.


14. Starting the custom server: 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. Assumingyour application is a simple one that asks for a number to transfer to,and then evokes the ssct_transfer state table, the sequence of eventsshould be:

16. Pick up Phone A's handset and dial the application profile ID.WebSphere Voice Response runs your application, which performs thetransfer to a third party. It answers the call and prompts you to input thetelephone number that you want to transfer to, followed by a # key.


18. Pick up Phone B's handset.The application completes the transfer when Phone B is answered andthe voice path for the two calls is connected within the switch.

19. The two remaining connections to WebSphere Voice Response (originallyconnected to Phones A and B) are disconnected shortly after the transferis completed.

Configuring the SSTransfer custom serverThe SSTransfer custom server has some command line parameters that youcan set to help you debug problems, or to fine-tune the operation of thecustom server.

The parameters are defined in Table 10 on page 262. For information on howto set the parameters, see “Setting configuration options” on page 262.


Table 10. Configuration options for the SSTransfer custom server


-d off Provide extra debugging information (in addition tothe information that always gets sent). Valid valuesare 0 (none) to 4 (everything). To set the logginglevel to 3, specify –d3 .

-f DTstatus.out A fully qualified file name where trace output is tobe written, for example -f/home/dtuser/sstransfer.log. The SSTransfer custom server willcontinue to write some critical information toDTstatus.out.


To set one or more of the configuration options, follow the procedure below:1. From the Welcome window, click on Applications —> Custom Servers

2. Setting a command line parameter for the custom server: Highlight theSSTransfer 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.

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.8. Restarting the custom server: 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 thecustom 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. Thenew command line parameters are now in effect. If the Run Statusremains at None, there is probably an error with one of the commandline parameters. Check the error log for details.

How to use ISDN single step call transferThis section describes how to perform a transfer operation using the ISDNsingle 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 tableso that the contents of SV542 (call data) are saved into SV51 before the callis 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 actionhas been upgraded to detect the presence of saved facility (FAC) tag data. If itfinds such data, it sends a facility message to the network using theinformation contained in the tag.

The description in the WebSphere Voice Response for AIX: ApplicationDevelopment using State Tables book of how the TransferCall state table actionworks gives general information on how to perform a transfer. ISDN singlestep call transfer using ISDN supports blind transfer only and not screenedtransfer.

Custom server functionsThis section describes the custom server functions supplied with the ISDNsingle step call transfer application. The purpose of the SSTransfer customserver is to take address information and encode it as ASN.1 encoded data inaccordance with the facility message definition in Single Step Call Transfer(SSCT) Supplementary Service (ECMA-300, edition 2 Dec 2001)


Two functions are provided with the SSTransfer custom server:

TransferTagAllows calling number addressing details to be supplied in the TAGformat captured in SV252, supplied when an incoming call arrives.TransferTag is described on page “TransferTag” on page 267.

TransferAllows calling number addressing details to be supplied as separate(number , number plan, and number type) parameters. Transfer isdescribed on page “Transfer” on page 267.

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 UserResponse, 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 AIXsystem trace taken when the problem occurs. Before taking the trace, set the-d option in the custom server. For more information on the command lineoptions see “Configuring the SSTransfer custom server” on page 261

The possible return codes generated by the ISDN single step call transfer,together with explanations and suggested responses, are as follows:

Table 11. ISDN single step call transfer return codes

ErrorCode Description Explanation User response

0 Success ASN1 has been generatedsuccessfully.

None required

1 Transfer to numberplan not valid

The custom server received anumber plan value which didnot conform to the allowedvalues in the Single Step CallTransfer (SSCT) SupplementaryService (ECMA-300, edition 2Dec 2001) specification.

Review the Single Step Call Transfer(SSCT) Supplementary Service(ECMA-300, edition 2 Dec 2001)specification and change the numberplan setting to an allowed value.

2 Transfer to numbertype not valid

The custom server received anumber type value which did notconform to the allowed values inthe 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 numbertype setting to an allowed value.

3 Transfer to numberplan and numbertype not consistent

The custom server receivednumber plan and number typevalues which did not conform tothe allowed combinations in theSingle 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 numberplan and number type values to anallowed combination.

4 AwaitConnect not setto a valid value

The custom server received anAwaitConnect parameter valuewhich did not conform to theallowed values in the Single StepCall 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 theAwaitConnect parameter setting toan allowed value.


Table 11. ISDN single step call transfer return codes (continued)


6 Transferred numbernot present andpresentation fielddoes not indicate itshould not bepresent.

The custom server received notransferred from number valuebut the transfer from numberpresentation value indicates thatit should be present.

Review the Single Step Call Transfer(SSCT) Supplementary Service(ECMA-300, edition 2 Dec 2001)specification and either add atransferred from number or changethe transfer from number to indicatethat no transfer from number isrequired.

7 Transferred numberpresentation field notvalid

The custom server received atransferred number presentationvalue which did not conform tothe allowed values in the SingleStep 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 thetransferred number presentationsetting to an allowed value.

8 Transferred numberpresentation andscreening fields areinconsistent.

The custom server receivedtransferred number presentationand screening values which didnot conform to the allowedcombinations in the Single StepCall 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 thetransferred number presentation andscreening type values to an allowedcombination.

10 Internal error withASN1 generation

The custom server hasexperienced an internal error inits ASN1 generation

Re-create the problem and take anAIX system trace (specify the –d3command-line parameter for thecustom server), before calling IBMSupport.

21 No transferrednumber present

The custom server received tagdata that does not contain atransferred number within theCLGN tag.

Review the tag data that is beingpassed into the custom server bytaking a system-level trace. Correctthe tag data as appropriate.

22 Unable to determinetransferred number’snumber plan

The custom server received tagdata that does not contain ordoes not contain a valid numberplan within theCLGN.NUMBER_PLAN tagattribute.



Table 11. ISDN single step call transfer return codes (continued)


23 Unable to determinetransferred number’snumber type

The custom server received tagdata that does not contain ordoes not contain a valid numbertype within theCLGN.NUMBER_TYPE tagattribute.


24 Unable to determinetransferred number’sscreening value

The custom server received tagdata that does not contain ordoes not contain a valid numberscreening value within theCLGN.NUMBER_SCREEN tagattribute.


25 Unable to determinetransferred number’spresentation value

The custom server received tagdata that does not contain ordoes not contain a valid numberpresentation value within theCLGN.NUMBER_PRESENT tagattribute.


31 State tableopenhostserver failed

scct_transfer state table error Re-create the problem and take anAIX system trace, before calling IBM

32 State table senddatafailed


33 State table receivedata failed with nomore data error

scct_transfer state table error Re-create the problem and take anAIX system trace, before calling IBMSupport.

34 State table receivedata failed with datanot found


35 State table receivedata failed with hostproblem


36 State table receivedata failed with hostnot open


37 State table receivedata failed withtimeout


40 State tableTransferCall actionfailed

An Edge other than Succeededwas returned from theTransferCall action

Re-create the problem and take anAIX system trace, before calling IBM


TransferTag

Description:

Allows calling number addressing details to be supplied in the TAG formatcaptured 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 astransfer is attempted or only after connection is established to the third party.The values are as defined in Single Step Call Transfer (SSCT) SupplementaryService (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]


short Transfer_TransfertoNumberPlan


short Transfer_TransfertoNumberType


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

short Transfer_TransferredNumberPresent

The presentation indicator for the number set as the number from which thecall is transferred.

short Transfer_AwaitConnect


Output parameters:

short TransferTag_rc

The return code.

char TransferTag_data[250]


The ASN1 BER encoding of supplied called and calling number parameters.

State table definitionsThis section describes the state tables supplied with the ISDN single step calltransfer application.

Four state tables are provided as compiled state tables and ASCII state tablesource code. The compiled state tables are compiled directly from the ASCIIstate table source code. The source code for the state tables is provided in thedirectory $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 SV51global variable before answering the call. The saved call data in SV51 can beused to extract the calling party number when transfer is requested. IfIncoming_Call state table has already been modified, add a statement to saveSV252 to SV51. If SV51 is already in use then use another string globalvariable and modify ssct_transfer state table to use it rather than SV51.


Parameters:

None

ssct_transfer state table

The ssct_transfer state table is invoked from your application to create facilitymessage contents using the SSTransfer TransferTag function call and pass ittoWebSphere Voice Response. The transfer state table action is then used totrigger the sending of the facility message and transfer the call. Refer to thessct_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 inSV51.

The ssct_transfer state table only works if TIncoming call state table, or onewith similar functionality, has been used to replace Incoming_call state table.

The state table returns the following return code values:

31 State table openhostserver failed


32 State table senddata failed

33 State table receive data failed with no more data error

34 State table receive data failed with data not found

35 State table receive data failed with host problem

36 State table receive data failed with host not open

37 State table receive data failed with timeout

These return code values are issued along with those returned by theSSTransfer custom server.

Parameters:

char TransferTag_TransfertoNumber[32]


short TransferTag_TransfertoNumberPlan


short TransferTag_TransfertoNumberType


short TransferTag_AwaitConnect


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

Parameters:

None


ssct

The ssct state table demonstrates how to use SSTransfer custom serverTransfer function call, which is used when calling party number details arepassed as individual parameters. You may choose to use this when you wantto specify a different calling party number from that passed on the originalcall.

Parameters:

None


Chapter 18. Using the IBM_Trombone_Custom_Server

This chapter describes the IBM_Trombone_Custom_Server.v “What is a trombone (in telephony terms)?”v “Installing the IBM_Trombone application” on page 275v “Configuring IBM_Trombone_Custom_Server” on page 277v “How to use the trombone operation” on page 280v “Custom server functions” on page 286v “State table definitions” on page 296v “IBM_Trombone_Custom_Server errors” on page 320

What is a trombone (in telephony terms)?

A trombone operation occurs when a call coming in on one WebSphere VoiceResponse channel connects directly with an outgoing call on anotherWebSphere 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 tromboneoperation.

v WebSphere Voice Response makes an outgoing call to the third party onanother channel.

v When they answer, the third party is connected to the original caller usingthe TDM bus internal to the WebSphere Voice Response system. At thispoint, the connection looks like this:


Note: Because the trombone operation uses the TDM bus, this functionrequires a DTTA card installed in the WebSphere Voice Response system.

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 usingcannot support transfer, you can use the trombone operation to simulate atransfer operation with a trombone operation. The connection ismaintained until either the caller or the third party terminates the call byhanging up.This has the disadvantage over a normal switch-based transfer operationthat two WebSphere Voice Response channels are occupied for the wholetime that the caller and third party are talking. With a switch-basedtransfer, the channel between the caller and WebSphere Voice Response isbroken as soon as the caller is transferred to the third party.

2. To allow consultation with a third party, returning to the WebSphere VoiceResponse application.The trombone allows the caller to consult with a third party. When thethird party hangs up, or the caller terminates the consultation, the caller isconnected back to WebSphere Voice Response at the point where they leftthe application they were using.This might be useful in a voice mail application, for example, where acaller can break out to respond to an urgent voice mail message, thenreturn to processing the rest of the voice mail after dealing with the urgentmatter.

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 44. Voice path between caller and third party during a trombone operation


Installing the IBM_Trombone application

This section describes the components of the IBM_Trombone application, andthe 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 calledIBM_Trombone.imp, which you can find in the $VAE/sw/samples directory. (Youmust install the samples LPP to have access to this function.)

The application contains four components and some source code to help youcustomize the trombone operation to your specific needs. If you just needstraightforward tromboning, you need no customization. The components ofthe application are:

State tablesThere 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” onpage 296.

Prompt directoriesA prompt directory called IBMTrombone holds the prompts requiredby the IBMTromboneXmp state table sample application.

Note: All the supplied state tables specify this prompt directory; youmay need to change it if you customize the state tables.

Voice directoriesA voice directory called IBMTrombone holds the voice segmentsrequired by the IBMTromboneXmp state table sample application. Theprompts in the IBMTrombone prompt directory access these segments.

Chapter 18. Using the IBM_Trombone_Custom_Server 275

Custom serversA custom server called IBM_Trombone_Custom_Server performs thelow-level functions of the trombone operation.

See “Custom server function definitions” on page 286 for details ofthe available calls.

Note: We supply only the binary (not the source code) of this customserver.

Source codeSource code for the 14 state tables listed above is supplied in ASCIIformat 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 operationon your system, follow the procedure given below:

Prerequisitesv A WebSphere Voice Response system with one or more DTTA adapters. If

two or more DTTA adapters are installed, connect them together using anH.100 ribbon cable. If only one is installed, you do not need an H.100 cable.

v A connection to a switch or public network using a trunk that supportsboth 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.

Procedure1. From the Welcome window, click on Applications —> Applications

2. Importing the application : Click Application —> Import.3. Click the /usr/lpp/dirTalk/sw/samples/IBM_Trombone.imp file.

The system displays the IBM_Trombone application icon.4. Creating an application profile: 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 theApplication Profile window.

6. Type any name in the Name field (for example, “Trombone Example”).7. Click State Table —> IBMTromboneXmp

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.


13. Starting the custom server: 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.

15. Running the application: Pick up Phone A's handset and dial theapplication profile ID.WebSphere Voice Response answers the call and prompts you to input atelephone number.


17. Pick up Phone B's handset.The two calls are connected by the TDM bus completing a voice pathbetween the two telephones.

18. If phone B hangs up, or Phone A dials 1234, the trombone operationterminates and Phone A is prompted to enter another telephone number.If the trombone operation doesn't work, WebSphere Voice Response playsa “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 parametersthat you can set to help debug problems, or to fine tune the operation of thecustom server. These are defined here.

The command-line parameters are defined in Table 12.

Table 12. Configuration options for IBM_Trombone_Custom_Server.

Parameter Default Description

-d off Provide extra debugging information (over and abovethe normal information that always gets sent).


Table 12. Configuration options for IBM_Trombone_Custom_Server. (continued)

Parameter Default Description

-s off Print debugging information to stdout as well as toAIX system trace.

-a off Send extra Information alarms to the error log.

-pn n=0.1Number of child helper processes to run.

See “About child helper processes” for informationabout setting this parameter.

-en 0 The event data (n) sent by the custom server if thethird party hangs up (see the WebSphere Voice Responsefor AIX: Custom Servers book:CA_Report_Channel_Event()).

-in 0 The information field (n) sent by the custom server ifthe third party hangs up (see the WebSphere VoiceResponse for AIX: Custom Servers book:CA_Report_Channel_Event()).

-z off This parameter is for test purposes only. It causes thecustom server to enrol one of each type of errorpossible 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 tomake the TDM connection and disconnection requests, which block otherTDM connection and disconnection requests while they are being processed.These helper processes are required only during the actual connection ordisconnection phase of a trombone, so you must have enough to cope withthe peak demand of trombone connections or disconnections.

A good compromise between process availability and response time is to haveone process for every 10 possible trombone operations. This is why thedefault value for the -pn parameter is 0.1. If you only need the tromboneoperation 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 variousvalues are:


0 < -pn <= 1The number of child processes to run = n * max_trombones (with aminimum of 2 child processes)

-pn > 1The number of child processes to run = n (with a maximum of numberof channels/2)

-pn < 0Use the default value of -pn=0.1

Note: Maximum number of trombones = number of channels/2.


To set one or more of these options, follow the procedure below:

Procedure1. From the Welcome window, click on Applications —> Custom Servers

2. Highlight IBM_Trombone_Custom_Server3. Setting a command- line parameter for the custom server: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, clickFile —> Save.

8. Re-starting the custom server: Open the Custom Server Managerwindow: 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, thecustom 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 thenew command-line parameters will be in effect.


11. If the Run Status remains at None, there is probably an error with one ofthe command-line parameters. Check the error log for details.

How to use the trombone operation

A number of state tables are provided to allow you to set up a tromboneoperation. 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 theIBMTromboneCall state table to make a tromboned call to a third party in onesimple operation, and a high level flow chart for this application is given inFigure 45 on page 281.

If your requirements are more complex, a number of state tables are providedthat break down the function provided by the IBMTromboneCall state tableinto several stages. For most users, this should allow more control over settingup the trombone operation without having to modify the supplied statetables. The state tables that break down the IBMTromboneCall function areIBMTromboneMake, IBMTromboneRdy, IBMTromboneConn,IBMTromboneDisc, and IBMTromboneWait. The two state tablesIBMTromboneXmpA and IBMTromboneXmpB show two slightly differentways of using these state tables to setup a trombone operation.

This section uses the IBMTromboneXmp application to explain tromboneoperation.

As you can see, you must supply the IBMTromboneCall state table with thephone number to which to make the outbound part of the trombone call andthe format string for dialing this number. You can leave all other parametersto the IBMTromboneCall state table blank, unless you want to use the extrafunctionality 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 book for information about viewing logged events.

2. The end_on_DTMF parameter is set to “1234” to allow the caller todisconnect the trombone call by dialing 1234 during the tromboneoperation.


How tromboning works

This section describes the calls that should occur to set up and terminate atrombone operation. These actions are encapsulated within IBMTromboneCall(caller state table), IBMTromboneOut (third party state table), and

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 45. High-level flow chart for the IBMTromboneXmp state table


IBM_Trombone_Custom_Server. They describe the order in which eventsshould occur for a successful trombone operation. If you customize thesupplied state tables, make sure that you don’t change this event flow, or thecustomized 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

2833. “Terminating a trombone operation using caller hang-up” on page 2834. “Voice paths” on page 285

Setting up a trombone operation

1. The Caller state table issues an OpenHostServerLink and a TromboneCallrequest 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 functionof IBM_Trombone_Custom_Server after issuing an OpenHostServerLink. Itthen uses the WaitEvent state table action to wait for a hang-up or hostevent.

Caller

Third party

Incoming Channel Outgoing ChannelIBM_Trombone_Custom_Server

IBMTromboneCall

OpenHostServerLink

SendData(TromboneCall) InvokeStateTable

(default = IBMTromboneOut) IBMTromboneOut

ReceiveData(TromboneCall) MakeCall

Third partyanswers

SendData(TromboneMakeCallStatus)Connect caller and third party

using CA_TDM_Connect()

Send response toTromboneMakeCall request

Note new connection

WaitEventfor DTMF, hang-up

or host event


or host event

Figure 46. Event flow required to set up a trombone operation.


4. IBM_Trombone_Custom_Server connects the caller and third party on theTDM bus and informs the caller state table of the success or failure of theoriginal TromboneCall request.

5. The caller state table uses the WaitEvent state table action to wait for ahang-up, host event, or caller DTMF keys.

At this point, the caller is connected to the third party using the TDM bus andthe 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, orCloseHostServerLink tells IBM_Trombone_Custom_Server that this hashappened.

2. IBM_Trombone_Custom_Server disconnects the caller and third party fromthe TDM bus and sends a HostEvent to the Caller state table to indicate athird party hang-up.

3. The Caller state table uses CloseHostServerLink to detach fromIBM_Trombone_Custom_Server.

At this point, the caller is connected back to the state table application thatinvoked the IBMTromboneCall state table, and the third party has beendisconnected.

Terminating a trombone operation using caller hang-up


or host event

Third party


IBMTromboneCall

CloseHostServerLink

IBMTromboneOut

hangs up

CloseEverything(Implied CloseHostServerLink)Disconnect caller and third

party using

Send host event to caller


or host event

Hang-up event

CA_TDM_Disconnect()

Host event

Clean up connection details

ExitStateTable

Figure 47. Event flow required to terminate a trombone operation when the third party hangs up


1. The caller state table uses CloseHostServerLink, TerminateCall, orCloseHostServerLink to tell IBM_Trombone_Custom_Server that the callerhas hung up.

2. IBM_Trombone_Custom_Server disconnects the caller and third party fromthe TDM bus and sends a HostEvent to the third party state table toindicate that the caller has terminated the trombone operation.

3. The third party state table uses CloseEverything, CloseHostServerLink, orTerminateCall to detach from IBM_Trombone_Custom_Server.

At this point, the caller and the third party have both been disconnected. Thecaller state table that invoked the IBMTromboneCall state table is still runningand may perform clean-up operations that don’t involve interacting with thecaller.

Terminating a trombone operation using caller DTMF


or host event


IBMTromboneCall

CloseHostServerLink

IBMTromboneOut

CloseEverything(Implied CloseHostServerLink)

Disconnect caller and thirdParty using



or host event

Hang-up event

CA_TDM_Disconnect()

Host event


ExitStateTable

Callerhangs up

with return code to indicatethat the caller has hung up

Third partydisconnected

Figure 48. Event flow required to terminate a trombone operation when the caller hangs up


1. If the caller state table detects a valid sequence of DTMF keys from thecaller requesting the trombone to terminate, it sendsTromboneDisconnectCall to IBM_Trombone_Custom_Server.

2. IBM_Trombone_Custom_Server disconnects the caller and third party fromthe TDM bus and replies to the TromboneDisconnectCall.

3. The caller state table then uses CloseHostServerLink to informIBM_Trombone_Custom_Server that the caller has ended the tromboneoperation. (Using TerminateCall or CloseEverything would disconnect thecaller which is probably not what you want at this point.)

4. IBM_Trombone_Custom_Server sends a HostEvent to the third party statetable to indicate that the caller has terminated the trombone operation.

5. The caller state table uses CloseEverything, CloseHostServerLink, orTerminateCall to detach from IBM_Trombone_Custom_Server (and hangup on the third party if desired).

At this point, the caller is connected back to the state table application thatinvoked the IBMTromboneCall state table, and the third party has beendisconnected.

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 partiesand record their voices during the trombone operation. You will find a


or host event


IBMTromboneCall

CloseHostServerLink

IBMTromboneOut

CloseEverything(Implied CloseHostServerLink)

Disconnect Caller and thirdparty using



or host event

DTMF event

CA_TDM_Disconnect()

Host event


ExitStateTable

Callerdials DTMF

SendData(TromboneDisconnectCall)

ReceiveData(TromboneDisconnectCall)

Send response toTromboneMakeCall request

Third partydisconnected

Figure 49. Event flow required to terminate a trombone operation when the caller requests this by dialing a DTMFsequence


discussion of the voice paths used in the trombone operation, and problemsthat might be caused by echo, see “Voice paths ” on page 220.

Custom server functions

In this section we describe the five functions supplied withIBM_Trombone_Custom_Server, and how you can configure the custom serverto meet your own requirements.v The 14 trombone state tables (“State table definitions” on page 296).


IBM_Trombone_Custom_Server has five functions, which have to be used inthe correct order for a successful trombone operation. (See “How tromboningworks” on page 281 for details of which custom server calls to use.)

There are some configuration options that you can use to fine tune theoperation of the custom server; see “ConfiguringIBM_Trombone_Custom_Server” on page 277 for details.

The custom server functions are defined in the following sections:v “TromboneCall” belowv “TromboneMakeCall” on page 289v “TromboneMakeCallStatus” on page 292v “TromboneConnectCall” on page 293v “TromboneTerminationValue” on page 295v “TromboneDisconnectCall” on page 295

Note: Throughout the sections that follow, you will find numerouscross-references in the form “see the definition of....”. All these references areto sections in State Tables, Prompts, and Voice Segments book.

TromboneCall

Description

TromboneCall is called with several parameters, most of them required for theMakeCall action itself, and to determine which state table to use to make thecall.

Using the data provided by the input parameters, the custom server invokes astate table (by default IBMTromboneOut) to make a call to the third party. Itthen waits for a response in the form of a TromboneMakeCallStatus requestfrom the invoked state table. If this response indicates that the outbound callwas successful, the custom server requests TDM Manager to connect the caller


and third party using the TDM bus. When this completes successfully, theTromboneCall request returns a zero response in the make_call_status toindicate 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 anon-zero response in the make_call_status to indicate that the tromboneoperation 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 definitionof 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 thetrombone (see the definition of format in the MakeCall state table action fordetails).

char permitted_channel_groups[64]:

The permitted channel groups for the outgoing part of the trombone (see thedefinition 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 thedefinition 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 youwant no event logging.

char user_data[64]:

Some user-defined data for simple communications from theIBMTromboneCall state table to the IBMTromboneOut state table.

This may be used, for example, to reference a prompt to be played as anannouncement to the third party before the trombone operation connects themto the caller.

char outbound_state_table_name[16]:


The name of the state table to use for the outbound part of the tromboneoperation. 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 thetrombone operation. If this is blank, the default label begin is used.

char additional_call_info1[140]:

Reserved for WebSphere Voice Response.








Reserved WebSphere Voice Response.

Output parameters

short trombone_make_call_status:

The trombone_make_call_status for the TromboneCall request indicates thestatus of the trombone operation. The trombone_make_call_status falls intovarious groups defined in Table 13.

Table 13. Return values for the trombone_make_call_status parameter of theTromboneCall function

MakeCallStatus 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_statusoutside the valid range (0 to 99).


Table 13. Return values for the trombone_make_call_status parameter of theTromboneCall function (continued)


101 The IBMTromboneOut state table performed a CloseHostServerLink whilethe custom server was waiting for a response to the TromboneMakeCallrequest

102 The custom server request is invalid at this time (probably because of anerror in the sequence of custom server calls).

103 CA_Open_CHP_Link() failed, probably because there are not enough freeCHPs.

104 CA_Execute_State_Table() failed, probably because of an invalid state tablename, entry point, or the state table not being validated.

105 CA_Get_Channel_Info() failed, probably because the outbound call hasbeen terminated.

106 A TDM connect or disconnect request failed because of an adapterhardware problem.

107 A TDM connect or disconnect request failed because the requested port isalready connected. This may be caused by other applications running thatcan make TDM connect and disconnect requests.

108 A TDM connect or disconnect request failed because there is no callpresent. One of the parties has probably hung up.

109 A TDM connect or disconnect request failed because the Timeslot Manageris not ready. It may be very busy, or not available.

110 A TDM connect or disconnect request failed because of an internal customserver problem.

111 A TDM connect or disconnect request failed because of an unexpectedreturn code.

112-199 Spare: may be used for user-defined values.

TromboneMakeCall

Description

TromboneMakeCall is called with several parameters, most of them requiredfor the MakeCall action and to determine which state table to use to make thecall.

Using the data provided by the input parameters, the custom server invokes astate 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 callwas successful, the custom server returns a zero response in themake_call_status to indicate that the outbound call is in place. TheTromboneConnect function call should be used next to connect the caller andthe third party.

If any of the steps in this process fail, the TromboneMakeCall request returnsa non-zero response in the make_call_status to indicate that the tromboneoperation 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 definitionof Phone_Number in the MakeCall state table action for details).

char format[50]:


char permitted_channel_groups[64]:

The permitted channel groups for the outgoing part of the trombone (see thedefinition of SV178 for information on how this variable is used).

char permitted_channels[64]:

The permitted channels for the outgoing part of the trombone (see thedefinition 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 beblank if no event logging is required.

char user_data[64]:


char outbound_state_table_name[16]:


The name of the state table to use for the outbound part of the tromboneoperation. 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 thetrombone operation. If this is blank, the default label begin is used.











Output parameters


The trombone_make_call_status for the TromboneMakeCall request indicatesthe status of the trombone operation. The trombone_make_call_status fallsinto various groups defined in Table 14 on page 292.

long partner_call_id:

The Call Reference of the outbound part of the trombone operation. It issupplied to provide a unique link between the two halves of the tromboneoperation, for debug purposes.

string user_status_data[65]:

Some user-defined data provided to allow for simple communications fromthe 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 canthen play a prompt to the caller appropriate to the third party response.

Table 14. Return values for the trombone_make_call_status parameter of theTromboneMakeCall function

Make CallStatus 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_statusoutside the valid range (0 to 99).

101 The IBMTromboneOut state table performed a CloseHostServerLinkwhile the custom server was waiting for a response to theTromboneMakeCall request.

102 The custom server request is invalid at this time (probably because ofan error in the sequence of custom server calls).

103 CA_Open_CHP_Link() failed, probably because there were not enoughfree CHPs.

104 CA_Execute_State_Table() failed, probably because of an invalid statetable name, entry point, or the state table not being validated.

105 CA_Get_Channel_Info() failed, probably because the outbound call wasterminated.

112-199 Spare

TromboneMakeCallStatus

Description

TromboneMakeCallStatus is called by the IBMTromboneOut state table whenthe result of the outbound call part of the trombone function is known, or ifthere has been some other error. The values it can return are in the range 0(success) to 99. Table 15 on page 293 shows the initial meaning of valuesbetween 1 and 99, but you can customize these if you want.

Input parameters


The status of the outgoing part of the trombone. See Table 15 on page 293 forinitial values.


Table 15. Status values supplied by the TromboneMakeCallStatus function

Call Status Error Description


The following return codes represent a bad return code from the MakeCall request tothe third party by the IBMTromboneOut state table (assuming that you have notcustomized the IBMTromboneOut state table to alter these values)

1 Invalid phone number

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 IBMTromboneOutstate table, other than from the MakeCall request (assuming that you have notcustomized 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 trombonefunction (the caller) to connect the two halves of a trombone operation, afterthe original state table has set up the outbound part of the trombone using


the TromboneMakeCall custom server. When it receives this request, thecustom server uses TDM Manager to connect the caller and third party usingthe TDM bus. When this completes successfully, TromboneConnectCall returnsa zero response in the connect_call_status to indicate that the two tromboneparties are now connected.

If this process fails, TromboneConnectCall returns a non-zero response inconnect_call_status to indicate that the trombone connect operation has failedfor the given reason.

Input parameters

None.

Output parameters

short trombone_connect_call_status:

The status of the connect request; zero means that the operation wassuccessful. Error cases are shown in Table 16 and are a subset of those shownin Table 13 on page 288.


Make CallStatus Error Description




107 A TDM connect or disconnect request failed because the requested portwas already connected. This may be caused by other applicationsrunning that can make TDM connect and disconnect requests.

108 A TDM connect or disconnect request failed because there was no callpresent. One of the parties has probably hung up.

109 A TDM connect or disconnect request failed because the TimeslotManager was not ready. It may be very busy, or not available.

110 A TDM connect or disconnect request failed because of an internalcustom server problem.

111 A TDM connect or disconnect request failed because of an unexpectedreturn code from the connect or disconnect request.

112-199 Spare


TromboneTerminationValue

Description

TromboneTerminationValue can be used by the called party to specify atermination value before hanging up. When it receives this request, thecustom server stores the value it receives and when the outbound part of thetrombone disconnects it uses it to set the event data value on the channelevent it uses to report the disconnect to the inbound part of the trombone.The inbound part of the trombone can retrieve this value from SV234 whenthe channel event indicating disconnection of outbound part of the trombonehas been received.

Input parameters

long termination_value:

The value the outbound part of the trombone wants the inbound part of thetrombone to receive as event data when the outbound part of the trombonedisconnects.

Output parameters

None

TromboneDisconnectCall

Description

TromboneDisconnectCall is usually used by the caller to terminate thetrombone operation and remain connected to WebSphere Voice Response.When it receives this request, the custom server asks TDM Manager todisconnect the caller and third party from the TDM bus. When this completessuccessfully, the TromboneDisconnectCall request returns a zero response inthe disconnect_call_status to indicate that the two trombone parties are nowdisconnected, and that the caller is connected to WebSphere Voice Response.

If this process fails, the TromboneDisconnectCall request returns a non-zeroresponse in the disconnect_call_status to indicate that the trombone disconnectoperation has failed for the given reason.

Input parameters

None.


Output parameters

short trombone_disconnect_call_status:

The status of the disconnect request, as shown in Table 17.






107 A TDM connect or disconnect request failed because the requested portwas already connected. This may be caused by other applications runningthat can make TDM connect and disconnect requests.

108 A TDM connect or disconnect request failed because there was no callpresent. One of the parties has probably hung up.

109 A TDM connect or disconnect request failed because the Timeslot Managerwas not ready. It may be very busy, or not available.

110 A TDM connect or disconnect request failed because of an internal customserver problem.

111 A TDM connect or disconnect request failed because of an unexpectedreturn 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 tablesource code. The compiled state tables are compiled directly from the ASCIIstate table source code.

The state tables fall into three groups:

Example codeTo show how to perform a trombone operation with a singleInvokeStateTable call (IBMTromboneXmp, IBMTromboneXmpA, andIBMTromboneXmpB).


Trombone implementation codeTo encapsulate the complexities of the trombone operation(IBMTromboneCall, IBMTromboneConn, IBMTromboneDisc,IBMTromboneMake, IBMTromboneOut, IBMTromboneRdy, andIBMTromboneWait).

Helper state tablesTo encapsulate code that is used in various places and to keep thetrombone 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 304v “IBMTromboneC5” on page 305v “IBMTromboneC10” on page 306v “IBMTromboneDisc” on page 307v “IBMTromboneLog” on page 308v “IBMTromboneMake” on page 309v “IBMTromboneMus” on page 312v “IBMTromboneOut” on page 312v “IBMTromboneRdy” on page 314v “IBMTromboneWait” on page 316v “IBMTromboneXmp” on page 318v “IBMTromboneXmpA” on page 318v “IBMTromboneXmpB” on page 319

IBMTromboneCall

This state table encapsulates the code needed to create the trombone betweena caller and a third party in a single call. This state table is called by theuser’s application, along with a number of parameters using theInvokeStateTable action. The code is encapsulated in this way to allow it to beused in a similar way to other telephony actions without having to beconcerned about the details of performing the trombone.

If the trombone is set up successfully, this state table will not return untileither one of the parties hangs up, or the caller terminates the trombone bydialing a specified number using DTMF keys.

If the trombone operation fails, the state table exits immediately with a statuscode (and return edge) that indicates what the problem is.


For details of the communications that this state table performs withIBM_TromboneCustom_Server, see “How tromboning works” on page 281.

The source code is commented to help make customization easy. The ability tolog data and turn background music on and off has been provided in twoseparate state tables (IBMTromboneLog and IBMTromboneMus) that you caninvoke to prevent this state table becoming too complex and cluttered.

Parameters

String phone_number (40 character max):


String format (50 characters max):


String log_filename (64 characters max):

If this is blank, no event logging is performed. If you supply a filename, theIBMTromboneLog state table logs trombone calls and their results to an eventlog with that filename.

String user_data (64 characters max):


This may be used, for example, to reference a prompt to be played as anannouncement to the third party before the trombone operation connects thethird party to the caller.

String out_stbl_name (16 characters max):


String out_stbl_entry (16 characters max):

The entry point to use within the state table used for the outbound part of thetrombone 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 callerduring the trombone operation.

If this parameter contains a number (one or more digits), it terminates thetrombone operation on receiving the given number from the caller. When thetrombone terminates, the third party is disconnected and the caller remainsconnected to WebSphere Voice Response.

If this parameter is set to -, the trombone terminates when it receives anyDTMF 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 callerwhile the trombone operation is being set up.

If this parameter contains a string, the state table tries to play backgroundmusic (simulating music on hold) to the caller while the trombone is being setup. This parameter defines the name of the music file to play.

See Chapter 14, “Background music,” on page 195 for details of how to setupand configure background music.

If background music is not configured on WebSphere Voice Response, andyou try to play background music during the trombone operation, thatoperation 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 wasterminated by either the third party hanging up, or the caller requesting adisconnection by dialling the correct DTMF sequence.

If this value is non-zero, the trombone operation did not completesuccessfully. Table 18 on page 300 shows the meanings of the possiblecall_status values. Valid values are any given in the table except thosebetween 221 and 227.

This state table returns different edges depending on where in the range ofpossible values the call_status (also defined in Table 18 on page 300). Thisallows the general area of the problem to be determined immediately by thereturn edge of the InvokeStateTable action that called IBMTromboneCall.


Table 18. Return values from the IBMTromboneCall state table (call_status)

ReturnEdge

CallStatus Error Description

0 0 Trombone function request was successful.

1 Bad return code from the MakeCall request to the third party by theIBMTromboneOut state table (assuming that the IBMTromboneOut andIBMTromboneCall state tables have not been customized to alter thesevalues)

1 Invalid phone number

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

2 Bad return code from the IBMTromboneOut state table, other than fromthe MakeCall request (assuming that the IBMTromboneOut andIBMTromboneCall state tables have not been customized to alter thesevalues)

10 to 99 These values are reserved for user-defined return values.

3 Bad return code from the IBM_Trombone_Custom_Server (assuming thatthe IBMTromboneCall state table has not been customized to alter thesevalues)

100 IBMTromboneOut state table returned atrombone_make_call_status outside the valid range (0 to 99).


Table 18. Return values from the IBMTromboneCall state table(call_status) (continued)

ReturnEdge


101 The IBMTromboneOut state table performed aCloseHostServerLink while the custom server was waiting for aresponse to the TromboneMakeCall request

102 The custom server request is invalid at this time (probablybecause of an error in the sequence of custom server calls).

103 CA_Open_CHP_Link() failed, probably because there are notenough free CHPs.

104 CA_Execute_State_Table() failed, probably because of aninvalid state table name, entry point, or the state table notbeing validated.

105 CA_Get_Channel_Info() failed, probably because the outboundcall was terminated.

106 A TDM connect or disconnect request failed because of anadapter hardware problem.

107 A TDM connect or disconnect request failed because therequested port was already connected. This may be caused byother applications running that can make TDM connect anddisconnect requests.

108 A TDM connect or disconnect request failed because there wasno call present. One of the parties has probably hung up.

109 A TDM connect or disconnect request failed because theTimeslot Manager is not ready. It may be very busy or notavailable.

110 A TDM connect or disconnect request failed because of aninternal custom server problem.

111 A TDM connect or disconnect request failed because of anunexpected return code from the connect or disconnect request.

112-199 Spare



ReturnEdge


4 Bad status returned from the IBMTromboneCall state table itself (assumingthat the IBMTromboneCall state table has not been customized to alterthese values)

200 IBM_Trombone_Custom_Server returned atrombone_make_call_status outside the valid range (0 to 199).

201 Could not open a server link to theIBM_Trombone_Custom_Server.

202 Failed to send the data for the TromboneMakeCall request tothe IBM_Trombone_Custom_Server

203 to207

Bad return code from the ReceiveData corresponding to theTromboneMakeCall request. A status of 203 to 207 represents areturn edge of 1 to 5.

208 The caller hung up during the trombone operation.

209 Received a Fax Event during the trombone operation (SV227 isprobably not set to zero).

210 Received a Voice Event during the trombone operation (SV227is 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 requestto the IBM_Trombone_Custom_Server.

216 to220

Bad return code from the ReceiveData corresponding to theTromboneDisconnectCall request. A status of 216 to 220represents a return edge of 1 to 5.



ReturnEdge


221 Failed to send the data for the TromboneConnectCall request tothe IBM_Trombone_Custom_Server.

222 to226

Bad return code from the ReceiveData corresponding to theTromboneConnectCall request. A status of 222 to 226 representsa return edge of 1 to 5.

227 The ReceiveData corresponding to the TromboneConnectCallrequest timed out.

228 The ReceiveData corresponding to the TromboneDisconnectCallrequest timed out.

229 The ReceiveData corresponding to the TromboneCall orTromboneMakeCall request. timed out.

If you are using the IBMTromboneRdy state table, youprobably specified a fairly short time for the timeout. CallIBMTromboneRdy again until you are sure that the call hasfailed.

230 to249

Spare: may be used for user-defined values.

5 Bad status returned from the IBMTromboneCall state table itself, causedby a problem with music on hold. Most of these errors are generated inthe IBMTromboneMus state table, which is invoked by theIBMTromboneCall state table (assuming that the IBMTromboneCall andIBMTromboneMus state tables have not been customized to alter thesevalues)

250 Music on hold was specified, but the IBMTromboneMus statetable was either not available, or not validated. This mightoccur if the juke_box application is not installed.

251 The IBMTromboneMus state table returned a status outside thevalid range (> 251).

252 Unrecognized on_or_off value supplied to theIBMTromboneMus state table.



ReturnEdge


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 tothe juke_box custom server.

255 to259

Bad return code from the ReceiveData corresponding to thejuke_box_start_music request. A status of 255 to 259 representsa return edge of 1 to 5.

260 The status returned by the juke_box_start_music request wasout of range (<1000).

261 The requested music was not available.

IBMTromboneConn

This state table encapsulates some of the code needed to continue a tromboneoperation that is performed in several parts. It connects the caller with a thirdparty that has already been contacted using the IBMTromboneMake statetable. The call to the third party must have completed successfully for thisstate table to work successfully.

IBMTromboneConn uses the TromboneConnectCall function of theIBM_Trombone_Custom_Server. On successful completion, the caller isconnected to the third party using the TDM bus.

This state table is called by the user’s application, along with a number ofparameters, using the InvokeStateTable action. See “IBMTromboneXmpA” onpage 318 and “IBMTromboneXmpB” on page 319 for examples of how to usethis state table.

The source code is well commented and customization should be easy. Thefunction to log data has been provided in a separate state table that may beinvoked (IBMTromboneLog) to prevent this state table becoming too complexand cluttered.

Parameters

String log_filename(64 characters max):


If this is blank, no event logging is performed. If a filename is supplied, eventlogging of the trombone calls and the results are logged to an event log withthe given filename. The logging is performed by the IBMTromboneLog statetable.

Number call_status (thisvalue is returned):


If the value is zero, the trombone operation was successful and wasterminated either by the third party hanging up, or by the caller requesting adisconnection by dialling the correct DTMF sequence.

If this value is non-zero, the trombone operation did not completesuccessfully. Table 18 on page 300 shows the meanings of the possiblecall_status values.

This state table returns different edges depending on which range of possiblevalues the call_status lies in (also defined in Table 18 on page 300). Thisallows the general area of the problem to be determined immediately by thereturn 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 fivestrings 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 isreturned):

The concatenation of the input strings (in0 + in1 + in2 + in3 + in4).

IBMTromboneC10

This state table encapsulates the states needed to concatenate up to 10 stringstogether. 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.

String in9:

The 10th string.

String out (this value isreturned):

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 tromboneoperation that is performed in several parts. It disconnects the caller from athird party that has already been connected using the IBMTromboneMake andIBMTromboneConn state tables. The call and connection to the third partymust have completed successfully for this state table to work successfully.

IBMTromboneDisc uses the TromboneDisconnectCall function ofIBM_Trombone_Custom_Server. On successful completion, the caller isdisconnected from the third party (the connection on the TDM bus is broken).If the application allows, the caller can now continue with the application thatwas being used before the trombone connection was made.

This state table can be called by the user’s application, along with a numberof parameters using the InvokeStateTable action. This state table is used bythe IBMTromboneWait state table, which can be used as an example of how touse it.


Parameters



Number call_status(this value is returned):





This state table returns different edges depending on which range of possiblevalues the call_status lies in (also defined in Table 18 on page 300). Thisallows the general area of the problem to be determined immediately by thereturn 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. Itfirst checks the logging_on flag to see if the supplied data should be sent tothe log file. The data to be logged consists of a header string, followed by sixgeneral strings, which are all concatenated before being logged using aLogEvent action. The header string should contain the filename to which tolog the data in the format required by the LogEvent action. The state tablealways returns edge 0 regardless of any errors.

Parameters

Number logging_on:

A value of 1 means perform data logging; otherwise exit the state tablewithout logging anything.

String header:

The header string for the logging function (should contain at least thefilename 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 operationthat is performed in several parts. It requests an outbound call to be made bythe trombone custom server ready for a trombone operation.

If the wait_time parameter is set to zero, it returns as soon as the request foran outbound call has been sent. On successful completion, the outbound callto the third party should be in progress. The IBMTromboneRdy state table canthen be used to determine if the outbound call is successful, has failed, or isstill progressing.

If the wait_time parameter is non-zero, it waits for that amount of time for aresponse to the make call request. On successful completion, a third party hasbeen called, and is connected to WebSphere Voice Response. The caller andthird party are not connected on the TDM bus at this time. TheIBMTromboneConn state table should be used to complete the connection.

This state table is called by the user’s application, along with a number ofparameters using the InvokeStateTable action. See “IBMTromboneXmpA” onpage 318 and “IBMTromboneXmpB” on page 319 for examples of how to usethis state table.

The source code is well commented and customization should be easy. Thefunctionality to log data has been provided in a separate state table that maybe invoked (IBMTromboneLog) to prevent this state table becoming toocomplex and cluttered.


Parameters

String phone_number(40 character max):


String format (50 charactersmax):




String user_data (64characters max):



String out_stbl_name(16 characters max):


String out_stbl_entry(16 characters max):

The entry point within the state table to use for the outbound part of thetrombone operation. If this is blank, the default label begin is used.

Number wait_time (valueis in seconds):

The amount of time to wait for a response to the MakeCall request that is sentto IBM_Trombone_Custom_Server.


If this is set to zero, the state table returns as soon as the MakeCall requesthas been sent, without checking to see if the MakeCall has failed orsucceeded.

If this is set to a non-zero value, the state table waits for up to this amount oftime to see if the MakeCall has failed or succeeded. The IBMTromboneRdystate table is used to perform this test.





This state table returns different edges depending on which range of possiblevalues the call_status lies in (also defined in Table 18 on page 300). Thisallows the general area of the problem to be determined immediately by thereturn 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 229v 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. Itis supplied to provide a unique link between the two halves of the tromboneoperation for debug purposes. This value is set only if the wait_time isnon-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 statetable to the inbound state table. This may be used, for example, to indicate theresponse of the third party to the trombone request (such as a reason code forconnection refused). The inbound state table can then play a prompt to thecaller appropriate to the third party response. This value is set only if thewait_time is non-zero and the outbound call is successful within thewait_time specified.


IBMTromboneMus

This state table turns background music on or off, as requested by theon_or_off parameter, to simulate music on hold. The encapsulation of thisfunction keeps the IBMTromboneCall state table much simpler.

This state table has to communicate with the juke_box custom server toprovide this function. Any problems encountered with this communicationreturn a non-zero status (with an exit edge of 1).

The most likely area that might need customizing is the fading in or out ofthe 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 aperiod 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; anyother 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 valueis 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 theState 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 inTable 18 on page 300 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 operationand 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 toIBM_Trombone_Custom_Server. If the MakeCall is successful, it uses aWaitEvent 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; acaller 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 anannouncement prompt to the third party before connecting to the caller (lookfor the “MakeCall succeeded” comment in the source code for this state table).A simple PlayPrompt can be inserted here if the prompt is fixed.

If you want to vary the prompt to be played depending on who the caller is,use the user_data parameter to carry data to specify which prompt to play.

Parameters

String phone_number(40 character max):

The number to dial for the outgoing part of the Trombone (see definition ofphone_number in the MakeCall state table action for details).

String format (50 charactersmax):


String permit_ch_grps(64 characters max):

The permitted channel groups for the outgoing part of the trombone. Thisvalue should be copied into SV178 (see the definition of SV178 for informationon how this variable is used).

String permit_channels(64 characters max):

The permitted channels for the outgoing part of the trombone This valueshould be copied into SV228 (see the definition of SV228 for information onhow this variable is used).


If this is blank, no event logging is performed.

If you supply a filename, the IBMTromboneLog state table logs the trombonecalls and their results to an event log with that filename.

String user_data (64characters max):




String partner_call_id:

This is the Call Reference of the inbound part of the trombone operation. It issupplied to provide a unique link between the two halves of the tromboneoperation for debug purposes. It is included in the header information of anyevent logging.

String addn_call_info1(140 characters max):







Reserved forWebSphere Voice Response.



IBMTromboneRdy

This state table encapsulates some of the code needed to continue a tromboneoperation that is performed in several parts. It checks to see if an outboundcall, previously requested by the IBMTromboneMake state table, hascompleted successfully or with an error.

IBMTromboneRdy uses a ReceiveData action to wait for the amount of timespecified in wait_time for a response to the make call request. On successfulcompletion, a third party has been called and connected to WebSphere VoiceResponse. The caller and third party are connected on the TDM bus at this


time. The IBMTromboneConn state table should be used to complete theconnection. If the ReceiveData action times out, a return code of 229 isgenerated.

This state table is called by the user’s application, along with a number ofparameters using the InvokeStateTable action. See “IBMTromboneXmpB” onpage 319 for an examples of how to use this state table.

This state table may also be called by the IBMTromboneMake state table.


Parameters



Number wait_time (valueis in seconds):

The amount of time to wait for a response to the MakeCall request that is sentto the IBM_Trombone_Custom_Server.

If this is set to zero, the state table returns as soon as the MakeCall requesthas been sent, without checking to see if the MakeCall has failed orsucceeded.

If this is set to a non-zero value, the state table waits for up to this amount oftime to see if the MakeCall has failed or succeeded. The IBMTromboneRdystate table is used to perform this test.






This state table will return different edges depending on which range ofpossible values the call_status lies in (also defined in Table 18 on page 300).This allows the general area of the problem to be determined immediately bythe return edge of the InvokeStateTable action that called IBMTromboneRdy.

The IBMTromboneRdy state table can return any of the following values: 0 to200, 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. Itis supplied to provide a unique link between the two halves of the tromboneoperation for debug purposes. This value is set only if the outbound call issuccessful 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 statetable to the inbound state table. This may be used, for example, to indicate theresponse of the third party to the trombone request (such as a reason code forconnection refused). The inbound state table can then play a prompt to thecaller appropriate to the third party response. This value is set only if theoutbound call is successful within the wait_time specified.

IBMTromboneWait

This state table encapsulates some of the code needed to continue a tromboneoperation that is performed in several parts. It waits for a tromboneconnection to terminate, either by the caller or third party hanging up, or bythe caller dialling a specified DTMF sequence. It requires that a trombone hasalready been set up successfully using the IBMTromboneMake andIBMTromboneConnect state tables.

IBMTromboneWait uses the WaitEvent state table action to wait for eitherparty to hang-up, or for DTMFs to be sent from the caller. When it detectstrombone termination, it calls the IBMTromboneDisc state table if necessaryand closes the host server link to the IBM_Trombone_Custom_Server. Onsuccessful completion, the trombone operation is terminated, and, if theapplication allows, the caller can continue with the application that was beingused before the trombone connection was made (unless a caller hang-upcaused the trombone termination).


This state table can be called by the user’s application, along with a numberof parameters using the InvokeStateTable action. See “IBMTromboneXmpA”on page 318 and “IBMTromboneXmpB” on page 319 for examples of how touse this state table.


Parameters



String end_on_DTMF(64 characters max):

If this is blank, the state table ignores any DTMFs it receives from the callerduring the trombone operation.

If this parameter contains a number (one or more digits), it terminates thetrombone operation on receiving the given number from the caller. When thetrombone terminates, the third party is disconnected, and the caller remainsconnected to WebSphere Voice Response.

If this parameter is set to -, the trombone terminates on reception of anyDTMF from the caller.

Valid DTMF digits are 0 to 9, *, and #.






This state table returns different edges depending on which range of possiblevalues the call_status lies in (also defined in Table 18 on page 300). Thisallows the general area of the problem to be determined immediately by thereturn 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 keptit intentionally simple to demonstrate the minimum that is required toperform a trombone operation. It uses the IBMTromboneCall state table toperform a trombone operation with a single call.

When the application is invoked by an incoming call, it requests a number totransfer to, and then tries to trombone to that number. If the trombone fails, itplays the “Technical difficulties...” prompt and exits. If the Trombone issuccessful, on termination of the Trombone operation (the third party hangsup or the caller dials 1234), it asks the caller for another number to which totransfer.

You can customize this application by altering the variables defined at thestart of the state table, or by adding different prompts and actions on thevarious trombone exit conditions near the end of the state table. The variablesat the start of the state table are passed directly to the IBMTromboneCall statetable; their meanings are described in “TromboneCall” on page 286.

The prompts and voice segments for this application are held in directoriescalled IBM_Trombone.

Parameters

None.

IBMTromboneXmpA

This is an application that can be invoked on an incoming call. Theapplication has been kept intentionally simple to demonstrate the minimumthat is required to perform a trombone operation. It uses theIBMTromboneMake, IBMTromboneConn, and IBMTromboneWait state tablesto perform a trombone operation. It allows slightly more control over settingup 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 isconnected to the third party. In this example we play a long beep to indicatethat the connection is about to be made.


When the application is invoked by an incoming call, it requests a number totransfer to, and then tries to trombone to that number. If the trombone fails, itplays the “Technical difficulties...” prompt and exits. If the trombone issuccessful, when the trombone operation terminates (the third party hangs upor the caller dials 1234), it asks the caller for another number to which totransfer.

This application may be customized by altering the variables defined at thestart of the state table or by adding different prompts and actions on thevarious trombone exit conditions near the end of the state table. The variablesat the start of the state table are passed directly to the IBMTromboneMake,IBMTromboneConn, or IBMTromboneWait state tables and their meanings aredescribed in the definition of the state tables.

The Prompts and Voice segments for this application are held in directoriescalled IBM_Trombone.

Parameters

None.

IBMTromboneXmpB

This is an application that can be invoked on an incoming call. Theapplication has been kept intentionally simple to demonstrate the minimumthat is required to perform a trombone operation. It uses theIBMTromboneMake, IBMTromboneRdy, IBMTromboneConn, andIBMTromboneWait state tables to perform a trombone operation. It allowsslightly more control over setting up the trombone than the examples given inthe IBMTromboneXmp and IBMTromboneXmpA state tables. It allows aprompt to be repeatedly played to the caller while the outbound call isprogressing 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 theoutbound call is progressing and a long beep to indicate that the connection isabout to be made.

When the application is invoked by an incoming call, it requests a number towhich to transfer, and then tries to trombone to that number. If the trombonefails, it plays the “Technical difficulties...” prompt and exits. If the trombone issuccessful, when the trombone operation terminates (the third party hangs upor the caller dials 1234), it asks the caller for another number to which totransfer.

This application may be customized by altering the variables defined at thestart of the state table or by adding different prompts and actions on thevarious 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 aredescribed in the definition of the state tables.

The Prompts and Voice segments for this application are held in directoriescalled 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 forinformation purposes.

The errors are issued as standard custom server errors in the range 20500 to20504. The IBM_Trombone_Custom_Server error title and ID are shown inparameters 1 and 2 of the standard custom server errors. The error IDs havethe form TROMBONEnnn. The remaining parameters contain informationspecific to the particular error.

With any of these errors, if you have followed the suggestions in the UserResponse, and you are unable to solve the problem, contact IBM Support.When you call, have details of any errors, your system setup, and details ofthe conditions that cause the problem. An AIX system trace taken when theproblem occurs may also be required. Before taking the trace, set the -d optionin the custom server. For more information on the command line options see“Configuring IBM_Trombone_Custom_Server” on page 277.

The IBM_Trombone_Custom_Server errors are listed in the WebSphere VoiceResponse for AIX: Problem Determination book.


Chapter 19. Using the VOX_CTI Custom Server

How to install and use the VOX_CTI Custom Server.

Avaya Interaction Center VOX Connector for WebSphere Voice Response

The Avaya Interaction Center VOX Connector for WebSphere Voice Responsefor AIX (VOX_CTI) custom server provides an interface between state tablesand the Quintus VOX Server. A state table sends VOX commands by passingstate table variables into the custom server via the SendData action. VOXresponses are returned via the ReceiveData action.

This chapter contains the following sections:v “Installation”v “VOX_CTI.ini file configuration”v “VOX_CTI Custom Server functions” on page 323v “VOX_CTI function return codes” on page 329v “General guidelines” on page 330

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 = 16384no -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 itemsmust be placed under this General section. The only compulsory tag in theVOX_CTI ini file is the port tag.


Here is an example .ini file that sets the VOX_CTI custom server to listen onport 3000:[General] port = 3000

The full list of supported tags is as follows:

port The port tag can be set to a single number or to a list of portnumbers. For example, to start a listening socket for ports 3000 and3001 the entry in the .ini file would be port = 3000 3001.

dt_childrenThe dt_children tag specifies the number of child processes to initiallyspawn when the VOX_CTI custom server is started. Each WebSphereVoice Response channel that is using the VOX_CTI custom serverrequires one child process to service the requests. Therefore ifdt_children = 20, then 20 channels can simultaneously issue VOXcommands without the VOX_CTI custom server having to spawnmore children.

The dt_children tag is optional and the default value is 0 as theVOX_CTI custom server will spawn more child processes as they areneeded. The minimum and maximum values are 0 and 480respectively.

vox_timeoutThe vox_timeout tag specifies the number of milliseconds to wait for aVOX response after issuing a VOX command. If the VOX responsedoes not arrive before the timeout the VOX_CTI function will returnVOX_TIMED_OUT.

The vox_timeout tag is optional and the default value is 5000. Theminimum and maximum values are 500 and 60000 respectively.

newcall_timeoutThe newcall_timeout tag specifies the number of milliseconds to waitbefore forcing the association between the state table and the channel(from the VOX Server point of view). This timeout is only used if acall arrives at a channel and a Newcall function has been called whilstan existing channel process or state table is still using the channel(that is, it has not issued a Gone command). Gone is issuedautomatically after the timeout for the existing channel process orstate table, and the Newcall proceeds. The default is to allow theoriginal state table two seconds to issue a Gone response after itdetects 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_sizeThe send_buffer_size tag specifies the number of VOX commands that


can be buffered in the TCP send buffer. As its default value, the TCPsend buffer uses the size of the AIX TCP send buffer. However, thedefault AIX send buffer size is 4096 bytes, which is equivalent to onlyfour VOX commands (each VOX command requires 1024 bytes). It ispreferable to increase the AIX TCP send buffer size to 16K bytes (toallow for 16 simultaneous VOX commands) and also to omit thesend_buffer_size tag from the .ini file. This can be achieved by usingthe no command no -o tcp_sendspace = 16384.

The send_buffer_size tag is optional and has a default value of -1 (thismeans use AIX's TCP send buffer size). The minimum and maximumvalues are 4 and 128 respectively.

recv_buffer_sizeThe recv_buffer_size tag specifies the number of VOX requests thatcan be buffered in the TCP recv buffer. As its default value, the TCPrecv buffer uses the size of the AIX TCP recv buffer. However thedefault AIX buffer size is 4096 bytes which is equivalent to only fourVOX responses (each VOX response requires 1024 bytes). It ispreferable to increase the AIX TCP recv buffer size to 16K bytes (toallow for 16 simultaneous VOX responses) and also to omit therecv_buffer_size tag from the ini file. This can be achieved by usingthe no command no -o tcp_recvspace = 16384.

The recv_buffer_size tag is optional and has a default value of -1 (thismeans use AIX's TCP recv buffer size). The minimum and maximumvalues are 4 and 128 respectively.

VOX_CTI Custom Server functions

This section describes the VOX_CTI custom server functions that can be usedfrom within a state table to access the VOX Server:v “Alarm” on page 324v “Getvdu” on page 324v “Getvox” on page 325v “Gone” on page 326v “Newcall” on page 326v “Ping” on page 327v “Pseudo_Ani” on page 327v “Setvdu” on page 327v “Tr” on page 328v “Transfer” on page 329

Each function is described using the following headings:

Input The parameters or variables to be passed in the VOX command.

Chapter 19. Using the VOX_CTI Custom Server 323

OutputThe return values from the VOX response.

Note: VOX_CTI functions always send back a return code and anypotential VOX error messages.

VOX commandThe actual VOX command sent to the VOX Server. All variables in theVOX command are derived from the input variables except for reqidand channelnum, which are automatically generated by the VOX_CTIcustom server.

VOX responseThe positive response sent back from the VOX Server. All variables inthe VOX response are mapped across to the corresponding outputvariables.

Valid An indicator of whether or not the function called is valid. Forexample, the Getvdu function is only valid after a Newcall functionand before a Gone.

Note: String variables passed to the VOX Server do not all need to beenclosed in quotes unless specifically stated. For example, to send a lowpriority VOX alarm command to the VOX Server, set the priority variable toLow from within the state table rather than to "Low".

For more information about each VOX command see the Avaya InteractionCenter VOX Server Programmer's Guide.

Alarm

Input char alarmname[64]char priority[16]char description[128]

Outputlong rcchar 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]


Outputlong rcchar error_msg[256]char value[1024]

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 thecomma as a delimiter to generate the name1, name2, name3 variables. Theoutput variable called value is set to the returned set of "name","value" pairswithout the quotes.

For example, to request both a balance and a pin number (on channel 10) thefollowing 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.getvducommands must return less than 1024 bytes. Using the previous example, ifboth the balance and pin had returned a character string great than 512, thenthe entire response would have exceeded 1024 characters and thus failed. Thesolution to this is to call the Getvdu function twice, once with the balance andthe other with the pin.

Getvox


Outputlong rcchar error_msg[256]char value[1024]


VOX command[VOX.getvox(#channelnum,"name",)][reqid]

VOX response[VOX.getvox.response(,#channelnum,"name","value")][reqid]


Note: The maximum size of a VOX response is 1024 bytes so all VOX.getvoxcommands must return less than 1024 bytes.

Gone

Input No input parameters or variables


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 detectsthat the call has hung up. The Gone function disassociates the link betweenthe 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 (besidesAlarm and Ping).

If a new call arrives on the channel whilst an existing CHP/state table isusing that channel a VOX.gone command is automatically sent to the VOXServer for that channel. Preferably, application writers should always call theGone function.

Newcall



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. TheNewcall function associates the CHP/state table with the channel from theVOX Server's point of view.

Ping



VOX command[VOX.ping()][reqid]

VOX response[VOX.ping.response(,)][reqid]

Valid Always

Pseudo_Ani

Input No input or variables

Outputlong rcchar error_msg[256]char ps_ani[32]

VOX command[VOX.pseudo_ani(#channelnum)][reqid]

VOX response[VOX.pseudo_ani.response(,#channenum,"ps_ani")][reqid]


Setvdu



VOX command[VOX.setvdu(#channelnum,"name1","value1","name2","value2",

"name3","value3")][reqid]


VOX response[VOX.setvdu.response(,#channelnum,"name1","value1","name2",

"value2","name3","value3")][reqid]


The name input variable is split into one or more sub strings using thecomma as a delimiter to generate the name1, value1, name2, value2, name3,value3 variables. For example, to set the balance to 3000 and pin number to1234 (on channel 10) the following variable would be set and VOX commandsand requests issued:

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 outputchar arg1[32]char arg2[32]char arg3[32]char arg4[32]

Outputlong rcchar error_msg[256]char output[64]

When the output variable is set to 1 the following VOX command is sent andVOX 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 andVOX response received:

VOX command[VOX.tr2<op>(#channelnum,"arg1","arg2","arg3","arg4")][reqid]


VOX response[VOX.tr2<op>.response(,#channelnum,"arg1","arg2","arg3","arg4",

"output")][reqid]


Transfer

Input char destination[32]


VOX command[VOX.transfer(#channelnum,"destination")][reqid]

VOX response[VOX.transfer.response(,#channelnum,"destination")][reqid]


VOX_CTI function return codes

Every VOX_CTI function has an output variable called rc which is used toreturn the result of sending the VOX command and receiving the VOXresponse (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 responsesuccessfully received.

The rc variable can take one of the following values:

0 - VOX_OKThe VOX command was successfully sent and a VOX responsesuccessfully received.

1 - VOX_NO_VOX_SERVERThe 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_UNKNOWNSomething unknown went wrong. This return code should never bereturned.

3 - VOX_NO_CHANNELThe CHP/state table no longer has access to the channel from a VOXServer 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 answeredby another state table. The second state table will automatically issue aGone (see Gone for more information.)

v The Newcall function has not been called.

4 - VOX_REQUEST_TOO_LONGThe request is too long (more than 1024 characters). This will occur if theoutcome of the VOX command would be more than 1024 characters long.

5 - VOX_TIMED_OUTThe VOX Server did not respond to the VOX command within thetimeout period specified in the ini file.

6 - VOX_BAD_RESPONSEThe VOX response received by VOX_CTI was not understood. Theresponse will be stored in the error_msg variable.

General guidelines

Here are some general guidelines for keeping the VOX Server and WebSphereVoice 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 notcontain more than 255 name and value pairs.

v Check the return code from each VOX_CTI functionv As mentioned in the Avaya IC VOX Server Programmer's Guide hookflash

transfer is not supported.


Part 3. Appendixes


Appendix A. ID and name limitations

This chapter lists the identifiers and names used in WebSphere VoiceResponse application development functions and describes the data typelimitations that apply to each ID and name.

The table below lists the identifiers and names used in WebSphere VoiceResponse application development functions and describes the data typelimitations that apply to each ID and name.

ID or Name Data Type Limitations

Application name Up to 15 characters. The first character is limited toA–Z, a–z, and underscore ( _ ). The second throughfifteenth 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 profilepassword

Up to eight characters.

Custom server name

Custom server user function

Custom server argument

Up to 63 characters. The first character is limited toA–Z, a–z, and underscore ( _ ). The second throughsixty-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 anapostrophe (’) in the description, you must type twoconsecutive 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 inthe WebSphere Voice Response Languages window)that identifies the default language.

IDs for user-defined languages must be in the range129-255.

Local variables Up to 15 characters, limited to a–z, and A–Z.



Mailbox ID A numeric value in the range 1–10.

Mailbox password A numeric value up to eight digits in length.

Music title Up to 31 characters. Can include alphabeticcharacters (uppercase and lowercase), numericcharacters, #, _, +, -, *, @, (, ), [, ], !, ?, &, <,>, /, \, ‘, semicolon (;), colon (:), comma (,), period(.), and space.

Prompt directory name Up to 15 characters. The first character is limited toA–Z, a–z, and underscore ( _ ). The second throughfifteenth characters can include alphanumeric (0–9,A–Z, a–z) and underscore characters.

Prompt name Up to 15 characters. The first character is limited toA–Z, a–z, and underscore ( _ ). The second throughfifteenth characters can include alphanumeric (0–9,A–Z, a–z) and underscore characters.

State table entry label/statelabel

Up to 15 characters. The first character is limited toA–Z, a–z, and underscore ( _ ). The second throughfifteenth 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 toA–Z, a–z, and underscore ( _ ). The second throughfifteenth 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 than4096 parameter variables can be used in each statetable.

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 toA–Z, a–z, and underscore ( _ ). The second throughsixty-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 toA–Z, a–z, and underscore ( _ ). The second throughfifteenth characters can include alphanumeric (0–9,A–Z, a–z) and underscore characters.

Voice table name Up to 15 characters. The first character is limited toA–Z, a–z, and underscore ( _ ). The second throughfifteenth 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.

Appendix A. ID and name limitations 335

Appendix B. Voice interrupt detection: technicalinformation

Voice interrupt detection is controlled using three system parameters and foursystem variables. The system parameters specify default values for the wholesystem. These can be overridden for an individual application by usingsystem variables.

The other system variable turns voice interrupt detection on or off. Thiscannot be done on a system-wide basis. Indeed, during the course of anapplication, you may turn voice interrupt detection on and off again, perhapsmore than once. For example, when you are using parts of older applicationswhich were not written to handle voice interrupt detection along with newerparts which can.

The system parameters and their equivalent system variables are shown inTable 19.

Table 19. 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 DetectionLevel

SV219 System : Voice Interrupt Detection On Time Voice Interrupt DetectionOn Time

SV220 System : Voice Interrupt Detection Off Time Voice Interrupt DetectionOff Time

The value of Voice Interrupt Detection Level specifies the minimum energylevel that the voice interrupt detector considers to be an interrupt. That is, anynoises below that level don't count as interrupts.

Be careful when setting the voice interrupt detection level variable, if it is toohigh the caller will be unable to interrupt prompts even by shouting. If the


value is too low, the echo5 from a prompt being played combined with thebackground noise level from the caller's telephone may interrupt promptsunintentionally. If there is a very loud echo on a particular line, it isrecommended that the level is increased.

The value of Voice Interrupt Detection On Time specifies the minimum lengthof time for which the audio signal must remain above the minimum energylevel. 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 minimumenergy level and longer than the minimum on time), the detector must makesure that the caller has finished speaking the word before starting the nextstate table action. This is because the caller may have spoken a multi-syllableword as the interrupt: for example, “cancel”. If the detector stops as soon as ithas heard “Can”, the rest of the word, “cel” could be taken as another wordand passed to a speech recognizer. If you add a tone between the play andrecord actions in the state table, this ensures that the caller's interruptcompletes before the record action begins. So, the Voice Interrupt DetectionOff Time value is used to make sure that there is a period of silence after theinterrupt-word has been spoken.

This also ensures that a continuous sound picked up by the caller's telephoneis not assumed to be an interrupt.

5. Echo can be generated by any connectors or switches that have analog circuits. Echo can come from localequipment, the service provider, or the caller's equipment.

Audiosignalenergylevel

Voice Response detectsvoice interrupt

Time

voice interrupt detection levelOn time Off time

Figure 50. WebSphere Voice Response detects a voice interrupt


There are default values for all of these parameters and variables, which workin most circumstances. Change these values only if you have a need to, forexample, if levels are set too high or too low for the environments yourapplications are used in. Refer to the WebSphere Voice Response for AIX: ProblemDetermination book for examples of problems you may encounter using voiceinterrupt detection and suggested solutions.

All you need to do to activate voice interrupt detection is to set SV217 to 1 inthe state table. To turn voice interrupt detection off again, for example, wheninvoking 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 thevoice interrupt detection edges and variable settings when a prompt isinterrupted.

Example of how voice interrupt detection works

This example illustrates the stages that WebSphere Voice Response goesthrough in interpreting a voice interrupt.

Figure 51 shows the audio signal level of the two-syllable word “cancel” beingspoken to a WebSphere Voice Response application. We follow the stageswhich WebSphere Voice Response goes through for this word to beinterpreted as a voice interrupt.

1. The energy level of the audio signal exceeds the level set in the voiceinterrupt detection level parameter.

2. The value of the voice interrupt detection on time parameter is reachedand the audio signal will qualify as a voice interrupt.

3. The sample energy level of the voice sample falls below the voice interruptdetection level parameter. WebSphere Voice Response counts (inmilliseconds) until the value of the off time parameter is reached. If the off

Time

Audio

Voice Interrupt Detection Level

Off time

Off time

SignalEnergy

1 2 3 4 5 6

Ontime

Level

7

Figure 51. How voice interrupt detection parameters act on a voice sample

Appendix B. Voice interrupt detection: technical information 339

time elapses without the audio signal exceeding the voice interruptdetection level parameter, WebSphere Voice Response interprets this as avoice Interrupt.

4. The sample energy level rises above the voice interrupt detection levelagain. WebSphere Voice Response registers this and the off time is resetuntil the level drops below the line again, and no voice interrupt detectionis reported to the application.

5. Again, the sample energy level falls below the threshold. WebSphere VoiceResponse begins counting milliseconds for the off time parameter toexpire.

6. If the second peak of the energy level of the sample was not here, theWebSphere Voice Response would report a voice interrupt at this point.However, as the peak is there, the off time has not been reached, sonothing is done here.

7. WebSphere Voice Response registers that the off time has elapsed and theenergy level of the audio signal has remained below the voice interruptdetection level. A voice interrupt is reported, and the play action stops(unless the prompt has been force played).

In Figure 51 on page 339, when the off time is less than the difference betweenpoints 3 and 4, the off time criterion is satisfied before point 4, and a voiceinterrupt is detected. WebSphere Voice Response acts on the next action in thestate table and if this is a record or speech recognition action, then the secondhalf of the word in this example may be used.

Similarly, if the voice interrupt detection level is set higher, the time differencebetween 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 maybe used.

Summary

For a voice interrupt to be detected by WebSphere Voice Response threecriteria 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 timespecified in the voice interrupt detection off time variable.


Appendix C. Background music: technical information

This appendix contains information on controlling sound levels, customizingthe juke box, and writing your own background music subsystem.

This appendix contains the following information:v “Sound levels”v “Customizing the Juke Box” on page 344v “Writing your own background music subsystem” on page 348

Sound levels

When two sounds are added together, the volume increases. Limits must beset so that the total volume level (measured in dBm) does not exceed theallowed maximum on a telephone channel. Background music uses the systemvariables and system parameters described here to control these levels.

Background music uses the system variables and system parameters shown inTable 20 to control these levels.

Table 20. System variables and parameters used for background music.

System Variable System Parameter 1 Parameter Group

SV223 System : Prompt volume ceiling Prompt Volume CeilingDefault

Trunk Interface

SV224 System : Music : Volume ceiling Music Volume CeilingDefault

Trunk Interface

SV225System : Music : Automatic fade time

Music Automatic FadeTime Default

ApplicationServer Interface

SV226System : Music : Automatic fadebefore actions

Music Automatic FadeBefore Actions

ApplicationServer Interface

Music ChannelsMaximum

Trunk Interface

Music Absolute SilenceThreshold

Trunk Interface


Table 20. System variables and parameters used for background music. (continued)

System Variable System Parameter 1 Parameter Group

1. For details of system parameters, see the WebSphere Voice Response for AIX:Configuring the System book.

To reset the value of a system parameter: Welcome window —>Configuration —> System Configuration —> Change —> open theparameter group —> open the system parameter —> click or type in the newvalue —> OK. Before closing the System Configuration window, you need toSave the new value.

Each system parameter has help information which is also listed, inalphabetical order, in the WebSphere Voice Response for AIX: Configuring theSystem book.

The music volume ceiling and the prompt volume ceilingThe prompt volume ceiling and the music volume ceiling system variables aredefined so that the maximum permissible volume on your telephone system isnot exceeded when a voice sample is played at both volumes and both voicestreams are mixed together. When one volume is high, the other must be low,as shown in Table 21

Table 21. Music volume and prompt volume ceilings

Music VolumeCeiling

Prompt VolumeCeiling

Prompt VolumeCeiling

Music VolumeCeiling

0 10 or higher 0 10 or higher








8 or higher 0 8 or higher 0

Figure 52 on page 343 shows a diagrammatic version of events in theMusical_Welcome state table; shaded areas indicate when prompts orbackground music is playing.


Figure 53 on page 344 shows how you would set the prompt volume ceilingand the music volume ceiling to the same level to play both prompts andtunes 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 52. Musical welcome state table: volume levels

Appendix C. Background music: technical information 343

Customizing the Juke Box

The following information may be useful to you if you change the Juke_Boxcustom server or either of the music players (pl_seg and pl_elem).

Source code files for the Juke BoxThe 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:

|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 53. Playing prompts and tunes at the same volume


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

Collecting statistics from the Juke_Box custom serverThis function is not in the Juke_Box custom server, it is included here as asuggestion for an extension to the custom server.

When playing music you may want to keep statistics of how often each pieceof music is played.


You can change the Juke_Box custom server to add a record to a file each timea juke_box_start_music command is received. The file name can be aparameter 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, theJuke_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 playersThe music players pl_elem and pl_seg are built with special options using theLd 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_segWhen your state table asks the Juke_Box custom server to start playing atune, the Juke_Box custom server starts a process to play the tune to themusic channel until it is told to stop.

The program, or music player, uses the following input parameters:

argv[0] player_program_nameThe name used to invoke the music player, for example, pl_elem.

argv[1] pack_numberAn ASCII string containing the decimal representation of a number;the number of the pack where the tune is to be played. This string ispassed to CA_Open_Music_Channel in the vpack field.

argv[2] music_titleAn ASCII string giving the music title to the music player. The musicplayer passes this string to the CA_Open_Music_Channel call in themusic_title field.

argv[3] parameter_stringAn ASCII character string specified either in the Juke_Box customserver configuration file, or passed by the state table when a musictitle is added using juke_box_configure_music. This string containsthe information the music player needs to find and access the tuneknown as music_title.


Message queueThe music player opens a message queue to communicate with the Juke_Boxcustom server using the function in jb_shared.c. The Juke_Box custom serverand the music player can both send messages to, and receive messages fromeach other.

When the music player is initialized, either successfully or unsuccessfully, itsends the message Q_MSG_TYPE_INITIALIZED to the Juke_Box customserver.

The music player sends the message Q_MSG_TYPE_EXITING to theJuke_Box custom server before terminating. It sends this message even ifinitialization failed, or the rest of the music player process was not executed.

The Juke_Box custom server can send the messageQ_MSG_TYPE_TERMINATE to the music player at any time. The musicplayer releases any resources it is using and terminates.

When a music player terminates, the Juke_Box custom server receivesSIGCHLD signals. The Juke_Box custom server knows which music playerhas terminated, and cleans up its own internal data structures.

Messages sent to the music player by the Juke_Box customserver

Q_MSG_TYPE_TERMINATEWhen this message is received, the music player releases anyresources it is using, sends a message Q_MSG_TYPE_EXITING to theJuke_Box custom server, and terminates.

Messages sent to the Juke_Box custom server by the musicplayer

Q_MSG_TYPE_INITIALIZEDIf initialization is successful the code sent with this message is 0, if itis unsuccessful, the code sent is non-zero.

Q_MSG_TYPE_EXITINGThe music player sends this message to the Juke_Box custom serverwhen it is about to end. This is either in response to aQ_MSG_TYPE_TERMINATE message from the Juke_Box customserver or indicates a failure in the music player. A return code is alsosent indicating the reason for the music player ending.


Writing your own background music subsystem

When writing your own background music custom server and music players,you must consider how to pass dynamic voice data to a custom server.

Passing dynamic voice data to a custom serverFor this, you will need a program that accepts data supplied in adynamic stream, and uses the custom server API (similar to thepl_elem music player program). For example, your music data maycome from a line-in on an Ultimedia Audio adapter.

You must set the dBm level in the CA_Play_Voice_Stream customserver API call. It is your responsibility to ensure that WebSphereVoice Response never receives audio data which exceeds this peakdBm level.

To find out this what this level should be, run your program to recordsome incoming audio data. Use a sample that contains the loudestsound the source will send. Use CA_Import_Voice to convert the voicedata to an elements structure, then use CA_Get_Element_Info to findthe dBm level.

Note: If the dBm level is too high you may damage your telephoneprovider’s equipment!

When you know what the dBm level is, your music player can passthis dBm level to CA_Play_Voice_Stream.

Use cvelem off-line to pre-process music into elements moreefficiently than using CA_import() and CA_Play_Voice_Elements()dynamically.


Notices

This information was developed for products and services offered in theU.S.A.

IBM may not offer the products, services, or features discussed in thisdocument in other countries. Consult your local IBM representative forinformation on the products and services currently available in your area. Anyreference to an IBM product, program, or service is not intended to state orimply that only that IBM product, program, or service may be used. Anyfunctionally equivalent product, program, or service that does not infringeany IBM intellectual property right may be used instead. However, it is theuser’s responsibility to evaluate and verify the operation of any non-IBMproduct, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not giveyou 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 theIBM Intellectual Property Department in your country or send inquiries, inwriting, 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 anyother country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THEIMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY


OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allowdisclaimer 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 willbe incorporated in new editions of the publication. IBM may makeimprovements 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 forconvenience only and do not in any manner serve as an endorsement of thoseWeb sites. The materials at those Web sites are not part of the materials forthis 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 itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for thepurpose of enabling: (i) the exchange of information between independentlycreated programs and other programs (including this one) and (ii) the mutualuse of the information which has been exchanged, should contact: IBM UKLimited, Department 88013, 4NW, 76/78 Upper Ground, London, SE1 9PZ,England. Such information may be available, subject to appropriate terms andconditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM CustomerAgreement, IBM International Programming License Agreement, or anyequivalent agreement between us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly availablesources. IBM has not tested those products and cannot confirm the accuracyof performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should beaddressed to the suppliers of those products.

COPYRIGHT LICENSE: This information contains sample applicationprograms in source language, which illustrate programming techniques onvarious operating platforms. You may copy, modify, and distribute thesesample programs in any form without payment to IBM, for the purposes ofdeveloping, using, marketing or distributing application programs conformingto the application programming interface for the operating platform for whichthe sample programs are written. These examples have not been thoroughly


tested under all conditions. IBM, therefore, cannot guarantee or implyreliability, serviceability, or function of these programs.

For country-specific notes on the use of WebSphere Voice Response, refer tothe README file located in the directory /usr/lpp/dirTalk/homologation.The file name is in the format README_homologation.xxxx, where xxxx isthe country/region identifier.

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corp., registered in many jurisdictionsworldwide. Other product and service names might be trademarks of IBM orother companies. A current list of IBM trademarks is available on the Web atCopyright and trademark information at http://www.ibm.com/legal/copytrade.shtml.

Adobe, is a registered trademark of Adobe Systems Incorporated in theUnited States, and/or other countries.

Java and all Java-based trademarks and logos are trademarks of Oracleand/or its affiliates.

Microsoft, Windows, and the Windows logo are trademarks of MicrosoftCorporation in the United States, other countries, or both.

Notices 351

http://www.ibm.com/legal/copytrade.shtml

Glossary

The following terms and abbreviations are defined as they are used in the context ofWebSphere 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 isused primarily in North Americaand Japan when converting fromanalog to digital speech data.(Compand is a contraction ofcompress and expand.) Contrastwith A-law.

Numerics

2 B-channel transfer featureSee Integrated Services DigitalNetwork (ISDN) two B-channeltransfer.

3270 host applicationAn application on the IBMSystem/370™ System/390®, orAS/400® that interacts withterminals that support the 3270 datastream.

3270 script languageSee script language.

3270 serverA function of WebSphere VoiceResponse that provides a softwareinterface between WebSphere VoiceResponse and IBM System/370,System/390, or AS/400 architecturebusiness applications that interactwith terminals that support the 3270data stream. Contrast with customserver.

5ESS (1) A Lucent Technologies switch.

(2) The ISDN protocol that is usedon the 5ESS switch. It provides 23B-channels and a D-channel over aT1 trunk.

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 TelephonyAdapter with Blind Swap Cassette.

A

A-law The companding algorithm that isused in Europe, Latin America, andother countries when convertingfrom analog to digital speech data.(Compand is a contraction ofcompress and expand.) Contrastwith µ-law.

access protocolA protocol that is used between anexternal subscriber and a switch in atelephone network.

ACD See automatic call distributor.

ACL See application connectivity link.

action See state table action.

Action PaletteAn area that contains folders andicons that can be selected to createstate table actions.


Address Resolution Protocol (ARP)In HACMP, the Internetcommunication protocol thatdynamically maps Internetaddresses to physical (hardware)addresses on local area networks.Limited to networks that supporthardware broadcast.

The usr/sbin/cluster/etc/clinfo.rcscript, which is invoked by theclinfo daemon whenever a networkor node event occurs, updates thesystem ARP cache. This ensures thatthe IP addresses of all cluster nodesare updated after an IP addresstakeover. The script can be furthercustomized to handle site-specificneeds.

administrator profileData that describes a WebSphereVoice Response user. Informationthat is in an administrator profileincludes ID, password, languagepreference, and access privileges.

ADSI See analog display services interface.

ADSI telephoneA “smart” telephone that caninterpret and return ADSI data.

advanced intelligent network (AIN)A telephone network that expandsthe idea of the intelligent network(IN) to provide special services moreefficiently; for example, by givingusers the ability to program manyof the services themselves.

AIN See advanced intelligent network.

alarm Any condition that WebSphere VoiceResponse thinks worthy ofdocumenting with an error message.Strictly, the term alarm shouldinclude only red (immediateattention) and yellow (problem

condition), but it is also used torefer to green (a red or yellowmessage has been cleared) andwhite (information) conditions.Contrast with alert.

alert A message that is sent to a centralmonitoring station, as the result ofan alarm. Contrast with alarm.

alternate mark inversion (AMI)A T1 line coding scheme in whichbinary 1 bits are represented byalternate positive and negativepulses and binary 0 bits by spaces(no pulse). The purpose is to makethe average dc level on the lineequal to zero.

AMI See alternate mark inversion.

analogData in the form of continuouslyvariable signals, such as voice orlight signals.

analog display services interface (ADSI)A Bellcore signaling protocol that isused with existing voice networks.ADSI supports analog transmissionof voice and text-based informationbetween a host or switch, voice mailsystem, service bureau, or similar,and a subscriber's ADSI-compatiblescreen telephone. A singlevoice-grade telephony channel isshared between voice and data,using a technique by which thechannel is taken over for thetransmission of modem-encodeddata.

ANI See automatic number identification.

annotationIn speech recognition, analphanumeric string that is used tomark a grammar when it is defined.When the grammar is used in an


application, both the word and thealphanumeric string are returned tothe application.

announcement-only greetingIn voice mail, a greeting that doesnot give the caller a chance to leavea voice message.

applicationA (usually) customer-writtenprogram or set of programs thatmight consist of one or more statetables or custom servers that arerunning on WebSphere VoiceResponse, with associated voicesegments. See voice application.

application connectivity link (ACL)A service that transmits out-of-bandinformation between WebSphereVoice Response and the SiemensHicom 300 switch.

application profileData that describes initial actionsthat are to be performed when thetelephone is answered. Informationin an application profile indicates tothe channel process which statetable to load.

application server interface (ASI)The principal software componentof WebSphere Voice Response thatmanages the real-time channelprocessing.

application server platform (ASP)A platform that is used for Web andvoice applications for e-business.

ASI See application server interface.

ASP See application server platform.

audio nameThe audible name that relates to aspecific application profile ID andmailbox.

auto-attendantAutomated attendant. A voiceapplication that answers incomingcalls and asks callers which numberor other service they would like.

automatic call distributor (ACD)A telephone system feature thatautomatically queues and processesinbound calls according topredefined rules. For example, a callmight be routed to the agent whoseline has been idle longest.

automatic number identification (ANI)A service available in the U.S. thatprovides the telephone number ofthe calling party. It is generated bythe caller's originating central officeswitch, sent to a telephone networkcarrier if required, then sent directlyeither to a switch or to a voiceprocessing system.

autostubbingA state table icon view utility thatautomatically converts lines intostubs when they cross a specifiednumber of columns.

B

B8ZS Bipolar with 8-zero substitution. AT1 line code that is required for64Kb channels such as ISDN.

B-channelSee bearer channel. See also IntegratedServices Digital Network (ISDN) .

background musicAny audio data that is to be playedon a music channel.

barge-inThe capability that allows a promptto be interrupted by an utterance

Glossary 355

that is then passed to a speechrecognizer. See also cut-throughchannel.

baseformsThe set of phonetic pronunciationsthat are associated with a grammar.In WebSphere Voice Server, the IBMdictionary of pronunciations is used.

basic rate interface (BRI)The means of ISDN access that isnormally used by privatesubscribers. It provides twoB-channels of 64 Kb per second andone D-channel of 16 Kb per secondfor signaling. This is often known as2B+D. Contrast with primary rateinterface (PRI).

beans Java beans with which you canbuild voice applications to use theservices of WebSphere VoiceResponse on any platform.

bearer channelIn an ISDN interface, a duplexchannel for transmitting data ordigital voice between the terminaland the network. The B-channeloperates at 64 Kb per second.

bearer serviceThe type of service that defines howan ISDN connection will be used.Typical bearer services are speechtelephony, 64 Kb per second data,and high-quality speech.

blind transferA type of call transfer in which thecall is routed to another extensionand the original call is ended. Nocheck is made to determine whetherthe transferred call is answered or ifthe number is busy. Contrast withscreened transfer.

bnf Abbreviation for Backus-Naur Form,

which is used to describe the syntaxof a given language and its notation.In speech recognition, a specialadaptation of grammarrepresentation that is specified bySpeech 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 forTelecommunications

The British standards organizationthat is responsible for approval ofequipment that is to be attached tothe PSTN.

C

cadenceThe modulated and rhythmicrecurrence of an audio signal. Forexample, a series of beeps or aseries of rings.

call Telephone call. Often used to meana single run-time instance of a voiceapplication.

call centerA central point at which all inboundcalls are handled by a group ofindividuals in a controlledsequential way. Call centers areusually a front end to a businesssuch as airline ticketing or mailorder.

Call Control eXtensible Markup Language(CCXML)

Language designed to providetelephony call control support forVoiceXML or other dialog systems.


Refer to the CCXML forum web siteat http://www.w3.org/TR/ccxml

call forwardingThe process of sending incomingcalls to a different number.

called partyAny person, device, or system thatreceives a telephone call. Contrastwith caller.

caller (1) Any person, device, or systemthat makes a telephone call. (2)Often used to refer to any user of avoice application, althoughWebSphere Voice Response mighthave made an outbound call andthe user is really the called party. (3)In voice mail, any person whomakes a telephone call to asubscriber. Contrast with user.

calling line identification presentation(CLIP) An ISDN supplementary service

that advises the called party of thecaller's number; for example, bydisplaying it on a telephone displaypanel.

CallPathSoftware that provides basiccomputer-telephony integration(CTI) enablement andcomprehensive CTI functionality.This includes access to, andmanagement of, inbound andoutbound telecommunications.

call sessionThe sequence of events that occursfrom the time a call is started to thetime all activities related toanswering and processing the callare completed.

call transferA series of actions that directs a call

to another telephone number. Seealso dual-line call transfer.

CAS See channel associated signaling.

cascading resourcesResources that can be taken over bymore than one node. A takeoverpriority is assigned to eachconfigured cluster resource group ina per-node way. In the event of atakeover, the node with the highestpriority gets the resource group. Ifthat node is unavailable, the nodewith the next-highest priority getsthe resource group, and so on.

CAS toneCustomer Premise EquipmentAlerting Signal tone. In ADSI, thistone is sent to the ADSI telephoneto switch the phone to data mode.

CBX See computerized branch exchange.

CCH See Comité de Coordination del'Harmonisation.

CCITTSee Comité Consultatif InternationalTélégraphique et Téléphonique.

CCS See common channel signaling (CCS).

central office (CO)A telephone switching system thatresides in the telephone serviceprovider's network. Different typesof central office switches exist,depending upon the role of theswitch in the telephone network.Commonly, a central office switchconnects customer lines to othercustomer lines or trunks, and is thepoint at which local subscriber linesend for switching to other lines ortrunks.

central registryA component of the Licence Use

Glossary 357

Management network topology. Aserver's database that logs requestsfor licenses, upgrades for licenses,and journals all license activity in atamper-proof auditable file.

CEPT See Conference Européenne desAdministrations des Postes etTélécommunications.

CGI See Common Gateway Interface.

channelOne of the 24 channels that are on aT1 trunk, or one of the 30 channelsthat are on an E1 trunk. See alsospeech recognition session, musicchannel.

channel-associated signaling (CAS)A method of communicatingtelephony supervisory or linesignaling (on-hook and off-hook)and address signaling on T1 and E1digital links. The signalinginformation for each traffic (voice)channel is transmitted in a signalingchannel that is permanentlyassociated with the traffic channel.On T1 links, supervisory signalingis sent in the traffic channel byusing robbed-bit signaling (RBS). OnE1 links, a separate channel is usedto send signaling. Address signalingcan be transmitted either in thesignaling channel (out-of-band) orin the traffic channel (in-band).Contrast with common channelsignaling (CCS).

channel bankA device that converts an analogline signal to a digital trunk signal.

channel numberThe identifying number that isassigned to a licensed channel onthe T1 or E1 trunk that connects

WebSphere Voice Response to theswitch, channel bank, or channelservice unit.

channel process (CHP)The AIX process that runs the logicof the state table; each active callersession has one active channelprocess.

channel service unit (CSU)A device that is used to connect adigital phone line to a multiplexer, achannel bank, or directly to anotherdevice that generates a digitalsignal. A CSU performs specificline-conditioning and equalizationfunctions, and responds to loopbackcommands that are sent from theCO.

CHP See channel process.

CIC See circuit identification code.

CICS See customer information controlsystem.

circuit identification code (CIC)A 12-bit number that identifies atrunk and channel on which a call iscarried.

clear messageA message that is displayed byWebSphere Voice Response to tellthe operator that a red or yellowerror message has been cleared.

client nodeIn a single system image (SSI), aWebSphere Voice Response systemthat handles interactions withcallers. A client node must have atelephony connection. It does notstore application or voice data; itgets data from the server node ofthe SSI.


CLIP See calling line identificationpresentation.

clusterLoosely-coupled collection ofindependent systems (nodes) thatare organized into a network toshare resources and to communicatewith each other. HACMP definesrelationships among cooperatingsystems where peer cluster nodesprovide the services that a clusternode offers if that node cannot doso.

cluster configurationUser definition of all clustercomponents. Componentinformation is stored in the ObjectData Manager. Components includecluster name and ID, andinformation about member nodes,adapters, and network modules.

CO See central office.

codec Refers to adapters that compressand decompress video files. Theletters "codec" represent"compression/decompression"; inthe past, they represented"coder/decoder."

Comité de Coordination del'Harmonization

The CEPT committee responsible forstandards.

Comitato Elettrotechnico ItalianoThe Italian standards organizationresponsible for signaling protocols.

Comité Consultatif InternationalTélégraphique et Téléphonique (CCITT)

This organization has been renamedand is now known as theInternational TelecommunicationsUnion - TelecommunicationStandardization Sector (ITU-T).

common channel signaling (CCS)A method of communicatingtelephony information and linesignaling events (for example, callsetup and call clearing) on adedicated signaling channel. Thesignaling channel is either apredefined channel on an E1 or T1digital link, or a completely separatelink between the switch andWebSphere Voice Response. For dataintegrity and reliability, theinformation is usuallycommunicated using a data linkprotocol. The telephone informationand line signaling events are sent asdata packets. SS7 and ISDN arecommon-channel signalingprotocols. Contrast with channelassociated signaling.

Common Gateway Interface (CGI)An interface to programs thatprovide services on the world wideWeb.

compiled grammar fileA grammar in binary format thatwas built by the WebSphere VoiceServer grammar development tools.

compound licenseIn License Use Management, a typeof license that allows a systemadministrator to generate licensepasswords for a given number oflicenses. A compound license cangenerate either nodelocked ornon-nodelocked licenses, but notboth

computer-telephony integration (CTI)The use of a general-purposecomputer to issue commands to atelephone switch to transfer callsand provide other services.Typically, CTI is used in call centers.

Glossary 359

computerized branch exchange (CBX)A computer-driven, digitalcommunications controller thatprovides telephone communicationbetween internal stations andexternal networks.

Conférence Européenne desAdministrations des Postes etTélécommunications (CEPT)

European Conference of Postal andTelecommunicationsAdministrations.

configuration fileSee parameter file.

configuration parameterA variable that controls the behaviorof the system or the behavior of allapplications that are running on thesystem. See parameter file, systemparameter.

container windowA window that lists the names of allexisting objects of the same type.

contextA set of one or more grammars thatis enabled and used during arecognition action. The grammarsare specified by a FILELIST file.Parameters that influence therecognition, such as the maximuminitial silence period and the endingsilence period, are also defined bythe context. More than one contextcan be enabled for a recognition.

context nameThe name given to a context in acontext profile that is used forWebSphere Voice Server.

context profileDescribes to the WebSphere VoiceServer process which contextsshould be loaded into an engine. A

WebSphere Voice Response forWindows application specifieswhich context profiles to load intothe engine it has reserved.

context typeIndicates to the recognition enginehow to interpret the grammar file.Possible types are: VOCAB_FILE,GRAMMAR_FILE, TEXT,MNR_FILE, MNR,PERSONAL_FILE,PERSONAL_WDS,BASEFORM_FILE.

continuous speech recognitionRecognition of words that arespoken in a continuous stream.Unlike isolated or discrete wordrecognition, users do not have topause between words.

conversationSee 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 enablestransactions that are entered atremote workstations to be processedconcurrently by user-writtenapplication programs. It includesfacilities for building, using, andmaintaining databases.

custom serverA C language or C++ languageprogram that provides datamanipulation and local or remotedata stream, database, or otherservices that are additional to thosethat the state table interfaceprovides. Custom servers providean interface between WebSphere


Voice Response and businessapplications, functions, or otherprocesses to give callers access tobusiness information and voiceprocessing functions such as speechrecognition.

customer premises equipment (CPE)Telephony equipment that is on thepremises of a business or domesticcustomer of the telephone company.An example is a private branchexchange (PBX).

cut-through channelA channel of voice data that hasbeen passed throughecho-cancellation algorithms. Thechannel provides echo-canceledvoice data that can then be used bythe engine in a recognition attempt.This is similar to barge-in.

D

daemonIn the AIX operating system, aprogram that runs unattended toperform a standard service.

database server nodeIn a single system image (SSI), aWebSphere Voice Response systemthat contains the WebSphere VoiceResponse DB2® database. This isusually the same node as the voiceserver node.

DBIM The internal database manager ofWebSphere Voice Response.

DBS The database server of WebSphereVoice Response.

DCBU See D-channel backup.

D-channelSee delta channel.

D-channel backup (DCBU)An ISDN NFAS configuration wheretwo of the T1 facilities have aD-channel, one of which is used forsignaling, and the other as a backupif the other fails. See also non-facilityassociated signaling.

DDI See direct inward dialing.

DDS See production system.

delay startA procedure that is used with somechannel-associated signalingprotocols to indicate when a switchor PABX is ready to accept addresssignaling. After seizure, the switchsends off-hook until it is ready toaccept address signaling, at whichtime it sends on-hook. Contrast withimmediate start and wink start.

delta channelIn an ISDN interface, the D-channelor delta channel carries thesignaling between the terminal andthe network. In a basic rateinterface, the D-channel operates at16 Kb per second. In a primary rateinterface, the D-channel operates at64 Kb per second.

destination point code (DPC)A code that identifies the signalingpoint to which an MTP signal unitis to be sent. Unique in a particularnetwork.

development systemA WebSphere Voice Responsesystem that is not used to respondto, or make, “live” calls; it is usedonly to develop and testapplications. Contrast withproduction system.

dial To start a telephone call. Intelecommunication, this action is

Glossary 361

performed to make a connectionbetween a terminal and atelecommunication device over aswitched line.

dial by nameTo press the keys that are related tosubscribers' names instead of totheir telephone numbers orextensions.

dialed number identification service(DNIS)

A number that is supplied by thepublic telephone network to identifya logical called party. For example,two toll-free numbers might both betranslated to a single real number.The DNIS information distinguisheswhich of the two toll-free numberswas dialed.

dialog boxA secondary window that presentsinformation or requests data for aselected action.

dial toneAn audible signal (call progresstone) that indicates that a devicesuch as a PABX or central officeswitch is ready to accept addressinformation (DTMF or dial pulses).

DID See direct inward dialing.

digital signal processing (DSP)A set of algorithms and proceduresthat processes electronic signalsafter their conversion to digitalformat. Because of the specificmathematical models that arerequired to perform this processing,specialized processors are generallyused.

Digital Subscriber signaling SystemNumber 1 (DSS1)

A signaling protocol that is used

between ISDN subscriber equipmentand the network. It is carried on theISDN D-channel. ITU-Trecommendations Q.920 to Q.940describe this protocol.

Digital Trunk Ethernet Adapter (DTEA)A Radysis adapter card thatprovides the audio streaming (RTP)interface between the WebSphereVoice Response internal H.100 busand Ethernet for a maximum of 120channels using uncompressed(G.711) voice, and compressedG.723.2 and G.729A compressedvoice.

Digital Trunk No Adapter (DTNA)A device driver that supportsuncompressed (G.711) voice RTPstreaming.

Digital Trunk Telephony Adapter (DTTA)The IBM Quad Digital TrunkTelephony PCI Adapter. InWebSphere Voice Response, thisadapter is known as a DTTA. Itallows you to connect directly to thetelephony network from a pSeriescomputer without the need for anexternal pack.

Digital Trunk Telephony Adapter (DTTA)with Blind Swap Cassette (BSC)

The IBM Quad Digital TrunkTelephony PCI Adapter. InWebSphere Voice Response, thisadapter is known as a DTTA. Itallows you to connect directly to thetelephony network from a pSeriescomputer without the need for anexternal pack. This DTTA includes ashort Blind Swap Cassette (BSC)which is required for installing theDTTA in machines that use the BSC(for example, the pSeries 650–6M2).


diphoneA transitional phase from one soundto the next that is used as a buildingblock for speech synthesis. Typically,between one thousand and twothousand diphones exist in anynational language.

direct dial in (DDI)See direct inward dialing.

direct inward dialing (DID)A service that allows outside partiesto call directly to an extension of aPABX. Known in Europe as directdial in (DDI).

direct speech recognitionIdentification of words from spokeninput that are read directly from thetelephony channel. Contrast withindirect speech recognition.

DirectTalk beanOne of the beans that is providedwith WebSphere Voice Response. Itprovides access from a voiceapplication to simple call controlfunctions: waiting for a call, makingan outgoing call, handing a call overto another application, andreturning a call when finished.

discrete word recognitionIdentification of spoken words thatare separated by periods of silence,or input one at a time. Contrastwith continuous speech recognition.

disconnectTo hang up or terminate a call.

Distributed Voice Technologies (DVT)A component of WebSphere VoiceResponse that provides an interfaceto allow you to integrate your ownvoice technology (such as a speechrecognizer) with your WebSphereVoice Response system.

distribution listIn voice mail, a list of subscribers towhom the same message can besent.

DMS100(1) A Northern Telecom switch. (2)The custom ISDN protocol that isrun on the DMS100 switch,providing 23 B-channels and aD-channel over a T1 trunk.

DNIS See dialed number identificationservice.

double-trunkingSee trombone.

down The condition in which a device isunusable as a result of an internalfault 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 networkhost system.

DPC See destination point code.

drop-in grammarA set of precompiled grammar rulesthat can be used by anapplication-specific grammar toimprove the recognitionperformance.

DSP See digital signal processing.

DSPU See downstream physical unit.

DSS1 See Digital Subscriber signalingSystem Number 1.

DTMFSee dual-tone multifrequency.

DTEA See Digital Trunk Ethernet Adapter.

DTNASee Digital Trunk No Adapter.

Glossary 363

DTTA See Digital Trunk Telephony Adapter.

dtuser The name of the AIX account that isset up during the installationprocess for the use of all users ofWebSphere Voice Response.

dual-line call transferA call transfer method in which theprimary and secondary lines remainbridged until a call is completed.(Also known as tromboning: seetrombone).

dual-tone multifrequency (DTMF)The signals are sent when one of thetelephone keys is pressed. Eachsignal is composed of two differenttones.

DVT See Distributed Voice Technologies.

DVT bridgeThe interface between a voicetechnology component (such as aspeech recognizer) and the DVTserver. A bridge must exist for eachtechnology that you want tointegrate with DVT.

DVT_Client2A WebSphere Voice Responsecustom server that passescommands and data to DVT_Server.

DVT interfaceA WebSphere Voice Responseprogramming interface that is usedby a DVT bridge. It enablesintegration of voice applicationswith Distributed Voice Technologies toprovide functions such as speechrecognition.

DVT_ServerA component of DVT that allocatesand manages system resources inresponse to requests fromDVT_Client2.

DVT serviceThe combination of a voiceapplication, a DVT bridge, and avoice technology that allows a callerto interact with your business.

dynamic vocabularyA vocabulary that is defined whilean application is running.

E

E&M A channel-associated signalingprotocol in which signaling is doneusing two leads: an M-lead thattransmits battery or ground and anE-lead that receives open or ground.

E1 A digital trunking facility standardthat is used in Europe andelsewhere. It can transmit andreceive 30 digitized voice or datachannels. Two additional channelsare used for synchronization,framing, and signaling. Thetransmission rate is 2048 Kb persecond. Contrast with T1.

echo cancelationA filter algorithm that compares acopy of the voice data that is beingsent to a caller, with the voice databeing that is received from thecaller. Any echo of the sent data isremoved before the received data issent on, for example, to a speechrecognizer.

edge See result.

EDL See exchange data link.

emulationThe imitation of all or part of onecomputer system by another, so thatthe imitating system accepts thesame data, runs the same programs,and gets the same results as theimitated computer system does.


endpointIn Voice over Internet Protocol, a placewhere calls are originated andended.

engineA speech recognition process thataccepts voice data as input andreturns the text of what was said asoutput. It is the process thatperforms the recognition.

engine typeEach engine must be configuredwith a specific type. The type is atextual tag that is associated with aspecific engine and does not changethe operation or functionality of theengine.

error messageAny message that is displayed byWebSphere Voice Response in theSystem Monitor as an alarm andoptionally written to the WebSphereVoice Response error log, or to theAIX error log (as an alert). Strictly,the term error message shouldinclude only red (immediateattention) and yellow (problemsituation) messages, but it is alsoused to refer to green (a red oryellow message has been cleared)and white (informational) messages.

EthernetA 10/100 network connectionbetween the VoIP gateway and theSpeech Server that supports VoIP.

ETS European TelecommunicationsStandard or EuropeanTelecommunication Specification.

ETSI European TelecommunicationsStandards Institute.

Euro-ISDNThe common European ISDN

standard, agreed in 1993, thatprovides a basic range of servicesand supplementary services using30 B-channels plus a D-channel overan E1 trunk.

exchange data linkA serial connection that carriesmessaging information betweenWebSphere Voice Response and theLucent Technologies 1AESS,Northern Telecom DMS100, EricssonMD110 switch, or Siemens Hicom300.

exit A point in a supplied applicationfrom which control can be passed toanother custom-written application.On completion, the custom-writtenapplication passes control back tothe supplied application.

F

fade inTo gradually increase the volume ofsounds, such as background music.

fade outTo gradually decrease the volume ofsounds, such as background music.

failoverA transparent operation that, in theevent of a system failure, switchesresponsibility for managingresources to a redundant or standbysystem. Also known as fallover.

FDM See Feature Download Management.

Feature Download Management (FDM)An ADSI protocol that enablesseveral alternative key and screenoverlays to be stored in an ADSItelephone, and to be selected bypredetermined events at thetelephone.

Glossary 365

Federal Communication Commission(FCC) The standard body in the United

States that is responsible forcommunication.

field An identifiable area in a windowthat is used to enter or display data.

FILELISTA WebSphere Voice ServerTelephony runtime file that defineswhich files to load into a WebSphereVoice Server engine. It contains alist in the form:context type grammar filename

... ...

Recursion is not permitted; that is,no contexts of type FILELIST can bespecified in a FILELIST. When aFILELIST is loaded, all thegrammars that are specified in it areloaded into the engine. From thenon, the grammars that are loadedwhen the FILELIST is specified areregarded as a single context.

Foreign Exchange Subscriber (FXS)A signaling protocol that links auser's location to a remote exchangethat would not normally be servingthat user, to provide, for example,calls to outside the local area at thelocal rate.

frame A group of data bits that issurrounded by a beginningsequence and an ending sequence.

fsg Abbreviation for finite stategrammar. In WebSphere VoiceServer, the extension of a file thatcontains grammar specifications incompiled, binary form. It isgenerated from a .bnf file and iscalled a .fsg file.

functionIn ADSI, an ADSI instruction orgroup of instructions.

FXS See Foreign Exchange Subscriber.

G

gatekeeperA component of a Voice over InternetProtocol that provides services suchas admission to the network andaddress translation.

gatewayA component of Voice over InternetProtocolthat provides a bridgebetween VoIP and circuit-switchedenvironments.

G.711 Specification for uncompressedvoice for PSTN and Voice overInternet Protocol access.

G.723.1Compressed audio codecs that areused on Voice over Internet Protocolconnection for voice.

G.729ACompressed audio codecs that areused on Voice over Internet Protocolconnection for voice.

glare A condition that occurs when bothends of a telephone line or trunk areseized at the same time.

grammarA structured collection of words andphrases that are bound together byrules. A grammar defines the set ofall words, phrases, and sentencesthat might be spoken by a callerand are recognized by the engine. Agrammar differs from a vocabulary inthat it provides rules that governthe sequence in which words andphrases can be joined together.


greetingIn voice mail, the recording that isheard by a caller on reachingsubscriber's mailbox. See alsoannouncement-only greeting. Contrastwith voice message.

greeting headerIn voice mail, a recording that ismade by a subscriber and played tocallers either before or instead of apersonal greeting.

Groupe Special Mobile (GSM)A CEPT/CCH standard for mobiletelephony.

H

HACMP (High-Availability ClusterMulti-Processing) for AIX

Licensed Program Product (LPP)that provides custom software thatrecognizes changes in a cluster andcoordinates the use of AIX featuresto create a highly-availableenvironment for critical data andapplications.

HACMP/ESLicensed Program Product (LPP)that provides Enhanced Scalabilityto the HACMP for AIX LPP. AnHACMP/ES cluster can include upto 32 nodes.

hang upTo end a call. See also disconnect.

HDB3 High-density bipolar of order 3. AnE1 line coding method in whicheach block of four successive zerosis replaced by 000V or B00V, so thatthe number of B pulses betweenconsecutive V pulses is odd.Therefore, successive V pulses are ofalternate polarity so that no dccomponent is introduced. Note: Brepresents an inserted pulse that

observes the alternate mark inversion(AMI) rule and V represents an AMIviolation. HDB3 is similar to B8ZSthat is used with T1.

HDLC See high-level data link control.

high-level data link controlAn X.25 protocol.

homologationThe process of getting a telephonyproduct approved and certified by acountry's telecommunicationsauthority.

hook flashA signal that is sent to a switch torequest a switch feature (such as calltransfer).

host applicationAn application residing on the hostcomputer.

hunt groupA set of telephone lines from whicha non-busy line is found to handle,for example, an incoming call.

I

immediate startA procedure that is used with somechannel-associated signalingprotocols, when the addresssignaling is sent within 65milliseconds of going off-hook.Contrast with delay start and winkstart.

IN See intelligent network.

in-bandIn the telephony voice channel,signals are said to be carriedin-band. Contrast with out-of-band.

indirect speech recognitionIdentification of words from spoken

Glossary 367

input that are read from a file.Contrast with direct speechrecognition.

initializeTo prepare a system, device, orprogram for operation; for example,to initialize a diskette.

input parameterData that is received by a programsuch as a prompt, 3270 script,custom server, or state table fromthe program that called it. Contrastwith local variable and systemvariable.

integrated messagingA messaging system in which morethan one copy of a single message isstored, the copies being keptsynchronized by the applicationsthat are used to access them.Contrast with unified messaging.

Integrated Services Digital Network(ISDN)

A digital end-to-endtelecommunication network thatsupports multiple servicesincluding, but not limited to, voiceand data.

Integrated Services Digital Network(ISDN) call transfer

In WebSphere Voice Response, anapplication that allows you totransfer calls on Nortel DMS-100switches using Integrated ServicesDigital Network (ISDN) two B-channeltransfer, and on Nortel DMS-100 andDMS-250 switches using Nortel'sproprietary Release Link Trunk(RLT) call transfer protocol.

Integrated Services Digital Network(ISDN) two B-channel transfer

A call transfer feature that isdefined by Bellcore GR-2865-CORE

specification, and used on Norteland Lucent switches.

Integrated Services Digital Network userpart (ISUP)

Part of the SS7 protocol thatsupports telephony signalingapplications. The ISDN user part isdefined to carry signalinginformation that relates to digitaltelephones, terminals, and PABXs incustomer premises.

intelligent network (IN)A telephone network that includesprogrammable software that is notresident on the switch. It allows theservice provider to provide specialservices, such as specialcall-handling, that are notdependent on the capabilities of theswitch. See also advanced intelligentnetwork.

intelligent peripheral (IP)A voice processing system (such asWebSphere Voice Response) thatprovides enhanced services such asvoice response, speech recognition,text-to-speech, voice messaging, anddatabase access in an advancedintelligent network.

interactive voice response (IVR)A computer application thatcommunicates information andinteracts with the caller via thetelephone voice channel.

International Telecommunications Union –Telecommunication Standardization Sector(ITU-T)

The name of the organization thatwas previously known as theCCITT.

IP See intelligent peripheral.


ISDN See Integrated Services DigitalNetwork (ISDN) .

ISDN two B-channel transferSee Integrated Services DigitalNetwork (ISDN) two B-channeltransfer.

ISDN-UPSee Integrated Services DigitalNetwork user part.

ISUP See Integrated Services DigitalNetwork user part.

ITU-T See International TelecommunicationsUnion – TelecommunicationStandardization Sector.

IVR See interactive voice response.

J

Java BeanA reusable Java component. Seebeans.

jump outSee call transfer.

K

key (1) One of the pushbuttons on thetelephone handset; sometimesreferred to as a DTMF key. (2) Acomponent of the keyboard that isattached to the computer system.

key padThe part of the telephone thatcontains the pushbutton keys.

key pad mappingThe process of assigning specialalphanumeric characters to the keysthat are on a telephone key pad, sothat the telephone can be used as acomputer-terminal keyboard.

L

LAN See local area network.

language modelFor speech recognition, a set ofacoustic shapes (in binary format)for a given set of words, in whichword-to-word differences aremaximized, but speaker-to-speakerdifferences are minimized. See alsovocabulary.

LAPD See link access protocol for theD-channel.

licensed program product (LPP)A separately-priced program and itsassociated materials that bear anIBM copyright and are offeredunder the terms and conditions of alicensing agreement.

license serverA machine on a network that holdslicenses and distributes them onrequest to other machines on thenetwork.

line errorAn error on the telephone line thatcauses the signal to be impaired.

link access protocol for the D-channelAn HDLC protocol used in ISDNthat ensures a reliable connectionbetween the network and the user.Often used as another name forQ.921.

local area network (LAN)A network in which computers areconnected to one another in alimited geographical area.WebSphere Voice Responsecommunication with WebSphereVoice Server speech recognition,text-to-speech, and single systemimage (SSI) requires a LAN that isdedicated to that purpose (unless

Glossary 369

both are installed on the samesystem). A token-ring network is atype of LAN.

local variableA user-defined temporary variablethat can be accessed only by theprogram (state table, prompt, or3270 script) for which it is defined.Contrast with input parameter, systemvariable.

M

macro See system prompt.

MAP See mobile application part.

MB See megabyte.

megabyte(1) For processor storage and realand virtual memory, 1 048 576bytes. (2) For disk storage capacityand transmission rates, 1 000 000bytes.

Message CenterSee Unified Messaging

message delivery preferenceThe subscriber's choice of whethervoice mail is stored as voice mailonly, as e-mail only, or as both voicemail and e-mail.

message delivery typeThe format in which a voicemessage is delivered.

message signal unit (MSU)An MTP packet that contains data.

message transfer part (MTP)Part of the SS7 protocol that isnormally used to provide aconnectionless service that isroughly similar to levels onethrough three of the OSI referencemodel.

message waiting indicator (MWI)A visible or audible indication (suchas a light or a stutter tone) that avoice message is waiting to beretrieved.

MFR1 An in-band address signalingsystem that uses six tonefrequencies, two at a time. MFR1 isused principally in North Americaand is described in ITU-Trecommendations Q.310 throughQ.332.

MIME See multipurpose Internet mailextensions.

mobile application part (MAP)Optional layer 7 application for SS7that runs on top of TCAP for usewith mobile network applications.

MP See multiprocessor.

MSU See message signal unit.

MTP See message transfer part.

mu(µ)-lawThe companding algorithm that isused primarily in North Americaand Japan when converting fromanalog to digital speech data.(Compand is a contraction ofcompress and expand.) Contrastwith A-law.

multiprocessor (MP)A computer that includes two ormore processing units that canaccess a common main storage.

multipurpose Internet mail extensions(MIME)

A protocol that is used on Internetfor extending e-mail capability andmerging it with other forms ofcommunication, such as voice mailand fax.


mumbleNon speech noise that a userinterjects while speaking.

music channelA channel on which sounds can bebroadcast to one or more telephony(voice) channels.

music titleThe name by which WebSphereVoice Response knows a tune.

MWI See message waiting indicator.

N

National ISDNA common ISDN standard that wasdeveloped for use in the U.S.

NAU See network addressable unit.

N-BestThe ability to return more than onespeech recognition result. Typically,an array of results is available in theapplication in sequence ofdescending probability.

NCP See network control program.

NET Norme Européenne deTélécommunication.

Net 5 The test specification forconformance to the Euro-ISDNstandard for primary rate access toISDN.

network addressable unit (NAU)Any network component that can beaddressed separately by othermembers of the network.

network control program (NCP)Used for requests and responsesthat are exchanged between physicalunits in a network for data flowcontrol.

Network File System (NFS)A protocol, developed by SunMicrosystems, Incorporated, thatallows any host in a network togain access to another host ornetgroup and their file directories.In a single system image (SSI), NFSis used to attach the WebSphereVoice Response DB2 database.

network terminationSee NT mode.

NFAS See non-facility associated signaling.

NFS See Network File System.

node In a single system image (SSI), oneof the WebSphere Voice Responsesystems that are in the cluster.

non-facility associated signaling (NFAS)An ISDN configuration whereseveral T1 facilities can becontrolled by a single D-channel,instead of the normal T1configuration where each T1 facilityhas 23 B-channels and a D-channel(23B+D). With NFAS, all 24timeslots of the non signaling trunksare available for voice, whereas only23 channels can be used on thetrunk that carries signaling traffic(23B+D+n24B).

NT modeAttachment to the ISDN network isasymmetric. The network side of theconnection operates in networktermination, or NT, mode. Userequipment operates in terminalequipment, or TE, mode.

O

ODM See Object Data Manager.

Object Data Manager (ODM)A data manager intended for thestorage of system data. The ODM is

Glossary 371

used for many system managementfunctions. Information that is usedin many commands and SMITfunctions is stored and maintainedin the ODM as objects withassociated characteristics.

off-hookA telephone line state, usuallyinduced by lifting a receiver, inwhich the line is ready to make acall.

offlineNot attached or known to theexisting system configuration, andtherefore not in active operation.

on-hookA telephone line state, usuallyinduced by hanging up a receiver,in which the line is ready to receivea call.

online In active operation.

OPC See originating point code.

Open Systems Interconnection (OSI)(1.) The interconnection of opensystems as specified in particularISO standards. (2.) The use ofstandardized procedures to enablethe interconnection of dataprocessing systems.

Open Systems Interconnection (OSI)architecture

Network architecture that observesthe particular set of ISO standardsthat relate to Open SystemsInterconnection.

Open Systems Interconnection (OSI)Reference Model

A conceptual model composed ofseven layers, each specifyingparticular network functions.Developed by the InternationalOrganization for Standardization

(ISO) in 1984, it is considered to bethe primary architectural model forintercomputer communications

originating point code (OPC)A code that identifies the signalingPoint that originated an MTP signalunit. Unique in a particularnetwork.

OSI See Open Systems Interconnection.

outgoing mailIn voice mail, messages that are sentby a subscriber to anothersubscriber on the same system, andhave not yet been listened to by theaddressee.

out-of-bandIn the telephony signaling channel,as opposed to the voice channel.Signals are said to be carriedout-of-band. Contrast with in-band.

P

PABX See private automatic branch exchange.

pack Each DTTA contains the equivalentof four packs. The pack is a digitaltrunk processor built into the digitaltrunk adapter, so there is no needfor external hardware. See alsoTPACK.

parameter fileAn ASCII file that sets configurationparameters.

passwordA unique string of characters that isknown to a computer system and toa user. The user must specify thecharacter string to gain access to thesystem and to the information thatis stored in it.

PBX See private branch exchange.


PCI See peripheral component interconnect.

PCM See Pulse Code Modulation.

PCM fault conditionA fault, such as power supplyfailure, or loss of incoming signal, inT1 or E1 equipment. (ITU-T G.732and G.733.)

peripheral component interconnect (PCI)A computer busing architecture thatdefines electrical and physicalstandards for electronicinterconnection.

personal greetingIn voice mail, a greeting that isrecorded by a subscriber. Contrastwith system greeting.

phone recognitionCommunicating with a computerusing voice via a telephone, over atelephone line. The computerapplication recognizes what wassaid and takes suitable action.

port In time-slot management, one endof a 64 Kbps unidirectional streamthat can be attached to the TDMbus.

port setIn time-slot management, acollection of ports that can beconnected using a singleCA_TDM_Connect() API call to acomplementary collection of ports.

PRA Primary rate access (PRA). Used asanother name for primary rateinterface (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. Itprovides 30 (E1) or 23 (T1)B-channels of 64 Kb per second andone D-channel for signaling. This isoften known as 30B+D or 23B+D.Contrast with basic rate interface.

primary rate ISDN (PRI)See primary rate interface.

primitiveA message that is sent from oneprocess to another.

private automatic branch exchange (PABX)An automatic private switchingsystem that services an organizationand is usually located on acustomer's premises. Often used asanother name for private branchexchange (PBX) .

private branch exchange (PBX)A switch inside a private businessthat concentrates the number ofinside lines into a smaller numberof outside lines (trunks). Many PBXsalso provide advanced voice anddata communication features. Oftenused as another name for privateautomatic branch exchange .

process a callTo answer the telephone andperform the correct tasks.

Process ManagerIn WebSphere Voice Server, theprocess that manages the interactionof all telephony system processes;for example, starting and stoppingtext-to-speech or speech recognitionsessions.

production systemA WebSphere Voice Responsesystem that responds to or makes“live” calls. A production systemcan also be used to develop new

Glossary 373

applications. Contrast withdevelopment system.

program temporary fix (PTF)An update to IBM software.

program dataApplication-specific data that can beassociated with a call transfer fromCallPath to WebSphere VoiceResponse, or in the oppositedirection. This is equivalent toCallPath program data, butWebSphere Voice Response imposesthe restriction that the data must bea printable ASCII character string,with a maximum length of 512bytes.

prompt(1) A message that requests input orprovides information. Prompts areseen on the computer display screenand heard over the telephone. (2) InWebSphere Voice Response, aprogram that uses logic todetermine dynamically the voicesegments that are to be played as avoice prompt.

prompt directoryA list of all the prompts that areused in a particular voiceapplication. Used by the state tableto play the requested voice prompts.

pronunciationThe possible phoneticrepresentations of a word. A wordcan have multiple pronunciations;for example, “the” has at least twopronunciations, “thee” and “thuh”.

pronunciation dictionaryA file that contains the phoneticrepresentation of all of the words,phrases, and sentences for anapplication grammar.

pronunciation poolA WebSphere Voice Server resourcethat contains the set of allpronunciations.

protocolA set of semantic and syntactic rulesthat determines the behavior offunctional units when they getcommunication. Examples ofWebSphere Voice Responseprotocols are FXS, RE, and R2.

PSTN An ITU-T abbreviation for publicswitched telephone network.

PTF See program temporary fix.

Pulse Code Modulation (PCM)Variation of a digital signal torepresent information.

pushbutton(1) A key that is on a telephone keypad. (2) A component in a windowthat allows the user to start aspecific action.

pushbutton telephoneA type of telephone that haspushbuttons. It might or might notsend tone signals. If it does, eachnumber and symbol on the key padhas its own specific tone.

Q

Q.921 The ITU-T (formerly CCITT)recommendation that defines thelink layer of the DSS1 protocol.Q.921 defines an HDLC protocolthat ensures a reliable connectionbetween the network and the user.Often used as another name forLAPD.

Q.931 The ITU-T recommendation thatdefines the network layer of theDSS1 protocol. This layer carries the


ISDN messages that control themaking and clearing of calls.

quiesceTo shut down a channel, a trunkline, or the whole system afterallowing normal completion of anyactive operations. The shutdown isperformed channel-by-channel.Channels that are in an idle stateare shut down immediately.Channels that are processing callsare shut down at call completion.

R

RAI See remote alarm indication.

RBS See robbed-bit signaling.

RE See remote extension.

Recognition Engine serverIn WebSphere Voice Server, thesoftware that performs the speechrecognition and sends the results tothe client. This consists of one ‘Tsmrouter' and at least one ‘tsmp' andone ‘engine'.

reduced instruction set computer (RISC)A computer that uses a small,simplified set of frequently-usedinstructions to improve processingspeed.

referral numberThe phone number to which callsare routed, when call forwarding isactive.

rejectionThe identification of an utterance asone that is not allowed by agrammar.

release link trunk (RLT)A custom specification from Nortelfor ISDN call transfer.

remote alarm indication (RAI)A remote alarm (also referred to asa yellow alarm) indicates that thefar-end of a T1 connection has lostframe synchronization. The SendRAI system parameter can be set toprevent WebSphere Voice Responsefrom sending RAI.

remote extension (RE)An E1 signaling protocol that issimilar to FXS loop start.

resource elementA component of an IntelligentNetwork. The resource elementcontains specialized resources suchas speech recognizers ortext-to-speech converters.

responseIn speech recognition, the characterstring that is returned by therecognizer, through DVT_Client, tothe state table. The string representsthe result of a recognition attempt.This is the word or words that therecognizer considers to be the bestmatch with the speech input.

result An indicator of the success orfailure of a state table action. It isreturned by WebSphere VoiceResponse to the state table. Alsoknown as an edge.

result stateThe state that follows each of thepossible results of an action.

return codeA code that indicates the status ofan application action when itcompletes.

RISC See reduced instruction set computer.

RLT See release link trunk.

Glossary 375

robbed-bit signaling (RBS)The T1 channel -associated signalingscheme that uses the leastsignificant bit (bit 8) of eachinformation channel byte forsignaling every sixth frame. This isknown as 7-5/6-bit coding ratherthan 8-bit coding. The signaling bitin each channel is associated onlywith the channel in which it iscontained.

S

SAP See service access point.

SAS A T1 signaling protocol that issimilar to FXS.

SCbus See Signal Computing bus.

SCCP See signaling connection control part.

SCP See service control point.

screened transferA type of call transfer in which thetransfer of the held party to thethird party is completed only if thethird party answers the call.Contrast with blind transfer.

script The logical flow of actions for a3270 server program.

script languageA high-level, application-specificscripting language, which consistsof statements that are used todevelop 3270 scripts. These scriptsare part of the interface between astate table and a 3270-based hostbusiness application.

SCSA See Signal Computing SystemArchitecture.

SDC See Server Display Control.

SDLC See Synchronous Data Link Control.

segment ID numberOne or more numbers that are usedto identify a voice or promptsegment.

Server Display Control (SDC)An ADSI control mode in which theADSI telephone is controlledthrough a dialog with a voiceresponse system.

server nodeIn a single system image (SSI), aWebSphere Voice Response systemthat contains either the WebSphereVoice Response DB2 database, or thevoice data, or both.

service access point (SAP)An OSI term for the port throughwhich a service user (layer N+1)accesses the services of a serviceprovider (layer N).

service control point (SCP)A component of the intelligentnetwork that provides transactionalservices, such as translation oftoll-free numbers to subscribernumbers.

service information octet (SIO)A field that is in an MTP messagesignal unit. It identifies a higherlayer user of MTP, and whether themessage relates to a national orinternational network.

service nodeAn element of an IntelligentNetwork. The service node containsthe service logic that controls anintelligent network application andresources.

service providerAny company that provides servicesfor a fee to its customers, such astelecommunication companies,


application service providers,enterprise IT, and Internet serviceproviders.

service provider equipment (SPE)The switching equipment that isowned by the telephone company.

sessionSee speech recognition session.

Session Initiation ProtocolA signaling protocol used forinternet conferencing, telephony,presence, events notification andinstant messaging.

short message service center (SMSC)A component of the mobiletelephony network, specified by theGSM group of standards, thatprovides for exchange ofalphanumeric messages of less than160 bytes. Messages can beexchanged between different typesof 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 byDialogic to support interoperabilityof software and hardwarecomponents that are developed bydifferent vendors in the computertelephony industry.

Signal Computing bus (SCbus)A time division multiplexed (TDM)hardware bus that was originatedby Dialogic to interconnect differentvendors' computer telephonyadapters. Specified as part of SignalComputing System Architecture(SCSA).

signalingThe exchange of control informationbetween functional parts of thesystem in a telecommunicationsnetwork.

signaling connection control part (SCCP)A layer 3 protocol that observesOSI.

signaling information field (SIF)The user data portion of an MTPmessage signal unit.

signaling link code (SLC)A code that identifies a particularsignaling link that connects thedestination and originatingsignaling points. This is used inMTP signaling networkmanagement messages to indicatethe signaling link to which themessage relates.

signaling link selection (SLS)A field that is used to distributeMTP signal units across multiplesignaling links.

signaling modeThe type of signaling protocol,either channel-associated signaling,or common-channel signaling.

signaling pointA node in a signaling network thateither originates and receivessignaling messages, or transferssignaling messages from onesignaling link to another, or both.

signaling processA WebSphere Voice Responsecomponent that controls signalingfor an exchange data link orcommon-channel signaling protocol.Some signaling processes are

Glossary 377

supplied with WebSphere VoiceResponse, and others can becustom-written.

signaling System Number 7 (SS7)The international high-speedsignaling backbone used for thepublic-switched telephone network.

silenceA short pause between utterances.

simple mail transfer protocol (SMTP)An Ethernet protocol that is relatedto TCP/IP.

simple network management protocol(SNMP)

In the Internet suite of protocols, anetwork management protocol thatis used to monitor routers andattached networks. SNMP is anapplication layer protocol.Information on devices managed isdefined and stored in theapplication's ManagementInformation Base (MIB). SNMPprovides a means of monitoringWebSphere Voice Responseresources remotely.

Simplified Message Desk Interface(SMDI)

A Northern Telecom service thattransmits out-of-band informationbetween WebSphere Voice Responseand particular switches.

Simplified Message Service Interface(SMSI)

A Lucent Technologies service thattransmits out-of-band informationbetween WebSphere Voice Responseand particular switches.

single system image (SSI)A cluster of WebSphere VoiceResponse systems that areconnected together using a local area

network. Each system (known as anode) in the cluster is configured aseither a client or a server. A singlesystem image typically consists ofone server node and multiple clientnodes. The client nodes retrieveapplications and voice data from theserver. A second server can beconfigured for redundancy.

sink A port that takes voice data fromthe 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 ServiceInterface.

SMTP See simple mail transfer protocol.

SNA Systems Network Architecture.

SNMPSee simple network managementprotocol .

source A port that puts voice data on to theTDM bus. Contrast with sink.

SPACKA logical component that consists ofa base card, which connects to thedigital trunk adapter in the pSeriescomputer, and a trunk interface card(TIC), which manages the trunkconnection to the switch. Contrastwith VPACK and TPACK.

SPE See service provider equipment.


speaker-dependent speech recognitionIdentification of spoken words thatis related to knowledge of thespeech characteristics of onespeaker. Contrast withspeaker-independent speech recognition.

speaker-independent speech recognitionIdentification of spoken words thatis related to collected knowledge ofthe speech characteristics of apopulation of speakers. Contrastwith speaker-dependent speechrecognition.

special characterA character that is not alphabetic,numeric, or blank. For example, acomma (,) or an asterisk (*).

speech recognitionThe process of identifying spokenwords. See discrete word recognition,continuous speech recognition,speaker-dependent speech recognition,speaker-independent speech recognition.

Speech Recognition Control Language(SRCL)

In WebSphere Voice Server, astructured syntax and notation thatdefines speech grammars,annotations, repetitions, words,phrases, and associated rules.

speech recognition sessionIn WebSphere Voice Server, asequence of recognition commandsthat allocate a recognition engine,and return a unique identifier toidentify the engine.

speech synthesisThe creation of an approximation tohuman speech by a computer thatconcatenates basic speech partstogether. See also text-to-speech.

SRCL See Speech Recognition ControlLanguage (SRCL).

SS7 See signaling System Number 7.

SSI See single system image.

SSI-compliant custom serverA custom server that runs correctlyin a single system image. Thecustom server observes all theguidelines for the operation ofcustom servers in an SSIenvironment.

SSI-tolerant custom serverA custom server that runs in asingle system image, but with onlysome restrictions.

standalone systemA WebSphere Voice Responsesystem that is not part of a singlesystem image (SSI). A standalonesystem is not connected to otherWebSphere Voice Response systems,so it contains its own applicationand voice data.

state One step in the logical sequence ofactions that makes a WebSphereVoice Response voice application.

state tableA list of all the actions that are usedin a particular voice application. Acomponent of WebSphere VoiceResponse.

state table actionOne instruction in a set ofinstructions that is in a WebSphereVoice Response state table thatcontrols how WebSphere VoiceResponse processes variousoperations such as playing voiceprompts or recording voicemessages. See also state.

Glossary 379

stub A line in a state table that is onlypartially displayed.

subscriberIn voice mail, any person who ownsa mailbox.

subscriber classA named set of variables thatdefines a specific level of serviceavailable to telephone subscribers,such as maximum number ofmessages per mailbox andmaximum number of members permailbox distribution list.

subvocabularyA vocabulary that is called byanother vocabulary.

supplementary serviceIn Euro-ISDN, a service outside theminimum service offering that eachsignatory is obliged to provide. Forexample, calling line identificationpresentation (CLIP) and call session.

switch A generic term that describes atelecommunications system thatprovides connections betweentelephone lines and trunks.

symmetric multiprocessor (SMP)A system in whichfunctionally-identical multipleprocessors are used in parallel,providing simple and efficientload-balancing.

Synchronous Data Link Control (SDLC)A discipline for managingsynchronous, code-transparent,serial-by-bit information transferover a link connection. Transmissionexchanges can be duplex orhalf-duplex over switched ornonswitched links.

system administratorThe person who controls and

manages the WebSphere VoiceResponse system by adding users,assigning account numbers, andchanging authorizations.

system greetingIn voice mail, a default greeting thatis heard by callers to the mailboxesof subscribers who have notrecorded a personal greeting or whohave selected the system greeting.Contrast with personal greeting.

System Management Interface Tool(SMIT)

A set of utilities that can be used forvarious purposes, such as loadingWebSphere Voice Responsesoftware, installing the exchangedata link, and configuring SNA.

Systems Network Architecture (SNA)An architecture that describes thelogical structure, formats, protocols,and operational sequences fortransmitting information unitsthrough the networks and also theoperational sequences forcontrolling the configuration andoperation of networks.

system parameterA variable that controls some of thebehavior of WebSphere VoiceResponse or applications that arerunning under WebSphere VoiceResponse. System parameters are setthrough System Configuration orPack Configuration options on theConfiguration menu. Some systemparameter values are assigned tosystem variables when an applicationis initialized. Contrast with inputparameter, local variable, systemvariable.

system promptThe symbol that appears at the


command line of an operatingsystem, indicating that the operatingsystem is ready for the user to entera command.

system variableA permanent global variable that isdefined by WebSphere VoiceResponse for use by state tables.Many system variables are loadedwith values when the state table isinitialized. Some values are takenfrom system parameters. Contrastwith input parameter, local variable,system parameter.

T

T1 A digital trunking facility standardthat is used in the United States andelsewhere. It can transmit andreceive 24 digitized voice or datachannels. Signaling can beimbedded in the voice channeltransmission when robbed-bitsignaling is used. The transmissionrate is 1544 kilobits per second.Contrast with E1.

T1/D3 A framing format that is used in T1transmission.

T1/D4 A framing format that is used in T1transmission.

tag A text string that is attached to anyinstance of a word in a grammar. Atag can be used (1) to distinguishtwo occurrences of the same wordin a grammar or (2) to identify morethan one word in a grammar ashaving the same meaning.

Tag Image File Format-Fax (TIFF-F)A graphic file format that is used tostore and exchange scanned faximages.

TCAP See transaction capabilities applicationpart.

TCP/IPSee Transmission ControlProtocol/Internet Protocol.

TDD See Telecommunications Device for theDeaf.

TDM See time-division multiplex bus.

technologyA program, external to WebSphereVoice Response, that providesprocessing for functions such astext-to-speech or speech recognition.

Telecommunications Device for the Deaf(TDD) A telephony device that has a

QWERTY keyboard and a smalldisplay and, optionally, a printer.

telephone input fieldA field type that containsinformation that is entered by acaller who is using pushbuttonsignals. See also field.

terminal(1) A point in a system orcommunication network at whichdata can enter or leave. (2) In datacommunication, a device, usuallyequipped with a keyboard anddisplay device, that can send andreceive information.

termination characterA character that defines the end of atelephone data entry.

text-to-speech (TTS)The process by which ASCII textdata is converted into synthesizedspeech. See also speech synthesis.

TIC See trunk interface card.

time-division multiplex bus (TDM)A method of transmitting many

Glossary 381

channels of data over a smallernumber of physical connections bymultiplexing the data into timeslots,and demultiplexing at the receivingend. In this document, one suchchannel can be considered to be ahalf-duplex unidirectional stream of64 Kb per second.

TIFF-FSee Tag Image File Format-Fax

timeslotThe smallest switchable data unit ona data bus. It consists of eightconsecutive bits of data. Onetimeslot is similar to a data pathwith a bandwidth of 64 Kb persecond.

token A particular message or bit patternthat indicates permission ortemporary control to transmit.

token-ring networkA local area network that connectsdevices in a ring topology andallows unidirectional datatransmission between devices by atoken-passing procedure. A devicemust receive a token before it cantransmit data.

tone An audible signal that is sent acrossa telephone network. Single(one-frequency) tones, tritones (threesequential tones at differentfrequencies), dual tones (twosimultaneous tones at differentfrequencies), and dual sequentialtones exist. Each has a differentmeaning.

TPACKA digital trunk processor that isimplemented using DSP technologyon the digital trunk adapter withoutthe need for external hardware. One

DTTA digital trunk adapterprovides up to four TPACKs on aPCI card.

transactionA specific, related set of tasks in anapplication that retrieve informationfrom a file or database. Forexample, a request for the accountbalance or the available credit limit.

transaction capabilities application part(TCAP)

Part of the SS7 protocol thatprovides transactions in thesignaling network. A typical use ofTCAP is to verify a card number, forthe credit card calling service.

transaction messagingThe ability to associate an item ofdata, such as a transaction identifier,with a voice message. The voicemessage can later be retrieved byreferencing the data value.

transferSee call transfer.

Transmission Control Protocol/InternetProtocol (TCP/IP)

A communication subsystem that isused to create local area and widearea networks.

tromboneA connected voice path that entersan IVR from a switch on one circuit,then returns to the same switch on aparallel circuit. Two IVR ports andtwo circuits are consumed, but insome circumstances this might bethe only way to make a connectionbetween two callers if the attachedswitch does not support a CallTransfer function. Also known asdouble-trunking.

trunk A telephone connection between


two central offices or switchingdevices. In WebSphere VoiceResponse, a trunk refers to 24 or 30channels that are carried on thesame T1 or E1 digital interface.

trunk interface card (TIC)The component of the pack thatmanages the trunk connection to theswitch.

Tsm RouterIn WebSphere Voice Server, aprocess that controls which engineprocesses are in use at any time.Requests for an engine by aWebSphere Voice Server Client areaccepted or rejected depending onwhether an engine that meets theTsm Client's requirements isavailable.

tsmp In WebSphere Voice Server, aprocess that is running on theRecognition engine server machinethat passes messages between anengine and a Tsm Client. One tsmpexists for every engine.

TTS See text-to-speech.

tune A piece of music or other audiodata that is intended to be played asbackground music.

U

underrunTo run out of audio data to play,causing voice or music to beaudibly broken up or cut off.

unified messagingA messaging system in which asingle copy of a message is storedand accessed by multipleapplications (for example, voicemail and e-mail). Contrast withintegrated messaging.

Unified MessagingAn IBM product that usesWebSphere Voice Response's voiceprocessing capabilities to provide awide range of voice mail, fax, ande-mail functions. Previously knownas Message Center.

user Someone who uses WebSphereVoice Response as a systemadministrator, application developer,or similar. Contrast with caller.

utteranceA spoken word, phrase, or sentencethat can be preceded and followedby silence.

V

variableA system or user-defined elementthat contains data values that areused by WebSphere Voice Responsevoice applications. See inputparameter, local variable, systemparameter, system variable.

VMS See Voice Message Service.

vocabularyA list of words with whichWebSphere Voice Response matchesinput that is spoken by a caller. Seealso language model.

voice applicationA WebSphere Voice Responseapplication that answers or makescalls, plays recorded voice segmentsto callers, and responds to thecaller's input.

voice directoryA list of voice segments that isidentified by a group ID. Voicedirectories can be referenced byprompts and state tables. Contrastwith voice table.

Glossary 383

voice mailThe capability to record, play back,distribute, and route voicemessages.

voice mailboxThe notional hard disk space wherethe incoming messages for a voicemail subscriber are stored.

voice messageIn voice mail, a recording that ismade by a caller for later retrievalby a subscriber.

Voice Message Service (VMS)An Ericsson service that transmitsinformation between WebSphereVoice Response and particularswitches.

voice messagingThe capability to record, play back,distribute, route, and manage voicerecordings of telephone callsthrough the use of a processor,without the intervention of agentsother than the callers and those whoreceive messages.

voice modelA file that contains parameters thatdescribe the sounds of the languagethat are to be recognized on behalfof an application. In WebSphereVoice Server, this is a bnf file. Seealso grammar.

Voice over Internet Protocol (VoIP)The sending of telephony voice overInternet Protocol (IP) dataconnections instead of over existingdedicated voice networks, switchingand transmission equipment. Seealso gatekeeper and gateway.

voice port libraryA library that manages a socketconnection from the client to the

voice technology. The library usesentry points that are provided byDVT.

Voice Protocol for Internet Messaging(VPIM)

The standard for digital exchange ofvoice messages between differentvoice mail systems, as defined inInternet Request For Comments(RFC) 1911.

voice response unit (VRU)A telephony device that usesprerecorded voice responses toprovide information in response toDTMF or voice input from atelephone caller.

voice segmentThe spoken words or sounds thatmake recorded voice prompts. Eachsegment in an application isidentified by a group ID and asegment ID and usually includestext.

voice server nodeIn a single system image (SSI), aserver node that contains the voicedata. This is usually the same nodeas the database server node.

voice tableA grouping of voice segments that isused for organizational purposes.Voice tables can be referenced byprompts, but not by state tables.Contrast with voice directory.

voice technologySee technology.

VoiceXMLVoiceXtensible Markup Language.An XML-based markup languagefor creating distributed voiceapplications. Refer to the VoiceXMLforum web site at www.voicexml.org


VoIP See Voice over Internet Protocol.

VPACKA component consisting of a basecard, which connects to the digitaltrunk adapter in the pSeriescomputer, and a trunk interface card(TIC), which manages the trunkconnection to the switch. The singledigital trunk processor contains oneVPACK, and the multiple digitaltrunk processor contains slots for upto five VPACKs. Contrast withSPACK and TPACK.

VPIM See Voice Protocol for InternetMessaging.

VRU See voice response unit.

W

World Wide Web Consortium (W3C)An organization that developsinteroperable technologies(specifications, guidelines, software,and tools) to lead the Web to its fullpotential. W3C is a forum forinformation, commerce,communication, and collectiveunderstanding. Refer to the web siteat http://www.w3.org

WebSphere Voice ResponseA voice processing system, thatcombines telephone and datacommunications networks to use,directly from a telephone,information that is stored indatabases.

wink startA procedure that is used with somechannel-associated signalingprotocols to indicate when a switchor PABX is ready to accept addresssignaling. After seizure, the switchsends a short off-hook signal (wink)when it is ready to accept address

information. Contrast with delaystart and immediate start.

word spottingIn speech recognition, the ability torecognize a single word in a streamof words.

wrap In ADSI, the concatenation of twocolumns of display data to form asingle column.

Y

yellow alarmSee remote alarm indication.

Z

zero code suppression (ZCS)A coding method that is used withalternate mark inversion to preventsending eight successive zeros. Ifeight successive zeros occur, thesecond-least significant bit (bit 7,with the bits labeled 1 through 8from the most significant to the leastsignificant) is changed from a 0 to a1. AMI with ZCS does not supportclear channel operation.

Glossary 385

List of WebSphere Voice Response and associateddocumentation

Here is a list of the documentation for WebSphere Voice Response for AIX andassociated products. PDF and HTML versions of the documentation areavailable from the IBM Publications Center at http://www.ibm.com/shop/publications/order. Hardcopy books, where available, can be ordered throughyour IBM representative or at this Web site.

WebSphere Voice Response for AIX documentation can also be found by goingto the IBM Pervasive software Web site at http://www.ibm.com/software/pervasive, selecting the WebSphere Voice products link, and then selectingthe library link from the WebSphere Voice Response page.

PDF and HTML versions of the WebSphere Voice Response for AIXpublications are available on the CD-ROM supplied with the product. Inaddition, WebSphere Voice Response for AIX, WebSphere Voice Response forWindows, Unified Messaging, and other WebSphere Voice publications areavailable together in PDF and HTML formats on a separately-orderableCD-ROM (order number SK2T-1787).

Note: To read PDF versions of books you need to have the Adobe AcrobatReader (it can also be installed as a plug-in to a Web browser). It is availablefrom Adobe Systems at http://www.adobe.com .

WebSphere Voice Response software

v WebSphere Voice Response for AIX: General Information and Planning,GC34-7084

v WebSphere Voice Response for AIX: Installation, GC34-7095v WebSphere Voice Response for AIX: User Interface Guide, SC34-7091v WebSphere Voice Response for AIX: Configuring the System, SC34-7078v WebSphere Voice Response for AIX: Managing and Monitoring the System,

SC34-7085v WebSphere Voice Response for AIX: Designing and Managing State Table

Applications, SC34-7081v WebSphere Voice Response for AIX: Application Development using State Tables,

SC34-7076v WebSphere Voice Response for AIX: Developing Java applications, GC34-7082v WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and Java

Applications, GC34-7080


v WebSphere Voice Response for AIX: Custom Servers, SC34-7079v WebSphere Voice Response for AIX: 3270 Servers, SC34-7075v WebSphere Voice Response for AIX: Problem Determination, GC34-7087v WebSphere Voice Response for AIX: Fax using Brooktrout , GC34-7083v WebSphere Voice Response for AIX: Cisco ICM Interface User's Guide, SC34-7077v WebSphere Voice Response for AIX: MRCP for State Tables, SC34-7086v WebSphere Voice Response for AIX: Programming for the ADSI Feature,

SC34-7088v WebSphere Voice Response for AIX: Programming for the Signaling Interface,

SC34-7089v WebSphere Voice Response for AIX: Voice over IP using Session Initiation

Protocol, GC34-7093v WebSphere Voice Response for AIX: Using the CCXML Browser, SC34-7092v WebSphere Voice Response for AIX: VoiceXML Programmer's Guide, SC34-7117

IBM hardware for use with WebSphere Voice Response

v IBM Quad Digital Trunk Telephony PCI Adapter (DTTA): Installation and User'sGuide, part number 00P3119 (DTTA card)

WebSphere Voice Response related products

WebSphere Voice Server

The documentation for Version 5.1 of WebSphere Voice Server is provided inthe 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 Responsev Unified Messaging: General Information and Planning, GC34-6398v Unified Messaging: Subscriber's Guide (Types 0, 1, 2, 3, 4 and 9), SC34-6403v Unified Messaging: Subscriber's Guide (Types 5, 6, 7 and 8), SC34-6400v Unified Messaging: Administrator's Guide, SC34-6399v Unified Messaging: Voice Interface, GC34-6401v Unified Messaging: Web Services Voicemail API, SC34-6975

Unified Messaging publications can be found by going to the IBM Pervasivesoftware Web site at http://www.ibm.com/software/pervasive, selecting theproducts link, and then selecting the library link from the Unified Messagingpage.


http://publib.boulder.ibm.com/pvc/wvs/51/en/infocenter/index.html

AIX and the IBM pSeries computer

For information on AIX Version 6.1, refer to the AIX V6.1 infocenter

For information on System p5 and BladeCenter computers, refer to the IBMPower hardware infocenter

HACMPv HACMP for AIX: HACMP 5.4 Concepts and Facilities, SC23-4864-09v HACMP for AIX: HACMP 5.4 Planning Guide, SC23-4861-09v HACMP for AIX: HACMP 5.4 Installation Guide, SC23-5209-00v HACMP for AIX: HACMP 5.4 Administration Guide, SC23-4862-09v HACMP for AIX: HACMP 5.4 Smart Assist for DB2, SC23-5179-03v HACMP for AIX: HACMP 5.4 Troubleshooting, SC23-5177-03v HACMP for AIX: Enhanced Scalability Installation and Administration Guide,

Volume 1, SC23-4284v HACMP for AIX: Enhanced Scalability Installation and Administration Guide,

Volume 2, SC23-4306

For more information on HACMP, refer to the HACMP Library and the AIXV6.1 infocenter.

SS7v SS7 Support for WebSphere Voice Response: SS7 User's Guide, GC34-7090

IBM SS7 Support for WebSphere Voice Response observes the applicable partsof the following specifications for ISUP:v CCITT Blue book (1988) Q.701 - Q.707v ITU-T (formerly CCITT) Recommendations Q.700 - Q.716, Volume VI Fascicle

VI.7v CCITT Blue book (1988) Q.711 - Q.714v ITU-T White book (1993) Q.711 - Q.714v CCITT Blue book (1988) Q.721 - Q.724v ITU-T (formerly CCITT) Recommendations Q.721 - Q.725, Volume VI Fascicle

VI.8v ITU-T White book (1992) Q.730 groupv CCITT Blue book (1988) Q.761 - Q.764v ITU-T White book (1992) Q.761 - Q.764v CCITT Blue book (1988) Q.771 - Q.775v ITU-T (formerly CCITT) Recommendations Q.771 - Q.775, Q.791, Volume VI

Fascicle VI.9

ADC

v ADC NewNet AccessMANAGER™: Installation and MaintenanceManual

List of WebSphere Voice Response and associated documentation 389

http://publib.boulder.ibm.com/infocenter/systems/scope/aix/index.jsp

http://www-03.ibm.com/systems/power/hardware/

http://www-03.ibm.com/systems/power/hardware/

http://publib.boulder.ibm.com/infocenter/clresctr/vxrx/index.jsp?topic=/com.ibm.cluster.hacmp.doc/hacmpbooks.html



v ADC NewNet AccessMANAGER™: User Manual

Integrated Services Digital Network

WebSphere Voice Response ISDN support observes the applicable parts of thefollowing standards for User Side protocol:

Custom ISDN Standards:

v Northern Telecom DMS/250 Primary Rate Interface NIS A211-4 Release8, July 1995. (IEC05 level)

v Northern Telecom DMS/100 Primary Rate Interface NIS A211-1 Release7.05, May 1998. (NA007 & RLT)

v AT&T 5ESS Switch. ISDN Primary Rate Interface Specification. 5E7 and5E8 Software Release AT&T 235-900-332. Issue 2.00 December 1991

v AT&T 5ESS Switch. ISDN Primary Rate Interface Specification. 5E9Software Release AT&T 235-900-342. Issue 1.00 November 1993(National ISDN only)

v Lucent 5ESS-2000 Switch ISDN Primary Rate Interface, InterfaceSpecification, 5E9(2) and Later Software Releases, 235-900-342. Issue5.00 January 1997 (National ISDN only)

v AT&T ISDN Primary Rate Specification TR41449 July 1989v AT&T ISDN Primary Rate Specification TR41459 August 1996

Euro-ISDN

The following documents refer to the specifications required forobserving ISDN:v TBR4-ISDN; Attachment Requirements For Terminal Equipment To

Connect To An ISDN Using ISDN Primary Rate Access, Edition 1, Nov.95, English

v CTR 4 - European Communities Commission Decision 94/796/ECpublished in the Official Journal of the European Communities L329, 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

Bellcorev National ISDN-1, SR-NWT-001937, Issue 1, February 1991, published

by Bellcorev 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 TelephoneCorporation

v Interface for the INS Net Service Volume 3 (Layer 3 Circuit Switching),5th Edition, published by Nippon Telegraph and TelephoneCorporation

Bellcore Specifications for ADSI Telephones

The following Bellcore specification documents contain technical details of therequirements for ADSI telephones, and the interface to voice response systemssuch 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 PremisesEquipment Data Interface for Analog Display Services

List of WebSphere Voice Response and associated documentation 391

Index

Numerics3270 field

name limitation 3343270 host application

interfacing with 3270 server 863270 screen

definitions used by 3270 application 86name limitation 334

3270 servername limitation 334overview 86purpose 86requirements 26sample (3270ServerSample) 130sample application 129

3270 server scriptname limitation 334purpose 86

3270ServerSample.imp 129, 130

Aaccess mode

mailbox 173accessibility xvAlphabet voice table 83annotating messages 156AnswerCall 136application

See ISDN_Call_Transfer application 230See SSTransfer application 260

Application - Profile ID system variable 138application folder

opening and closing 31application object

advantages of creating an application for 29definition 28deleting 55displaying 30editing and testing 33exporting 44importing 46managing 27migrating from previous release 50moving 54

application prerequisitepurpose 37when to export 53

application profilecreate, how to 90

application profile (continued)create, using command line 94creating 89greetings 150ID limitation 333mailbox identification 167name limitation 333purpose 89selecting according to call identification 140subscriber classes 169voice application

See also application profile 89voice mailbox 149wvrapplprof 94

application profile IDspecifying 92

Application window 31Applications window 30archiving application objects 13audio name

description 150recording 157

Ayavaswitch converse feature 134, 140

Bbackground music

adding to a state table 202controlling the volume 198debugging your state table 205defining a tune 202defining a tune in the configuration file 201fading 203getting music into WebSphere Voice Response 206Juke_Box custom server 200overview of a state table 205playing multiple tunes 196silence 204sound levels 341state table, prerequisites 202supplied tunes 206T1 A-law systems 198the Music Available window 206tune 195use by multiple applications 196uses of 197with speech recognition 198with voice interrupt detection 198writing your own background music

subsystem 348


backup copyvoice application 38

barge-in 121base applications 101blind (immediate) transfer 233blind transfer 142, 262bvi_aiff command 111bvi_wav command 111

Ccalibration of echo cancellation 124call

answering 136incoming

writing your own state table to answer 139Incoming_Call

purpose 136call info status

system variable 139call progress tones

handling in a voice application 133call transfer 142, 143call-answer supervision on screened transfer 233called number

specifying in an application profile 92system variable 138

Caller - Profile ID system variable 139caller variables

mailbox owner status 168Calling Number system variable 139CallPath Server 133, 147CallPath_SigProc 144changing

message attributes 156system voice tables 116

channelidentifying 140incoming

answering 140invoking an application based on 140load-balancing 141

channel identificationnumber 140specifying in an application profile 93

checking voice messages 154child helper processes,

IBM_Trombone_Custom_Server 278commands

dtexport 56dtimport 59wvrapplprof 94, 177wvrmailbox 177

common objects 53compressed voice format 106

compressed voice format (continued)developing

creating prompt directories 113specifying for prompt directory 113

compression of voice segments 105configuration file for Juke_Box custom server 200configurations

VOX_CTI.ini file 322configuring IBM_Trombone_Custom_Server 277constant

used in State Table Parameters 73consultation with third party using trombone 274controlling disk space used for messages 168coordinated call and data transfer 144creating

application profiles 89distribution lists 188multilingual applications 117prompt directories 113prompts 113subscriber classes 185

creating an application 34Currency system prompt 77, 82current language variable 118custom server

accessing data on other systems 87argument limitation 333capabilities 87initiated explicitly 87Juke_Box 200name limitation 333overview 87purpose 86requirements 26sample application 128speech recognition 126text-to-speech 126waiting to be called 87

custom server functionsISDN_Call_Transfer 245SSTransfer 263

custom server subroutines, TDD 193customizing the Juke_Box custom sever 344CustomServerSample.imp 128

Ddata

returning to a state table 73date of last update

application object 31Date system prompt 76, 81Day_Of_Month voice table 84Day_Of_Week voice table 84Default application

moving objects from 54


Default application (continued)purpose 32, 52

default promptoverview 114

definingmailboxes 170prompts 113subscriber classes 170

deletingapplication object 55voice application 55voice messages 156

delta export 13definition 38purpose 52

dependencyapplication object, purpose 36

descriptionlimitations in 333

designing voice applications 15dialog design 19

considerations 19lo-fi prototyping 18

dialog design, user participation 18dialog style

choosing 20digit name

application profile, specifying 91disk space

controlling use by messages 168distributed voice technologies (DVT) 121distributing

updates to applications 13voice applications 27

distribution listcreating 188maximum entries in 187maximum number of entries 187maximum number per mailbox 186

Divisor voice table 84dtexport command 56dtimport command 59duplicate objects 53

Eecho cancellation 123

calibration 124with speech recognition 124

editing system prompts 117Enter Key system parameter 119entry point

specifying in an application profile 91state table 74

error messagesIBM_Trombone_Custom_Server 320

EuroISDN SST call transferbefore you install 260components 259configuring the custom server 261custom server 259how to use 262Incoming_call state table 269installing 259, 260ISDN Signaling Process 258limitations 259ssct_tag state table 270ssct_transfer state table 269

export commandSee dtexport 56

export fileformat 39purpose 38

export report 43exporting

application object 44voice application 38

Fformat of export file 39forwarding messages 155frequently asked questions 51full export

definition 38purpose 52

Ggeneral guidelines

VOX_CTI custom server 330GetUserStatus

ISDN_Call_Transfer custom server function 246TransferTag custom server function 267

global user variables 71greetings

active number 173, 181ID limitation 333

Hhangup detection 134host application (3270)

interfacing with 3270 server 86host data 87housekeeping 13

IIBM solutions 5IBM_Trombone application 274

components 275example state tables 296helper state tables 297how it works 281IBMTromboneC10 state table 306

Index 395

IBM_Trombone application (continued)IBMTromboneC5 state table 305IBMTromboneCall state table 297IBMTromboneConn state table 304IBMTromboneDisc state table 307IBMTromboneLog state table 308IBMTromboneMake state table 309IBMTromboneMus state table 312IBMTromboneOut state table 312IBMTromboneRdy state table 314IBMTromboneWait state table 316IBMTromboneXmB state table 319IBMTromboneXmp state table 318IBMTromboneXmpA state table 318implementation state tables 297import file 275installing 275, 276prerequisites 276running the application 277setting up a trombone operation 281simulating call transfer 274starting the custom server 277state table definitions 296terminating a trombone operation (caller

DTMF) 284terminating a trombone operation (caller

hang-up) 283terminating a trombone operation (third party

hang-up) 283using 280voice paths 285

IBM_Trombone_Custom_Server 273child helper processes 278command line parameters 277configuring 277custom server functions 286error messages 320setting configuration options 279starting 277TromboneCall function 286TromboneConnectCall function 293TromboneDisconnectCall function 295TromboneMakeCall function 289TromboneMakeCallStatus function 292TromboneTerminationValue function 295

IBMTromboneC10 state table 306IBMTromboneC5 state table 305IBMTromboneCall state table 297IBMTromboneConn state table 304IBMTromboneDisc state table 307IBMTromboneLog state table 308IBMTromboneMake state table 309IBMTromboneMus state table 312IBMTromboneOut state table 312IBMTromboneRdy state table 314

IBMTromboneWait state table 316IBMTromboneXmp state table 318IBMTromboneXmpaA state table 318IBMTromboneXmpB state table 319identifying

channels 140incoming calls 140

import commandSee dtimport 59

import report 48importing

application objects 46voice application 46

incoming callidentifying 140

incoming messagesstatus 153

Incoming_call state table 269Incoming_Call state table

customizing 139input parameter

name limitation 333Installation

VOX_CTI custom server 321installing IBM_Trombone application 276interrupting a prompt with speech 25introduction 3ISDN call transfer 225

before you install 229components 228configuring the custom server 231custom server 229helper state tables 249how to use 233installing 228, 230ISDN Signaling Process 227ISDN_Imm_Xfer state table 249ISDN_SupA_Xfer state table 251ISDN_Xfer_C10 state table 253ISDN_Xfer_C5 state table 253ISDN_Xfer_Log state table 256ISDN_Xfer_Stat state table 257limitations 228outbound state tables 249running the application 230, 261screened transfer (with call answer

supervision) 235screened transfer (with third party

consultation 239state table definitions 248, 249, 269state table ISDN_Xfer_Data 254state table ssct 271

ISDN RLT call transferNortel DMS-100 226Nortel DMS-250 226


ISDN single step call transfer custom server 263ISDN two B-channel transfer

Nortel DMS-100 226ISDN_Call_Transfer application 230ISDN_Call_Transfer custom server

configuration options 232definitions 245, 263

GetUserStatus and SetUserData 245MakeCallStatus 245

functions 245messages 245restarting 232

ISDN_Imm_Xfer state table 249ISDN_SupA_Xfer state table 251ISDN_Xfer_C10 state table 253ISDN_Xfer_C5 state table 253ISDN_Xfer_Data state table 254ISDN_Xfer_Log state table 256ISDN_Xfer_Stat state table 257ISDNSignaling Process, ISDN call transfer 227ISDNSignaling Process, single step call transfer 258

JJuke_Box custom server 200

configuration file 200customizing 344format, configuration file 201starting and stopping 200tracing 206

KKey Signals parameter group 119kry input 119

multiple keys 119single key 119

Llanguage

current, system variable 118specifying in an application profile 92

language-specific promptoverview 114

limitingmessage length 169number of messages 169

load-balancing across channels 141local variable 72

name limitation 333

Mmailbox

application profile 149graphical interface, using the 170

mailbox, voiceaccess mode 173accessing messaging information 150

mailbox, voice (continued)active greeting number 173, 181announce and take messages 173application profile requirement 89creating 167, 170ID limitation 334information in system variables 168maximum number assigned to guests 186maximum number of distribution lists 186maximum number of mailboxes 186options 172password 173, 182password limitation 334prompt level system variable 174referral number 176referral type 176retrieval order 173sample application 158use information 167

MakeCallStatusISDN_Call_Transfer custom server function 247Transfer custom server function 267

matrix switching 209message

annotating 156announce and take messages 173changing attributes 156checking 154controlling 168deleting 156forwarding 155leaving and retrieving 153limiting length of 169limiting number of 169mailboxes required for 167maximum length 187maximum number accepted by mailbox 186playing 155recording 153retrieval order 173sample application 157saving 156sending 154status of incoming and outgoing 153status variable 153system parameters 157

message numberusing to retrieve messages 155

Message Waiting Indicator 147migrating voice application 50modifying system voice tables 116Month_Of_Year voice table 84moving application objects 54multilingual applications

creating 117

Index 397

music catalog 200music player

building 346Musical_Welcome state table 195

Nname

application profile, specifying 91name limitations

description length limitation 333Noise voice table 84Nortel DMS-100

ISDN RLT call transfer 226ISDN two B-channel transfer 226release level 226

Nortel DMS-250ISDN RLT call transfer 226release level 226

numberreferral 176

Numbers voice table 84

Oobject

See application object 28Object Index

purpose 45one-call fax 209Ordinal prompt 76Ordinal voice table 85outgoing messages

status 153

Pparameter

description 70passing between state tables 72used by state table actions 70

parametersstate table action 73

partial exportdefinition 38purpose 52

passwordapplication profile 173, 177, 182mailbox 173, 177, 182

Password Minimum Length parameter 173, 182phone number

referral 176Phone prompt 77Phone system prompt 77playing voice messages 155PlayPrompt

force played 120interruptible 120

program data 144

progress tones, callhandling in a voice application 133

promptcreating 113defining 113interrupting with speech 25level heard by callers 174overview 74TDD 192wording 24

prompt directorycreating 113description 75name limitation 334

prompt statementsdescription 74

putting applications into production 38

RReal_number system prompt 76Record Voice Maximum parameter 169Record_Uncomp voice application 106RecordAudionameSample application 157RecordAudionameSample.imp 157recording

audio names 157data for background music 109voice messages 153voice segments over the telephone 106

referral number 176Release Link Trunk (RLT)

See also ISDN RLT call transfer 225remote data 87removing

application object 55voice application 55

reportexport 43import 48

retrieval ordermessage 173

retrievingmessages, using message number 155messages, using transaction ID 155

returning data to a state table 73RLT (Release Link Trunk)

See ISDN RLT call transfer 225

Ssample application

3270ServerSample.imp 129CustomServerSample.imp 128RecordAudionameSample 157RecordAudionameSample.imp 157VoiceMessagingSample 157


sample application (continued)VoiceMessagingSample.imp 158

saving voice messages 156screened transfer 142

with call_answer supervision 233with third party consultation 233

script for distributing applications 56script language

3270 server 86sending

voice messages 154setting up a trombone application 281SetUserData

ISDN_Call_Transfer custom server function 248sharing objects 53shell script for distributing applications 56signaling protocols

limitations 133silence

dBm value for background music 204Simple_record application 106simulating call transfer using trombone 274single system image

application design considerations 223configuration, querying 223

Small_number system prompt 75, 81speech recognition

barge-in 121echo cancellation 124error handling 25introduction 121limitations 25prompt wording 24voice interrupt detection 123while a prompt is playing 25

SR-INS-002461 Bellcore specification 391ssct state table 271ssct_tag state table 270ssct_transfer state table 269SSTransfer application 261SSTransfer custom server

configuration options 262definitions

Transfer 263TransferTag 263

functions 263messages 263restarting 262

statedescription 61resulting from actions 73

state label name limitation 334state table

background music, adding 202design worksheet example 68

state table (continued)Musical_Welcome state table 195name limitation 334overview 61parameters 70returning data to 73specifying in an application profile 91variables 70

state table actionsdescription 61resulting states 73system parameters affecting 143used to interact with servers 127voice messaging 151

State Table Name for Incoming Calls parameter 140status

message, system variable 153subscriber class

creating 185introduction 169specifying in an application profile 92use in applications 169

subscriber classesspecifying in an application profile 92

switchAyava converse feature 134, 140

switch toneshandling in a voice application 133

System application 32System Default Application Profile parameter

specifying in an application profile 93system parameters

dial actions 143ring actions 143voice messages 157

system promptsCurrency 77, 82Date 76, 81description 75editing 117in Brazilian Portuguese 80in French 78languages other than U.S. English 77, 115Ordinal 76Ordinal, date prompt 81Ordinal, number prompt 80Phone 80Real_number 76, 80Small_number 75, 81Small_number, number prompt 80Time 77, 81translating 115using translated 117Whole_number 76Whole_number, date prompt 81

Index 399

system prompts (continued)Whole_number, number prompt 80

system variables 170current language 118description 70subscriber class limits 170

system voice segments 83system voice tables

list of 83modifying 116overview 83

System_Msgs voice table 85System/370 application

interfacing with 3270 server 86System/390 application

interfacing with 3270 server 86

TTDD

See Telecommunications Device for the Deaf(TDD) 191

TDMapplication development 217ASCII state tables 217cleaning connections 218concepts 209

port sets 209ports 209resource groups 210

connection token 218custom server main()function 218custom servers 213

subroutines 214data structures 217designing an application 213echo susceptibility 221error handling 217multiprocess custom server, moving to 219notifying hang-ups 219port set naming 211sample application 211

implementation 217prerequisites 212

sample application, design 214See time-division multiplex (TDM) 209state tables 213TromboneCS state machine 217voice paths 220

technical difficulties message 138Telecommunications Device for the Deaf (TDD)

control codes 194custom server subroutines 193prompts 192restrictions 193uncompressed format 193

Telecommunications Device for the Deaf (TDD)(continued)

valid characters 194voice applications 191voice segments 192

terminating a trombone operationcaller DTMF 284caller hang-up 283third party hang-up 283

third party consultation on screened transfer 233Time system prompt 77, 81Time_Of_Day voice table 85Time_Of_Week voice table 85time-division multiplex (TDM)

TDM connection management 209time-division multiplex (TDM) bus 209Tone voice table 85tones, call progress

handling in a voice application 133TR-NWT-001273 Bellcore specification 391transaction ID 155, 334

length limitation 334using to retrieve messages 155

transfer typesblind 262blind (immediate) 233screened (with call_answer supervision) 233screened (with third party consultation) 233

transferring a call 142transferring voice data 109

analog tape 110digital audio tape (DAT) 110diskette 110from the studio 109storage device 110

translatingsystem prompts 115

tromboneSee also IBM_Trombone application 273what is it? 273

trombone connection 209TromboneCall custom server function 286TromboneConnectCall custom server function 293TromboneCS custom server 215TromboneDisconnectCall custom server function 295TromboneIn state table 214TromboneMakeCall custom server function 289TromboneMakeCallStatus custom server function 292TromboneMonitor state table 214TromboneOut state table 214TromboneTerminationValue custom server

function 295tune

supplied with WebSphere Voice Response 206used in background music 195


Uuncompressed voice format 106

specifying for prompt directory 113updating system voice tables 116User application

introduction 32moving objects from 54purpose 52, 90

user function, custom servername limitation 333

user variables, global 71using command line 94using the IBM_Trombone application 280

Vvariable

description 70global 71local 72system 70

voice applicationarchiving 13components 3creating 34creating an application profile for 89deleting 55design hints 23designing 15dialog design 19dialog design, user participation 18dialog style 20exporting 38finding 30housekeeping 13importing 46including messaging in 149invoking servers from 61, 127migrating from previous release 50opening 31RecordAudionameSample 157selecting to answer incoming calls 140subscriber class limits 169TDD 191VoiceMessagingSample 158

voice dataAIFF (Macintosh audio interchange file format 111converting 110non-AIX systems 110raw (unformatted) data 110WAV (Microsoft Windows format) 111

voice directory name limitation 335voice interrupt detection 122

interrupting prompts 25technical information 337with speech recognition 123

voice messagingaccessing mailbox information 150audio name 150distribution list 150greeting 150including functions in an application 149managing resources 167state table actions 151voice mailbox 149

voice paths 285voice prompts

creating 113voice segment

batch import 112compression 105compression type 113database 112description 82dynamic range 107filters 107high-quality voice data 106ID limitation 334limiting length of 169planning 103recording over the telephone 106recording with a microphone 107sampling rate 106saving 111source format 106system 83TDD 192transferring data 109using a recording studio 108window 112

voice signal processingoverview 101

voice tablefor system voice segments 83, 116name limitation 335used by the system prompts 116

VoiceMessagingSample application 157VoiceMessagingSample.imp 158VOX connector

Avaya 321Quintus 321

VOX_CTI custom serverAvaya Interaction Center VOX connector 321configuration 322functions 323

Alarm 324Getvdu 324Getvox 325Gone 326Newcall 326Ping 327

Index 401

VOX_CTI custom server (continued)functions (continued)

Pseudo_Ani 327Setvdu 327Tr 328Transfer 329

general guidelines 330how to use 321Installation 321

VOX_CTI funtionreturn codes 329

VOX_CTI.ini fileconfiguration 322

WWebSphere Voice Response

business requirements 4data requirements 5external code repository 10implementation 8maintenance and support 13migrating application objects 10Packaging and distribution 11programming requirements 5requirements and planning 4supplied tunes 206system design 6telephony requirements 4user requirements 4

Welcome state tablecustomizing 139Incoming_Call

customizing 139purpose 139Welcome

customizing 139purpose 139

Whole_number system prompt 76worksheets

state table design example 68wvrapplprof 94, 177

action flags 94attribute flags 95examples 96purpose 94syntax 94

wvrmailbox 177action flags 178attribute flags 178examples 178field names 179prerequisites 177purpose 177syntax 178


��

Product Number: 5724-I07

SC34-7081-02

designing and managing state table applications...websphere voice response software . . . 387 ibm...

Documents