Designing and Managing State Table Applications

Transcription

1 WebSphere Voice Response for AIX with DirectTalk Technology Designing and Managing State Table Applications Version 6.1 SC

2 Note Before using this information and the product it supports, read the general information under Notices on page 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 new editions. Make sure you are using the correct edition for the level of the product. Copyright IBM Corporation 1991, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents Figures ix Tables xi About this information xiii Who should use this information..... xiii How to use this information xiii Following the procedures in this book... xiv Typographic conventions xiv Accessibility xv Notes on terminology xv Where to find more information..... xvi Useful Web sites xvi Making comments on this book..... xvi Part 1. The life cycle of a voice response service Chapter 1. Introduction Requirements and Planning Business requirements Telephony requirements User requirements Data requirements Programming requirements IBM solutions Suggestions Design High-level and low-level design Design considerations Suggestions Implementation What does implementation involve?... 9 System parameters Testing the voice response service Migrating application objects Using an external code repository Suggestions Packaging and distribution Distributing an application to other WebSphere Voice Response systems Suggestions Maintenance and support Housekeeping Archiving application objects Distributing updates Suggestions Chapter 2. Designing a voice application 15 User participation in dialog design Designing the dialog Good things to do in voice applications Wording prompts for speech recognition applications Defining server requirements Chapter 3. Creating and managing application objects What are application objects? Managing application objects efficiently Using the applications and application windows Discovering what applications and objects are in the system Editing and testing application objects Creating an application Exporting an application Exporting one or more objects Importing application objects Migrating from an earlier release of IBM WebSphere Voice Response for AIX Frequently asked questions Do you have to create applications? What about the integrity of applications that are already in use? Where are newly-created or migrated objects put? What happens when you import objects belonging to an application that does not exist on the target system? When should you use full export, delta export, and partial export? When should you export prerequisites along with an application? What happens to duplicate objects?.. 53 What if more than one application needs to use the same object? Moving objects from the default or user applications Copyright IBM Corp. 1991, 2012 iii

4 Deleting an application The dtimport and dtexport commands dtexport command dtimport command Chapter 4. Overview of application objects 61 State tables State table actions Example state table State table variables and parameters Returning data to the state table Possible results Entry points Prompts System prompts System prompts in languages other than U.S. English System prompts in French System prompts in Brazilian Portuguese 80 Changing the system prompts for your language Voice segments Voice directories Voice tables System voice segments System voice tables and custom servers servers Custom servers Further information Chapter 5. Creating an application profile 89 Introduction How to create an application profile Using the command line wvrapplprof command Part 2. Design topics Chapter 6. Creating the voice output for voice applications Overview of voice signal processing Planning your voice segments Compression Recording voice segments over the telephone High-quality voice data Transferring the prerecorded data to WebSphere Voice Response Converting voice data transferred from non-aix computer systems Saving voice segments The batch voice import utilities or the Voice Segments window? The voice segment database Creating prompts About creating prompt directories About defining prompts Default and language-specific prompts 114 Using languages other than U.S. English 115 Modifying the system voice tables Editing the system prompts Creating multilingual applications Using application profiles Using the System: Current language system variable Chapter 7. Handling key input from callers Making a selection (single key) Entering data (multiple keys) Pressing keys while voice data is being played Chapter 8. Handling spoken input from callers Speech recognition with distributed voice technologies Barge-in, voice interrupt detection, and echo cancellation Barge-in Voice interrupt detection Echo cancellation Writing a custom server to handle speech recognition Chapter 9. Accessing data with a 3270 or custom server Sample 3270 and custom servers CustomServerSample ServerSample Chapter 10. Telephony activity Handling switch and protocol limitations 133 Handling switch tones Accounting for protocol limitations Answering calls How does WebSphere Voice Response answer an incoming call? iv Designing and Managing State Table Applications

5 Making, transferring, reconnecting, and terminating calls Call transfer State table actions System parameters Coordinated call and data transfer What does the state table have to do? What format must the data be in? How much data can you pass? Examples Setting the MessageWaiting Indicator using CallPath Server Chapter 11. Designing voice messaging applications Voice messaging resources Using state table actions for voice messaging 151 Interacting with callers and messages System parameters that affect voice messaging A sample voice message application Chapter 12. Managing voice messaging resources Voice mailboxes How do I create a mailbox? How is mailbox information used? Controlling messages Limiting message length Limiting the number of messages What are subscriber classes? How do subscriber classes work? When should you define subscriber classes? Creating mailboxes for application use Before you start Using the graphical interface Using the wvrapplprof and wvrmailbox commands wvrmailbox command Creating a subscriber class Creating a distribution list Chapter 13. Telecommunications Devices for the Deaf Making voice applications available to TDD users Chapter 14. Background music Why use background music? How many tunes can you play at once? When should you play background music? 197 How loud is the background music? T1 A-law systems Voice interrupt detection and speech recognition Using the WebSphere Voice Response Juke Box The Juke_Box custom server Starting and stopping the Juke_Box custom server The Juke Box configuration file Adding background music to a state table 202 Prerequisites Debugging your state table Getting music into WebSphere Voice Response Supplied tunes Chapter 15. TDM connection management 209 Concepts Ports Port sets Resource groups Port set naming The TDM sample application Prerequisites Designing an application State tables Custom servers The design of the sample application Implementation notes Chapter 16. Designing for a single system image Querying the single system image configuration Chapter 17. Using ISDN call transfer When can I use ISDN Two B-channel transfer? When can I use ISDN RLT call transfer? When can I use ISDN single step call transfer? What the ISDN call transfer application does 227 Limitations of ISDN call transfer Installing the application Configuring the ISDN_Call_Transfer custom server How to use ISDN call transfer Contents v

6 Custom server functions State table definitions What the ISDN single step call transfer application does Limitations of ISDN single step call transfer Installing the application Configuring the SSTransfer custom server 261 How to use ISDN single step call transfer 262 Custom server functions State table definitions Chapter 18. Using the IBM_Trombone_Custom_Server What is a trombone (in telephony terms)? 273 What you can use a trombone for Installing the IBM_Trombone application Components of the IBM_Trombone application Installing the IBM_Trombone application 276 Configuring IBM_Trombone_Custom_Server 277 About child helper processes Setting configuration options How to use the trombone operation How tromboning works Setting up a trombone operation Terminating a trombone operation using third party hang-up Terminating a trombone operation using caller hang-up Terminating a trombone operation using caller DTMF Voice paths Custom server functions Custom server function definitions TromboneCall TromboneMakeCall TromboneMakeCallStatus TromboneConnectCall TromboneTerminationValue TromboneDisconnectCall State table definitions IBMTromboneCall IBMTromboneConn IBMTromboneC IBMTromboneC IBMTromboneDisc IBMTromboneLog IBMTromboneMake IBMTromboneMus IBMTromboneOut IBMTromboneRdy IBMTromboneWait IBMTromboneXmp IBMTromboneXmpA IBMTromboneXmpB IBM_Trombone_Custom_Server errors Chapter 19. Using the VOX_CTI Custom Server Avaya Interaction Center VOX Connector for WebSphere Voice Response Installation VOX_CTI.ini file configuration VOX_CTI Custom Server functions VOX_CTI function return codes General guidelines Part 3. Appendixes Appendix A. ID and name limitations Appendix B. Voice interrupt detection: technical information Example of how voice interrupt detection works Summary Appendix C. Background music: technical information Sound levels The music volume ceiling and the prompt volume ceiling Customizing the Juke Box Source code files for the Juke Box Collecting statistics from the Juke_Box custom server Building music players Juke_Box custom server communication with pl_elem and pl_seg Message queue Writing your own background music subsystem Notices Trademarks Glossary vi Designing and Managing State Table Applications

7 List of WebSphere Voice Response and associated documentation WebSphere Voice Response software IBM hardware for use with WebSphere Voice Response WebSphere Voice Response related products 388 WebSphere Voice Server Unified Messaging for WebSphere Voice Response AIX and the IBM pseries computer HACMP SS Integrated Services Digital Network Bellcore Specifications for ADSI Telephones 391 Index Contents vii

8 viii Designing and Managing State Table Applications

9 Figures 1. The life cycle of a voice response service 3 2. Example of main activities to be performed by a voice application Voice application objects The Application window Two applications, one of which contains commonly-used objects System variables A list of parameters to be passed to a prompt Barge-in Voice interrupt detection Voice interrupt detection with speech recognition Calibrating the echo canceller External speech recognition overview Accessing data using custom servers and 3270 servers (for example, a system/390 server) How WebSphere Voice Response finds the state table to handle an incoming call Application profile needed with one state table for all Application profiles needed when using called number Application profiles needed when using channel identification CallPath Server and WebSphere Voice Response installed in the same pseries computer Receiving a call and data transferred by CallPath Server Transferring a call and data to another number using CallPath Server Using CallPath Server to set the message waiting indication VoiceMsgMenu and VoiceMsgAnswer VoiceMsgRecord and VoiceMsgListen VoiceMsgOptions Example listing of the first two states in a state table Two people communicating using TDD How WebSphere Voice Response interacts with a TDD Using background music What the caller hears at each stage in the interaction Example of a configuration file for the Juke_Box custom server Schematic overview of part of a state table using background music Getting tunes into WebSphere Voice Response for background music Ports, port sets, sources, and sinks Making and breaking a trombone connection The TromboneCS state machine Voice paths in a trombone connection Voice paths when the switch is in TDM position Voice paths when the switch is in host position Event flow for a blind (immediate) transfer Event flow for a screened transfer with call answer supervision (for a successful call) Event flow for a screened transfer with call answer supervision (for an unsuccessful call) Event flow for a screened transfer with third party consultation (ending in a transfer) Event flow for a screened transfer with third party consultation (ending up reconnecting to the original caller) Voice path between caller and third party during a trombone operation High-level flow chart for the IBMTromboneXmp state table Event flow required to set up a trombone operation Event flow required to terminate a trombone operation when the third party hangs up Event flow required to terminate a trombone operation when the caller hangs up Copyright IBM Corp. 1991, 2012 ix

10 49. Event flow required to terminate a trombone operation when the caller requests this by dialing a DTMF sequence WebSphere Voice Response detects a voice interrupt How voice interrupt detection parameters act on a voice sample Musical welcome state table: volume levels Playing prompts and tunes at the same volume x Designing and Managing State Table Applications

11 Tables 1. Example dialog segments Where To find newly-created objects Example state table Creating voice segments for WebSphere Voice Response Responses for spot frequencies Application profile examples Mailbox field names used with wvrmailbox command Applications simultaneously playing tunes from music channels Configuration options for the ISDN_Call_Transfer custom server Configuration options for the SSTransfer custom server ISDN single step call transfer return codes Configuration options for IBM_Trombone_Custom_Server Return values for the trombone_make_call_status parameter of the TromboneCall function Return values for the trombone_make_call_status parameter of the TromboneMakeCall function Status values supplied by the TromboneMakeCallStatus function Return values for the trombone_make_call_status parameter of the TromboneMakeCall function Return values for the trombone_make_call_status parameter of the TromboneMakeCall function Return values from the IBMTromboneCall state table (call_status) System variables and parameters for voice interrupt detection System variables and parameters used for background music Music volume and prompt volume ceilings Copyright IBM Corp. 1991, 2012 xi

12 xii Designing and Managing State Table Applications

13 About this information This information tells you how to design voice applications to suit your requirements for voice response services, and then provides guidance for implementing them with IBM WebSphere Voice Response for AIX with DirectTalk Technology. This book also tells you how to put applications into production on one or more WebSphere Voice Response systems, and keep your applications running smoothly. Throughout this book, IBM WebSphere Voice Response for AIX is referred to as WebSphere Voice Response. Who should use this information This book is for anyone involved in designing, implementing, or managing a voice response service with WebSphere Voice Response. Knowledge of how the voice response service fits into your business would be valuable for all readers. Before starting to read this book, you should be familiar with the first few chapters of the WebSphere Voice Response for AIX: General Information and Planning book. How to use this information If you are commissioning a voice response service, you will find guidance on how to specify and plan for it in Chapter 1, Introduction, on page 3 and Chapter 2, Designing a voice application, on page 15. If you are implementing an application, you should read this book to get background information, before using the reference and procedural information in the WebSphere Voice Response for AIX: Application Development using State Tables book, the WebSphere Voice Response for AIX: Custom Servers book, or the WebSphere Voice Response for AIX: 3270 Servers book. This book provides specific guidance about implementing various types of application and including different voice processing functions in your applications, whereas the procedural information in the other book is more generic. The background information in this book is organized by function, whereas the reference information in the other information is organized alphabetically. Copyright IBM Corp. 1991, 2012 xiii

14 If you are responsible for managing voice response services running in production, use the information in Chapter 3, Creating and managing application objects, on page 27, Chapter 5, Creating an application profile, on page 89, and Chapter 12, Managing voice messaging resources, on page 167, as necessary. This book contains background information and some procedural information, with step-by-step instructions. The procedures explain how to complete the tasks using the WebSphere Voice Response windows. Following the procedures in this book The procedures assume that you are already familiar with using a mouse and window environment and that you know how to use the common actions such as Save to work with information. If you are new to WebSphere Voice Response, have a look at the WebSphere Voice Response for AIX: User Interface Guide book, which tells you how to log on and log off, and use the WebSphere Voice Response windows efficiently. Typographic conventions This book uses the following typographic conventions: boldface Identifies an item that is in a WebSphere Voice Response window. The item might be a keyword, an action, a field label, or a pushbutton. Whenever one of the steps in a procedure includes a word in boldface, look in the window for an item that is labeled with that word. boldface italics Are used for emphasis. Take extra care wherever you see bold italics. italics Identify one of the following: v New terms that describe WebSphere Voice Response components or concepts. A term that is printed in italics is usually followed by its definition. v Parameters for which you supply the actual names or values. v References to other books. monospace Identifies one of the following: v Text that you type in an AIX window. Because AIX is case sensitive, ensure that you type the uppercase and lowercase characters exactly as shown. v Names of files and directories (path names). xiv Designing and Managing State Table Applications

15 Accessibility WebSphere Voice Response for AIX is a voice application enabler. The applications that are developed to run on WebSphere Voice Response provide telephone access to business data and services. In this way, WebSphere Voice Response provides accessibility for people who cannot access the data and services by using regular Web pages or traditional graphic interfaces. These telephone user interfaces are fully accessible to people who are blind or have low vision and, if speech recognition is used, to people with mobility impairments or limited hand use. Speech recognition capability can be provided by IBM WebSphere Voice Server, or other MRCP-V1.0-compliant speech recognition products. In addition, support for users of Telephony Devices for the Deaf (TDD) is provided as part of the WebSphere Voice Response product. With WebSphere Voice Response you can perform many application development and system administration tasks with a text editor or line commands these are accessible if you use a screen reader product to interface with them. Also, the default settings of the WebSphere Voice Response graphical user interface can be changed to produce large fonts and high contrast colors. Details of how to use these accessibility features can be found in the WebSphere Voice Response for AIX: User Interface Guide book. Alternatively, application development can be done with Java or VoiceXML development tools that are supplied by IBM and third parties. You can also use a screen-reader product to access the WebSphere Voice Response publications in HTML format (for details of their availability see List of WebSphere Voice Response and associated documentation on page 387). Notes on terminology v A glossary of commonly-used terms is at the end of this book. v The full product name of WebSphere Voice Response for AIX with DirectTalk Technology is generally abbreviated in this book to WebSphere Voice Response. v The term pseries is generically used in this book to refer both to PCI-based RS/6000 computers and to appropriate models of the System p5 and pseries ranges. (Consult your IBM representative for details of models that are supported for use with WebSphere Voice Response.) RS/6000 computers with an MCA bus are not supported. v The IBM Quad Digital Trunk Telephony PCI Adapter is generally referred to in this book by its abbreviation DTTA. This adapter is a replacement for the IBM ARTIC960RxD Quad Digital Trunk PCI Adapter, which is generally referred to by the abbreviation DTXA. The DTXA is not supported with WebSphere Voice Response Version 6.1. About this information xv

16 v References made to the VoiceXML 2.1 specification are intended to include VoiceXML 2.0 unless otherwise specified. Where to find more information The information provided in the WebSphere Voice Response library will help you complete WebSphere Voice Response tasks more quickly. A complete list of the available publications and where you can obtain them is shown in List of WebSphere Voice Response and associated documentation on page 387. Useful Web sites The following Web sites are useful sources of information about WebSphere Voice Response and related products: WebSphere Voice Response IBM WebSphere developerworks resources (including WebSphere Voice products) VoiceXML Version 2.0 and 2.1 specifications CCXML Version 1.0 specification Genesys For more information on Genesys products go to the Genesys Web site at Making comments on this book If you especially like or dislike anything about this book, feel free to send us your comments. You can comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book. Please limit your comments to the information that is in this book and to the way in which the information is presented. Speak to your IBM representative if you have suggestions about the product itself. When you send us comments, you grant to IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. xvi Designing and Managing State Table Applications

17 You can get your comments to us quickly by sending an to 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

18 xviii Designing and Managing State Table Applications

19 Part 1. The life cycle of a voice response service Copyright IBM Corp. 1991,

20 2 Designing and Managing State Table Applications

21 Chapter 1. Introduction This chapter begins with an overview of the process of providing a voice response service by means of a WebSphere Voice Response application, and the components that comprise an application. Subsequent chapters elaborate on the steps in the process, introducing the components involved. These are followed by chapters that give more information about implementing specific types of service, using specific techniques and technologies. The process is assumed to be top-down, though iterative (as shown in Figure 1), and throughout the book, the organizing principle is to start with the high-level, broad view and progress through lower-level views to the details of individual elements. Plan Establish requirements for the voice response service: Business goals Caller needs WebSphere Voice Response facilities Design Allocate functions to different parts of the application: Interaction with caller Data access Telephony activity Design the dialog with the caller: Key input Speech input Speech output Implement and Test Voice Segments Prompts State tables 3270 servers Custom servers System parameters Application profiles Package and Distribute Applications Maintain and Support Mailboxes Distribution lists Subscriber classes Figure 1. The life cycle of a voice response service Requirements and Planning The WebSphere Voice Response for AIX: General Information and Planning book describes the kind of services that WebSphere Voice Response can support, and the facilities it uses to support them. Use this information to guide you in the planning phase. Copyright IBM Corp. 1991,

22 Plan Design Implement and test Package and distribute Maintain and support A voice response service typically handles information requests from telephone callers. 1 You design and develop voice applications to satisfy your business requirements: the voice application can make calls, answer calls, perform computations, pass information from local or remote databases, communicate information to a caller by speaking it back over the telephone, let callers leave and retrieve messages, transfer calls to other applications, connect callers to a human operator, and so on. Business requirements You need to establish how the proposed service fits in with your business or organization goals. What is the purpose of the service and is an automated voice response service the best way of achieving this? What are the benefits of automating the service to your organization and to the target population? Is an automated voice response service likely to be accepted by the target population and generate business or cut costs? Telephony requirements How does the new service fit into existing services? Is it going to be a single-purpose or multi-purpose service in its own right? Or is it just going to be a new part of an existing service? Does the telephony equipment you use support this kind of service, or are you going to have to make changes there? User requirements What are the characteristics of the target population? What kind of output is going to be acceptable to them? What kind of input mode are they going to prefer? How big is the target population? How frequently are they likely to use the service? Is the service likely to be frequently used or rarely used? 1. Voice response services can also make outbound calls. However, throughout this book, the word caller refers to the person on the other end of the conversation, who may be either the calling party or the called party. 4 Designing and Managing State Table Applications

23 Data requirements What data is to be provided by the service, where is it stored (currently or in the future), what format is it in? Is it frequently updated or rarely updated? What kind of output mode is going to be suitable for it? Would you be able to use other software or write new programs to access data if necessary? Programming requirements Who is going to implement the components of the voice response service? Is the department who understands the business and the callers going to develop the application themselves? Or do you have professional programmers or a service bureau that you can call upon? Even if you use professional programmers or a service bureau, the business departments and the callers themselves should be involved too. Conversely, even if the business departments are comfortable with implementing small and medium-scale systems, it may be advisable to involve system integrators if you are scaling up to something large. IBM solutions Can your requirements be satisfied by an IBM solution? For example, before starting to develop your own voice mail system, consider the advantages of buying IBM s Unified Messaging program offering. This is very much easier than writing your own system: Unified Messaging comes with additional system administration utilities and, if it does not fit your requirements exactly, you can tailor just about every aspect of it. For more information, see your IBM representative. Suggestions Use existing services as a model Start planning an application by surveying the requests for information that your company currently receives. Repetitive requests that are time-consuming for your personnel to satisfy are good candidates for voice applications. Start small Begin by serving your most important customers, or set up an application to service a pilot group. Provide a feedback mechanism to measure how the system is meeting your customers and employees needs. Encourage complaints. Prioritize your applications Don t expect the system to solve every problem from the first day. It s important to set fairly easy and reasonable objectives which can be met during the initial phase of use, and then move on to more sophisticated Chapter 1. Introduction 5

24 applications as your staff and customers become better acquainted with the system. Design High-level design consists of analyzing your requirements, both business goals and caller needs, decomposing the functions of the service, and determining what application components are required to perform each function. Low-level design then involves examining how WebSphere Voice Response facilities and the facilities of other hardware and software (such as the telephone switch and database access) are to be used to accomplish the goals of each component. You need to prototype and document, visually, at each stage in the design process. Plan Design Implement and test Package and distribute Maintain and support High-level and low-level design Design considerations In designing the voice response service, you need to consider telephony activities and data access as well as the dialog design: v What are the functions of the service, and what is each part of the application going to do? v Is the application going to answer, make, transfer, reconnect, or terminate calls, and how? v Do the switch and signaling protocol at your site support the telephony functions required? v Where is the application going to get data from and how? Will callers be updating databases or files, and how? What are the security and data integrity implications? v How will the application communicate with the caller? v How will the caller communicate with the application, using tones or speech or a mixture of the two? v How will the application handle situations such as the caller hanging up in mid-transaction or the database link failing? 6 Designing and Managing State Table Applications

25 For more information, see Chapter 2, Designing a voice application, on page 15. To design your application, you need to understand the facilities and programming interfaces that will be used to implement it, as well as the requirements for it, so you ll also need to read the appropriate chapters on implementation before you start designing your own applications to run with WebSphere Voice Response. Suggestions Flowchart applications Draw step-by-step flowcharts of specific applications both before and after the system is installed. This will help you to catch duplications or redundancies in procedure that existed in the past and that might occur again in new applications. Are there paper documents that need to be maintained? Are there ways to simplify your business operations before or during your conversion to voice response? Are jobs going to be changed? Keep it simple The basic rule for designing voice applications is: keep prompts simple, short, and specific. Don t provide an endless list of options to callers, which will surely confuse them. Offer callers just what they need in order to get to the information they want. If there are many options, and you want to make them all available, create a series of branched prompts that break the options into small groups of two or three options each. Accommodate frequent as well as new users Don t make experienced users sit through an entire script. Allow them to override prompts by pressing keys at any time during the call. Allow callers to change their entries After a caller has entered an order or request for information, always allow for a change of mind. Also, try to allow for errors throughout the transaction. If a caller doesn t get it right in three or four tries, return to the main menu or play a prompt that tells the caller to call back and start again. Develop design documentation Applications should be clearly documented. Provide the name of the application, its purpose and benefits, how to access the system for the application, and the specific steps involved. Include the commands to be entered via the telephone keypad, the specific actions or results of each command, what to do in case something goes wrong, and the correct way to sign off the system. Chapter 1. Introduction 7

26 Develop a draft set of voice segments Don t have your voice segments recorded professionally right at the beginning: record them yourself to begin with, because they are sure to change before the voice response service is put into production, and you don t want to waste professional recording fees. With voice segments, the rule is, Start early, finish late! Design for maintenance Build tracing and debugging into the voice response service from the start, and make it configurable. You can either turn on tracing and debugging statements by setting variables at the beginning of the state table, or you can include parameters in a command file that is read by a custom server. Implementation To implement your design, you need to understand how to create and manage the objects that are required to make a voice response service work. These are described in Plan Design Implement and test Package and distribute Maintain and support v Chapter 3, Creating and managing application objects, on page 27 v Chapter 4, Overview of application objects, on page 61 v Chapter 5, Creating an application profile, on page 89 Following this are chapters that contain guidance on the following topics: v Chapter 6, Creating the voice output for voice applications, on page 101 v Chapter 7, Handling key input from callers, on page 119 v Chapter 8, Handling spoken input from callers, on page 121 v Chapter 9, Accessing data with a 3270 or custom server, on page 127 v Chapter 10, Telephony activity, on page 133 v Chapter 11, Designing voice messaging applications, on page Designing and Managing State Table Applications

27 v Chapter 12, Managing voice messaging resources, on page 167 v Chapter 13, Telecommunications Devices for the Deaf, on page 191 v Chapter 14, Background music, on page 195 v Chapter 15, TDM connection management, on page 209 What does implementation involve? Implementation of a voice response service involves: v Recording voice segments v Designing and building prompts v Designing and building state tables v Designing and building 3270 server scripts v Designing, coding, and building custom server programs v Testing and debugging components separately and together We cannot stress too much that testing is vital to the success of your voice response service. Not only functional testing, but also getting users involved in early trials, and evaluating their experiences. Early user involvement in design should ensure that you don t find reach the beta-test stage before finding too many usability problems that are costly to fix, but you should also ensure that the service is tried out by a limited set of users before going live. There is a gray area between implementation and putting your voice response service into production. You may think of the following tasks as belonging to implementation, as you will certainly need some resources with which to test. However, you should consider these to be administration tasks that belong to the packaging and distribution or maintenance and support phases: v Creating application definitions v Exporting application packages v Importing application packages v Creating application profiles v Defining mailboxes, distribution lists, and subscriber classes v Ensuring that system parameters are appropriately defined System parameters Among the many parameters that control the way the WebSphere Voice Response system works are two groups of particular importance to applications: v Application Server Interface parameter group v General parameter group See the WebSphere Voice Response for AIX: Configuring the System book for details of each parameter in these groups. Chapter 1. Introduction 9

28 Testing the voice response service Test phases Testing should be performed in distinct phases, in which you are checking for different kinds of problem: 1. Logical or unit test, to test the basic logical flow 2. Functional test, to test the interaction with the caller 3. Performance or stress test (more than one call at a time, and so on) 4. Critical test (removing the most critical parts of the application, to find out what callers would hear) Hints and tips To use the Debug option in the State Table window, you need to include an AnswerCall state in the state table. When using the debugger, this is converted into a MakeCall. Using the debugger, you can step through the actions, modifying the values of variables to test different paths through the state table. It s useful if a voice application can output its own trace data, using the LogEvent action or a custom server. You should design this so that tracing can be switched on or off when the application is in production. Migrating application objects If you are migrating to WebSphere Voice Response Version 6.1 from WebSphere Voice Response Version 4.2, use the restoredt utility to bring your application objects and data into the new system (refer to the WebSphere Voice Response for AIX: Installation book for more information on using restoredt). When you do this, all your application objects are placed in the Default application. You can either leave them there or, if you want to manage application objects efficiently (see Managing application objects efficiently on page 29), you can create your own applications (see Creating an application on page 34) and move objects into them from the Default application. If you export applications from IBM WebSphere Voice Response for AIX, you need to import them (see Importing application objects on page 46). Using an external code repository If you develop applications using a text editor, and store them in a code repository such as CMVC, you can import ASCII versions of state tables, prompts, 3270 servers, and custom servers into WebSphere Voice Response. Once imported, the object can optionally be stored in WebSphere Voice Response with a user-specified version ID, which makes synchronization with 10 Designing and Managing State Table Applications

29 external code control systems possible. Optionally, you can make the imported object read-only, which prevents it from being modified and saved using the WebSphere Voice Response windows. The read-only property (if set) is displayed in the object s container window. Suggestions Modularity For maintainability, you are recommended to implement applications as multiple state tables rather than one large state table. Encapsulation Consider implementing some parts of the application as common state tables that can be called as subroutines by other state tables. Commenting and documentation In state tables, use the Description field in each state to describe what it does. Add further comments using the DoNothing action. Packaging and distribution Creating an application profile will enable you to run state tables that handle incoming calls, or which are invoked by application profile by other state tables, in production (see Chapter 5, Creating an application profile, on page 89). You may also need to create voice messaging resources before putting your application into production (see Chapter 12, Managing voice messaging resources, on page 167). Plan Design Implement and test Package and distribute Maintain and support Packaging involves creating an application definition, which specifies which components are required to run the voice response service. If you have only Chapter 1. Introduction 11

30 one WebSphere Voice Response system, you don t need to package your applications, although creating an application definition can help you keep the components organized. To distribute the components of an application, you then use the application definition to create a package: this is known as exporting. You then send the package you created using the application definition to whichever systems are going to run it. The package is simply a file that you can send using any suitable file transfer method to another pseries computer. After transferring the package, you import it into the WebSphere Voice Response system on the other pseries computer and install its contents: the original application components. Distributing an application to other WebSphere Voice Response systems You may develop the components of a voice application on a system reserved for development, or you may want to run the same voice response service on multiple systems. In either case, you need to be able to transport application objects from one system to another. To do this, you export the application from WebSphere Voice Response. This creates a single AIX file that you can transport to another system. The file must then be imported into WebSphere Voice Response. See Exporting an application on page 38 and Importing application objects on page 46. Suggestions Spread the word Send a memo around your site announcing the planned installation date of a new voice application and describe clearly how the system works and what the benefits are to the staff. Conduct a promotional campaign for your customers explaining your new service and educate them in the use of the system by flowcharting the application for them. Also select a staff person who will serve as a contact for additional information and questions. Select a system administrator Assign someone to maintain the system and the applications. The role of the system administrator is to configure the system as required by your voice applications, establish the data interface between the system and your host computer, set up controls and authorizations, monitor system performance, and take whatever action is necessary to manage and keep the system up and running. 12 Designing and Managing State Table Applications

31 Maintenance and support Once the application is in production, new requirements may arise, or problems occur. These can result in a re-iteration of any of the preceding steps. Requirements for important new function will cause you to go back to the requirements phase. Major usability issues may return you to the requirements or the design phase. Performance problems may return you to design or implementation, as will failure to handle every situation that arises or provide correct output. Plan Design Implement and test Package and distribute Maintain and support Housekeeping Some application objects, such as voice segments, take up a lot of storage, so you need to attend to the housekeeping regularly. Before deleting an object you think might no longer be used, check its dependencies, to make sure that no other object uses it. See What is a dependency? for more information. Archiving application objects To archive the application objects necessary for a voice response service, you export the application from WebSphere Voice Response. This creates a single AIX file that you can store on disk, tape, or other media. When the application is required again, the file can be imported into WebSphere Voice Response. See Exporting an application on page 38 and Importing application objects on page 46. Distributing updates Updates to some of the objects in the application can easily be distributed using delta export: exporting only those objects that have changed since the last full export, delta export, or since a specified date. See Exporting an application on page 38. Chapter 1. Introduction 13

32 Suggestions Conduct system user surveys Gather feedback both before and after system installation. This will help you to diffuse any fears or misunderstandings and to compare expected and actual reactions to the system. 14 Designing and Managing State Table Applications

33 Chapter 2. Designing a voice application When you understand the requirements for the voice response service, the business goals and callers needs, you can begin designing your application. You may not yet know which WebSphere Voice Response facilities and other software and hardware you will use to implement it. Part of the design process will be to decide on the implementation of the high-level activities. This process will be iterative, as you create prototypes and learn more about both requirements and ways of implementation. Always involve users, both callers and the departments commissioning the voice response service, in the design process. However, there will be work you need to do without them. Copyright IBM Corp. 1991,

34 Welcome and find out if caller has a pushbutton phone Transfer a caller without a pushbutton phone to a human agent, or invoke a speech recognition application Offer choice of services Account balances Interest rates Please try again Goodbye and thank you for calling Notice that the designer has already considered the possibility that the caller may press a key that is not assigned to either a service offering or to ending the call. Figure 2. Example of main activities to be performed by a voice application. 1. Before the first meeting with users, identify the main activities to be performed by the application. An example is shown in Figure Together with users, design the dialog for each activity, concentrating on everything proceeding smoothly (as you hope it will in majority of calls). You must take into consideration all the possible responses by the caller, remembering that they may have either keys or speech or both to respond with. Table 1. Example dialog segments ID Words 1 Thank you for calling the WebSphere Voice Response Automated Account Inquiry Service. 16 Designing and Managing State Table Applications

35 Table 1. Example dialog segments (continued) ID Words 2 To hear your account balance, press 1. 3 To hear the current interest rate, press You have in your current account in your savings account. 31 Today s interest rate is... 7 To leave the WebSphere Voice Response Automated Account Inquiry Service, press 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 you can use in the text versions of voice segments: An initial capital letter at the beginning of a voice segment indicates the beginning of a prompt. Ellipsis (...) at the beginning of a voice segment indicates the continuation of a prompt. Ellipsis (...) at the end of a voice segment indicates that further voice segments are to be appended in the prompt. Period (.) at the end of a voice segment indicates the end of the prompt. 3. You need to decide whether you are going to allow both keys and speech throughout the call, keys for some parts and speech for others, or whether you are going to restrict the caller to either keys or speech. You may decide on two versions of the service: one for callers who have pushbutton phones, and one for callers with rotary phones, who have to use speech. 4. As your dialog design progresses, make sure you document each of the branches of the application. You can use the WebSphere Voice Response State Tables window to create a graphical representation of the state table, filling in the details later. Chapter 2. Designing a voice application 17

36 5. Before the next meeting, identify all the things that could go wrong: for example, the caller could hang up in the middle of the call, the connection with a host computer could fail. Again, you can use the WebSphere Voice Response State Tables window, this time looking at the possible results for the actions and filling in the details. 6. Again, with users, refine the dialog, taking into consideration all the things you have identified that could go wrong. The business departments will want to be assured that the caller is going to hear the right thing whatever happens. They do not want to lose business through a badly designed voice application. If the voice application itself cannot continue, ideally, the caller should be transferred to a human agent. User participation in dialog design The words used in the dialog must satisfy both the business goals (including the company or organization image) and be meaningful and unambiguous to callers, so you need participation from business people and representative callers. Lo-fi prototyping Before recording anything, act out the dialogs, using the Wizard-of-Oz technique, with one person reading out the application s words from out of sight (say behind a screen or curtain), and another person acting the part of a caller. This avoids the need to write prompts and state tables before you have refined the design. Recording voice segments and writing code increases your reluctance to make changes, so try the live Wizard-of-Oz prototyping technique first. When you are fairly happy with the dialog design, record the voice segments using the telephone, or synthesize them using text-to-speech. Recording over the telephone is easily done with either of two sample programs supplied with WebSphere Voice Response. To test the dialog, you ll need to write prompts and a simple state table too. Start with company employees as the callers, and, when you are happy with the dialog, try it on potential customers or clients. If the service is aimed at company employees, start with experienced employees, but don t forget to try it out on newcomers. Only when you are satisfied with the dialog, should you invest in professional recording. 18 Designing and Managing State Table Applications

37 Designing the dialog Customer satisfaction with your voice response service will depend on a number of factors, including the voice you choose, the information you provide, and the ease with which callers can get the information they want. The sound and feel of the service is every bit as important as the look and feel of a visual computer application. With careful design, the caller s experience will be pleasurable; with lack of attention to dialog design, the caller will get frustrated and hang up. At best this will result in your people handling just as many calls as they ever did; at worst it may mean loss of business. You re already considering a voice response service, so you re aware of the strengths of voice response: telephones are ubiquitous, familiar, and easy-to-use and an automated system can provide more speed, privacy, efficiency, availability, and accuracy than some human operators, and at lower cost. Nevertheless, when designing the dialog, you need to be aware of some of the limitations of the medium. Compared with people, automated systems are inflexible, demanding, and intolerant of deviations from the expected conversation. They are best at handling very routine calls. Almost without exception, all voice response services should offer help in some way, for example by offering the choice of transferring to an operator (if call transfer is provided by the switch) or calling another number to speak to an operator. If call transfer is provided by the switch, the application can automatically transfer the caller to a human agent in some circumstances. You should give human factors and usability a high priority when designing voice response services, in addition to testing the usability of the services later. Design considerations Compared with today s multiwindowed screen-based computer applications, voice response applications have a number of potential limitations. With careful design, you can overcome the limitations and make your application a delight to use: v Auditory output is sequential, and hard to keep in short-term memory: you have to take great care wording the prompts. v Auditory output can be slow: unfortunately, someone (either you or the caller) is paying for the call, and wants the whole transaction to take as little time as possible: again, the prompts need to be worded carefully so that they convey the greatest amount of information, unambiguously, and in the shortest amount of time. Chapter 2. Designing a voice application 19

38 v The very ubiquity and availability of telephones means that callers don t have access to manuals and other supporting materials: the whole point is that the voice response service can be used from anywhere, so the application itself must be completely self-documenting. v Voice data takes up a lot of storage space (one second of voice occupies 8000 bytes of storage). This can be reduced by a factor of 5 by compression, or even further by generating synthesized speech from text. On the input side, from the caller s point of view, the telephone is an inferior device compared with the computer keyboard and mouse: v There are two ways of communicating with a WebSphere Voice Response application: by key or by voice. If keys are used, they must transmit dual-tone multifrequency (DTMF) tones. If the caller is able to transmit these tones, keys are the most accurate and efficient method of input. v Bear in mind that many callers may be using phones with an integral keypad and handset: they will take longer to press the keys than callers using traditional phones with a separate keypad. v Compared with the 100 or so keys on a computer keyboard, the standard telephone has twelve keys (WebSphere Voice Response supports up to sixteen: 0 through 9, *, #, A, B, C, and D). v The standard keypad is fine for numeric input, making simple choices, and answering yes-no questions, but what about alphabetic input? In some countries, there are no alphabetic characters on the keys at all; even in countries where telephones still have the alphabetic characters on the number keys, people don t use them enough to be familiar with their positions. (And note that different countries use different layouts anyway.) v Many telephones cannot transmit DTMF tones reliably or at all: rotary dial, hybrid tone, and dial-pulse phones are still in use; cellular and portable phones often suffer from noise interference; some equipment sends tones of fixed duration or cannot send tones at all during a call. In these cases, the only reasonable input device is voice, and for that, you require access to speech recognition hardware or software. Faced with all these challenges, you have a number of design decisions to make. First you need to determine the right dialog style or styles and then you need to attend to the detail of each interaction, or task, within the application. If you design your application well, callers will prefer it to the human agent, and the reward will be savings in business costs. Choosing a dialog style No single dialog style is best for all applications, for all tasks within an application, or for all callers: 20 Designing and Managing State Table Applications

39 v Callers may be familiar or unfamiliar with the mechanics of driving the application. v Callers may be familiar or unfamiliar with other voice response services. v Callers may use the service frequently (and therefore acquire expertise with the mechanics, or the content, over time) or infrequently (never acquiring expertise). v The content of the dialog may be familiar and predictable (for example, days of the week) or relatively unfamiliar and unpredictable (for example, toppings available for pizzas). v It may be appropriate to provide documentation or training sessions, for example, if callers are employee or students, but it is unreasonable to base your design on the assumption that documentation will be read or training sessions attended. There is a far greater choice of dialog designs for voice response services than you might imagine. Some less common designs overcome the problems encountered by callers in using traditional voice response services. Different styles of dialog may be appropriate in different parts of the service, depending on the task being performed: after all, these days one expects to see pull-down menus, radio buttons, check boxes, and so on, used in visual applications, so it s not surprising that there might be a variety of techniques you can use in voice response dialogs. There are three basic styles of voice response dialog, suited to different types of task: Menu: List: Form: suited to selecting one of a small number of options suited to choosing multiple items, perhaps from a large number suited to providing input such as addresses and telephone numbers Within these basic styles, there are numerous variations. It s hard to provide rules for good dialog design, but you need to classify your application and your callers in these terms before considering the following questions: 1. Composite or separate actions? Composite actions may be simpler for the caller, but separate actions gives more flexibility. If your callers are unlikely to use the application often, give them composite actions that accomplish the most with the fewest keystrokes. If callers are likely to use the application often, however, they may want to combine actions in different ways. 2. Keys or speech recognition? The application is using speech to communicate with the caller, but should the caller be using speech or keys? Remember it takes longer to speak a command and have it Chapter 2. Designing a voice application 21

40 recognized than it does to press a key. Also, people are better at pressing keys accurately than speaking clearly enough to be recognized accurately. 3. A mixture of key and speech input? You can mix key input and speech input in a single application (though you are not recommended to allow both at the same time). For example, entering a Personal Identification Number (PIN) is easier using keys, whereas recording a street address is easier with speech. 4. Command-driven or prompted? You need to make a decision about whether to let callers interrupt the prompts or not. In general, you should let them interrupt. Once they learn the choices at each point, they can key ahead (or speak ahead), without waiting for the prompt to finish. There may, however be some prompts that you want to force play to the end; there may even be whole applications in which you want all prompts to be force played. The type of dialog that allows key-ahead or speak-ahead is sometimes known as a command-driven dialog, but you still need to play the prompts in a voice application, because of the absence of documentation. 5. A single selection key or option-specific selection keys? With a single selection key, you play each choice to the caller and give them a few seconds to press the nominated key (for example, 1); if they do not press a key, you play the next choice, and so on. The caller always presses 1 to select the current option. There is less for callers to learn if, at any point, they have only two choices: to select the current option or to proceed to the next; it can be useful for long lists of options (for example film titles). On the other hand, this kind of design tends to restrict the caller s ability to key ahead and bypass menus. With option-specific selection keys, you allocate a different key to each option. This has the advantage of allowing callers to key ahead, but limits the options available at any one time. It can also be difficult to ensure consistency of key-allocation throughout the application (for example, on one menu, 3 may be Delete message while on another menu, it is something less destructive). Again, infrequent use may indicate the single selection key and frequent use the option-specific selection keys. 6. Passive or active advance through menus? Should each option drop through to the next option, or should the caller have to press a key to proceed? This becomes an issue if you provide a single selection key. Again, passive advance is probably most suitable for callers who use the application infrequently but, to avoid the problem of callers selecting an option just after the menu has moved on to the next option, you need to include a few seconds of silence between each option. Passive advance might seem easiest for the caller, but only at first. Later, callers may become frustrated at having to sit through whole menus. Providing a Next key would seem to prevent this, but the 22 Designing and Managing State Table Applications

41 drop-through behavior often results in callers never learning about the Next key, unless the menus mention it. 7. Long or short prompts? The more information you provide, the more likely the caller is to learn how to drive the application. However, long prompts slow down callers, particularly experienced ones. A choice of novice and expert prompts can help. The difference between them is not necessarily verbose versus terse: you could actually leave some information out of the expert prompts altogether. Always provide essential information before information that is merely helpful. Provide Next and Previous keys, so that callers can skip over information they don t want to hear. Good things to do in voice applications Correct wording of your prompts is particularly critical when you are using speech recognition. Your prompts must tell the caller what to say, when to say it, and how to say it. Here are several considerations for wording prompts: v Voice output can be speeded up with no loss of intelligibility. This could be under the caller s control. v Subdivide the recording of voice output, to allow random access to it. Callers can skip and scan. v Make sure that callers know they re using a machine; don t try to make them think they re talking to a human agent. v Ask the caller whether they are using a phone that generates tones, by asking them to press a specific key. v Allow the caller to interrupt prompts (key ahead) wherever possible (that is, don t force play the prompts). v Refer to the # key as pound in the U.S. or hash in the U.K. v Refer to the * key as star. v Use the star key for the control menu. v Refer to the 0 key as zero. v Use the zero key to provide access to the operator. v Always phrase your prompts so that the goal precedes the means of achieving it (for example, to contact the operator, press 0 ); if you mention the key first, the caller may forget which one it was before realizing that it was they one they wanted. v Use questions and commands rather than statements, to encourage callers to take immediate action. For example: To check your account balance, press 1. Is this correct? Press 1 for yes, 2 for no. v Ask closed questions such as Do you want a large, medium, or small pizza? rather than What size pizza would you like?. Chapter 2. Designing a voice application 23

42 v Add pauses to encourage the caller to take immediate action. v Always try to allocate similar functions to the same keys. v Use directional metaphors where appropriate (use the relative position of the keys on the keypad to indicate some logical direction associated with the command, for example, 7 for back, 8 for pause, and 9 for forward). v Try to limit menus to about four options, with a fifth option ( for more choices ) if necessary; this adheres to the magic number 7 plus or minus 2 items that people can hold in short-term memory; also it won t take too long to play. v The order in which you play the options depends on the application: you might choose to start with most frequently used, or least-frequently used, or play them in ascending numerical sequence. v Use simple, explicit language, for example: Press for single key entry (no delimiter) and Enter for multiple keys (which need a delimiter). v Give feedback: repeat long data entries back to the caller. v If something s going to take a long time, tell the caller and then play background music; repeat the message saying it s going to take a long time at intervals. v If the caller does not make a selection, repeat the menu. v If the caller makes an error, explain valid choices. v Employ a professional to record the final version of the prompts. v Don t mix prompts recorded in more than one voice, unless you do this consistently to convey information (for example, voice A for menus and voice B for data retrieved for playback to the caller). For this reason, you should get the system voice segments recorded by the same professional as your other voice segments. Wording prompts for speech recognition applications Like DTMF applications, your instructions to the caller must be brief. The caller cannot be expected to remember more than two or three instructions before making a response. 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 a pizza, say YES now rather than Do you want a pizza? v To encourage the caller to speak digits rather than whole numbers, you might provide an example. Your recorded voice segment must speak in digits. How many bottles of item one seven five do you want? is better than How many bottles of item one hundred and seventy five do you want? 24 Designing and Managing State Table Applications

43 v It is useful to include directions such as say YES or NO now in the prompt. This helps callers understand that they must wait for the prompt to be over before they can speak. v Your prompts are models for the caller. That is, the caller is likely to mimic the volume, pace, enunciation, and terseness of the recorded speech. Handling all responses When designing a speech-recognition application, you must decide when to repeat a prompt, request verification, or transfer to a human operator. Your decisions are based on confidence factors. Ask for the same information not more than twice, to avoid irritating the caller and jeopardizing the business transaction. The second prompt should apologize to the caller, accept responsibility for the communication error, and repeat the request. You might change the wording in the second request to give additional clues or information. Speech recognition while a prompt is playing Full-duplex barge-in allows the caller to start speaking while the prompt is still playing. See Barge-in on page 121. Interrupting prompts To enable callers without DTMF phones to interrupt a prompt with a short speech utterance (for example stop! ), you need to enable voice interrupt detection. See Voice interrupt detection on page 122. Limitations Speech-recognition applications work best when there is a high signal-to-noise ratio. The speech recognition process can fail when background noise, such as traffic, is louder than the caller s speech. If you expect many of your customers to be calling from a noisy environment, your application should include a test and branch to a human operator. For example, a first prompt asks callers if they have their account number ready. If the external voice services system fails to find a good match, the state table could branch to a TransferCall action to transfer the call. Chapter 2. Designing a voice application 25

44 Defining server requirements Before you create a 3270 server or custom server to access business information, you need to perform an analysis of your requirements, to determine how you can most effectively use a server. The analysis involves identifying information such as: v Remote data required by a voice application v Where the required data resides v Existing applications that access the data v Data the server needs to satisfy a request v Processes required (both new and existing) to satisfy a request v Whether voice data is to played or recorded on multiple channels at the same time: a multiprocess custom server makes this easier to manage v Whether database access is on a serial link, in which case a single process will suffice, or on a multilink or virtual session, in which case the server needs to be multiprocess (3270 host access is multiprocess) v How the server is to be activated (such as by a state table or a timed event) v How to respond to both successful and unsuccessful attempts to provide the requested information v Considering custom server resource requirements, things such as CPU, memory and page space v Any additional processing you may want to perform as a result of a request (such as maintain a count of types of requests for business activity statistics). When you have identified the information that defines the requirements for a server, you can determine whether a 3270 server or custom server best suits your needs. 26 Designing and Managing State Table Applications

45 Chapter 3. Creating and managing application objects To implement a voice response service using WebSphere Voice Response, you need to create a number of objects. This chapter introduces the concept of a voice application and its constituent objects, and tells you how to create, manage, and distribute applications and objects. (The object types and their role in the application are introduced in more detail in Chapter 4, Overview of application objects, on page 61.) This chapter contains the following sections: v What are application objects? on page 28 v Using the applications and application windows on page 30 v Managing application objects efficiently on page 29 v Discovering what applications and objects are in the system on page 30 v Editing and testing application objects on page 33 v Creating an application on page 34 v Exporting an application on page 38 v Exporting one or more objects on page 44 v Importing application objects on page 46 v Migrating from an earlier release of IBM WebSphere Voice Response for AIX on page 50 v Frequently asked questions on page 51 v Moving objects from the default or user applications on page 54 v Deleting an application on page 55 v The dtimport and dtexport commands on page 55 Copyright IBM Corp. 1991,

46 What are application objects? To create a voice response service, you need to create (or import) a number of objects of various types: Prompts Application Profile Other State Tables 3270 Servers Information via 3270 data stream Caller Voice Segments Main State Table Custom Servers Information or resources, such as speech recognition Application Figure 3. Voice application objects 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 servers, to provide access to data on host computers, via existing applications that use the 3270 data stream. (See 3270 and custom servers on page 85.) v The state table can invoke prompts, which are specialized programs that control the dialog that the caller hears. (See Prompts on page 74). Prompts are collected together in a prompt directory. v The recorded words or sounds that the caller hears are known as voice segments. Although these can be played directly by the state table, it is much more efficient to play each voice segment from a prompt. (See Voice segments on page 82). Voice segments are collected together in a voice directory, and can also be indexed by a voice table. v Typically, most voice applications also include at least one application profile, which defines various characteristics of the application. Application profiles have several functions. Each application profile specifies a main (or initial) state table which: 28 Designing and Managing State Table Applications

47 Can be invoked in response to incoming calls if the application profile ID matches the called number or channel identification. Can be invoked by other state tables (but note that you can invoke a state table from another state table without an application profile). Uses the specified language database to play prompts and voice segments. Thus you can have the same state table to handle calls in different languages; only the application profiles need to be different. Can access up to ten voice mailboxes, together with associated voice messaging resources, such as distribution lists, for use by the state table described in the profile. For information about defining an application profile, see Chapter 5, Creating an application profile, on page 89. v Files and databases containing information can be accessed by a custom server. All these objects comprise the voice response service, or voice application. To help you manage these objects in an application-oriented way, WebSphere Voice Response includes an Applications window in which you can see all the applications in the system, and an Application window for each application, which shows all the objects in the application, grouped into folders: one folder for each type of object in the application. Managing application objects efficiently All application objects in the WebSphere Voice Response system must be in one and only one application. The application provides you with: v A place to keep: All the objects required for a voice response service All the objects shared by multiple voice response services Other objects that are not currently in use, or are under development This enables you to: Find objects easily Open objects for browsing or editing Delete objects from the 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

48 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 name for the copied object, whether or not it has been copied to a different application. Using the applications and application windows There are several ways of doing many of the tasks described in the following sections. The procedures describe the simplest way, using the mouse to single-click, double-click, or drag-and-drop. Most tasks are also available from one of the pulldown menus on the menu bar, and from the object popup menu. To use the pulldown menu, select the object first and then select the menu option using mouse button 1. To use the popup menu, select the object first and then press mouse button 3. Alternatively, all tasks can be done using keyboard keys. See wvrapplprof command on page 94 and the WebSphere Voice Response for AIX: User Interface Guide book for more information. Discovering what applications and objects are in the system Before you start, see the note on Using the applications and application windows. From the Welcome window click on, Applications > Applications The Applications window shows all the applications in the system. 30 Designing and Managing State Table Applications

49 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 the application: Figure 4. The Application window 2. Opening a folder and displaying information about objects: Single-click on the folder icon to open it. The folder contains all the objects of that type in the application: The system displays the date and time of the last update of each object, and the application that contains it, and other relevant information, depending on the type of object: Chapter 3. Creating and managing application objects 31

50 You can select the names of the objects in this view. About the supplied applications: When you install WebSphere Voice Response, three applications are supplied: The Default application The Welcome, Incoming_Call, Record_Comp, and Record_Uncomp state tables, and other objects they need are in the Default application. If you migrated your own application objects from IBM WebSphere Voice Response for AIX Version 4.2, they are also placed in the Default application. The User application For information about the User application, see Table 2 on page 52. The System application The System application contains only the System application profile. This is reserved for use by voice messaging applications. To organize your application-related objects, you should create your own applications and move your objects into them (see Creating an application on page 34 and Moving objects from the default or user applications on page 54). 32 Designing and Managing State Table Applications

51 Editing and testing application objects You can do most of the work involved in implementing a voice response service from the Application window. Before you start, see the note on Using the applications and application windows on page 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 and objects are in the system on page 30). 3. Double-click on the object name. When you open an application object, or create a new one, a container window listing all the objects of that type appears, followed by the editing window for that object. For example, the Prompt Directories window, followed by the Prompt Directory window: Using the container windows: The name preceding the type of object (in this example, Default), tells you which application was selected when the container window opened. However, the container window lists all the objects of that type in the system. You can use the container window to find objects, using the Search popup window (mouse button 3). (For information about using the container windows and about searching for information, see the WebSphere Voice Response for AIX: User Interface Guide book.) Chapter 3. Creating and managing application objects 33

52 To open objects such as prompts and voice segments, which are contained in prompt directories and voice directories respectively, double-click on the directory name in the container window. This displays all the objects in that directory. Find the object name and double-click on it. Using the editing windows You can develop all the objects, except for the C or C++ code for custom servers, using the editing window that opens when you open an object. Importing ASCII files Alternatively, you can use an ASCII editor to develop the code for state tables, prompts, and 3270 scripts. Then create a new object (if necessary) and import the ASCII code into the appropriate editing window, by clicking Utilities > Import. Or, you can import ASCII state tables and prompts using a command that can be issued from the command line or from a script. For more information See the appropriate book for all the detailed information you need about creating, editing, and testing these objects (and importing ASCII code for them): v WebSphere Voice Response for AIX: Application Development using State Tables book v WebSphere Voice Response for AIX: 3270 Servers book v WebSphere Voice Response for AIX: Custom Servers book The remainder of this chapter tells you about creating the application as a container for your objects, managing the objects within the application, and exporting and importing whole applications and individual objects. Creating an application Before you start, see the note on Using the applications and application windows on page 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 (up to 255 characters). The name must be unique. 4. Click Create. The name of the new application is displayed in the Applications window and a new Application window opens automatically. 34 Designing and Managing State Table Applications

53 5. You can now either move or copy existing objects into the application, or create new objects within it. 6. Moving an object: Open both the source and target Application windows. Note: It does not matter whether there is a folder for the type of object in the Application window, because folders are created automatically by the system; and it does not matter which folder you drop the object into, because the system makes sure it goes into the right one. 7. Click an object in the source Application window and drag it, using mouse button 2, to the target Application window. The object is moved to the target Application window, and displayed in the appropriate folder. Note: If you drag an object from the Object Index window into an Application window, the object is not removed from the Object Index window, but the application name is changed. The object appears in the target Application window. 8. Moving multiple objects: Click multiple objects of the same type (in the same folder): you can either select adjacent objects by dragging down them using mouse button 1, or you can add objects to the selection by holding down the Ctrl key while clicking with mouse button Drag them, using mouse button 2, to the target Application window. The objects are moved to the target Application window, and displayed in the appropriate folder. 10. Copying an object: Click the object in the source Application window and drag it, using mouse button 2 + Ctrl, to the target Application window. Because you cannot have two objects with the same name, the system asks you for a new name. 11. Type in the name. The name must be unique. 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. Refer to the WebSphere Voice Response for AIX: Application Development using State Tables book for detailed procedural and reference information, or use the online help. Chapter 3. Creating and managing application objects 35

54 When you click View > Refresh Now, the new object is displayed in the Application window. Note: If you create a new object within the Object Index window, the object is stored in the Default application and displayed in the Application (Default) window. 16. Creating more objects: You can create further objects of the same type by repeating steps 13 on page 35 and 14 on page 35, or by clicking New from the appropriate menu in the container window. 17. Displaying dependent objects: Click an object and then click Dependencies from the object's popup menu. The system displays the Dependencies window: What is a dependency?: A dependency is an object that is necessary for another object to run correctly. For example, prompt directory B becomes a dependency of state table A when you specify it as the prompt directory in state table A. WebSphere Voice Response cannot find all of the dependencies if variables are used to name them (for example, InvokeStateTable by variable). To run a state table on a development system, it is not necessary to include all dependencies in the same application. Provided that all the dependencies are actually present, the state table can be run. But, before you export the state table to another system, you should check that the state table and all its dependencies (other state tables, prompts, voice segments, and so on) are present on the target system, whether in this application or in another one, for example, a common application. 18. Adding application prerequisites: Click Application Prerequisites from the application's popup menu. 36 Designing and Managing State Table Applications

55 The system displays the Application Prerequisites window. What is an application prerequisite?: An application prerequisite is another application that contains objects that are necessary for the application to run. After you've traced all the dependencies of the objects in your application, you can add the applications that contain them to the Application Prerequisites list. (When you export the application, the system asks you if you want to export the prerequisite applications too.) 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. Chapter 3. Creating and managing application objects 37

56 22. Deleting application prerequisites: Click the applications that are no longer required. 23. Click Delete. The system removes the applications from the list in the Add Application Prerequisites window. The applications are not deleted from the system. Exporting an application To distribute a voice application to other systems, or to make a backup copy of the application, you need to export all the objects that comprise the application. The export process involves the creation of an export file, in which all the objects in the application are packaged. It is then up to you to send the file to another system by any suitable method. You can export an application from: v The Applications window (from the Application menu or from the applications s popup menu) v The Application window (from the Application menu) v The AIX command line (see dtexport command on page 56) v A script (see dtexport command on page 56). You can export a complete application (full export) or only those objects which have changed since either the last export time or a date and time you specify (delta export), or you can select individual objects to export (partial export). In addition, you can choose to export only binary objects. These choices are explained further in Choosing objects to export and What are text and binary Objects?. Multiple simultaneous import or export operations using dtimport or dtexport from the command line, or using import or export functions from the Application Manager are not allowed. If you attempt to start an export operation while another import or export operation is in progress, the Application Manager will display a warning dialog notifying you that another import or export operation is already in progress. 38 Designing and Managing State Table Applications

57 Note: The export process uses the AIX tar command to create a file in United States Tape Archiver (USTAR) format. This supports file path names with a maximum of 155 characters for the prefix part (the directory name) and a maximum of 100 characters for the name part (the file name itself). 1. From the Welcome window, click on Applications > Applications 2. Selecting the application: Either click the application name in the main Applications 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 Exporting updated objects only: Click Application > Export > Delta. The system displays the Delta Export window: Chapter 3. Creating and managing application objects 39

58 6. Click the appropriate radio button for objects changed since Last Full Export, Last Delta Export, or a Specific Date, and if necessary fill in the date fields. 7. Proceed to step 13 on page 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 for each of the applications. You don t have to export them all. If you are sure that a prerequisite application is already on the target system, click Export > Cancel. All the objects in the application are listed: 40 Designing and Managing State Table Applications

59 This window allows you to drag in any objects that you want to add to the export file, from any other applications. It also allows you to exclude objects from the list, to prevent them from being exported. 9. To remove an object from the list, click it and click Exclude from the popup menu. 10. To add all the objects that are used by an object in the list, click the object and then click Include Dependencies from the popup menu. 11. To add an object from another application to the list, open the other application. Then click the object in the Application window and drag it into the Partial Export window. 12. Exporting: Select Export > Confirm on the Partial Export Preview window to display the Partial Export window. Click the appropriate radio button for Text and Binary objects, or Binary Only. Chapter 3. Creating and managing application objects 41

60 What are text and binary Objects?: Each state table, prompt, and 3270 script comprises a text file and a binary (executable or runtime ) file. You need both files for development, but only the binary file for running applications in production. Select Text and Binary if: v You are exporting to another development system or v You are exporting to a production system but want to ensure that you don t lose the source files. Select Binary Only if: v You are distributing the object to production systems and v You don't want anyone else to see or modify the code. Note: The Object Settings window for each object has a radio button for Do not export when "Binary Only" is selected. Selecting this means that when you select Binary Only, the object is not exported. 13. Specifying where to put the export file: Click the appropriate radio button for media type. If you click File, the system displays the Export File window: 42 Designing and Managing State Table Applications

61 a. Click the directory and select or type in the file name for the export file. b. Click OK. The working dialog is displayed. The progress of the export is displayed on the status line in the Applications window. When the export is completed, the system displays the Export Report window, giving details of what was exported: 14. Saving or printing the export report: If you want to keep the Export Report you can print it or save it in a file. v To print the Export Report, click Print. The report is printed on the printer specified by the Printer Queue system parameter in the WebSphere Voice Response parameter group. Chapter 3. Creating and managing application objects 43

62 v To save a copy of the Export Report, click Save. The system displays the Save Report window: Next Step a. Click the directory and select or type in the file name for the export report file. b. Click OK. The export file is now ready to be transported to another system. Use whichever method you normally use for this (for example, file transfer protocol (ftp)). Exporting one or more objects Although the recommended methods of export are full export and delta export of an application (see Exporting an application on page 38), partial export of one or more objects is also available if necessary. To preserve the integrity of your applications, however, partial export is not recommended. 1. From the Welcome window, click on Applications > Applications 2. Displaying the Object Index: If the Object Index window is not already displayed, click Options > Object Index from the Applications window. 44 Designing and Managing State Table Applications

63 The Object Index window shows a folder for each type of object in the system: The Object Index shows you all the application-related objects in the system, organized into folders. It s another view of the objects in the system, each of which is contained in a single application. In other words, you cannot move objects out of the Object Index into an application: all objects are shown in the Object Index. 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 Object Index window. 5. Click Object > Export > Partial. The system displays the Partial Export window. This window allows you to drag in any objects from any applications. 6. To remove an object from the list, click it and then click Removefrom the popup menu. 7. To add all the objects that are used by an object in the list, click the object and then click Get Dependencies from the popup menu. For guidance, see Choosing objects to export. 8. To add an object from another application to the list, open the other application. Then click the object in the Application window and drag it into the Partial Export window. 9. Exporting binary objects only: Click the appropriate radio button for Text and Binary (executable) objects, or Binary only. For guidance, see Exporting. Chapter 3. Creating and managing application objects 45

64 10. Specifying where to put the export file: Click the appropriate radio button for media type. If you click File, the system displays the Export File window. a. Click the directory and click or type in the file name for the export file. b. Click OK. The working dialog is displayed. The progress of the export is displayed on the status line in the Applications window. Once the export is completed, the system displays the Export Report window, giving details of what was exported. To keep a record of the export, click Print or Save. When you click Print, the report is printed on the printer specified by the Printer Queue system parameter in the WebSphere Voice Response parameter group. When you click Save, the system displays the Save Report window. a. Click the directory and select or type in the file name for the export file. b. Click OK. Next Step The export file is now ready to be transported to another system. Use whichever method you normally use for this (for example, file transfer protocol (ftp)). Importing application objects You can import any file that was exported from a WebSphere Voice Response system using any of the following methods. You can also import all the files that are supplied with WebSphere Voice Response as import files (file names ending in.imp). v The procedure described in Exporting an application on page 38 v The procedure described in Exporting one or more objects on page 44 v 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) 46 Designing and Managing State Table Applications

65 When you import voice prompts or voice directories, you can choose either to replace existing objects of the same name, or to merge them with existing objects. When you choose to merge objects, the objects are replaced if they already exist, and they are added if they do not. For objects other than voice prompts and voice directories, you can only replace them. Multiple simultaneous import or export operations using dtimport or dtexport from the command line, or using import or export functions from the Application Manager are not allowed. If you attempt to start an import operation while another import or export operation is in progress, the Application Manager will display a warning dialog notifying you that another import or export operation is already in progress. Attention: If the imported object belongs to a different application, it is put into an application of that name on the target system, even if the replaced object was in a different application. 1. From the Welcome window, click on Applications > Applications 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 is displayed on the status line in the Applications window. When the Chapter 3. Creating and managing application objects 47

66 import has completed, the system displays the Import Report window: 6. Printing or Saving a Report: If you want to keep a the Import Report you can print it or save it in a file. Click Print. The report is printed on the printer specified by the Printer Queue system parameter in the WebSphere Voice Response parameter group. To keep a record of the import, click Save. The system displays the Save Report window. a. Click the directory and select or type in the file name for the import report file. b. Click OK. 7. Simply importing from tape or diskette: Ensure that the Default Tape Drive or the Default Diskette Drive system parameter in the General parameter group is set as appropriate. 8. Click Application > Import > Merge > Tape or Diskette. The working dialog is displayed. The progress of the import is displayed on the status line in the Applications window. When the import has completed, the system displays the Import Report window. 9. To keep a record of the import, click Save or Print. 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. 48 Designing and Managing State Table Applications

67 The system displays the objects included in the file. 14. Open and close the folders by single-clicking on the folder icon. If you do not want to install all objects, click any object not required, and then click Exclude from the popup menu. The selected objects are removed from the list. (If you remove one by mistake, click Cancel and start over.) Note: For the most efficient application distribution, you are recommended to ensure that the export file contains the correct set of objects and then import all of them, rather than exporting more than you need and then picking the ones you don t want. See Exporting an application on page Click OK. The working dialog is displayed. The progress of the import is displayed on the status line in the Applications window. When the import has completed, the system displays the Import Report window. 16. If you want to keep the Import Report you can print it or save it in a file. When you click Print the report is printed on the printer specified by the Printer Queue system parameter in the WebSphere Voice Response parameter group. When you click Save, the system displays the Save Report window: a. Click the directory and select or type in the file name for the import report file. b. Click OK. Chapter 3. Creating and managing application objects 49

68 17. Checking the objects you are importing from tape or diskette: Ensure that the Default Tape Drive or the Default Diskette Drive system parameter in the General parameter group is set as appropriate. 18. Click Application > Import with Preview > Merge > Tapeor Diskette. The system displays the objects included in the file. 19. Open and close the folders by single-clicking on the folder icon. Click any objects you do not want to import. 20. Click Exclude. The selected objects are removed from the list. (If you remove one by mistake, click Cancel and start over.) 21. Click Import > Confirm. The working dialog is displayed. The progress of the import is displayed on the status line in the Applications window. When the import has completed, the system displays the Import Report window. Done The application objects are now ready to be used in the target system. Migrating from an earlier release of IBM WebSphere Voice Response for AIX As described in the WebSphere Voice Response for AIX: Installation book, there are two methods of migrating applications: v If you used the savedt command to save your WebSphere Voice Response application objects and data before installing WebSphere Voice Response, you must use the restoredt command to bring them into WebSphere Voice Response (see the WebSphere Voice Response for AIX: Installation book for details). v If you exported application objects from IBM WebSphere Voice Response for AIX Version 4.2, you must import them into WebSphere Voice Response Version 6.1, as described in Importing application objects on page 46. In both cases, objects created using IBM WebSphere Voice Response for AIX Version 4.2 are v 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 own applications and move your objects into them (see Creating an application on page 34 and Moving objects from the default or user applications on page 54). 50 Designing and Managing State Table Applications

69 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 52 v 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 52 v When should you export prerequisites along with an application? on page 53 v What happens to duplicate objects? on page 53 v 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 own applications to put the objects in 2. In other words, you can develop and run a voice response service without creating your own application containers. Nevertheless, you will find that applications make management and distribution of objects easier. If you decide to create your own applications after all, follow the instructions in Moving objects from the default or user applications on page 54. What about the integrity of applications that are already in use? Moving objects between applications has no effect on any objects that are in use. However, if you choose to delete an object, you really will be deleting it from the system, and a dialog will ask you to confirm your decision, even if the object is not in use. Similarly, if you import a new version of a state table when that state table is already running (and so is already cached), the running state table is not changed. The new version is used next time you start the application. Where are newly-created or migrated objects put? All application objects in the WebSphere Voice Response system must be in one and only one application. However, objects can arrive in a WebSphere Voice Response system in a variety of ways. Table 2 on page 52 shows which applications these objects are put into. 2. When you put the application into production, it is the application profile that defines the main state table and entry point to the runtime WebSphere Voice Response system. (See Chapter 5, Creating an application profile, on page 89 for more information.) Chapter 3. Creating and managing application objects 51

70 Table 2. Where To find newly-created objects Method of Creating the Object Migrated from IBM WebSphere Voice Response Version 4.2 Imported from another WebSphere Voice Response Version 6.1 system (including application objects supplied with the WebSphere Voice Response product or its features) Created by clicking Object "> New in an Application window Created by clicking the object type (for example, State Tables, from the Applications menu in the Welcome window and then File "> New Created by clicking Object "> New from the Object Index window Application Default The application that contained the object in the other system The current application User Default What happens when you import objects belonging to an application that does not exist on the target system? Whether you re importing an application into a system for the first time, or if you have deleted the application and are importing it again, the answer to this question depends on whether you are importing a file that was the result of: v A full or delta export v A partial export With full or delta export, the application is created in the target system and all the objects are placed within it. With partial export, when the file is imported into another system, WebSphere Voice Response attempts to place each object into the application to which it belonged on the system from which it was exported. If an application with that name does not exist on the target system, the object is not created, and an error is reported. When should you use full export, delta export, and partial export? Use full export the first time you need to copy an application to another system. After the first time, delta export is recommended, because it includes only the objects that have been changed, and therefore reduces the size of the file. Use full export for a complete backup of an application. 52 Designing and Managing State Table Applications

71 Partial export is recommended only for exporting one or a few individual objects. It s not recommended as the normal method of exporting voice application objects: to ensure the integrity of your applications, use delta export instead. When should you export prerequisites along with an application? Prerequisite applications contain objects necessary for the application to run: these may be objects, such as system prompts, that are used by many applications. It s not necessary to export those prerequisite applications unless you know they don t exist on the target system or you know that some of the objects have changed. What happens to duplicate objects? Each object name must be unique across all the applications in a system. This means that you have to be careful when importing an application for the first time. The same applies to using the restoredt command when migrating from a release of IBM WebSphere Voice Response for AIX. Any object already in the target system, with the same name as an object being imported, will be overwritten. What if more than one application needs to use the same object? The application is a container of application objects, which means that each object must be specified in one, and only one, application. In addition, each object must have a unique name, within that type of object, across all applications. It is very likely that some objects will be useful in more than one voice response service: for example, voice segments for commonly-used phrases. Copying them has two disadvantages: storage is used unnecessarily and you have to rename each copy. Instead of copying, you can make an object available to be used by more than one application, by putting it into a common application.a common application is just an ordinary application whose objects are to be used by more than one other application. You then add the common application to the list of application prerequisites for any application that is to use it. When you export any of these applications, the system gives you the opportunity to export the common application at the same time. For example, the cemg application in Figure 5 on page 54 includes all the state tables, and the specific prompts, voice segments, and voice tables used by those state tables; while the common application includes prompts, voice segments, and voice tables that might be used by other applications too. Chapter 3. Creating and managing application objects 53

72 Figure 5. Two applications, one of which contains commonly-used objects Moving objects from the default or user applications If you have just migrated from IBM WebSphere Voice Response for AIX Version 4.2, or for some other reason all your objects are in either the Default application or the User application, you may find it more convenient to sort them out into application packages (for reasons, see Managing application objects efficiently on page 29). The following instructions assume that the source application is the Default application, but they work just as well for the User application or any other application. 1. From the Welcome window, click on Applications > Applications 2. Displaying the Default application: Find the object named Default and double-click on it to open it. The Application (Default) window is displayed. 3. In the Applications window, create your own application, and move objects from the Application (Default) window into the new window, following the instructions in Creating an application on page 34. Hints and Tips: v To select objects that are next to each other, hold down mouse button 1 and drag across the object names. 54 Designing and Managing State Table Applications

73 v v v v To select multiple objects that are not necessarily next to each other, click the mouse button 1 to select one object, and then hold down the Ctrl key while clicking on more objects. Use mouse button 2 to drag the objects across to your application. You can't select objects from more than one folder at a time. You might be wondering why you shouldn't use the Object Index to do this task. You can drag objects from the Object Index to an Application window, but it's harder to keep track of what you've done, because the objects are still displayed in the Object Index after you've dragged them. The Object Index is just an Index. Deleting an application Before you do this, make sure that the application is not a prerequisite of any other application, and make sure that the objects in the application are not used by any other objects. You must first delete or move all the objects from an application before you can delete it. Note: You cannot delete the User, Default, orsystem applications. 1. From the Welcome window, click on Applications > Applications 2. Removing the objects from the application: Double-click on the name of the application. The Application window is displayed. 3. Single-click to open the first folder. 4. Move any objects that you want to keep to another application. 5. If you are sure you don t need some or all of the objects any longer, select them and then click Object > Delete. Click Confirm on the delete confirmation dialog to delete the objects. The selected objects are deleted from the system. 6. Repeat from step 3 for all the other folders in the Application window. The Application window is empty. 7. Removing the application: Click Application > Delete. Note: If the application still contains any objects, the system does not allow you to delete it. 8. Click Confirm on the delete confirmation dialog to delete the application. The selected application is deleted from the system. The dtimport and dtexport commands The dtimport and dtexport commands are fully compatible with the Import and Export options in the windows, but also enable you to: Chapter 3. Creating and managing application objects 55

74 v Distribute the applications to multiple systems using shell scripts. This can automate the process of distributing updated application objects. v Start the dtexport command from the command line on a remote system. This means that you can capture an application from a remote site and examine or debug it at your location. The dtexport and dtimport commands perform most of the same functions as the Export and Import options. The following functions are not supported by the dtexport command: v The option to apply a text or binary selection to all objects in the export list. All objects must be either text or binary. v The option to apply dependencies to selected objects in the export list. All objects must have all or no dependencies. v A method for setting the application profile selection criteria; you must pass the list of profiles to be exported through command line arguments. The following functions are not supported by the dtimport command: v Selective object deletion. You must install all or none of the objects from the import file on the destination system. v Selective object merge. You must merge all or none of the objects that can be merged. Once invoked, dtexport and dtimport do not require any user intervention. They can be started either from within a shell script, or by typing the commands directly on the AIX command line. Starting the programs from within shell scripts gives a lot of power to the user because they can have the programs executed on remote machines and as a part of more complex operations. Because the command-line utilities are fully compatible with the options in the windows, you can use the dtimport command to import files that were exported by the Export option, and you can use the Import option to import files that were exported by the dtexport command. dtexport command Purpose Exports application objects into application or partial-export packages. Prerequisites v You must be logged onto AIX as dtuser. v WebSphere Voice Response must be running. 56 Designing and Managing State Table Applications

75 Syntax dtexport [-dev device -ffilename -t -D] [-x] [-b] [-appl application [-delta [-since yyyymmddhhmmss]]] [-stab statetable...] [-pdir promptdir...] [-vdir voicedir...] [-vtab voicetable...] [-3270 server...] [-cs server...] [-prof profileid...] [-sclass class...] Flags -dev device Export on to the specified device. The device can be either a fully-qualified AIX file name or a device path (for example, /dev/rmt0). -f Export into the AIX file specified as filename. The file name must not be longer than 100 characters. You can also specify the path to the file. The path name must not be longer than 155 characters. -t Export on to the tape drive specified in the Default Tape Drive system parameter. -D Export on to the diskette drive specified in the Default Diskette Drive system parameter. -x Extract all dependencies of the selected objects, and add them to the package. This option is not valid if you also specify the -appl option. If you do not specify the -x option, only those objects specified on the command are included in the package. -b Export only the binary format of those objects that have both a text and a binary form (that is, state tables, prompts, and 3270 scripts). -appl application Specifies the name of the application to be exported. This option cannot be specified in conjunction with the object type options described below. -delta The application objects to be exported are only those that have been modified since a certain date. If you do not specify the -since option, Chapter 3. Creating and managing application objects 57

76 this date is the date of the previous export. If you do specify the -since option, the date you supply is used. This option is valid only you also specify the -appl option. -since yyyymmddhhmmss Only those objects in the specified application that have been modified since the time yyyymmddhhmmss are to be exported. This option is valid only if the -appl and -delta options are also specified. -stab statetable... Specifies a space-delimited list of state tables that are to be exported. This option is not valid if -appl is also specified. -pdir promptdir... Specifies a space-delimited list of prompt directories that are to be exported. This option is not valid if -appl is also specified. -vdir voicedir... Specifies a space-delimited list of voice directories that are to be exported. This option is not valid if -appl is also specified. -vtab voicetable... Specifies a space-delimited list of voice tables that are to be exported. This option is not valid if -appl is also specified 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 be exported. This option is not valid if -appl is also specified. -prof profileid... Specifies a space-delimited list of application profile IDs that are to be exported. This option is not valid if -appl is also specified. -sclass class... Specifies a space-delimited list of subscriber classes that are to be exported. This option is not valid if -appl is also specified. Return values 0 Success <>0 Failure Usage notes v Multiple simultaneous import or export operations using dtimport or dtexport from the command line, or using import or export functions from the Application Manager are not allowed. If you attempt to start an export 58 Designing and Managing State Table Applications

77 operation while another import or export operation is in progress, the dtexport command will return an error message notifying you that another import or export operation is already in progress, and the command will return an exit code of 2. Examples To export objects of a specified type (profiles, in this example) to a file called /usr1/dtuser/profiles.imp: dtexport -dev /usr1/dtuser/profiles.imp -prof To export a state table and all its dependents to a file called /usr1/dtuser/stbl.imp: dtexport -dev /usr1/dtuser/stbl.imp -x -stab My_State_Table To export a combination of objects without their dependents to a tape: dtexport -t -stab Table1 Table2 -pdir Pdir1 -vdir Vdir1 Vdir2 Vdir2 To export a complete application called Sports_Results : dtexport -dev /tmp/sports.imp -appl Sports_Results To export only those objects in the Sports_Results application that have changed since the last export: dtexport -dev /tmp/sports.imp -appl Sports_Results -delta To export only those objects in the Proto application that have changed since a specific date: dtexport -dev /tmp/proto.imp -appl Proto -delta -since dtimport command Purpose Imports application or partial export packages Prerequisites v You must be logged on to AIX as dtuser. v WebSphere Voice Response must be running. Syntax dtimport [-dev device -ffilename -t -D] [-mp] [-mv] Chapter 3. Creating and managing application objects 59

78 Flags -dev device Import from the specified device, which either be a fully-qualified AIX file name or a device path (for example, /dev/rmt0). -f Import from the AIX file specified as filename. -t Import from the tape drive specified in the Default Tape Drive system parameter. -D Import from the diskette drive specified in the Default Diskette Drive system parameter. -mp -mv Specifies that any prompt directories in the export package will be merged into the corresponding prompt directory on the target system (if it exists). This means that prompts will be replaced if they already exist, and added if they do not. Specifies that any voice directories in the export package will be merged into the corresponding voice directory on the target system (if it exists). This means that voice segments will be replaced if they already exist, and will be added if they do not. Return values 0 Success <>0 Failure Usage notes v Multiple simultaneous import or export operations using dtimport or dtexport from the command line, or using import or export functions from the Application Manager are not allowed. If you attempt to start an import operation while another import or export operation is in progress, the dtimport command will return an error message notifying you that another import or export operation is already in progress, and the command will return an exit code of 2. Examples To import the objects contained in the file called /usr1/dtuser1/sports.imp: dtimport -dev /usr1/dtuser1/sports.imp To import the objects from a on a diskette and merge all matching voice directories and prompt directories: dtimport -D -mp -mv 60 Designing and Managing State Table Applications

79 Chapter 4. Overview of application objects Application objects were introduced briefly in the WebSphere Voice Response for AIX: General Information and Planning book, and are described in more detail in the following sections. You'll need the procedural and reference information in the WebSphere Voice Response for AIX: Application Development using State Tables; WebSphere Voice Response for AIX: 3270 Servers; and WebSphere Voice Response for AIX: Custom Servers books when you come to create your own objects to implement a voice response service. State tables A state table is a sequence of states, each of which performs a specific action, which can have one or more possible results. During a telephone call, the voice application progresses through the states, performing the actions in turn. The result of each action determines the next state to go to. See Table 3 on page 68 for an example of a state table. A state table can invoke a nested state table to perform a set of actions before returning control to the invoking state table. The state table can invoke different state tables depending on a condition, such as the response of the caller to a previous prompt. State table actions There is a range of state table actions, from very general (such as AssignData, which performs a variety of computational functions) to very specific (like ControlMusic, which is used to turn up or down the volume of background music). Because the general actions can be combined in so many ways, the following list may not be exhaustive, but it does give a goal-oriented overview of which action to choose to perform application functions. Telephony activity Task Respond to a ringing line (incoming call) Make an outbound call Send a set of numbers, a hook flash, or a ground key signal to the switch State Table Action AnswerCall MakeCall Dial Copyright IBM Corp. 1991,

80 Task Detect the presence of a dial tone Transfer a caller to an agent or another caller Reconnect a caller to the voice application (for example, if a TransferCall failed) Disconnect a caller State Table Action Dial TransferCall ReconnectCall TerminateCall Voice segments Task Record a segment of voice data Store a segment of voice data in a voice directory Remove a segment of voice data Play a prompt, which may include one or more prerecorded voice segments Play a single segment of prerecorded voice data State Table Action RecordVoiceSegment SaveVoiceSegment DeleteVoiceSegment PlayPrompt PlayVoiceSegment Output to the caller Task Play a prompt, which may include one or more prerecorded voice segments Play a single segment of prerecorded voice data Play speech from a text-to-speech server, database server, or another WebSphere Voice Response system Play voice data sent from another WebSphere Voice Response system and received by a custom server Play a pacing or other feedback tone State Table Action PlayPrompt PlayVoiceSegment PlayVoiceFromHost PlayVoiceFromHost PlayBeep 62 Designing and Managing State Table Applications

81 Background music Task Start or stop playing a background music tune Turn the volume of background music up or down State Table Action ControlMusic ControlMusic Key input from the caller Task Get a single key from the caller Get multiple keys from the caller, as digits Get multiple keys from the caller, as digits or letters Use keys pressed by the caller to retrieve data from a 3270 server or custom server Retrieve an application profile, using keys pressed by the caller Check the password keyed by the caller with the password defined in the application profile specified by SV20 for the mailbox ID specified by SV32 State Table Action GetKey GetData GetText GetFindData GetFindName GetPassword Program logic and flow of control Task Wait for a specified period of time Wait until one of a number of events occurs Log an event Compare one value with another value Select the next state to go to on the basis of the value of a character variable Invoke another state table State Table Action DoNothing WaitEvent LogEvent EvaluateData Case InvokeStateTable Chapter 4. Overview of application objects 63

82 Task Start communication with a custom server Start communication with a 3270 server Send data to a custom server Send data to a 3270 server Receive data items and return codes, from a custom server Receive data items and return codes, from a 3270 server Find out it there is enough storage available in the WebSphere Voice Response file system for an application to execute as planned State Table Action OpenHostServerLink OpenHostServerLink SendData SendData ReceiveData ReceiveData CheckStorage Computation and string handling Task Define a constant Assign a value to a variable Add two numbers and assign the result to a variable Subtract one number from another and assign the result to a variable Multiply one number by another and assign the result to a variable Divide one number by another and assign the result to a variable Divide one number by another and assign the remainder to a variable Assign the absolute value of a number to another variable State Table Action AssignData (Assign) AssignData (Assign) AssignData (Add) AssignData (Subtract) AssignData (Multiply) AssignData (Divide) AssignData (Modulus) AssignData (Absolute Value) 64 Designing and Managing State Table Applications

83 Task Truncate one number by the length specified by another and assign the result to a variable Round one number at the digit specified by another and assign the result to a variable Concatenate one character string to another and assign the result to a variable Take a specified number of characters from the beginning of one character string and assign them to a variable Take a specified number of characters from the end of one character string and assign them to a variable Take the character that occurs in a specified position of one character string and assign it to a variable Search for a specified character string in another character string and assign the position of it in the second string to a variable Count the number of characters in a character string and assign the result to a variable Convert all the characters in a string to uppercase, and assign the result to a variable Convert all the characters in a string to lowercase, and assign the result to a variable Remove a tag string designated by a tag label Remove the attribute substring Find a tag label and append the corresponding tag string to the result Find a tag and attribute substring and assign the attribute value to a variable Find a tag label and assign its value to a variable State Table Action AssignData (Truncate) AssignData (Round) AssignData (Concatenate) AssignData (Left) AssignData (Right) AssignData (Index) AssignData (Search String) AssignData (Length) AssignData (Uppercase) AssignData (Lowercase) AssignData(RemoveTag) AssignData(RemoveAttribute) AssignData(GetTag) AssignData(GetAttributeValue) AssignData(GetTagValue) Chapter 4. Overview of application objects 65

84 Task Build a tag string and assign it to a variable Build an attribute and assign it to a variable Find and replace a tag value State Table Action AssignData(PutTag) AssignData(PutAttribute) AssignData(ChangeTagValue) Voice mailboxes Task Set or change the attributes of a voice mailbox State Table Action UpdateProfile Voice messages Task Record a new voice message Add more to the beginning of a voice message Add more to the end of a voice message Set or change the attributes of a voice message Send a voice message to the mailbox specified by the application profile ID and mailbox ID Retrieve all voice messages of a specified type for the application profile specified by SV20 and mailbox ID specified by SV32 Play a voice message from a mailbox Save a voice message, which has been retrieved using CheckVoiceMessages, in the mailbox for later retrieval Play back a voice message which has just been recorded Remove a voice message previously retrieved using CheckVoiceMessages State Table Action RecordVoiceMessage RecordVoiceMessage RecordVoiceMessage ChangeMessageAttributes SendVoiceMessage CheckVoiceMessages PlayVoiceMessage SaveVoiceMessage PlayVoiceMessage DeleteVoiceMessage 66 Designing and Managing State Table Applications

85 Distribution lists Task Retrieve names of all recipients on a specified distribution list for a specified application profile and mailbox ID Retrieve names of all distribution lists for a specified application profile and mailbox ID Add a mailbox to a distribution list Add a distribution list to a distribution list Remove a name from a distribution list Remove a distribution list Copy a distribution list Append a distribution list to another distribution list State Table Action GetDistributionList GetDistributionList UpdateDistributionList UpdateDistributionList UpdateDistributionList UpdateDistributionList UpdateDistributionList UpdateDistributionList Audio names Task Record an audio name Store the audio name for the application profile and mailbox ID Play the audio name of the specified application profile and mailbox ID Remove the audio name of the specified application profile and mailbox ID State Table Action RecordAudioName SaveAudioName PlayAudioName DeleteAudioName Greetings Task Record a greeting State Table Action RecordUserGreeting Chapter 4. Overview of application objects 67

86 Task Store the greeting for the specified application profile and mailbox ID Play the greeting associated with the specified application profile and mailbox ID Remove the greeting specified by system variable SV102 State Table Action SaveUserGreeting PlayUserGreeting DeleteUserGreeting Endings Task Terminate a nested state table and return to the invoking state table Terminate a link with a custom server Disconnect a caller Terminate an application and clean up all resources State Table Action ExitStateTable CloseHostServerLink TerminateCall CloseEverything Example state table Table 3. Example state table. State Table Name: Simple_Sample Prompt Directory: Simple_Prompts Description: Account balances and interest rates State Label Action Parameter Description Possible Results Next State Start AnswerCall 1 None Succeeded Not ringing Welcome Exit 68 Designing and Managing State Table Applications

87 Table 3. Example state table (continued). State Table Name: Simple_Sample Prompt Directory: Simple_Prompts Description: Account balances and interest rates Welcome PlayPrompt Prompt name (plays segment 1) Succeeded Line Problem Nothing Played Caller Hung Up Options Exit Thanks Exit Options PlayPrompt Prompt name (plays segment 2) Succeeded Line Problem Nothing Played Caller Hung Up Retrieve Exit Thanks Exit Retrieve GetKey Caller s input (variable) Valid input Invalid input No input Caller hung up Check Options Options Exit..... Thanks PlayPrompt Prompt name (plays segment 15) Succeeded Line Problem Nothing Played Caller Hung Up Exit Exit HangUp Exit Error PlayPrompt Prompt name (plays segment 16) Succeeded Line Problem Nothing Played Caller Hung Up Options Exit HangUp Exit Chapter 4. Overview of application objects 69

88 Table 3. Example state table (continued). State Table Name: Simple_Sample Prompt Directory: Simple_Prompts Description: Account balances and interest rates HangUp TerminateCall Succeed Exit Exit CloseEverything 1. The AnswerCall statement is required only for using the Debug option in the state table window. The call has already been answered by the Incoming_Call state table: see How does WebSphere Voice Response answer an incoming call? on page 136. State table variables and parameters WebSphere Voice Response includes three types of variable: v System variables v Local variables v Input parameters Use the AssignData action to set the value of a variable and the EvaluateData action to check the value. System variables System variables are global variables predefined by WebSphere Voice Response; they are available to any WebSphere Voice Response state table or prompt, but not to 3270 servers or custom servers. There are a large number of system variables, and they are documented in the WebSphere Voice Response for AIX: Application Development using State Tables book. 70 Designing and Managing State Table Applications

89 Figure 6. System variables In the window for selecting system variables (shown in Figure 6), the variables are organized into groups, and listed by names that reflect those groupings. Each system variable also has a shorter numeric identifier preceded by SV. For example, the System : Call Info : Called number system variable (SV185) holds the number dialed by the caller (the called number passed by the switch), and the System : Call : Channel number system variable (SV165) holds the logical channel number of the channel currently in use by the application. The values of some system variables are read-only (RO) and cannot be changed by an application; other system variables are read-write (RW) and their values can be set using the AssignData action. Global user variables WebSphere Voice Response supplies 60 read-write system variables for your use. These include 45 string variables (SV51 through SV80 and SV82 through SV96), each of which can contain up to 3583 characters, and 58 numeric variables (SV241 through SV298), which are implemented as 32-bit signed integers. These variables, like other system variables, are global within a state table and all the state tables nested within it. They are not accessible by state tables running on other channels. When the main state table starts, the string variables are initialized to null and the numeric variables are set to 0. Chapter 4. Overview of application objects 71

90 Local variables Local variables are variables that you define for use by a single state table. You provide the names that identify each local variable and define the type of the variable as a string of characters or as a number. Local variables are not permanent. When the application is finished using a state table, it destroys the local variables you defined for that state table. The next time the application is invoked and uses the state table, it recreates the local variables. The information the local variable contains is accessible to any action in the state table in which you defined the variable. But only that state table can access or alter the contents of the variable. If you use an InvokeStateTable action to call another state table, the local variables defined for the invoking state table are not available to the invoked state table, unless they are passed as parameters. Input parameters Input parameters are used to define variables received by programs, including prompts, 3270 scripts, custom servers, or state tables, from the invoking state table. When you use the InvokeStateTable action to invoke a state table, parameters are passed by reference to the invoked state table: in other words, they are global variables accessible to, and modifiable by, both the invoking and invoked state tables. To pass parameters from a state table to another state table, prompt, custom server or 3270 server, click the Parameters pushbutton in the InvokeStateTable window, the PlayPrompt window, or the SendData and ReceiveData windows. This displays a window that lists the parameters required by the invoked state table, prompt, custom server or 3270 server, as shown in Figure 7 on page 73. Parameters are passed by value to prompts, custom servers, and 3270 servers. 72 Designing and Managing State Table Applications

91 Figure 7. A list of parameters to be passed to a prompt Note: No parameters can be passed from an application profile to a state table. State table action parameters Some state table actions require parameters to tell them what to do. For example, the PlayPrompt has a Force Play parameter that specifies that the prompt must be played through to the end. Some parameters can be constant values or variables. Returning data to the state table An invoked state table can return data to the invoking state table by assigning a new value to an input parameter. Because parameters are passed by reference to state tables, the new value will be available to the invoking state table. A prompt cannot return data to the state table, but the RETURN and ABORT statements set the value of the System : PlayPrompt status system variable (SV130), which can then be read by the state table. A 3270 server or custom server can return data to the state table using parameters on the ReceiveData action. Possible results Each state table action can have one or more possible results. The possible results of each action are predefined by WebSphere Voice Response. For example, the PlayPrompt action has four possible results: v Succeeded v Line problem v Nothing played v Caller hung up Chapter 4. Overview of application objects 73

92 For each result, the state table needs to know what to do next. For each possible result, of each state in your state table, you have two choices: 1. Fall through to the next state in the state table 2. Go to another state in the state table When you have identified the state table actions needed for your application, check the state table action descriptions in the WebSphere Voice Response for AIX: Application Development using State Tables to make sure that your design accounts for all possible results. You may need to modify your design if you find you have not allowed for some possible results. Decide how you want the application to handle each possible result and create the state you need. When interpreting results, you may find it useful to look at some of the system variables, such as the System : Action additional information system variable (SV180), which gives you additional information about some actions. (And note that SV180 is reset after every action, including DoNothing, so you should check its value immediately following the action.) Entry points You must define at least one entry point at which execution of the state table begins. If the state table always starts at the first state and executes through to the last state, there will be only one entry point. However, you can start execution at any state by defining entry points where applicable. When you call a state table from an application profile or another state table, you specify the entry point at which execution is to start. Prompts Prompts are used in state tables to define what a caller hears. A prompt not only identifies the words the caller hears, but also defines the logic of when and how the words are played. A prompt can be simple or complex, depending on whether the prompt always plays the same words or whether the prompt logic defines conditions for playing different phrases. For example, you may want an application to repeat the items that the caller has ordered, so the prompt would construct the utterance with phrases representing those items: you ordered a bagel with sour cream and lox, and a croissant with Canadian ham and salad. Prompts are constructed using the prompt statements described in the WebSphere Voice Response for AIX: Application Development using State Tables. The variables used by prompt statements work exactly the same way as state table variables. Generally, a state table passes input parameters to a prompt which it then uses to select the voice segments to play to the caller. 74 Designing and Managing State Table Applications

93 The set of prompts that are used by a particular state table are grouped in a prompt directory. All prompts used by a state table must be in the same prompt directory. Multiple state tables can use the same prompt directory. System prompts The System prompt directory contains the system prompts, which are included with WebSphere Voice Response when the system is installed. The system prompts do not operate any differently from the prompts you create. The only difference between system prompts and the prompts you write is that the system prompts are already written for you. If a state table uses the System prompt directory, the state table can call a system prompt by supplying the prompt name to the state table action that plays the prompt as a parameter. If a state table uses its own prompt directory, you can create new prompts that call the system prompts (using the SYSPROMPT prompt statement). Each system prompt accepts a number as input and plays a prompt that speaks the number as one of the following: v An integer between -999 and 999 v An integer between and v A real number v An ordinal number v The date (in U.S. format) v The time (in 12-hour format) v An amount of currency (in U.S. currency) v A telephone number For example, if an application passes the number to the Currency prompt, the phrase that results is twelve dollars and thirty-four cents. However, passing the same number to the Real_number prompt results in the phrase twelve and thirty-four hundredths. Note that although very large numbers can be stored and used by WebSphere Voice Response (using multiple precision format to store large numbers and floating point numbers), the system prompts cannot play numbers larger than the maximum size defined by the prompts. To play very large numbers, you may need to create your own system prompts. The Small_number prompt The Small_number system prompt plays an integer between -999 and 999 as a numeric quantity. Numbers larger than 100 are played without and between the word hundred and any of the digits. For example, an input of 123 produces the phrase one hundred twenty-three. Chapter 4. Overview of application objects 75

94 The small number prompt includes prompt statements that reference the Numbers and the Divisor voice tables. The Whole_number prompt The Whole_number system prompt plays a positive or negative integer of up to 12 digits as a numeric quantity. The prompt does not insert and between any of the units of measure or digits. For example, an input of produces the phrase one million one hundred three thousand two hundred ninety-four. Whole_number includes a prompt statement that references the Divisor voice table. The Real_number prompt The Real_number system prompt plays a positive or negative real number as a numeric quantity. The prompt expresses fractional amounts in one of two ways, depending on the amount: 1. If the number is expressed up to three decimal places (tenths, hundredths, thousandths), it is played as (number) and (number) (unit of measure). For example, an input of 1.2 produces the phrase one and two tenths. An input of 1.23 produces the phrase one and twenty-three hundredths. 2. If the number is expressed to more than three decimal places, it is played as (digit) point (digit) (digit) (digit) (digit). For example, an input of produces the phrase one point two three four five. Note that you can change the character to be used for the decimal place by modifying the System : MPN : Decimal point character system variable (SV168). The default character is the period (.), which plays the word point. The Ordinal prompt The Ordinal system prompt plays a positive integer of up to 12 digits as an ordinal number. For example, an input of 256 produces the phrase two hundred fifty-sixth. Ordinal includes prompt statements that reference the Numbers, Divisor, and Ordinal voice tables. The Date prompt The Date system prompt plays 8-digit input (yyyymmdd) as the month, day, and year. The convention followed is to play the name of the month, followed 76 Designing and Managing State Table Applications

95 by the day as an ordinal number, followed by the year as two numbers. For example, an input of produces the phrase January thirteenth, nineteen ninety-three. Date includes a prompt statement that references the Month of Year voice table. The Time prompt The Time system prompt plays 6-digit input (hhmmss) as two numbers followed by AM or PM. The seconds value is not played. If the minutes input is 00, Time plays o clock following the hours value. Although the input to Time is in 24-hour clock time, Time plays the time using a 12-hour clock. Noon is 12 PM and midnight is 12 AM (both and are interpreted as midnight). For example, an input of produces the phrase four oh one PM. An input of produces the phrase eleven o clock AM. Time includes prompt statements that reference the Numbers and Time of Day voice tables. The Currency prompt The Currency system prompt plays an input string as an amount of dollars and cents. For example, an input of produces the phrase one hundred twenty-three dollars and forty-five cents. Note that you can change the character to be used for the decimal place by modifying the System : MPN : Decimal point character system variable (SV168). The default character is the period (.). The Phone prompt The Phone system prompt plays an input string as a string of digits. For example, an input of produces the phrase five five five one two one two. System prompts in languages other than U.S. English The system prompts supplied with WebSphere Voice Response produce phrases that are spoken in U.S. English. In addition, system prompts for other national languages are supplied in the /usr/lpp/dirtalk/sw/samples directory (if you install the appropriate optional filesets, which are listed in the WebSphere Voice Response for AIX: Installation book): v Belgian Dutch Chapter 4. Overview of application objects 77

96 v Brazilian Portuguese (for more information, see System prompts in Brazilian Portuguese on page 80) v French (for more information, see System prompts in French ) v German v 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 samples include: v Prompts to be called by the Currency prompt (named xxx_frs) v Currency voice directory (named Monnaie) v Currency voice tables (named xxx_frs) v Phone numbers voice table (named Telephone) Each French system prompt accepts a number as input and plays a prompt that speaks the number as one of the following : v An integer between 1 and v A real number v A date (in French format: DD MM YYYY) v A time (in French format: HH MM) v A phone number (in French format : nn nn nn nn) v An amount of currency (in French format, using Francs and Centimes) Note that if you delete the French language from the system, the specific French system prompts (Small_number_frs, Whole_number_frs, and Real_number_frs) are not removed. You must remove each prompt individually. The standard French system prompts are : Small_number Plays an integer between -999 and 999. For example, 121 is spoken as "cent... vingt et un." Small_number includes prompt statements that reference the Numbers and the Numbers_c voice tables. Whole_number Plays a positive or negative integer. 78 Designing and Managing State Table Applications

97 For example, is spoken as "douze mille... trois cent... quarante cinq." Whole_number includes prompt statements that reference the Numbers, the Numbers_c, and the Numbers_m voice tables. Real_number Plays a positive or negative number. For example, 1,23 is spoken as "un... virgule... vingt trois." Date Plays 6 digits (DDMMYY) or 8 digits (DDMMYYYY) as day, month, and year. For example, is spoken as "Le premier... janvier... mille... neuf cent... quatre vingt quatorze." Date includes prompt statements that reference the Month of Year and the Day of Month voice tables. Time Plays 6 digits (HH MM SS) as hour and minutes. For example, 09:30 is spoken as "neuf heures... trente minutes." Time includes prompt statements that reference the Time of Day voice table Phone Plays 8 digits as 4 numbers For example, is spoken as "quarante neuf... zero cinq... soixante dix... zero zero." Phone includes prompt statements that reference the Telephone voice table. Currency Plays input as Francs and Centimes associated with the following specific French system prompts. The French system prompts called by the Currency prompt are: Small_number_frs Plays an currency integer between -999 and 999. For example, 121 is spoken as "cent... vingt et un francs." Small_number_frs includes prompt statements that reference the Numbers the Numbers_c, the Numbers_frs and the Numbers_cfrs voice tables. Whole_number_frs Plays a positive or negative currency integer. For example, is spoken as "douze mille... trois cent... quarante cinq francs." Chapter 4. Overview of application objects 79

98 Whole_number_frs includes prompt statements that reference the Numbers, the Numbers_c, the Numbers_m, the Numbers_frs, the Numbers_cfrs, and the Numbers_mfrs voice tables. Real_number_frs Plays a positive or negative currency number. For example, 1,23 is spoken as "un franc... vingt trois... centimes." Voice directories for French system prompts To run the French system prompts, there are two voice directories: v The System voice directory contains numbers: Units 1 through 99 Hundreds 100 through 900 Thousands 1000 through 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 Francs Million de Francs, milliard de Francs System prompts in Brazilian Portuguese Brazilian Portuguese is a user-defined language, so before importing the Brazilian Portuguese samples you must define a language called Brazilian Portuguese with the language code 213. For information on defining additional languages, see the WebSphere Voice Response for AIX: Configuring the System book. Changing the system prompts for your language For voice response services in languages other than those described in this book, you may need to modify the system prompts to use the correct syntax and conventions. The information in the following sections should help you determine whether you need to change the prompts. The number prompts The English language constructs numbers by concatenating words for smaller numbers and units of measure, as appropriate. All of the number prompts (Small_number, Whole_number, Real_number, Ordinal, and Phone) create the number to be spoken by analyzing the input for the components and then concatenating the voice segments that play each component. 80 Designing and Managing State Table Applications

99 For example, the number 81 is determined to be eighty and one and spoken by playing eighty followed by the voice segment that says one. The number 1204 is spoken by playing one followed by thousand followed by two followed by hundred followed by four. If the language spoken in your location does not construct numbers by following a concatenation pattern similar to the pattern in U.S. English, you may need to modify the number prompts to account for the differences. The System voice directory includes only the unique numbers and the building block components needed by U.S. English. These are the numbers 0 (as both zero and oh ) through 31, 40, 50, 60, 70, 80, 90, and 100. The System voice directory also includes the word point for use in decimal numbers, and the units of measure hundred, thousand, million, and billion. Besides recording the voice segments that play these numbers in a different language, you may need to record some additional voice segments. All of the number prompts use Small_number to play numbers from -999 through 999. The Date prompt Date plays the month first. However, the convention in many other languages is to play the day first. Date also plays the day of the month as an ordinal number (for example, first, sixteenth, twenty-second ) using the Ordinal system prompt. If the convention in your location is to play the day of the month as a cardinal number (for example, one, sixteen, twenty-two ), consider using Small_number to play the day. Date uses Small_number to express the year as the number of the decade, followed by the number of the year within the decade. If the convention in your location is to express the year in a different format, consider using a system prompt such as Whole_number to play the year. You will also need to change the logic in Date that parses and plays the input. The Time prompt Time accepts input in 24-hour clock time but plays the time according to a 12-hour clock. In addition, the logic in Time divides the day into two parts: morning (AM) and afternoon-evening (PM). The convention at your location may be to divide the day into more than two parts. Chapter 4. Overview of application objects 81

100 If expressions of time in your location are in 24-hour clock time, you will need to modify Time. You will also need to modify the prompt if your day has more (or less) than two parts. And since the System voice directory only includes four voice segments for expressing the time of day ( AM, PM, hours, and o'clock ), you may need to record some additional voice segments. Note that Time does not play seconds, although they are required as input. Time uses the following 24-hour clock conventions: v is 12 a.m. v is 12 a.m. v is 12 p.m. The Currency prompt Currency plays currency as a number of dollars followed by a number of cents. In addition to rerecording the units of currency, you may need to modify the prompt to play smaller units first. Voice segments A voice segment defines the spoken words (for example, hello or good morning ) or sounds (for example, music) available to WebSphere Voice Response voice applications. A segment can be a single word, a sound, a phrase, one or more sentences, or a combination of words and sounds. A segment can also be silence. System voice segments in several languages, including U.S. English, are provided with WebSphere Voice Response, and listed in the WebSphere Voice Response for AIX: Application Development using State Tables. The same voice application can play voice segments in different languages, without modification. The language used when the application is run in a production environment is specified in an application profile, and you can have one application profile for each language. Voice directories Voice segments are stored in voice directories. Prompts can use segments from any voice directory. Note: You are recommended to specify the voice directory name in state table actions, rather than the voice directory ID, which is retained only for compatibility. If you use don t use the name, WebSphere Voice Response cannot identify a voice directory as a dependent object for export. 82 Designing and Managing State Table Applications

101 Voice tables Segments can also be logically grouped in a voice table, so that you can reference the segments using an indexing mechanism. For example, you can use the numbers 1 through 12 to index the months of the year, and the numbers 1 through 7 to index the days of the week. Voice tables can help you find out what segments have been recorded and where they are stored. The segments in a voice table can be stored in the same voice directory or in different directories. Voice tables include a description of each voice segment and indicate where each segment is stored. System voice segments The system voice segments are a group of voice segments that are delivered with WebSphere Voice Response. They include all of the voice segments needed by the system prompts to play numbers, letters, days of the week, and other common terms. The system voice segments are stored in the System voice directory and should be recorded again to match the voice used in the voice segments that you create. Some of the system prompts reference the system voice segments using the Voice prompt statement. Others use the Table prompt statement. The voice tables referenced are all system voice tables. System voice tables The system voice tables catalog the system voice segments in groups such as all the letters of the alphabet, numbers, and days of the week. You can create additional voice tables as you need them, or as you record more voice segments, you can add them to the existing voice tables. The names of several of the system voice tables are referenced by other WebSphere Voice Response objects. For example, the DIGITS prompt statement uses the Numbers Voice Table Name system parameter, which has a default value of Numbers. If you decide to change the names of the system voice tables, you need to make the corresponding changes wherever the tables are referenced. The Alphabet voice table The Alphabet voice table contains the voice segments that play the letters of the alphabet ( A through Z ). Alphabet is the value of the Alphabet Voice Table Name system parameter, which is part of the Application Server Interface parameter group. The Alphabet Voice Table Name parameter in the Application Server Interface group specifies the name of the voice table that the CHARACTERS prompt statement uses to play alphabetic characters. The default value is Alphabet. Chapter 4. Overview of application objects 83

102 You can create additional voice tables for the CHARACTERS prompt statement to use, in which case, you need to set SV192 to specify the name. The day of month voice table The day of month voice table (Day_Of_Month) contains the voice segments that play the days of the month as ordinal quantities ( first through thirty-first ). The day of week voice table The day of week voice table (Day_Of_Week) contains the voice segments that play the days of the week ( Sunday through Saturday ). The divisor voice table The divisor voice table contains the voice segments that play the divisor portion of a numeric quantity ( hundred, thousand, million, billion, tenths, hundredths, thousandths, millionths, billionths ). The month of year voice table The month of year voice table (Month_Of_Year) contains the voice segments that play the months of the year ( January through December ). The noise voice table The noise voice table contains the voice segments for a beep and a warning tone. The numbers voice table The numbers voice table contains the voice segments that play the numbers zero through twenty, and multiples of ten from thirty through ninety. Numbers is the value of the Numbers Voice Table Name system parameter, which is part of the Application Server Interface parameter group. The Numbers Voice Table Name parameter in the Application Server Interface group specifies the name of the voice table that the DIGITS prompt statement uses to play numeric digits. The default value is Numbers. You can create additional voice tables for the DIGITS prompt statement to use, in which case, you need to set SV193 to specify the name. 84 Designing and Managing State Table Applications

103 The ordinal voice table The ordinal voice table contains the voice segments that play numbers as ordinal quantities ( first through thirty-first, and multiples of ten from fortieth through ninetieth ). The system messages voice table The system messages voice table (System_Msgs) contains the voice segment that plays the system messages. For example, We are experiencing technical difficulties. The time of day voice table The time of day voice table (Time_Of_Day) contains the voice segments that play time quantities ( AM, PM, O Clock, hours, oh, minutes, seconds ). The time of week voice table The time of week voice table (Time_Of_Week) contains the voice segments that play yesterday, today, and tomorrow. The tone voice table The tone voice table contains the voice segments for ringback tone, busyback tone, and fast busyback tone and custom servers Custom servers and 3270 servers are programs that provide a bridge between WebSphere Voice Response and data that resides outside WebSphere Voice Response. The data can be on a remote host computer or on the same pseries computer workstation as your WebSphere Voice Response software. The data can include business information held in a database, or digitized voice data. v A custom server is a program, using C language or C++ language, that provides an interface between data on host computers and WebSphere Voice Response, or performs other processes, such as speech recognition and text-to-speech, generation of fax output, or coordinated call and data transfer. A custom server that uses the signaling interface, a specialized library of C subroutines, is known as a signaling process. This is used to manage an external signaling device that controls or monitors telephony channels. For more information, see the WebSphere Voice Response for AIX: Programming for the Signaling Interface book. Chapter 4. Overview of application objects 85

104 v A 3270 server lets you access data on remote 3270 host computers. If you have existing 3270 host applications that retrieve data needed by your WebSphere Voice Response applications, you can create a 3270 server to obtain this data. Access to remote data means that your voice applications can use this data to perform a variety of tasks, such as: v Read a file or database to retrieve information that a caller needs v Maintain or manipulate files based on a caller's request v Obtain information from a combination of sources and business applications on other host computers v Call another program to perform any predefined process v Perform calculations and return the result to the state table v Generate business statistics based on telephony activity v Recognize spoken words using an external speech recognition server v Speak words created by an external text-to-speech server or sent from another WebSphere Voice Response system v Generate fax output. Both 3270 servers and custom servers must be invoked from a state table, which controls the dialog with the caller servers A 3270 server consists of screen definitions and logic in the form of scripts screen definitions The screen definitions are images of the screens used by a host application. A 3270 server uses these screen images to interact with the host application by sending data to the application in screen input fields, and reading the data retrieved by the application from screen output fields. When a voice application sends a request to a 3270 server, the 3270 server sends the appropriate screen definitions to the host application to start the application, provide input data, and retrieve output data. It then sends the output to the calling voice application scripts The logic of a 3270 server is defined in script language, a set of statements that instructs the server what to do. The WebSphere Voice Response for AIX: 3270 Servers book contains descriptions of each WebSphere Voice Response script language statement. The statements can accept parameters, check certain conditions, use the screen definitions to retrieve data from the host applications, and send the data back to your WebSphere Voice Response voice 86 Designing and Managing State Table Applications

105 application. A set of script language statements is commonly referred to as a script. A 3270 server may consist of one or more scripts, depending on the complexity of the required host interaction. The script uses the screen definition to ensure that the correct screen is displayed and then retrieves the data. Scripts interface with WebSphere Voice Response state tables and other scripts by passing input and output parameters. The input parameters receive the data from the calling state table or script. The output parameters contain the data to be returned to the calling state table or script. Refer to the WebSphere Voice Response for AIX: 3270 Servers book for guidance about creating a 3270 server and for language reference information. Custom servers Custom servers can be of two types: v Applications that wait to be called by one or more state tables. This type is the most common server, typically used for processing functions requested from incoming calls. v Applications that are initiated by other means under your control, such as another program or a timed event. This type is useful for processes like outbound calling, invoking a state table which might then call other custom servers and state tables. A custom server consists of a 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 server subroutines. If the main function is system-generated, you must develop user functions to support your WebSphere Voice Response application. The main function that the system generates can pass required information between user functions and WebSphere Voice Response and perform other processes. If you create the main function yourself, user functions are optional, depending on the requirements of your custom server. The capabilities of a custom server are limited only by the resources of the pseries computer and the connectivity options at your site. You can communicate with other systems such as the IBM System/36, or the Apple Macintosh, Hewlett Packard, or DEC personal computers, using any communications protocol supported by the pseries computer (refer to the AIX: Communications Programming Concepts for RISC System/6000 manual for information about communications protocols). Chapter 4. Overview of application objects 87

106 Refer to the WebSphere Voice Response for AIX: Custom Servers book for guidance about creating a custom server and for language reference information. Further information For procedural and language reference information, see the following manuals: v WebSphere Voice Response for AIX: Application Development using State Tables v WebSphere Voice Response for AIX: 3270 Servers v WebSphere Voice Response for AIX: Custom Servers 88 Designing and Managing State Table Applications

107 Chapter 5. Creating an application profile You need to create an application profile for any state table that is to be invoked in response to an incoming call or by another state table specifying the profile name, or to define one or more mailboxes for an application. 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 a meaningful string of characters. v A unique digit name, which can be used by callers and applications to identify the profile. WebSphere Voice Response creates the digit name by translating the application profile name into digits. v A unique application profile ID, which is used by WebSphere Voice Response to find the state table to answer an incoming call. You specify the ID, making it the same as one of the following: The number callers to the service are going to dial. You must ensure that called number information is sent by the switch. The application profile ID assigned to the channels you want to carry calls for this application v A state table name and, optionally, an entry point, which are used to invoke state tables. You specify these. Not all state tables need an application profile: if a state table is invoked only by other state tables, it does not need an application profile. However, invoking a state table by specifying a profile name is also an option. A state table can be referred to by more than one application profile (for example, specifying different entry points, languages, or mailbox details). v The language in which prompts are initially to be played. You can specify different application profiles for each language, each specifying the same state table. Because the state table uses the language specified by the application profile, this makes your state tables potentially multilingual. To do this, you have to provide different variants of the prompts and translations of the voice segments, but the state table can be identical for all languages. Copyright IBM Corp. 1991,

108 v Mailbox definitions and other voice messaging information, described further in What mailbox information does the application profile include? on page 167. This information defines voice mailboxes for voice messaging applications that require them. An application profile is required for a state table that is to respond to incoming calls, and is required for voice messaging. Application profiles are not required for other state tables. How to create an application profile 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 and managing application objects, on page 27). In the Application window click Object > New > Application Profile. The advantage of this method is that the resulting application profile is created in the same application. This is the method described in this procedure. v In the Configuration window click Application Profiles > File > New. Application profiles created in this way are put into the User application. You then need to move them to the appropriate applications as necessary. v Use the wvrapplprof command, as described in wvrapplprof command on page 94. Application profiles created in this way are put into the User application and can then be moved to the appropriate application, if necessary. 90 Designing and Managing State Table Applications

109 1. Naming the profile : Type a unique name in the Name field. The name can be up to 50 characters long, including blanks. As you type, you ll see digits appearing in the Digit Name field. This is the numeric equivalent of the name. The digit name is used by the GetFindName action to find an application profile that matches digits keyed in by the caller. You need to be aware that the digit name is used in this way, to help you determine what profile names should be allowed. You can t have two profile names whose corresponding digit names are the same, because each digit name must be unique. For example, if you have a profile called AAA, you cannot have a profile called BBB unless A and B are mapped to different keys on the telephone keypad. (For more information, see Entering data (multiple keys) on page 119.) 2. Specifying the initial state table for the application : Click the State Table pushbutton. The system lists all validated state tables. 3. Click the appropriate state table. If you have implemented your application as a set of state tables, click the main state table that includes the first part of the interaction with the caller. 4. Click OK. 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 state table has more than one entry point, the Entry Point is Undefined, in which 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

110 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 ID you used to log on. The language specifies which language database to use. The state table can be the same for all languages: only the application profiles, prompts, and voice segments are language-specific.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 any characters valid for a telephone number (the digits 0 through 9 and the letters A, B, C, and D). WebSphere Voice Response does not accept blanks or special characters as part of the profile ID. The profile ID depends on how you intend the application profile to be used: v For a state table that is to handle incoming calls when the called number is available, it should be the number callers are to dial to reach this application (the called number). 92 Designing and Managing State Table Applications

111 v v v For a state table to be used to handle all incoming calls on a specific channel, or channels, when the called number is unavailable, it should be the channel identification, as specified in the Pack Configuration window. For a state table to be used if an application profile matching the called number or the channel identification cannot be found, it should be the value of the System Default Application Profile parameter. If the application profile is not to be used to identify a state table to handle incoming calls, you can choose any valid value to identify it. Note: In a voice mail system, the profile ID is typically the extension number of the subscriber, and the state table is the main state table of the voice mail application. 15. Click OK. 16. In the Application window, click View > Refresh. The system displays the Application Profiles folder. 17. Single-click on the folder icon to display the new Application Profile icon inside it. The new profile is also listed in the Application Profiles window: Up to 250,000 application profiles can be displayed in the Application Profiles window. If you have more this number, use the command line tool wvrapplprof to manage the application profiles, as described in wvrapplprof command on page 94. Chapter 5. Creating an application profile 93

112 The Application Profile window is still open, so that you can create further application profiles or, if necessary, continue with the procedure in Creating mailboxes for application use on page 170. (If you prefer, you can add mailboxes later.) Note: You can create a profile to use as a template, editing it and saving it as a new profile when necessary. Using the command line You can perform the same functions of managing profiles and mailboxes as the graphical user interface, by using the wvrapplprof and wvrmailbox commands. Refer to the WebSphere Voice Response for AIX: User Interface Guide book. wvrapplprof command Purpose List application profiles, or view details of, add, change, delete, or copy, an application profile. Note that this command does not allow you to modify any of the mailbox properties or options. Syntax wvrapplprof {-c-iprofile_id -O target_profile_id -N target_profile_name -d-iprofile_id [-N profile_name] -h -l {-I {all profile_id_spec} -Nprofile_name_spec} -m-iprofile_id [-N profile_name] [-S state_table] [-E entry_point] [-L language] [-C subscriber_class] [-G active_greeting_id] -n-iprofile_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{-iprofile_id -Nprofile_name} -? } Action flags All action flags are lowercase. -c Copy the application profile identified by -I profile_id, to create an identical profile identified by -O target_profile_id. -d Delete the application profile identified by profile_id. The -N flag can 94 Designing and Managing State Table Applications

113 optionally be specified to help prevent inadvertent deletion of the wrong profile. Both profile_id and profile_name must match those of the profile for it to be deleted. -h Display help for the command -l List all the application profiles whose profile IDs match the profile_id_spec, ortheprofile_name_spec. These specifications can include percent (%) signs to indicate zero or more characters, or underscore to specify a single character. To list all application profiles on the system, use wvrapplprof -l -I all -m Modify the application profile identified by profile_id, as specified by the other parameters. -n Create a new application profile identified by profile_id. -v View the details of the application profile identified by profile_id or profile_name. -? Display syntax of the command Attribute flags All attribute flags are uppercase. -B The number of active mailboxes to be initially associated with this application profile. Mailboxes are numbered sequentially from 1 up to a maximum of 10. For example, if you specify -B5, mailboxes from 1 to 5 are created and activated. Mailboxes from 6 to 10 will not exist. See wvrmailbox command on page 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, to be used by the active mailboxes associated with this application profile. -I The profile ID of the application profile. -L The language in which the state table is to be run. A number in the range 1 to 255. Here is a list of example language numbers: 1 = US English 2 = Belgian Dutch 3 = Belgian French 4 = Canadian French 5 = Danish 6 = Finnish 7 = Swedish Chapter 5. Creating an application profile 95

114 8 = French 9 = German 10 = Italian 11 = Netherlands Dutch 12 = Norwegian 13 = Portuguese 14 = Spanish 15 = Swiss French 16 = Swiss German 17 = UK English 18 = Icelandic 19 = Greek 20 = Turkish 101 = US English TDD Other numbers can be created by the user. To find out what the numbers of the installed languages are, click Languages in the Configuration window. -N The name of the application profile. -O The output profile ID when copying an application profile (this is the letter 'O', not the digit zero). -S The name of the state table invoked by the application profile. Examples Copy the application profile to create an identical profile , with a profile name "newapp": wvrapplprof -c -I O N newapp Delete the application profile : wvrapplprof -d -I 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 , changing its language to French: wvrapplprof -m -I L 8 96 Designing and Managing State Table Applications

115 Create a new application profile , specifying only the mandatory parameters: wvrapplprof -n -I 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 : wvrapplprof -v -I Chapter 5. Creating an application profile 97

116 98 Designing and Managing State Table Applications

117 Part 2. Design topics Copyright IBM Corp. 1991,

118 100 Designing and Managing State Table Applications

119 Chapter 6. Creating the voice output for voice applications How to create voice output for voice applications and an overview of voice signal processing. This chapter provides information about: v Overview of voice signal processing v Planning your voice segments on page 103 v The voice segment database on page 112 v Creating prompts on page 113 v Creating multilingual applications on page 117 Overview of voice signal processing Normally, voice is transmitted to the human ear by means of an acoustic wave travelling through the air at the speed of sound. A conventional analog telephone transmits sound through a wire as an electrical signal which travels at close to the speed of light. To do this, the acoustic signal generated by the human vocal chords must first be converted to an electrical signal, and then converted back to an acoustic form before it can be heard by the human ear. These two conversions are done by a telephone mouthpiece and earpiece respectively. The electrical signal sent over the telephone wire for a conventional telephone is of an analog form. That is, it is represented as a voltage which varies continuously in a given range (for example, 0 to 1 volt) where the louder the signal, the higher the voltage. The normal electrical signal is described as analog because the voltage can take any value in the possible range, that is an infinite number of possible values. As well as the signal varying continuously in the voltage limits, an analog signal is able to vary continuously over time with no requirement to change only at fixed time intervals. Although analog signals are the easiest to handle in a simple telephone system, they give rise to a number of problems if they are to be stored or processed by computer or if they are to be sent over a long distance. Sending an analog signal over long distances rapidly decreases the signal strength, and can increase background noise level, both of which lead to severe quality degradation. For these reasons, almost all modern telephone systems are based on the concept of digital processing of voice, where the signal is converted to a form which can be handled by standard digital computers as a sequence of numbers. This means that voice can be stored on a standard Copyright IBM Corp. 1991,

120 computer as a set of numerical values, for example, just like a spreadsheet, and an operation such as increasing the volume of a segment is equivalent to multiplying every number in a spreadsheet by a certain value. To convert an analog signal into a digital form two steps are needed: First, the analog signal is sampled at a fixed rate to break it into a sequence of analog samples which can be handled individually. For the highest possible audio quality (such as CD audio), the sampling rate is usually very high, that is 44,000 times per second (44 khz), whereas for the telephone, where a much lower voice quality is acceptable, the sampling rate is only 8,000 times per second (8 khz). This is a fixed sampling rate now used by all telephone systems of the world. Note: The sampling rate is one factor limiting the voice quality that can be achieved over a telephone link as it limits the frequency response (the highest audio signal that can be carried) to one half of the sampling rate, that is 4 khz. The human ear can detect frequencies up to about 18 khz; dogs and bats can detect even higher frequencies. Second, each analog sample is converted to a number to allow it be handled by the digital computer. For example, if the input signal has a range of 0 to 1 volt and 16-bit numbers are used to represent the digital form of each signal sample, the digital value 0 would represent 0 volts, the digital value would represent 1 volt with a linear sliding scale for intermediate values (for example, = 0.5 volt). Note: Analog voltages are more usually transmitted with a center value of zero and, say, maximum and minimum values of +0.5 volt and -0.5 volt respectively. This corresponds with a two's complement digital numbering system which can, for 16-bit values, range from down to with a center value of zero. A special technique known as companding is used to reduce the number of bits for each voice sample from 16 to 8 bits. This halves the amount of data to be processed and stored. Companding applies a logarithmic conversion to each sample, resulting in a signal format known as µ-law (used in North America, Japan, and some other countries) or A-law (used in Europe, Latin America, and some other countries). These 8-bit samples can then be stored, transmitted and processed, and a reverse (anti-log) process applied to the signal at the receiver to reproduce the original signal with very little loss in quality. Note that almost without exception, T1 digital trunks are encoded as µ-law, and E1 trunks as A-Law. Also note that µ-law and A-law signals are not compatible, they must be converted to move from one to the other. 102 Designing and Managing State Table Applications

121 When WebSphere Voice Response plays voice to, or records voice from, the telephone line, it is at the standard 8 khz 8-bit rate (µ-law for T1, A-law for E1). When the data is stored on disk it can be in either uncompressed form (which is always 8 khz 8-bit µ-law or A-law), or compressed. WebSphere Voice Response applies a compression algorithm to the signal to reduce its size by a factor of five. When compressed voice is played to the line, WebSphere Voice Response decompresses it to reproduce the original 8 khz, 8-bit signal. WebSphere Voice Response uses a compression algorithm known as GSM (used in the digital mobile phone system of the same name). This gives a very good quality at a compression ratio of five to one, that is the data rate is reduced to 1600 bytes per second. Other compression techniques, such as ADPCM, are also used in the voice processing industry to reduce the size of voice data. WebSphere Voice Response uses only the five to one GSM compression algorithm; this is supplied as part of WebSphere Voice Response. The advantages of using compressed voice are that you use less disk storage, less system memory, less processing time, and less bus bandwidth. The disadvantage of compressed voice is that the quality of voice is slightly reduced. Depending on your application, this may or may not be a problem, although you can take steps to ensure that the quality of compressed voice is as high as possible (see the WebSphere Voice Response for AIX: Application Development using State Tables book). Planning your voice segments Step-by-step instructions on how to create voice segments are given later in this chapter, but there are different approaches to this, so it is worthwhile taking some time to plan what you are going to do: 1. Decide whether to store voice segments in compressed format, uncompressed format, or both. 2. Decide on the source for your voice segments. You have the following options: v Record directly into WebSphere Voice Response using the telephone. v Record high-quality voice data, by one of the following methods: Recording directly into WebSphere Voice Response using a microphone and an audio adapter such as the Ultimedia Audio Adapter in the pseries computer Using a recording studio. 3. If using a recording studio, decide how to transfer the voice data into the pseries computer. You can use either direct file transfer (recommended), digital audio tape (DAT), or analog tape. Note that you may have to convert the format of the voice data after transfer. Chapter 6. Creating the voice output for voice applications 103

122 4. If using a microphone directly or transferring voice data from a recording studio, decide how to import segments into the WebSphere Voice Response voice segment database. There are two methods: v v The Voice Segments window (select the voice segment in the Application window and open it) The Batch Voice Import command-line process (a set of command line utilities, with a control file). Note that you can use both the voice segment editor and the Batch Voice Import (BVI) utility to import voice data created on another system. The voice segment editor supports only raw unformatted voice data files, the BVI utility supports.wav files and audio interchange file format (AIFF) files. Table 4 shows you which tool to use. Table 4. Creating voice segments for WebSphere Voice Response Source Telephone Microphone Tape recorder, CD player, DAT Raw unformatted audio file Tool Record_Comp, Record_Uncomp Voice segment editor, BVI utility Voice segment editor, BVI utility Voice segment editor Ultimedia Audio Adapter Required? No Yes Yes Windows.wav file BVI utility No Apple Macintosh AIFF file BVI utility No Other file format Custom server you have written. (Not supplied with WebSphere Voice Response) No No Note: 1. Although the voice segment editor can be used to import multiple voice segments, depending on the number of voice segments, you might find it quicker to use the BVI utility. 2. The voice segment editor and the BVI utility both support only IBM audio adapters for direct input of voice from microphone, tape recorder, and so on. For PCI pseries computers, you might or might not have the audio function available on the planar (there is currently no PCI plug-in audio board). If you do not have audio on your PCI pseries computer, you can record voice segments in one of the following ways: 104 Designing and Managing State Table Applications

123 v Using the telephone v Using another pseries computer with a Ultimedia Audio Adapter installed v Using a separate personal computer with an industry audio adapter, and import standard audio files (such as.wav) using Batch Voice Import. 3. To import audio files from other computers, use either the TCP/IP file transfer program (FTP) over a LAN or other network, or use a removable storage device, such as a tape. You might find tape more convenient to move bulk voice data to your pseries computer. 4. For top-quality audio segments, we recommend that you record your voice segments in a professional recording studio, then either import a digital file (.wav or.aiff) or use digital audio tape. Compression When you store a voice segment in the database, you can save it in compressed format, uncompressed format, or both. WebSphere Voice Response uses a compression algorithm derived from the Groupe Speciale Mobile (GSM) digital mobile phone system, which gives high-quality voice suitable for telephony applications. Saving voice segments in a compressed format saves disk space and bus bandwidth (the compression ratio is 5:1), but tends to cause a slight loss of sound quality. If you compress a voice segment, then uncompress it, the sound quality of the resulting voice segment will not be equivalent to that of the original. However you can support more channels (more simultaneous calls) by using compressed voice. If, on the other hand, it is important to preserve the highest possible sound quality, choose uncompressed format. You can mix compressed and uncompressed voice segments in the same application using the System : PlayPrompt voice compression type system variable (SV182) to specify the compression type (or the System : Voice segment compression type system variable (SV50) if you are using the PlayVoiceSegment action). You might, for example, use uncompressed segments in the opening dialog and most frequently used menus, to give a good impression, but use compressed segments for less frequently used, or less essential, information. Note: If you use uncompressed voice segments with the PlayVoiceSegment action, this produces more network traffic when your WebSphere Voice Response system is part of a single system image. This is because the PlayVoiceSegment action has to retrieve the segment from the database every time it plays the segment. Chapter 6. Creating the voice output for voice applications 105

124 Recording voice segments over the telephone This does not always give the highest quality sound, and should be used for prototyping and testing rather than for production applications. To record via the telephone you use the Record_Comp or the Record_Uncomp voice applications supplied with the base WebSphere Voice Response system. The segments recorded using Record_Comp are stored by default as compressed voice segments. The segments recorded using Record_Uncomp are stored by default as uncompressed voice segments. The files for the applications are automatically imported into a directory at installation time, but, if they get corrupted by mistake, you can reimport them from /usr/lpp/dirtalk/sw/samples/basedata.imp. Before anyone can use either application, you must create an application profile that allows people to access it over the telephone. In the profile, specify the language in which you intend to record segments. Otherwise, the voice segments are stored in the wrong database. You can create an application profile for each application for each language you intend to use. In addition, you will probably want to create additional voice directories. Otherwise, all of the voice segments can only be stored in the system directory. The WebSphere Voice Response for AIX: Application Development using State Tables describes how to create voice directories. High-quality voice data Sampling rate All voice segments stored in the WebSphere Voice Response database use an 8 khz sampling rate, consistent with standards used for telephony transmission. The Voice Segment window lets you digitally input data from other sources, but converts it to 8 khz if necessary. There is no advantage to using sampling rates other than 8 khz when recording new voice segments using the Voice Segment window. Similarly, the command line utilities, bvi_aiff and bvi_wav, convert any sampling rate greater than 8 khz to the required 8 khz rate. Source format Use the best-quality source for your voice segments and import these into WebSphere Voice Response in 16-bit PCM (linear) format at an 8 khz sampling rate. To do this, use studio-quality DAT tape through the line-in of the Ultimedia adapter with the Ultimedia format set to 16-bit PCM. Alternatively, you may already have 16-bit PCM voice segments as files that can be imported directly into the Voice Segment Editor. The editor can change sampling rates are required, although slight distortion will usually result from 106 Designing and Managing State Table Applications

125 a change in sampling rate. You should therefore always use an 8 khz sampling rate for imported voice data if possible. Dynamic range When using the voice segment editor or the batch voice input utility to record voice segments via the Ultimedia adapter with an audio source connected to the its line input, you may find that the audio signal is relatively small compared to the available dynamic range. 16-bit PCM allows signal levels of up to 32K, whereas typical input signals from the Ultimedia adapter may have an amplitude of around 2K. When using 5:1 compression, the best quality is obtained if the input signal occupies as much of the 32K range as possible without signal peaks exceeding the available limits. This can be done with an external preamplifier or by using the MAXIMIZE option of the voice segment editor or batch voice input utility which digitally scales the input signal to occupy 90% of the full range. Note that the maximize button of the voice segment editor is only enabled when operating in 16-bit PCM mode. Filters When you record a high-quality input signal for use over the telephone, it is necessary to filter out all frequencies above 4 khz to allow transmission at the digital 8 khz rate. (The voice segment editor does this automatically when it stores the segment in the database.) Loss of these high frequencies can make the signal sound relatively dull. You can improve this by using the Boost button of the voice segment editor before saving the recorded segment. This increases the volume of frequencies in the range 1.5 khz to 4 khz by 2 db, and decreases the volume of frequencies in the range 500 Hz to 1.5 khz by 2 db. An identical effect can be achieved with the Boost option of the batch voice input utility where the boost amount can be set to any value. Note that the boost button of the voice segment editor is only enabled when operating in 16-bit PCM mode. Recording directly using a microphone A direct microphone input can provide excellent quality input. However, the pseries computer must be within feet (maximum) of the microphone in order to minimize electrical noise pick-up. This may be difficult to achieve in a studio environment because fan and disk noise prohibit the pseries computer from being in the same room as the microphone. Chapter 6. Creating the voice output for voice applications 107

126 Using a recording studio For the best results when recording voice segments, keep to the following rules: v It is recommended that a professional recording studio with an anechoic chamber be used to record the audio if you want segments to be of the highest possible quality. It is important to achieve a good acoustic ambience (a normal office has too much reverberation). v Keep background noise to an absolute minimum. Even low-level noise generated by cooling fans in machines such as personal computers, should be avoided. v If you are editing segments in the studio, do not put absolute silence between segments, as this sounds unnatural. Instead, insert room-tone silence breaks (background studio ambient sound). v Half a second of silence at the beginning and end of each segment is recommended. v Record segments as a continuous stream of audio with a silence gap between consecutive segments. The recommended silence gap is five seconds, because this allows the batch voice import utility to distinguish the silence gaps between segments from the natural gaps that occur within segments. v If a mistake is made during the recording of a segment, just stop, wait for five seconds (or whatever inter-segment gap you have decided to use) and then re-record the segment. Bad segments can be removed by the voice segment editor or the batch voice import utility. If you are working with a studio which has reasonably sophisticated audio processing capabilities, it is wise to apply the audio boost function at source rather than with batch voice import utility. The best frequency-shaping function to apply is defined in the ITU P-Series Blue Book (Volume ) in Supplement No. 10 (P332). This is the preferred response for a telephone microphone as determined by user trials, and can be applied to flat-spectrum audio, achieving the same results as if the voice was being spoken through a telephone. The frequency shaping function recommended by the ITU boosts the treble and cuts the bass in a signal in order to restore some of the brightness lost when a full-bandwidth audio signal is low-pass filtered at 3400 Hz prior to sampling at 8 khz and is similar to the BOOST option of the voice segment editor or the batch voice import utility. Be sure that the shaping is not done both in the studio and by one or other of WebSphere Voice Response s voice utilities. The ITU-recommended frequency response characteristic is as follows: 108 Designing and Managing State Table Applications

127 v 0 db reference at 1kHz v Under 1kHz, 4 db/octave roll-off to 200 Hz v Below 200 Hz, 8 db/octave roll-off v Above 1kHz, smooth increase to +7 db peak at 2600 Hz. v Sharp cutoff at 3.4kHz Responses for spot frequencies are shown in Table 5. Table 5. Responses for spot frequencies Frequency Response attenuated or amplified by 50 Hz -20 db 100 Hz -12 db 200 Hz -4.5 db 400 Hz -2 db 800 Hz -1 db 1000 Hz 0 db 1500 Hz +2.5 db 2000 Hz +6 db 2500 Hz +7 db 3000 Hz +6 db 3400 Hz 0 db To get the best results when recording data for use as background music: v Don t use the BOOST option of the voice segment editor or the batch voice import utility v Filter the signal using a graphic equalizer before the it reaches the Ultimedia adapter. Transferring the prerecorded data to WebSphere Voice Response v Direct transfer from the studio v Diskette or other removable storage device v Digital Audio Tape (DAT) v Analog Tape v Microphone Direct transfer from the studio Most recording studios use specialized voice processing systems for processing audio data. The best possible method for moving this data from Chapter 6. Creating the voice output for voice applications 109

128 the studio system to the WebSphere Voice Response system is direct file transfer across a network (for example, using TCP/IP FTP). If you transfer digital data directly, when using the batch voice import utility, you should bypass the bvi_rec step and go straight to bvi_seg. Diskette or other removable storage device This gives identical results to direct file transfer as the movement of data is 100% digital. If the recording studio uses Apple Macintosh based sound-processing applications, you can use Apple s system extension, Macintosh PC Exchange, or an equivalent product, to format a Macintosh diskette so that it can be read by a pseries computer. Write a diskette in a DOS format and use the AIX supplied utility dosread to read it. You can fit about two minutes of 8 khz sampled voice on a2mbdiskette. Digital audio tape (DAT) This is a good way of moving digitally-recorded audio data in bulk from a studio to the pseries computer. However, there is currently no method of taking a digital output from a DAT player and transferring it directly into the pseries computer without translating to analog and back again, using the Ultimedia Audio Adapter. The digital-to-analog and analog-to-digital conversions always introduce some low-level noise and distortion, but these are usually negligible for a system with optimum input level. Analog tape This is not recommended, because analog tape, even of the highest quality on the best audio equipment, can introduce low-level noise that can cause voice quality problems especially with compressed data. The compression algorithm operates best with a noise-free input signal. However, if you have no alternative, write a tape in AIX format and then copy data directly from it into the AIX file system. Converting voice data transferred from non-aix computer systems You can transfer audio data from other systems provided that you can get the audio data into the AIX file system. The audio data can be in one of the following formats: Raw (unformatted) data The data must be stored in the file in the following format: v Single channel v Linearly encoded PCM 16-bit samples (two s complement) 110 Designing and Managing State Table Applications

129 v 8 khz sampling rate v Big-endian format (ms byte before ls byte) v No header AIFF (Macintosh audio interchange file format) The bvi_aiff utility converts files stored in AIFF format into the required format for processing by bvi_seg. It takes an input file specified as a parameter and generates a file whose name is specified in the bvi.control file by the VOICE_FILE_NAME parameter. The AIFF file must be written in the following format: v Single channel v 16-bit samples (two s complement) v Sample rate equal to or greater than 8 khz (bvi_aiff will convert to 8 khz) WAV (Microsoft Windows format) The bvi_wav utility converts files stored in Microsoft WAV format (files with an extension of.wav) into the required format for processing by bvi_seg. It takes an input file specified as a parameter and generates a file whose name is specified in the bvi.control file using the VOICE_FILE_NAME parameter. The WAV file must be written in the following format: v Single channel v 16-bit samples (two s complement) v Sample rate equal to or greater than 8 khz (bvi_wav will convert to 8 khz) Saving voice segments The WebSphere Voice Response database only allows voice data to be stored at an 8 khz sampling rate in one of two formats: v 8-bit uncompressed A-law or µ-law (depending on your country). v 5:1 compressed. Note: A-law and µ-law voice cannot be mixed on the same system. It is not necessary to manually convert 8 khz 16-bit PCM data to your default (A-law or µ-law) when saving with the Voice Segment window. This is done automatically when you save a segment as either uncompressed or compressed. Note that converting from 16-bit PCM to 8-bit A-law or µ-law and back will degrade voice quality, as will compressing and uncompressing voice data. To save voice data for future use, always save it in 16-bit mode to an AIX file using the voice segment editor Export function. Don t just save it in the WebSphere Voice Response voice segment database. Chapter 6. Creating the voice output for voice applications 111

130 To find out more about the batch voice import process, see the WebSphere Voice Response for AIX: Application Development using State Tables. If you have only a few voice segments to record, use the Voice Segments window (also documented in the WebSphere Voice Response for AIX: Application Development using State Tables). The batch voice import utilities or the Voice Segments window? If you only need to create a few voice segments, you may find the Voice Segments window convenient, but if you are dealing with many voice segments, you will probably find it worthwhile to use the batch voice import process. Both processes allow you a choice of different input media. The voice segment database There is a voice segment database for each language. By creating an application profile for each language, you can make the same application work with different languages. Each voice segment has: v A segment ID v A description v Digitized audio data in either compressed or uncompressed format, or both. Each voice segment is stored in a voice directory, and can also be referenced by one or more voice tables. A voice directory has: v A name v A voice directory ID (retained only for compatibility with earlier releases) The voice directory must exist before you create the voice segment. German WebSphere Voice Response voice segment database French WebSphere Voice Response voice segment database U.S. English WebSphere Voice Response voice segment database Voice Directory Voice directory Voice segment Voice table Voice segment System voice directory Voice tables are optional, and you can create them at any time. Voice tables are particularly useful if you have applications that use voice segments which can be referenced using an index value, such as the spoken words for the months of the year. A voice table has: v A name v A description 112 Designing and Managing State Table Applications

131 Creating prompts The set of prompts that are used by a particular state table are grouped in a prompt directory. All prompts used by a state table must be in the same prompt directory. Different state tables can use the same prompt directory. If a state table uses its own prompt directory, you can use the system prompts by creating new prompts that call the system prompts (using the SYSPROMPT prompt statement). Note: System prompts cannot be exported as a dependency of another application object (for example, a state table), so we recommend that you don t use the System_Macros prompt directory for application specific, or user, prompts. You can distribute changes to system prompts only by explicitly exporting them and importing them to another system. If you want to store the prompts in a new, rather than an existing, prompt directory, the first step is to create the new prompt directory. Then, you create the prompts by defining new prompts, copying existing prompts, or importing prompts. You can edit the prompt statements that comprise the prompts that you create. About creating prompt directories Before you can save a prompt, the prompt directory to which it belongs must exist. A prompt directory is referred to by a prompt directory name. You must specify a default compression type for playing the voice segments included in the directory. Overriding the default compression type You can override the default compression type by setting the System : PlayPrompt voice compression type system variable (SV182) before the PlayPrompt action. A value of 0 specifies that the clear channel version of the segments is to be played; a value of 2 specifies that the compressed version is to be played; and a value of -1 indicates that the default compression type is to be used. A prompt can play audio names and greetings. About defining prompts Prompts are constructed using the prompt statements described in the WebSphere Voice Response for AIX: Application Development using State Tables. A prompt statement can use any of the following elements to define what a caller will hear: v Voice segments (stored in voice directories or voice tables) v Greetings Chapter 6. Creating the voice output for voice applications 113

132 v Audio names v Other prompts v Parameters passed from the calling state table v System variables or local variables v Conditional tests that determine what should happen in different cases For examples of prompts, look at the system prompts that are delivered with WebSphere Voice Response in the System prompt directory. For more information about the system prompts, see System prompts on page 75. Default and language-specific prompts Each new prompt that you create is called a default prompt. A default prompt is language-independent. If the logic of a particular prompt does not change from one language to another, the same prompt can be used for all languages. You will need to record the segments for all languages that reference the prompt, but you will not need to alter the prompt itself. Only one language can be active at any one point during the execution of a voice application. The active language is identified by the value in the System : Current language system variable (SV39). When the prompt references a voice segment, it uses the segment ID and voice directory name to locate the required segment in the active language. As long as the ID for a particular voice segment is not changed when the segment is translated into other languages, the default prompt will find the segment it needs to play. In some cases, the logic of a prompt may need to be altered for a specific language. For example, the system prompt that speaks the date (Date) uses U.S. English syntax to play the month, followed by the day spoken as an ordinal quantity, followed by the year. In other languages, the date syntax may be different. For example, the German version of Date will need to play the day, followed by the month, followed by the year. In such cases, you will need to create a language-specific version of the default prompt. The language-specific prompt for a particular language will be used instead of the default prompt when that language is the active language for the currently executing voice application. The inputs to the language-specific and default versions of a prompt, if any, must match exactly in number and type. Refer to Using languages other than U.S. English on page 115 for information about modifying the system prompts for other languages. All default and corresponding language-specific prompts for a state table are stored in the same prompt directory. When a state table encounters a PlayPrompt action, the system searches the specified prompt directory for the prompt to be played. If a language-specific version of the prompt exists for the active language, that version is played; otherwise, the default version of the prompt is played. 114 Designing and Managing State Table Applications

133 Using languages other than U.S. English When it has been installed, WebSphere Voice Response is ready to work in U.S. English. If you want to use other languages in your voice response services, you need to: 1. Install the language environment (locale) for each required language on your system. This is a system-level activity performed on AIX (see the AIX Installation Guide). 2. Install the optional fileset that contains the system prompts and voice segments for the languages you need (see the WebSphere Voice Response for AIX: Installation book). If the system prompts are not supplied in the languages you require, you may have to select one of the supplied languages, and then make modifications to suit your language (see Modifying the system prompts for other languages ). 3. Establish a database for the new language (refer to the WebSphere Voice Response for AIX: Configuring the System book) 4. If your language was supplied in an optional fileset, import the appropriate language.imp file (for example, BelgianDutch.imp) from the /usr/lpp/dirtalk/sw/samples directory. Ensure that objects in the System_Macros prompt directory are replaced, not merged, when you install them. You now have the following: v v v The System_Macros prompt directory containing the default prompts along with the derived language-specific prompts The System voice directory containing language-specific voice segments Language-specific voice tables Modifying the system prompts for other languages The prompts that are supplied in the System prompt directory are described in System prompts on page 75. To modify the system prompts, you must be familiar with programming logic and with the prompt statements described in the WebSphere Voice Response for AIX: Application Development using State Tables book. 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. Chapter 6. Creating the voice output for voice applications 115

134 6. Review the segments that are grouped in the following voice tables, which are used by the system prompts: v Numbers v Divisor v Ordinal v Time_Of_Day v Month_Of_Year 7. Make a list of the voice segments that will need to be changed or added to each of the voice tables. Make sure all of these voice segments are on the list you made in Step 5 on page Record the voice segments for the system prompts in the new language and also record any new segments (see the WebSphere Voice Response for AIX: Application Development using State Tables). 9. Modify the system voice tables to include any new voice segments (see the WebSphere Voice Response for AIX: Application Development using State Tables book). 10. Edit the system prompts to play voice segments using the correct syntax (see the WebSphere Voice Response for AIX: Application Development using State Tables book). Refer to Creating multilingual applications on page 117 for information about using the system prompts that you have created for the new language. Modifying the system voice tables Some of the system prompts invoke voice segments using the Table prompt statement. One of the parameters of the Table statement identifies the table in which the required segments are cataloged. For example, Small_number calls the voice segments that play numbers using the Table statement, with the Numbers table as a parameter. If you record a new number for Small_number to play and do not add it to the Numbers table, Small_number fails when it tries to play it. In this case, you must either add the new voice segment to the Numbers table or edit Small_number so that it no longer uses the Table statement. The other system prompts invoke voice segments using the Voice prompt statement. One of the parameters of the Voice statement identifies the directory (in this case, the System voice directory) in which the required segments are stored. As long as the voice segments you record are stored in the System voice directory for the language specified in the application profile, these prompts will be able to locate them. If you create additional voice segments for use by one of the prompts that includes a Table statement, either catalog it in the voice table that is the parameter for the statement, or edit the prompt to use the Voice statement 116 Designing and Managing State Table Applications

135 instead. The WebSphere Voice Response for AIX: Application Development using State Tables explains how to edit a prompt and how to modify a voice table: open the voice table you need to modify, then follow the procedure to add voice segments to the table. Editing the system prompts In some languages, the logic of a system prompt may need to be altered, for example, the Date system prompt which plays the date using U.S. English syntax. Before you start editing the system prompts, make sure you are familiar with the information in System prompts on page 75. Some of the system prompts rely on other system prompts, so make sure you edit the prompts in the following order: 1. Small_number 2. Whole_number 3. Real_number 4. Ordinal 5. Date 6. Time 7. Currency The Phone prompt does not rely on any other prompts. Refer to the procedures in the WebSphere Voice Response for AIX: Application Development using State Tables for instructions about defining a language-specific prompt. Creating multilingual applications You can create a voice database for each language, dialect, or regional accent you want to use for voice output. You can even use different voice databases for different voices speaking the same voice segments in the same language. You also create a voice database for each TDD language to be used for telephony devices for the deaf. Using application profiles Typically, multilingual applications are set up by defining a different application profile for each language. Thus, callers dial different numbers according to the language to be used, or you can call the state table by application profile, depending on a choice that the caller has made. Each profile refers to the same state table, but a different language is specified. The Application : Language system variable (SV142) contains the code for the language specified in the application profile. The System : Current language system variable (SV39) is also initially set to this value. Chapter 6. Creating the voice output for voice applications 117

136 Using the System: Current language system variable If the language defined for the application profile does not specify the required language, you can change the value of the System : Current language system variable (SV39), using the ReceiveData, AssignData, GetKey, or GetData state table actions in your voice application. For example, your voice application can prompt callers to press a key to request a specific language ( Por español, prensa el uno......for English, press two......pour Français, appuyez sur trois......für Deutsch, bitte drücken Sie auf die Vier. ) Then set the System : Current language system variable (SV39) to the code for the language chosen (the codes are listed in the Languages window (Configuration > Languages). The value of SV39 specifies which language database is to be used for prompts. 118 Designing and Managing State Table Applications

137 Chapter 7. Handling key input from callers WebSphere Voice Response supports up to 16 keys on the telephone keypad: A, B, C, and D in addition to the twelve normal keys (1 through 9, *, 0, and #). Callers can press single keys (for example, to select options) or multiple keys (to enter data such as personal identification numbers). Making a selection (single key) Use the GetKey action to get a single key press from the caller. Entering data (multiple keys) Use the GetData action to get a sequence of key presses from the caller. To indicate that the caller has finished entering data, the last key pressed must be the key specified by the Enter Key system parameter in the Application Server Interface parameter group. The default is # (pound or hash). The GetFindName action allows you retrieve an application profile whose digit name matches a sequence of key presses from the caller. The digit name is the numeric equivalent of the application profile ID. Again, the Enter Key is used to indicate the end of the data entry, and the Stop Key allows the caller to cancel the entry and start again. The default value for the Stop Key system parameter is * (star). The GetFindData action allows you to pass a sequence of key presses from the caller to a custom server or 3270 server, to retrieve information. Again, the Enter Key is used to indicate the end of the data entry, and the Stop Key allows the caller to cancel the entry and start again. The default value for the Stop Key system parameter is * (star). Alphabetic to numeric key mapping Alphabetic characters are assigned to the keys on the keypad, so that callers can enter alphabetic data if necessary. You can change the character-to-key assignments using system parameters in the Key Signals parameter group. Copyright IBM Corp. 1991,

138 Pressing keys while voice data is being played The PlayPrompt action can be interruptible or force played. Force played means the prompt is always played through to the end. If you do not specify force play, the caller can interrupt the prompt by pressing a DTMF key. You can specify that the caller can use any DTMF key to interrupt the prompt, or that they can use only one of a set of keys that you define. The caller can also interrupt the prompt by speaking. For more information on this, see Voice interrupt detection on page 122. The PlayVoiceFromHost action can also be interruptible or force played. In addition, you can specify that it can either be interrupted by any key or only by the Pause and Stop Keys. During the PlayAudioName, PlayUserGreeting, PlayVoiceSegment, and PlayVoiceMessage, the following keys are available to the caller: Forward Key (default value 9), Pause Key (default value 8), Reverse Key (default value 7) and Stop Key (default value *). These values can be changed by resetting the system parameters in the Application Server Interface parameter group. 120 Designing and Managing State Table Applications

139 Chapter 8. Handling spoken input from callers Speech recognition means that you can write voice applications that take action based on spoken input from the caller. You can implement speech recognition in your applications 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 could be a DVT_Client see Speech recognition with distributed voice technologies below. v By using a VoiceXML application refer to the WebSphere Voice Response for AIX: VoiceXML Programmer's Guide for further information. Speech recognition with distributed voice technologies The distributed voice technologies (DVT) subsystem provides support for communication with speech recognition technologies. The DVT subsystem includes a fully functional custom server that passes data from your state table to a speech recognizer. Using the DVT subsystem, WebSphere Voice Response can be integrated with TDM-based DSP or software-based speech recognition products. For more information, ask your IBM representative for the WebSphere Voice Response for AIX: Distributed Voice Technologies Integrator s Guide. Barge-in, voice interrupt detection, and echo cancellation When handling spoken input, it is important to understand these three concepts: v Barge-in v Voice interrupt detection on page 122 v Echo cancellation on page 123 Barge-in Barge-in, properly referred to as full-duplex barge-in, allows voice data to be recorded from the voice channel at the same time as voice data is being played in the opposite direction; voice data is going both ways at the same time, just as it is when two people are having a conversation and both are speaking at once. The most important use of barge-in is to allow spoken input to be sent to a speech recognizer while a prompt is being played. Copyright IBM Corp. 1991,

140 Figure 8. Barge-in Prompt is playing Voice data from the caller is being sent to a speech recognizer Time Essentially, to implement barge-in, you start a recognition session before beginning to play the prompt. You can use barge-in either with or without voice interrupt detection, depending on the needs of your application. With voice interrupt detection, the prompt stops as soon as the caller speaks, even if the word is not in the expected vocabulary. Without voice interrupt detection, the prompt continues until a custom server event happens (for example, when an utterance is recognized) or to the end. Voice interrupt detection Voice interrupt detection allows a caller to interrupt the playing of a prompt or a voice segment by speaking. This can be used in an application with speech recognition or it can be used on its own. Prompt is playing An utterance from the caller stops the prompt Figure 9. Voice interrupt detection Time If callers are using speech recognition rather than key input to interact with the voice application, voice interrupt detection is particularly useful. It can, however be used independently of speech recognition; you do not have to implement speech recognition to enable voice interrupt detection. And, of course, you can use voice interrupt detection, and speech recognition, in any combination along with DTMF-key input. With DTMF-keys, the application can allow callers to interrupt prompts or voice segments while they are being played. On the PlayPrompt and PlayVoiceFromHost actions, if you don t select Force Play when you define the action, the caller can interrupt. On PlayAudioName, PlayUserGreeting, PlayVoiceMessage and PlayVoiceSegment the caller can always interrupt. 122 Designing and Managing State Table Applications

141 In the same way, if you enable voice interrupt detection in an application, the caller can interrupt without pressing a DTMF-key, but simply by speaking. The caller can say anything: it does not have to be a recognizable word. Be aware that one of the drawbacks of using voice interrupt detection is that not all sounds picked up by the caller s phone are intended to be interruptions. In noisy environments it can be difficult to use an application that has voice interrupt detection enabled. To turn on voice interrupt detection, set the System : Voice interrupt detection On/Off system variable (SV217) to 1. To turn it off (the default), set SV217 to 0. For more information about voice interrupt detection, see Appendix B, Voice interrupt detection: technical information, on page 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 is thrown away and is not passed on to the recognizer. Without barge-in, you can let the caller stop the prompt and then start speaking the words to be recognized. Start the recognition session after the prompt has been interrupted. Play a pacing tone to let the caller know when the recognition session is ready to accept input. Prompt is playing An utterance from the caller stops the prompt, but is then discarded Voice data can now be sent to a speech recognizer Time Figure 10. Voice interrupt detection with speech recognition In most applications, however, callers find this unnatural: they expect to be able to speak-ahead, in the same way that they can key-ahead in a key-based application, with the word they utter during the prompt being passed on to the recognizer. Voice interrupt detection is probably better used with barge-in, in speech recognition applications. Echo cancellation Both barge-in and voice interrupt detection are enhanced by echo cancellation, which filters out any echo of the prompt from the spoken input. Echo cancellation is available to any custom server that records voice data from the line: it is not directly available to a state table. Chapter 8. Handling spoken input from callers 123

142 Calibration Before using echo cancellation in a state table, you need to instruct WebSphere Voice Response to calibrate the echo canceller for the line being used. The echo cancellation for DTTAs continues to monitor and reduce the echo when any prompt or voice segment is played. It is therefore particularly suitable for situations where the echo path is likely to change, for example when a call is transferred or when call tromboning is used. The calibration is requested by the state table, before invoking a custom server to begin recording voice data. Set the System : Echo Cancellation : Calibration system variable (SV231) to 1 and then use a PlayPrompt or PlayVoiceFromHost action to force play some uncompressed voice data. The outcome of the calibration is indicated by the value of SV231 following the Play action; if the value is 2, the calibration was successful. If calibration was unsuccessful, echo cancellation will not be used. To ensure that the initial calibration of the echo cancellation for DTTAs will always be successful, the duration of the uncompressed voice data used for calibration must be at least 0.5 seconds, With DTTAs, echo cancellation is recalibrated automatically, at every opportunity, as the call proceeds. Using echo cancellation with speech recognition Start the recognition by invoking a custom server using the SendData action. If the custom server was designed to use echo cancellation, and the calibration was successful, echo cancellation will be used. 124 Designing and Managing State Table Applications

143 OpenHostServerLink with DVT_Client2 SV231 = 1 AssignData Force Play some uncompressed data: this can be a normal prompt PlayPrompt If SV231 = 2, calibration was successful. Echo cancellation will be used during speech recognition if calibration was successful EvaluateData Start a speech recognition session SendData DVT_Start_Recognition ReceiveData DVT_Start_Recognition Further prompts need not be force-played or uncompressed PlayPrompt Figure 11. Calibrating the echo canceller Writing a custom server to handle speech recognition If none of the speech recognition implementations offered with WebSphere Voice Response satisfy your requirements, you can write your own custom server to pass voice data to an external voice services system for speech recognition. The custom server subroutines for voice handling are documented in the Custom Serversbook. Chapter 8. Handling spoken input from callers 125

144 Contact your IBM representative for more information if you plan to implement your own custom server for speech recognition. Telephone Network Voice Processing Data Communications Network WebSphere Voice Response State Table Local Area Network Local Area Network Caller Custom Server Speech Recognition Server Information Speech Recognition Server Speech Recognition Server pseries Figure 12. External speech recognition overview 126 Designing and Managing State Table Applications

145 Telephone Network Caller Telephone Network Caller Telephone Network Caller Telephone Network Caller Chapter 9. Accessing data with a 3270 or custom server How to use WebSphere Voice Response state tables and state table actions to get a server to access data. Telephone Network Voice Processing Data Communications Network Caller WebSphere Voice Response Local Database Sun Local Area Network HP 3270 Server Custom Server Communications Facility pseries APPC X.25 Ethernet Token ring TCP/IP OSI SNA ASYNC IBM Personal Computer Macintosh System/390 Figure 13. Accessing data using custom servers and 3270 servers (for example, a system/390 server) To invoke a server to access data, you must set up one or more WebSphere Voice Response state tables to do the following: v Initiate dialog with your customer. v Receive and control customer requests. v Activate the server when required, passing request parameters as necessary. v Log system events or detail records as needed. v Activate an appropriate response based on the results achieved by the server. The state table actions used to access data are: v OpenHostServerLink: Establishes a connection to a server. Copyright IBM Corp. 1991,

146 v GetFindData: Requests a list of items that match or begin with a specified generic 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 using State Tables book for information about these actions. Sample 3270 and custom servers WebSphere Voice Response includes many custom servers, which perform services for state tables. The following are supplied in object code only: v DVT_Client: to send requests to speech recognition servers v CallPath_SigProc: to send requests to CallPath Server The following are supplied in source form as well, so you can use them as examples: v SpeechServer: to send requests to speech recognition servers v CustomServerSample. In addition, the 3270ServerSample is also supplied in source form. CustomServerSample The application called CustomServerSample contains two sample custom servers. Before you can use CustomServerSample you must: 1. Import the CustomServerSample.imp file. The import file is located in the /usr/lpp/dirtalk/sw/samples directory. 2. Build the custom servers and install them (see the WebSphere Voice Response for AIX: Custom Servers 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, on page 89). The CustomServerSample application comprises six state tables and two custom servers that perform the following activities: 1. The state table SrvrSamp_Main greets a caller, then prompts the caller for the function to be performed. The caller can add scheduled wakeup calls, list scheduled wakeup calls, update scheduled wakeup calls, and delete scheduled wakeup calls. 2. From the caller's input, the SrvrSamp_Main state table then invokes the SrvrSamp_Write, SrvrSamp_Read, SrvrSamp_Update, or 128 Designing and Managing State Table Applications

147 SrvrSamp_Delete state table to perform the appropriate function. The caller is prompted to input the phone number to make the wakeup call, the time to call (in 24 hour format), and an indication of whether this is a one-time call or a daily call. The CS_Request_Call custom server is used to manipulate the corresponding database, based on the user inputs. 3. Whenever the database is modified, the CS_Wakeup_Call custom server checks it to determine the time of the next call. When it is time to make the wakeup call, CS_Wakeup_Call opens a channel process link and requests that the SrvrSamp_Wakeup state table be executed, which will make the actual wakeup call. The SrvrSamp_Wakeup state table will play a wakeup greeting, then prompt the called party whether or not to use the snooze feature to call again in 10 minutes. 3270ServerSample The application called 3270ServerSample contains a sample 3270 server. Before you can use 3270ServerSample you must do the following: 1. From the Welcome window, click on Configuration > System Configuration 2. Select Virtual Mode. The sample server is just that, a sample. Unless your environment is identical to the environment in which the sample was constructed, the sample can run only if you reconfigure the 3270 host connection to virtual mode. If you try to run the sample server in a different environment in real mode, you will disable the 3270 sessions defined for it. Therefore, we recommend that you run the sample only in virtual mode or use it as an example of the types of scripts and the kinds of logic you can include in the 3270 servers you write. 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 a 3270 terminal session for use by the 3270ServerSample server. 11. Create an application profile for the SrvrSample_3270 state table (see Chapter 5, Creating an application profile, on page 89). Chapter 9. Accessing data with a 3270 or custom server 129

148 Done: You can now run the 3270ServerSample application in virtual mode. 3270ServerSample is an example of a 3270 server that performs a simple query of an account balance based on a 6-digit account number. The sample includes script language statements that facilitate operation of the script in virtual mode. The SrvrSample_3270 state table The state table SrvrSample_3270 plays the initial greeting and prompts the caller to enter a 4-digit ID that identifies a valid application profile. The caller is allowed three attempts to enter a valid ID before the state table terminates the application with a good-bye message. Upon registering a valid ID, the state table uses the OpenHostServerLink state table action to call the 3270 server, SrvrSample_3270. The caller is then prompted to enter the 6-digit account number of the account to be queried. If the sample is run in virtual mode, interaction is not with real host screens but with screens stored in the WebSphere Voice Response database. Consequently, the list of valid account numbers in virtual mode is limited to those present on the abrw screen. These valid account numbers are: v v v v If the account number that the caller enters is valid, the account balance is played to the caller; otherwise, the caller is advised that the account number entered was not valid. The state table performs a CloseHostServerLink action on SrvrSample_3270. This is followed by a good-bye message and a CloseEverything action. The 3270ServerSample scripts The 3270ServerSample scripts fall into two groups: those used as part of the login and those called from the state table. The scripts that are used for the login navigate to the amnu screen, which is the main menu screen of the host application. These scripts are: v login_amnu v login_blank v login_cics v login_unformatted 130 Designing and Managing State Table Applications

149 v login_samon The main login script is login_amnu, which calls the other scripts, depending on the screen encountered. The remaining scripts are used to navigate to the screen containing the account information, namely abrw. Review the scripts themselves for a more detailed description of their behavior. Chapter 9. Accessing data with a 3270 or custom server 131

150 132 Designing and Managing State Table Applications

151 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 135 v Making, transferring, reconnecting, and terminating calls on page 142 v Coordinated call and data transfer on page 144 v Setting the MessageWaiting Indicator using CallPath Server on page 147 Handling switch and protocol limitations When you design your voice applications, you need to consider the limitations and operation of the signaling protocol and switch you are using. For example, some switches and signaling protocols do not allow WebSphere Voice Response to initiate a call transfer. Handling switch tones A switch issues different tones, to indicate the current activity on the phone line. However, any one activity, for example, ringing, is indicated differently by each switch; the tones may be switch-specific or defined by national standards. In addition, some switches send different tones depending on whether the target number is internal or external to the switch. For example, when a ROLM switch receives a signal that the telephone receiver is off-hook, it generates a dial tone for a set number of seconds while waiting for dialing to begin, followed by a beep tone if the telephone is not dialed, followed by a howl tone after a set period of no activity. For more information about all progress tones, see the WebSphere Voice Response for AIX: Configuring the System book. Accounting for protocol limitations You need to be aware of the operation of the signaling protocol your system uses and design your state table accordingly. In general, trunk protocols provide call information (called and calling numbers) but not call transfer, while line-side (station) protocols provide call transfer but not call information. To get both call information and call transfer, you may need to use an exchange data link. For example, the exchange data link using CallPath Server provides call information. Copyright IBM Corp. 1991,

152 Far-end hangup detection is another function that is not supported by some protocols. Again, if you use an exchange data link that uses CallPath Server, far-end hangup detection is supported. (See Coordinated call and data transfer on page 144.) Getting call information when answering a call The best way of choosing a state table to handle an incoming call is to use the called number (appearing to callers that they have gone straight through to the voice response service). However, if the called number is unavailable there are two other options: see Handling incoming calls in your production system on page 140. Ayava switches with the converse feature cannot send DNIS information using the incoming address signaling options, and therefore cannot be retrieved by the WebSphere Voice Response system variable SV185. Such switches send DNIS information as DTMF keys after WebSphere Voice Response answers the call. To handle this, you need to modify the state table identified by the system parameter: State Table Name for Incoming Calls (the default is Incoming_Call). See Can you write your own state table to answer calls? on page 139 for details of how to do this. Making and transferring calls When using line-side (station) protocols such as FXS and RE, you are recommended to use dial tone detection when making outbound calls and call transfers (see the information about MakeCall in the WebSphere Voice Response for AIX: Application Development using State Tables book). Detecting far-end hangup You need to be aware that some protocols, generally loop start protocols such as FXS, do not include positive hangup detection. In the absence of any indication from the switch, when a caller hangs up, the state table continues to run until a CloseEverything action. To avoid executing a state table unnecessarily: v Consider using relatively low timeouts in actions that get caller input (for example, GetKey or GetData). If the Last Timeout result branches to a CloseEverything action, low timeout and repeat count values will end the state table execution soon after a caller hangs up. v After a Record... action or a speech recognition request, evaluate the System : Action additional information system variable (SV180), which 134 Designing and Managing State Table Applications

153 may indicate that the recording was terminated because the time limit specified by the Maximum Silence Duration system parameter was exceeded. Example: Here's an example that highlights the potential for various problems you may encounter based on your specific configuration. Suppose your system is connected to a ROLM 9751 switch that is configured to use the FXS Loop Start protocol. When a caller hangs up before a voice application has completed execution, the following events occur: 1. The protocol does not detect the hang up and WebSphere Voice Response remains off-hook. 2. As the voice application continues to execute, the ROLM switch issues an error tone for a number of seconds, then pauses, then issues a second error tone that alternates between the tones for the * and # keys. 3. The voice application state table encounters a GetData action and waits for caller input before timing out for the first time. 4. The state table branches to the state specified in the time-out result field (perhaps a PlayPrompt to prompt the caller for input), then again encounters the GetData action to wait for caller input. 5. Assuming a high time-out value, the repeat count value (the maximum number of timeouts allowed before branching to the state specified in the last timeout result field) may not be reached before the ROLM switch issues the second error tone. 6. GetData recognizes the # key in the error tone as end of input, but does not recognize the * key. 7. GetData exits with a result of Input Too Short, and branches to the state specified for this result. 8. If the state that is branched to is not CloseEverything, the state table continues to execute. 9. If the execution again encounters the GetData action, and the switch continues to issue the second error tone, the state table loops indefinitely. The problem in this example could have been eliminated by reducing the timeout and repeat count values so that the voice application timed out before the switch issued the second error tone. Answering calls AnswerCall is the state table action that answers an incoming call. Chapter 10. Telephony activity 135

154 An AnswerCall action in every state table is not mandatory, but it is useful for debugging. (See the WebSphere Voice Response for AIX: Application Development using State Tables book for information about using the debug option in the State Table window.) How does WebSphere Voice Response answer an incoming call? When WebSphere Voice Response receives an incoming call it uses the call's application profile ID to determine how it should be answered. Initially, control of the call is always passed to the Incoming_Call state table. Incoming_Call issues the AnswerCall action then the InvokeStateTable action to invoke the state table specified in the application profile. If the application profile specifies a state table called JavaApplication and the Java and VoiceXML environment is installed and running, control of the call passes to a Java application. The JavaApplication state table needs to be available in case the Java and VoiceXML environment is not running. For more information on configuring your system to answer incoming calls with Java applications, see WebSphere Voice Response for AIX: Deploying and Managing VoiceXML and Java Applications. Each state table that is designed to handle incoming calls therefore requires an application profile, and WebSphere Voice Response must find the appropriate application profile before Incoming_Call can invoke the right state table to handle the call. 136 Designing and Managing State Table Applications

155 Is WebSphere Voice Response configured to receive the called number? No SV129 is set to 0 Yes Has a called number been received? No SV129 is set to 2 Yes SV129 is set to 1 Is there an application profile to match the called number? No Yes Is there an application profile to match the channel identification? No Yes SV22 and SV185 are set to the application profile ID. Is there an application profile to match the System Default Application Profile? Yes No Incoming_Call answers the call and invokes the state table specified in the profile The call is not answered Is state table name=java Application No and is Java and Voice XML Environment running? Control is passed to the state table specified by the application profile Yes Control is passed to a Java application Figure 14. How WebSphere Voice Response finds the state table to handle an incoming call Chapter 10. Telephony activity 137

156 How does WebSphere Voice Response find the application profile? Incoming_Call works on the basis that an application profile specifying a state table has been found. Figure 14 on page 137 shows how WebSphere Voice Response finds the application profile. When a call comes in and the called number is available, WebSphere Voice Response looks for an application profile whose ID matches the called number. (If the called number was received on an exchange data link, the area code specified in the channel group is concatenated to the beginning of the number before the search.) If the called number is unavailable for any reason, WebSphere Voice Response looks for an application profile whose ID matches the channel identification (for details, see the WebSphere Voice Response for AIX: Configuring the System book). If no profile is found, WebSphere Voice Response looks for an application profile whose ID matches the value of the System Default Application Profile system parameter (whose supplied value is ). 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 Accounts_Main Tell callers their account details Interest_Main Tell callers the current interest rates Main Offer callers a choice of services. What happens when Incoming_Call answers the call? After issuing the AnswerCall action, the Incoming_Call state table invokes the state table specified in the application profile. Because it invokes the state table by application profile, Incoming_Call cannot pass any parameters to the state table. The following system variables are, however, available for the state table to use: Application - Profile ID (SV22) The ID of the application profile found by WebSphere Voice Response. System : Call Info : Called Number (SV185) The called number or, if no called number is available, the channel identification. 3. If WebSphere Voice Response is configured to go off hook in order to receive DNIS information, the system plays the caller a message saying that there are technical difficulties, and then hangs up. 138 Designing and Managing State Table Applications

157 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 calling number) was received. If the value of this variable is 1 (successful), SV185 is the called number; if the value is 0 (undefined) or 2 (failed), it is the channel identification. What happens if the state table is invalid? If there is a problem with the state table specified in the application profile, for example, if it is not found or is invalid, Incoming_Call invokes another supplied state table, Welcome, which greets the caller and hangs up. Welcome is also invoked during the installation test described in the WebSphere Voice Response for AIX: Installation book: WebSphere Voice Response finds the application profile whose ID is , and this application profile specifies Welcome as the state table. Do Incoming_Call and Welcome need customizing? Incoming_Call and Welcome are set up and ready to use. You should record a new voice segment for Welcome to play, perhaps explaining to the caller that the system is experiencing technical difficulties. Both of these applications are imported into WebSphere Voice Response as part of the installation process. Do not delete the state table specified in the State Table Name for Incoming Calls parameter (Incoming_Call), because WebSphere Voice Response cannot answer calls without it. Do not delete the application profile specified in the System Default Application Profile parameter ( ), because WebSphere Voice Response may need it to answer a call if no other application profile can be found. If they get modified or deleted by mistake, you can reimport them from /usr/lpp/dirtalk/sw/samples/basedata.imp. Can you write your own state table to answer calls? If you prefer to write your own state table to answer incoming calls, you can. If you choose a different name for it, you must change the State Table Name for Incoming Calls parameter in the Application Server Interface parameter Chapter 10. Telephony activity 139

158 group (after you've done this, you need to stop WebSphere Voice Response and start it again to make the new value take effect). If your state table for incoming calls does not include an AnswerCall action, each state table invoked by it must include its own AnswerCall action. Ayava switches send DNIS information as DTMF keys after WebSphere Voice Response answers the call, instead of using the incoming address signaling options. To use such switches with WebSphere Voice Response you must either customize the state table identified by the system parameter: State Table Name for Incoming Calls (the default is Incoming_Call) or substitute one of your own. The customized state table must include the GetData action immediately after the AnswerCall action. The KeyBuffer, Minimum, Maximum, and Timeout parameters for the GetData action should be set according to the length of the DNIS digits and the expected time to receive all digits. If you want to use the received digits to select the application profile, add an AssignData action to set SV22 with the received digits before calling the InvokeStateTable action. Handling incoming calls in your production system Even if you do not change Incoming_Call, there are several method of handling incoming calls, and your decision partly depends on the capabilities of the switch to pass the called number on to WebSphere Voice Response. You need to decide whether to: v Have one state table to handle all incoming calls v Choose the state table on the basis of the called number v Dedicate a group of channels to each voice response service, and let the switch make the decision based on the called number Have one state table to handle all incoming calls: With this method, the state table asks the caller which service they require, and invokes another state table. You only need one application profile to make this work: you can use one of the following methods: v Make the application profile ID match the value of the System Default Application Profile parameter in the General system parameters group v Give all your channels the same identification (the same area code and phone number) and make the application profile ID match this. 140 Designing and Managing State Table Applications

159 Figure 15. Application profile needed with one state table for all Choose the state table on the basis of the called number: With this method, WebSphere Voice Response can respond with the appropriate voice response service for each caller. Each caller dials a different number depending on which service they require, and gets straight through to that service. In the example shown in Table 6 on page 138, callers dial for the accounts application (Accounts_Main) or for the interest rates application (Interest_Main) Figure 16. Application profiles needed when using called number You should have one application profile for each state table that might be invoked in this way. You also need a default application profile and state table. Typically, the default state table would ask the caller which service they require, in the event that the called number is, for some reason outside your control 4, unavailable. This is the most efficient method. However, if your switch is unable to pass the called number to WebSphere Voice Response, you cannot use this method. Dedicate a group of channels to each voice response service: This method has the same advantage as choosing the state table on the basis of called number. The disadvantage of this method is that it ties channels to specific applications, which is inefficient if all the calls at one time are for one of the applications: it makes load-balancing difficult. If it's possible to get the called number from the switch, you should use that method. 4. The called number may be unavailable if, for example, the switch did not receive the full information, or because the task the switch uses to send the information is busy. Chapter 10. Telephony activity 141

160 Again, you need one application profile for each state table that might be invoked in this way Figure 17. Application profiles needed when using channel identification Making, transferring, reconnecting, and terminating calls How WebSphere Voice Response makes, transfers, reconnects, and terminates telephone calls. Call transfer Most voice response services offer the caller the opportunity to transfer a call. Call transfer can be provided in several ways, although the only standard method uses PABX station or Centrex line features. Other methods of transfer include a release link trunk, unique T1 or E1 protocols, or exchange data link. There are two types of call transfer: v Screened (or supervised) transfer v Blind transfer Screened transfer is usually preferable, but a blind transfer does reduce the duration of a successful transfer process and may be acceptable. Screened transfer With a screened transfer, the state table places the caller on hold (suspending the call) and completes the transfer only if the call to the third party is answered. If the state table detects busy tone while transferring a call, or if the third party does not answer, the state table can take one of the following actions: v Reconnect to the original caller and offer another option v Dial an alternate number v Play a please hold message and continuously retry the number until it becomes free. Blind transfer With a blind transfer, the state table places the caller on hold, sends the address of the third party, and then disconnects from the call. If the transfer is 142 Designing and Managing State Table Applications

161 unsuccessful, the switch usually places a new call to the party that originally initiated the transfer request. Implementing call transfer with WebSphere Voice Response With channel associated signaling (CAS), WebSphere Voice Response can generate call transfer request signals using feature codes (character strings consisting of 0 through 9, *, and #) with or without hook or ground flash. To transfer a call, invoke the TransferCall action. With the Transfer Call Request Signal parameter (in the Signaling Type parameter group) set to Feature Code, the Transfer Call Feature Code (in the same group) identifies the character string recognized by the switch as a call transfer request. If the CAS protocol being used does not support call transfer, but the switch has a host access control link that does support it, a custom-written signaling process (see the WebSphere Voice Response for AIX: Programming for the Signaling Interface book for details). State table actions Refer to the WebSphere Voice Response for AIX: Application Development using State Tables book for information about the following state table actions: v MakeCall v Dial v TransferCall v ReconnectCall v TerminateCall System parameters Telephony activity is defined by a number of system parameters; those that are of interest to you when designing a state table to make outbound calls include: v Maximum Ring Time (in the Application Server Interface parameter group) v Maximum Ring Wait (in the Application Server Interface parameter group) v Maximum Dial Tone Wait (in the Application Server Interface parameter group) v Reconnect Call Feature Code (in the Signaling Type parameter group) v Transfer Call Feature Code (in the Signaling Type parameter group). For details, see the online help information for these parameters, or the WebSphere Voice Response for AIX: Configuring the System book. Chapter 10. Telephony activity 143

162 Coordinated call and data transfer Coordinated call and data transfer is the process of transferring a caller to another phone number together with some data. Typically, an account number or some other identifier is passed, to allow the receiving agent to find details about the caller without having to ask them for their account number again. The receiving agent can be a person, or another voice application. To implement coordinated call and data transfer in a voice application, you need the following: v A switch that supports program data. v CallPath Server installed, either on the same pseries computer or on another pseries computer or a personal computer connected by a local area network (LAN). v The CallPath_SigProc custom server imported from /usr/lpp/dirtalk/sw/ samples/cti.imp into your WebSphere Voice Response system. A single-system installation is shown in Figure 18. Telephone Network Caller Voice Processing pseries WebSphere Voice Response State Table CallPath_SigProc Custom Server Data Communications Network Information Switch CallPath Server Local Area Network Figure 18. CallPath Server and WebSphere Voice Response installed in the same pseries computer What does the state table have to do? The CallPath_SigProc commands are documented in the WebSphere Voice Response for AIX: Application Development using State Tables book. The 144 Designing and Managing State Table Applications

163 commands are used to read or set the program data. In addition, the state table also has access to information about an incoming call in the following system variables: System : Call Info : Called Number (SV185) The called number (the number to which the call has been transferred). System : Call Info : Calling Number (SV186) The number from which the call has been transferred. System : Call Info : User 1 (SV187) The dialed number (the number the caller originally dialed). System : Call Info : User 2 (SV188) The length of the program data. Receiving Data From Another Number (Read_Program_Data) Use the EvaluateData action to test the System : Call Info : User 2 system variable (SV188). If the value is 0, there is no program data to be read. Otherwise, use a SendData to send the Read_Program_Data command to CallPath_SigProc, followed by a ReceiveData to receive two parameters: the program data itself and the length of the string. These steps are shown in Figure 19 on page 146. Transferring Data To Another Number (Set_Program_Data) Pass the data you want to associate with the transfer as a parameter when you use the SendData action to send the Set_Program_Data command to CallPath_SigProc. Use a ReceiveData action following the SendData, and check the return code. If the Set_Program_Data appears to have been successful, use the TransferCall action to make the call transfer. These steps are shown in Figure 20 on page 147. What format must the data be in? The data must be printable ASCII characters: that is, no imbedded control characters are allowed in the string. How much data can you pass? WebSphere Voice Response has a limit of 512 bytes, but your switch may have a smaller limit. If so, it is your responsibility to ensure that you do not send a longer string. Chapter 10. Telephony activity 145

164 Examples Call transferred by CallPath Server and answered by WebSphere Voice Response If the value of SV188 is not 0, there is program data to be read. EvaluateData SV188 OpenHostServerLink to CallPath_SigProc Read the program data SendData Read_Program_Data ReceiveData Read_Program_Data CloseHostServerLink Application can use the information it received in the program data. Figure 19. Receiving a call and data transferred by CallPath Server 146 Designing and Managing State Table Applications

165 A call is in progress; the caller wants to be transferred, or the application decides to transfer them OpenHostServerLink to CallPath_SigProc Set the program data. This might be an account identifier or any other data. SendData Set_Program_Data ReceiveData Set_Program_Data Transfer the call. The data is set along with the call. TransferCall CloseHostServerLink Figure 20. Transferring a call and data to another number using CallPath Server Setting the MessageWaiting Indicator using CallPath Server You can use CallPath Server to set the message waiting indicator on any phone, for example, when virtual mailboxes are in use. To do this, you need the following: v A switch that supports message waiting indication v CallPath Server installed, either on the same pseries computer or on another pseries computer or a personal computer connected by a local area network (LAN) v The CallPath_SigProc custom server imported into your WebSphere Voice Response system. Chapter 10. Telephony activity 147

166 A single-system installation is shown in Figure 18 on page 144. The steps that the state table performs are shown in Figure 21. For details about the CallPath_SigProc Set_MWI command and its parameters, see the WebSphere Voice Response for AIX: Application Development using State Tables book. A call is in progress OpenHostServerLink to CallPath_SigProc Set the message waiting indicator on or off at the specified phone number. Optionally, you can set the duration that the MWI is to be on for, and the LED frequency. SendData Set_MWI ReceiveData Set_MWI CloseHostServerLink Figure 21. Using CallPath Server to set the message waiting indication 148 Designing and Managing State Table Applications

167 Chapter 11. Designing voice messaging applications You can create your own voice messaging applications or add voice messaging to existing applications. For example, in an ordering application, you may choose to let people leave a voice message to be associated with an order. This is known as transaction-related voice messaging. Your state table can include actions that record, send, check, play, annotate, delete, and save voice messages, and change their attributes. Note: If you require a voice mail system, you should also consider whether IBM s Unified Messaging program offering would satisfy your needs. Unified Messaging is a fully functional voice mail application that can be extensively tailored. For more information, see your IBM representative. Voice messaging resources This section describes the resources used for voice messaging: v Voice Mailboxes v Greetings v Audio Names v Distribution lists Voice mailboxes Voice messages are stored in mailboxes. To define mailboxes, you need an application profile. You can define up to ten mailboxes in one application profile, or you can give each mailbox its own profile. The application profile ID can be any value you want, but, for a voice mail application, the phone number or extension number of the subscriber who owns the mailbox is probably most convenient. In transaction messaging, you can use the different mailboxes in an application profile to store different categories of voice message. In this case, each subscriber has an application profile, each of which specifies the name of your voice mail application's initial state table. For more information about creating and maintaining mailboxes, see Chapter 12, Managing voice messaging resources, on page 167. Copyright IBM Corp. 1991,

168 Greetings An application profile can define up to 255 greetings. Each mailbox defined for the profile can use one or more greetings; a mailbox can play different greetings depending on the value of the Caller : Mailbox : Owner Status system variable (SV102). Each greeting is identified by a greeting ID. The administrator of a WebSphere Voice Response system can specify that all new greetings recorded using state table actions are compressed, or that they are all not compressed. The administrator specifies this using the User Greeting Compression Type system parameter. Audio names Each mailbox can also have an associated audio name that is normally used to contain the digitized voice data that identifies the owner of a mailbox. The audio name can be played to callers who leave and retrieve messages to identify the owner of a mailbox. Audio names are stored in compressed format only. The administrator of a WebSphere Voice Response system can specify that all new audio names recorded using state table actions are compressed, or that they are all not compressed. The administrator specifies this using the Audio Name Compression Type system parameter. Distribution lists A distribution list is a list of application profile IDs and mailbox IDs or other distribution list IDs, to which a message can be sent. There is no limit to the number of members in each distribution list. The distribution list is identified by a four-digit ID. A distribution list can be public or private to the mailbox for which it is defined. There are state table actions to manipulate distribution lists and distribution list editing functions available to the system administrator. For more information about creating distribution lists, see Chapter 12, Managing voice messaging resources, on page 167. Accessing mailbox information To access mailbox information, the state table must set the Caller - Profile ID system variable (SV20). To access information about a specific mailbox in the application profile, the state table must set the Caller : Mailbox - ID system variable (SV32). The rest of the Caller system variables are initialized with appropriate values when SV20 and SV32 are set. SV20 can be set in the following ways: 150 Designing and Managing State Table Applications

169 v When WebSphere Voice Response automatically loads it with the calling number information. In this case, the profile data is not retrieved from the database until the state table writes to SV20 (use AssignData to set SV20=SV20). v When the state table assigns a value to it using GetFindName, GetData, ReceiveData, or AssignData. In this case, the profile data is retrieved from the database when the state table writes to SV20. Using state table actions for voice messaging This section lists the state table actions for voice messaging. Voice mailboxes Task Set or change the attributes of a voice mailbox State Table Action UpdateProfile Voice messages Task Record a new voice message Add more to the beginning of a voice message Add more to the end of a voice message Set or change the attributes of a voice message Send a voice message to the mailbox specified by the application profile ID and mailbox ID State Table Action RecordVoiceMessage RecordVoiceMessage RecordVoiceMessage ChangeMessageAttributes SendVoiceMessage Retrieve all voice messages of a specified type for the application profile specified by SV20 and mailbox ID specified by SV32 CheckVoiceMessages Play a voice message from a mailbox Save a voice message, which has been retrieved using CheckVoiceMessages, in the mailbox for later retrieval PlayVoiceMessage SaveVoiceMessage Play back a voice message which has just been recorded PlayVoiceMessage Chapter 11. Designing voice messaging applications 151

170 Task Remove a voice message previously retrieved using CheckVoiceMessages State Table Action DeleteVoiceMessage Distribution lists Task Retrieve names of all recipients on a specified distribution list for a specified application profile and mailbox ID Retrieve names of all distribution lists for a specified application profile and mailbox ID Add a mailbox to a distribution list Add a distribution list to a distribution list Remove a name from a distribution list Remove a distribution list Copy a distribution list Append a distribution list to another distribution list State Table Action GetDistributionList GetDistributionList UpdateDistributionList UpdateDistributionList UpdateDistributionList UpdateDistributionList UpdateDistributionList UpdateDistributionList Audio names Task Record an audio name Store the audio name for the application profile and mailbox ID Play the audio name of the specified application profile and mailbox ID Remove the audio name of the specified application profile and mailbox ID State Table Action RecordAudioName SaveAudioName PlayAudioName DeleteAudioName 152 Designing and Managing State Table Applications

171 Greetings Task Record a greeting Store the greeting for the specified application profile and mailbox ID Play the greeting associated with the specified application profile and mailbox ID Remove the greeting specified by system variable SV102 State Table Action RecordUserGreeting SaveUserGreeting PlayUserGreeting DeleteUserGreeting Interacting with callers and messages A caller is anyone who dials or calls into the system, for example, to record a message or greeting or listen to a voice message. This caller is represented by the Caller : Profile - ID system variable (SV20), and the mailbox from which voice messages are sent or retrieved for listening is represented by the Caller : Mailbox - ID system variable (SV32). Each voice message is always associated with the Profile ID and Mailbox ID from which it was sent and the Profile ID and Mailbox ID from which it is to be retrieved. Recorded voice messages are stored in temporary workspace until they are sent to a mailbox. Voice messages can be retrieved from mailboxes to be played, annotated (repeatedly, if required), sent, deleted, saved, or their attributes can be changed before sending them to a specified mailbox. The attributes of a message in a mailbox are defined by the Message system variables, described in the WebSphere Voice Response for AIX: Application Development using State Tables book. The status of a message is stored in the Message : Status system variable (SV47). Incoming messages are received messages in the recipient's mailbox; the status of incoming messages can be New, Checked, Listened, Saved, or Undeliverable. Outgoing messages are sent messages in the sender's mailbox; the status of outgoing messages can be New or Future. Recording messages The RecordVoiceMessage state table action records a message in the workspace. Recording a new message clears the workspace of any existing voice data. RecordVoiceMessage is also used to annotate an existing message, as described in Annotating messages on page 156. Chapter 11. Designing voice messaging applications 153

172 After recording, a message is typically sent to a specified mailbox using the SendVoiceMessage state table action. Sending messages The SendVoiceMessage state table action sends a message to a mailbox. The message is stored in the recipient's mailbox as a New message, and is added to the sender's outgoing messages. If sent to someone else's mailbox, the message will be kept in the sender's outgoing messages until the recipient checks the message. If the message is future dated (status is Future), the message is not sent to the recipient's mailbox until the specified date and time. SendVoiceMessage is also used to forward messages from one mailbox to another, as described in Forwarding messages on page 155. If the sender requested acknowledgment of the message (using the Receipt Acknowledgment parameter of ChangeMessageAttributes), the message will be sent to the sender's mailbox as a New message when the recipient plays or deletes the message. The Message : Receipt acknowledgment status system variable (SV161) is set to indicate whether the message was listened to or not. Retrieving messages The CheckVoiceMessages state table action retrieves a list of messages from a mailbox. Before a message in a mailbox can be played, forwarded, annotated, saved, deleted, or the attributes changed, it must be retrieved from the mailbox by CheckVoiceMessages. When a message is retrieved, the Message system variables are initialized with the message information. Whenever the mailbox is accessed and a New message is counted, SV32 is set and the status of the message is changed to Checked. A retrieved message remains Checked until it is listened to, saved, or deleted. CheckVoiceMessages can retrieve one of the following categories of messages: v First Incoming New. Includes all incoming New, Checked, Listened, or Undeliverable messages. v First Incoming Saved. Includes all incoming Saved messages. v First Outgoing To All Recipients. Includes all outgoing messages (the messages that have a status of New or Future that have not been checked by the recipient). v First Outgoing To Selected Recipient. Includes outgoing messages sent to a specific recipient (the messages that have a status of New or Future that have not been checked by the recipient). v Next Message. Retrieves the next message in the list. When a list of messages is retrieved, the first message in the list is the current message, which can be played, forwarded, annotated, saved, deleted, or the 154 Designing and Managing State Table Applications

173 attributes changed. Once the list is retrieved, subsequent CheckVoiceMessages (Next Message) actions update the current message to the next message in the list. The Message system variables are always initialized with the current message information. To select a specific message in the list, you can use the AssignData state table action to assign a value to a Message system variable that defines the message you want. For example, to select the third message in a list retrieved by CheckVoiceMessages, you can assign the Message : Message number system variable (SV21) a value of 3. This automatically updates the current message to the third message in the CheckVoiceMessages list. You can also select a specific message based on the transaction ID of the message. By setting the Message : Transaction ID system variable (SV126) to a value, the list is searched for a message with a transaction ID that matches the value. If the first message in a newly retrieved list matches, that message remains the current message. Subsequent AssignData actions select and refresh the workspace information with subsequent matching messages in the list. In other words, subsequent checks for matches with the same transaction ID begin following the current message, not starting with the current message. If the sender requested acknowledgment of the message (using the Receipt Acknowledgment parameter of ChangeMessageAttributes), the Message : Receipt acknowledgment status system variable (SV161) has a value of 1. Playing messages If the voice message has just been recorded, the PlayVoiceMessage action plays it from the workspace; if the voice message is the current message in the list of retrieved messages, the PlayVoiceMessage action plays it from the mailbox. As soon as the mailbox is accessed, the status of all messages changes from New to Checked. When a message has been played successfully all the way through to the end, the status changes to Listened. If the sender requested acknowledgment of the message, (using the Receipt Acknowledgment parameter of ChangeMessageAttributes), the message is sent to the sender's mailbox as a New message when the recipient plays the message and the Message : Receipt acknowledgment status system variable (SV161) has a value of 2, which indicates that the message was listened to. Forwarding messages After a message has been retrieved from a mailbox, the SendVoiceMessage state table action can be used to forward the message from one mailbox to another. The recipient of a message can forward the message directly to another mailbox or can first change the attributes of a message or annotate the Chapter 11. Designing voice messaging applications 155

174 message before forwarding. In all cases, the sender information of the forwarded message reflects the forwarder. The sender information of the original message remains unchanged. For example, if Jay sends a message to Nick's mailbox, and Nick then forwards it to Daisy, the message in Daisy's mailbox will indicate Nick as the sender. Nick can also record an annotation to the message before sending it to Daisy. Jay's outgoing messages include the original message sent to Nick, but not the annotated message sent by Nick to Daisy. Nick's incoming messages include the original message sent by Jay; his outgoing messages include the message sent to Daisy. Daisy's incoming messages include the message sent by Nick. Annotating messages The RecordVoiceMessage state table action can use the options Add To Beginning and Add To End to annotate the message. The message can be a newly recorded message in the workspace or the current message retrieved by CheckVoiceMessages. The same message can be annotated multiple times. Changing message attributes The ChangeMessageAttributes state table action sets and changes the attributes of the message in the workspace. The attributes that can be changed are the date it is to be delivered, the security level, urgency level, whether to acknowledge receipt of the message, or transaction ID. Deleting messages After a voice message has been retrieved from a mailbox, the DeleteVoiceMessage state table action can be used to change the status of the message in the list to Deleted and clears the Message system variables. If the sender requested acknowledgment of the message (using the Receipt Acknowledgment parameter of ChangeMessageAttributes), and the recipient did not play the message before deleting it, the message is sent to the sender's mailbox as a New message and the Message : Receipt acknowledgment status system variable (SV161) has a value of 3, which indicates that the message was received but not listened to. Saving messages After a voice message has been retrieved from a mailbox, the SaveVoiceMessage state table action can be used to change the status of the message in the mailbox from Checked, Listened, or Undeliverable to Saved. 156 Designing and Managing State Table Applications

175 If you make any changes to a voice message (by using ChangeMessageAttributes or RecordVoiceMessage), you have created a new message, which must be sent to a mailbox. The mailbox can be the sender's own mailbox, or a different mailbox. If sent to the sender's mailbox, the message will be a New incoming message. If sent to someone else's mailbox, the message will be kept in the sender's outgoing messages until the recipient checks the message. Whether a message is sent to the sender's own mailbox or to another mailbox, the message is always added to the sender's outgoing messages list. System parameters that affect voice messaging The following parameters in the Application Server Interface parameter group affect voice applications that include messaging or use mailboxes: v Password Minimum Length v Play Skip v User Identifier Minimum Digits The following parameters in the General parameter group control the length of each voice message: v Record Voice Maximum Pause v Record Voice Maximum A sample voice message application The sample called VoiceMessagingSample is a voice application that includes messaging. The sample called RecordAudionameSample allows you to record the name of the owner of a mailbox for a voice application to speak to a caller (an audio name). To use these samples, you must: 1. Import the VoiceMessagingSample.imp and RecordAudionameSample.imp files. The import file is located in the /usr/lpp/dirtalk/sw/samples directory. 2. Create an application profile for it (see Chapter 5, Creating an application profile, on page 89). 3. Create the mailboxes for which you plan to record the audio names (see Creating mailboxes for application use on page 170). 4. Use RecordAudionameSample to record some audio names. RecordAudionameSample RecordAudionameSample enables you to record an audio name for an application profile mailbox. Chapter 11. Designing voice messaging applications 157

176 Note: This sample includes a state table and a prompt that are both named RecordAudioName. This is a reserved word in the ASCII state table language, so if you export these files for use as the basis for a new application, you must rename them. VoiceMessagingSample VoiceMessagingSample is an example of a messaging application that allows callers to: v Record messages v Listen to messages v Send messages (to individuals or to a distribution list) v Annotate (add to) messages v Save messages v Forward messages v Change personal options such as distribution lists, passwords, and greetings The flow of control in VoiceMessagingSample is illustrated in Figures Figure 22 on page 159 through Figure 24 on page 161. The application is modular, with the state table VoiceMsgMenu as the main controlling loop that calls the other state tables according to the caller s input. 158 Designing and Managing State Table Applications

177 VoiceMsgMenu Answer the call VoiceMsgAnswer Answer the call Get the profile ID Play the greeting Get the password Invoke VoiceMsgRecord Home state Exit 1 Record a message 2 Listen to your messages 3 Personal options Invoke VoiceMsgRecord Invoke VoiceMsgListen Invoke VoiceMsgOptions 9 Help 0 Exit Figure 22. VoiceMsgMenu and VoiceMsgAnswer Chapter 11. Designing voice messaging applications 159

178 VoiceMsgRecord Record the message VoiceMsgListen Listen Annotate the message Summary 1 Append 2 Prefix Message type 3 Re-record 1 New 5 Send 2 Saved 7 Listen 3 Outgoing Special delivery Play the message 1 Acknowledgement 2 Future delivery Message options 5 Send 1 Reply Invoke VoiceMsgRecord 2 Next message Destination 3 Save 1 To single recipient 5 Delete 2 To distribution list 7 Listen 9 Forward Invoke VoiceMsgRecord Send Check next message Resend 1 2 Send again Finished Figure 23. VoiceMsgRecord and VoiceMsgListen 160 Designing and Managing State Table Applications

179 Choose a person option 1 Greeting 1 Greeting Record new greeting 3 Password 2 Listen to current greeting 5 Distribution lists 6 Select standard greeting Distribution lists 1 Modify distribution list 2 6 Review distribution list Delete distribution list Modify distribution list Add recipient Review recipient Delete recipient Figure 24. VoiceMsgOptions An example state table Figure 25 on page 162 shows an example of the listing you get when you print a state table from WebSphere Voice Response. For each state, the listing has three sections: 1. The optional state State Label, the Action, and an optional Description. In Figure 25 on page 162, the first state in the table is labeled summary, its action is a PlayPrompt, and its description is Play summary of messages prompt. The second state is unlabeled, it is also a PlayPrompt, and its description is Play message type selection prompt. Chapter 11. Designing voice messaging applications 161

180 2. TRANSITIONS This section tells you the possible results that can be returned by the action, with the label of the state specified as the Goto State (the next state for that result). A blank in the Goto State column indicates that the state that follows this one will be the next state for that result. For example, the first action (summary) has four possible results: v If the action succeeds, the state table proceeds with the state that follows this one. v If there is a line problem, the next state is the state labeled error. v If nothing is played, the next state is the state labeled error. v If the caller hangs up, the next state is the state labeled end. 3. PARAMETER VALUES This section lists the parameters and the values set for them. In the first action (summary), the Prompt parameter specifies the name of the prompt (in this case, the Summary prompt) and the Force Play parameter, which is set to False, specifies that the prompt can be interrupted by the caller. State Table - VoiceMsgListen Voice Messaging Sample - "Listen" State Label Action Description =============== ==================== ====================================== summary PlayPrompt Play summary of messages prompt TRANSITIONS Result Goto State Succeeded Line Problem error Nothing Played error Caller Hung Up end PARAMETER VALUES Parameter Value Prompt Summary Force Play False Figure 25. Example listing of the first two states in a state table 162 Designing and Managing State Table Applications

181 State Label Action Description =============== ==================== ====================================== PlayPrompt Play message type selection prompt TRANSITIONS Result Goto State Succeeded Line Problem error Nothing Played return Caller Hung Up end PARAMETER VALUES Parameter Value Prompt MessageType Force Play False An example prompt The prompt for VoiceMsgSummary is typical of those you will write when creating a WebSphere Voice Response application. IF SV28 = 0 AND SV29 = 0 AND SV31 =0 THEN VOICE VoiceMsg (200); # You have no... VOICE VoiceMsg (220); #...messages If the caller s mailbox contains no new messages (SV28), saved messages (SV29), or outgoing messages (SV31), this section plays You have no messages (voice segment 200 followed by voice segment 220 in the VoiceMsg voice directory). Chapter 11. Designing voice messaging applications 163

182 ELSE ENDIF VOICE VoiceMsg (210); # You have... IF SV28!= 0 THEN SYSPROMPT Whole_number (SV28); VOICE VoiceMsg (250); #...new... PROMPT Message_s (SV28); IF (SV29 = 0 AND SV31!=0) OR (SV29!= 0 AND SV31 = 0) THEN VOICE System (301); #...and... ENDIF ENDIF This section plays You have (voice segment 210). It then checks SV28 to see if the caller has any new messages. If there are new messages, the Whole_number system prompt plays the value of SV28. This is followed by voice segment 250, which plays the word new and then the Message_s prompt. Message_s is a subroutine that determines whether the value passed as a parameter is 1, or >1. If this value is 1, the word message is played, otherwise the word messages is played. Next, SV29 (saved messages) and SV31 (outgoing messages) are checked. If either variable contains a number other than 0, the system prompt 301, which contains the word and, is played. 164 Designing and Managing State Table Applications

183 IF SV29!= 0 THEN SYSPROMPT Whole_number (SV29); VOICE VoiceMsg (250); #...saved... PROMPT Message_s (SV29); ENDIF # Determine whether to say and IF SV31 =!0 THEN VOICE System (301); #...and... ENDIF IF SV31!= 0 THEN SYSPROMPT Whole_number (SV31); VOICE VoiceMsg (270); #...outgoing... PROMPT Message_s (SV31); ENDIF This section checks SV29 to determine if the caller has saved messages. If so, it calls the system prompt Whole_number to play the value in SV29, followed by voice segment 250, which plays the word saved. The prompt Message_s again determines whether to play the work message or the word messages. Next, SV31 (outgoing messages) is checked. If it contains a number other than 0, the system prompt 301, which contains the word and, is played. This section checks SV31 to determine if the caller has outgoing messages. If so, it calls the system prompt Whole_number to play the value in SV31, followed by voice segment 270, which plays the word outgoing. The prompt Message_s again determines whether to play the word message or the word messages. Chapter 11. Designing voice messaging applications 165

184 166 Designing and Managing State Table Applications

185 Chapter 12. Managing voice messaging resources This chapter describes how to create and maintain mailboxes, subscriber classes and distribution lists for use by a voice messaging application. Messages occupy disk space, and disk space usage must be monitored. You can control the use of mailboxes by defining subscriber classes and assigning mailboxes to them. This can be done at any time, either when you first create the application profile, or later. The system administrator creates mailboxes for new users, removes unwanted mailboxes, and can also create, update, and remove distribution lists for general use or as required by subscribers. The system administrator can also view the number and status of messages in the mailboxes (the content of the messages cannot be accessed by the system administrator). If you are implementing a large-scale voice messaging application, you should also read about supporting applications that require a large amount of voice data in the WebSphere Voice Response for AIX: Installation book. Voice mailboxes Voice mailboxes are required for voice messaging. They are logical mailboxes, not physical ones: the system does not reserve space on the disk for each mailbox. When you define mailboxes for an application to use, you are really activating a mechanism that enables the state table messaging actions to work properly. If no mailboxes have been created, the messaging actions cannot work correctly. How do I create a mailbox? Mailboxes always belong to an application profile. Up to 10 mailboxes can be activated on any one application profile. You can do this either in the Application Profile window or by using the wvrapplprof and wvrmailbox commands. See Creating mailboxes for application use on page 170 What mailbox information does the application profile include? The application profile includes information that the voice application and the system administrator can use to control the usage of the mailboxes. The profile specifies, for example: v How many mailboxes the application can use. Copyright IBM Corp. 1991,

186 v What greeting the application plays to callers by default. v A password for each mailbox. v A referral telephone number at which the mailbox owner can be reached. v What greeting the owner of a mailbox wants played to callers who reach the mailbox when the owner has recorded more than one greeting. v A status for the owner, which can also control which greeting is played. v Whether a mailbox takes messages or only plays the owner s greeting. v The order in which messages are retrieved. v Whether callers can leave and retrieve messages in any mailbox controlled by the application or only in the current mailbox. v Which set of prompts a caller accessing the mailbox should hear when the application includes more than one set of prompts. How is mailbox information used? When the Caller - Profile ID system variable (SV20) and Caller - Mailbox ID system variable (SV32) have been set by an AssignData action, causing the profile information to be retrieved, the system loads each item of the mailbox information into a separate system variable. For example, if the application profile includes information about the owner s status, WebSphere Voice Response loads the information into the Caller: Mailbox: Owner status system variable (SV102). Voice applications can make control decisions based on the value of a variable. In this example, assuming the owner had recorded alternative greetings to be played when he was out of town or sick, the messaging application could use the value of SV102, Caller : Mailbox: Owner status to determine which greeting to play. Whether an application checks the value of the system variable that holds profile information is up to the application developer. Controlling messages All messages assigned to a mailbox are stored on the hard disk in the pseries computer. If one mailbox accumulates a lot of messages (or even a few very long messages), the messages can take up a large amount of disk space. WebSphere Voice Response includes two tools to help you control how much disk space messages can use. One controls the maximum length of a message. The other controls how many messages an application can store in a single mailbox. 168 Designing and Managing State Table Applications

187 Limiting message length The maximum length of a message is controlled by the Record Voice Maximum system parameter in the General parameters group. This controls the length of any voice data that is recorded over the telephone, both messages and voice segments. If you change the value of Record Voice Maximum, you will have to stop WebSphere Voice Response and start it again, for the new value to take effect. When the system is delivered, the parameter is set at 120 seconds. You can reset it to limit recorded voice to any number of seconds between 30 and In a state table, you can override the value of the Record Voice Maximum system parameter, by setting the System : Maximum record time system variable (SV179). Limiting the number of messages The object that controls the maximum number of messages in a single mailbox is called a subscriber class. The use of subscriber classes is optional. What are subscriber classes? Subscriber classes specify values that allow a voice application to control the use of mailboxes. Each subscriber class can specify different value for: v The maximum number of mailboxes that can be assigned to guest users v The maximum number of messages that a mailbox can accept v The maximum number of distribution lists that can be constructed for each mailbox v The maximum number of entries in a distribution list constructed for any mailbox v The maximum record time per message v The maximum number of greetings that the mailbox owner can record for a mailbox How do subscriber classes work? Subscriber classes allow you to limit the use of one or more sets of mailboxes at once. Using subscriber classes, you can also specify limits other than the system limits to a group of mailboxes. To use a subscriber class, specify it in an application profile. Specifying a subscriber class in an application profile indicates that you want the limits included in the definition of that subscriber class to apply to all mailboxes defined by that application profile. When the Out Mail - Profile ID system variable (SV25) and Application - Profile ID system variable (SV22) have been set and a profile that specifies a subscriber class has been retrieved, the system loads the values specified in the subscriber class definition into the appropriate Caller : Subclass system Chapter 12. Managing voice messaging resources 169

188 variables. (For more information on the system variables, see the WebSphere Voice Response for AIX: Application Development using State Tables book.) Once the values have been loaded into the variables, the voice application can check them and enforce the limits. WebSphere Voice Response does not automatically enforce the limits in a subscriber class definition. The voice application itself must include state table actions to ensure that the limits are not exceeded. When should you define subscriber classes? You can define subscriber classes at any time, before you create application profiles, or after your system has been operating for a while. You may find that you never need subscriber classes. Remember, subscriber classes only specify limits on the use of mailboxes. The voice application that is written to access the mailboxes must check these limits and then enforce them. Creating mailboxes for application use You can create mailboxes in two ways, using either the graphical user interface (GUI), or the wvrapplprof and wvrmailbox commands. Before you start WebSphere Voice Response does not automatically check mailbox definitions: only the messaging application can check to make sure mailboxes are being used properly. Therefore, the application designer must tell you what information is necessary. The application designer can interpret the system variables in any way that is appropriate. For example, value 0 for the Caller : Mailbox : Access mode system variable (SV106) is documented as meaning Global, but your application may use it to mean Read-only. To make it easier to use such Mailbox Options in the Application Profile window, you could edit the display text in the language database (see the WebSphere Voice Response for AIX: Configuring the System book for details). Using the graphical interface 1. In the Welcome window, click on Configuration > Application Profiles 2. Activating mailboxes : Open the application profile. If you haven't yet created it, follow the instructions in Chapter 5, Creating an application profile, on page Designing and Managing State Table Applications

189 3. Click Show Mailbox 1 Properties. The window expands to display the properties of mailbox 1. A single application profile can contain details of up to 10 mailboxes. Each mailbox is identified with a number from 1 through 10. When an application uses more than one mailbox, callers can enter this mailbox ID to select a mailbox to access. The selected mailbox then becomes the current mailbox. 4. Click the Active checkbox to make this mailbox active. 5. To specify a default active greeting for this mailbox, type the identifier of the greeting in the Profile Active Greeting field. 6. To activate another mailbox, click the Mailbox drop-down button, which reveals the mailbox identifiers 1 through 10. Click the identifier of the mailbox you want to activate. Note: The active mailbox IDs do not have to be sequential. For example, an application requiring three mailboxes can use 2, 6, and 10. The window changes to display the properties of the selected mailbox. Chapter 12. Managing voice messaging resources 171

190 7. Defining options for a mailbox : Click the mailbox from the Mailbox drop down button. 8. Click Show Mailbox 1 Options. The window opens up to display the options for the selected mailbox. 9. Fill in the fields as appropriate for your application. Note that WebSphere Voice Response itself does not use this information: it passes the 172 Designing and Managing State Table Applications

191 information on to the state table, without any validation. The following text describes each field name displayed in the Mailbox Options. Similar field names are used in the wvrmailbox command prompt as shown in Table 7 on page 179, where the corresponding GUI field names are shown in italics. Active Greeting Number identifies which greeting an application should play to callers when the owner has recorded more than one greeting. Announce and determines whether a caller who reaches the mailbox can leave a message. The default is Announce and Take Messages. Application Status indicates whether the owner of the mailbox is In, Out, Sick, Busy,or Traveling. Access Mode specifies how callers can use any mailboxes created for use by the application. Global access means that a caller can retrieve or leave messages in any mailbox. Read All access means that a caller can retrieve a message from any mailbox but only leave messages in the current mailbox. Read Write means that a caller can access only the current mailbox. The default is Global. Mailbox Busy indicates whether the mailbox is currently being used. Password identifies a password that opens the mailbox for the caller to retrieve messages. Password use is optional: you can create a mailbox without a password. It is up to the application to check such things as the length against the Password Minimum Length parameter in the Application Server Interface parameter group. The default value for this is four digits. The maximum length of a password is always eight digits. Again, it is up to the application to check this. Password change date date after which password must be changed. address address for notification. Retrieval Order specifies how messages are ordered in the message selection lists you can use to maintain the contents of a mailbox. It also defines the order in which messages are retrieved for a caller. (For more information on mailbox maintenance, see the information in the Chapter 12. Managing voice messaging resources 173

192 WebSphere Voice Response for AIX: Managing and Monitoring the System book.) Messages are grouped first by priority. All messages of the same priority are then sorted into chronological order: first in, first out (FIFO), or last in, first out (LIFO). The default is FIFO (the system lists the earliest message received first). Prompt Level specifies whether callers should hear Normal prompts, Novice prompts, or Expert prompts. If voice application developers have written three different sets of prompts and the application includes logic to check which set to use, this information determines which prompts the caller hears. The default is Normal. Play headers plays message header, before listening to each message: Play message headers, ordon't play message headers. New message delete allows subscribers to elect to delete new messages without listening to the whole message. The default is Don't delete messages without listening. Save messages automatically allows subscribers to elect to save new messages automatically after listening. The default is Only save when requested. Send message allows subscribers to select when to specify the address of the message: before, or after, recording the message. The default is Address after recording the message. Clock preference clock preference used by notification schedules, either 12-hour clock or 24-hour clock. Bilingual greeting user specifies whether to play bilingual greetings. First time user indicates the status of the subscriber: Yes: mailbox has never been entered or No: the user has listened to the tutorial already. Use the scroll bar to reveal more fields in the Mailbox Options 174 Designing and Managing State Table Applications

193 Assistant number an assistant (also known as deputy ) number is the number of another person who might be a useful contact for your callers. Chapter 12. Managing voice messaging resources 175

194 Temporary assistant number specifies a temporary alternative number for your assistant number. Reach-Me number ReachMe number. Temporary Reach-Me number PIN to be used when receiving calls transferred via the reach-me facility. Operator number Operator number. Referral Number specifies a number at which the mailbox owner can be reached. The number must be a string of up to 20 digits (no hyphens or parentheses). Temporary referral number temporary call-forwarding number. Referral Type specifies whether the referral number is a telephone number or a beeper number. The default is Telephone. Pager number paging bureau number. Pager reference pager reference number. Temporary pager number temporary paging bureau number. Temporary pager reference temporary pager reference number. Default fax number specifies fax number; a 20-character numeric string. Temporary fax number specifies temporary fax number VPIM address address for SMTP/MIME delivery VPIM MDP specifies the message delivery preference for VPIM. It can be Local, Remote, orlocal and Remote. The default is Local. VPIM voice format VPIM voice format 176 Designing and Managing State Table Applications

195 Notification schedule status specifies whether all notification schedules are turned On or Off. 10. To set the options for another mailbox, click on the Mailbox drop down button, which reveals the mailbox ids 1 through 10. Select the mailbox number you want to activate. The window changes to display the properties and options of the selected mailbox. 11. Click File > Save. The mailboxes are defined and ready for use. Using the wvrapplprof and wvrmailbox commands Before you can use the wvrmailbox command, you must import the admin custom server (see Importing application objects on page 46) and make sure that it is running (see WebSphere Voice Response for AIX: Managing and Monitoring the System). To activate mailboxes: 1. If the application profile does not already exist, use the wvrapplprof -n command to create it and set the number of active mailboxes. For example, if you want to allow five mailboxes to be associated with the application profile, type the following command and press Enter: wvrapplprof -n -I N name -S application -E entrypoint -B 5 2. If you need more mailboxes, activate them using the wvrmailbox command. For example, to activate mailbox 6 type: wvrmailbox -m -I M 6 -F mailbox_status -V 1 For more information see wvrapplprof command on page 94 and wvrmailbox command. To set or modify the options for a mailbox, use the wvrmailbox -m command with the -F and -V flags as described in wvrmailbox command. wvrmailbox command Purpose List mailboxes associated with an application profile, or change, or view details of mailboxes associated with an application profile. Note that the application profile must already exist (see wvrapplprof command on page 94). Prerequisites Before you can use the wvrmailbox command, you must import the admin custom server (see Importing application objects on page 46) and make sure that it is running (see WebSphere Voice Response for AIX: Managing and Monitoring the System). Chapter 12. Managing voice messaging resources 177

196 Syntax wvrmailbox -h -l-iprofile_id -m-iprofile_id -M mailbox_id [[-F field_name -V value]...] -v-iprofile_id -M mailbox_id {-F all -F field_name ]...] -? } Action flags All action flags are lowercase. -h Display help for the command -l List all the mailboxes associated with the application profile identified by profile_id. -m Modify the mailbox identified by profile_id and mailbox_id, as specified by the other parameters. -v View the details of the mailbox identified by profile_id and mailbox_id. -? Display help for the command. Attribute flags All attribute flags are uppercase and followed by a value. -I The profile ID of the application profile. -M The number of the mailbox. -F The field name to be modified or viewed. To specify multiple fields, specify -F as many times as you need. -V The corresponding value for the field to be modified. You must specify a -V flag and value for each -F flag and field name. Examples List all mailboxes of application profile : wvrmailbox -l -I Activate mailbox 1 for application profile : wvrmailbox -m -I M 1 -F mailbox_status -V 1 Modify some details of mailbox 2 for application profile : 178 Designing and Managing State Table Applications

197 wvrmailbox -m -I M 2 -F deputy_number -V F _address -V fred@whizzsystems.com View some details of mailbox 1 for application profile : wvrmailbox -v -I M 1 -F mailbox_status -F clock_pref View all the details of mailbox 1 for application profile : wvrmailbox -v -I M 1 -F all Field names For an alphabetical list of field names that are valid with the -F attribute flag, see the table that follows. All of these fields are user-modifiable except those marked as display-only in the Field Data column. Corresponding fields names used in the GUI are shown in italics. Table 7. Mailbox field names used with wvrmailbox command Field Name Description Length Field Data access_mode Access Mode This specifies how callers can use any mailboxes created for use by the application. Global access means that a caller can retrieve or leave messages in any mailbox. Read All access means that a caller can retrieve a message from any mailbox but only leave messages in the current mailbox. Read Write means that a caller can only access the current mailbox. 1 0 = Global (default) 1 = Read All 2 = Read/Write announce_only Announce and Determines whether a caller who reaches the mailbox can leave a message. 1 0 = take messages (default) 1 = don't Chapter 12. Managing voice messaging resources 179

198 Table 7. Mailbox field names used with wvrmailbox command (continued) Field Name Description Length Field Data autosave_new_msgs Allows subscribers to elect to save 1 0 = no (default) 1 = yes Save messages automatically new messages automically after listening. bilingual_grt Bilingual greeting user box_id Mailbox clock_pref Clock preference delete_new_msgs New message delete deputy_number Bilingual greeting user. Indicates the mailbox number. Clock preference used by notification schedules. Let subscribers delete new messages without listening to the whole message. 1 1 = play 0 = don't play 2 From1to10 This is a mailbox property display-only field 1 0 = 12-hour (default) 1 = 24-hour 1 0 = no (default) 1 = yes Assistant number 20 numeric string Assistant number _address address fax_number Default fax number first_time_user First time user Address for notification Fax number; a twenty-character numeric string First time user status 255 text 20 numeric string 1 0 = New mailbox (default) 1 = Tutorial has been used 180 Designing and Managing State Table Applications

199 Table 7. Mailbox field names used with wvrmailbox command (continued) Field Name Description Length Field Data mailbox_active_grt Active Greeting Number Identifies which greeting an application should play to callers when the owner has recorded more than one greeting. 3 0 = Default 1 = Personal greeting 1 2 = Personal greeting 2 3 = Personal greeting 3 4 = Personal greeting 4 5 = Personal greeting 5 7 = Announcement-only greeting 9 = System default 10 = System default announcement-only 11 = Alternative system announcement-only 12 = Alternative announcement-only mailbox_busy Mailbox Busy mail_status Active new_messages New notif_sched_status Notification schedule status number_of_mailboxes Total Active Mailboxes operator_number Operator number Is the mailbox currently busy on a call. Indicates whether mailbox is active or inactive Displays how many new messages are in the mailbox This specifies whether all notification schedules are turned On or Off. The number of mailboxes which are active. The number of the switchboard operator at your location. This is the default number to which a call is transferred if a caller chooses that option when leaving a message. Subscribers can set their own operator number to override the system default. 1 0=no 1 = yes 1 0 = inactive 1 = active This is a mailbox property display-only field 1 0 = All off 1 = Active on This is a mailbox property display-only field 20 numeric string Chapter 12. Managing voice messaging resources 181

200 Table 7. Mailbox field names used with wvrmailbox command (continued) Field Name Description Length Field Data outgoing_messages Outgoing Displays how many outgoing messages are in the mailbox. This is a mailbox property display-only field pager_number Pager number pager_ref Pager reference password Password Phone number of your pager Some pagers are identified by a unique reference number. If your pager uses a reference number, you can set this by entering it in this field. This identifies a password that opens the mailbox for the caller to retrieve messages. Password use is optional. You can create a mailbox without a password. It is up to the application to check such things as the length against the Password Minimum Length parameter in the Application Server Interface parameter group. The default value for this is four digits. The maximum length of a password is always eight digits. Again, it is up to the application to check this. 20 numeric string 20 numeric string 8 max numeric string 182 Designing and Managing State Table Applications

201 Table 7. Mailbox field names used with wvrmailbox command (continued) Field Name Description Length Field Data password_change_date Password change date Date after which password must be changed 8 YYYYMMDD play_headers Play headers profile_active_grt Profile Active Greeting prompt_level Prompt Level reachme_number Reach-Me number referral_number Referral Number referral_type Referral Type Play header before message. Specifies the identifier of the active greeting that will be played when a caller reaches this mailbox. Verbosity level for prompts the subscriber hears. A number where the subscriber can be reached. Calls can be forwarded to this number This specifies a number at which the mailbox owner can be reached. This specifies whether the referral number is a telephone number or a beeper number. 1 0 = no (default) - never play header 1 = yes Reserved for use by Unified Messaging 1 0 = Normal prompts (default) 1 = Novice prompts 2 = Expert prompts 20 numeric string 20 numeric string 1 0 = Telephone 1 = Beeper Chapter 12. Managing voice messaging resources 183

202 Table 7. Mailbox field names used with wvrmailbox command (continued) Field Name Description Length Field Data retrieval_order Retrieval Order Indicates the order in which to retrieve messages from the mailbox. An application can retrieve messages in the order that they arrived, or it can retrieve the most recent messages first. The possible values are: First in first out (the order in which the messages arrived), Last in first out (the most recently received message first). 1 0 = FIFO (default) 1 = LIFO saved_messages Saved send_msg_address Send message temp_deputy_number Temporary assistant number temp_fax_number Temporary fax number temp_pager_number Temporary pager number temp_pager_ref Temporary pager reference Displays how many saved messages are in the mailbox Indicates that you will specify the message address before or after recording the message. Temporary assistant number Temporary fax number Temporary paging bureau number Temporary pager reference number This is a mailbox property display-only field 1 0 = Message first, address after (default) 1 = Address first, message after 20 numeric string 20 numeric string 20 numeric string 20 numeric string 184 Designing and Managing State Table Applications

203 Table 7. Mailbox field names used with wvrmailbox command (continued) Field Name Description Length Field Data temp_reachme_number Temporary Reach-Me number temp_referral_number Temporary referral number user_status Application Status vpim_address VPIM address vpim_msg_del_pref VPIM MDP vpim_voice_type VPIM voice format The PIN to be used when receiving calls transferred via the reach-me facility. Temporary call-forwarding number Indicates whether the subscriber is in, out, sick, traveling or busy Address for SMTP/MIME delivery Message delivery preference for VPIM 20 numeric string 20 numeric string 1 0 = in (default) 1 = out 2 = sick 3 = busy 4 = traveling 255 text 1 0 = Local 1 = Remote 2 = Local and remote VPIM voice format 1 0 = wav 1=au 2 = 32KADPCM 3 = DT6 elements 4 = DT6 GSM Creating a subscriber class Use this procedure to create a subscriber class. Each subscriber class is identified by a name. The name can be any combination of 15 characters. From the Welcome window, click on Configuration > Subscriber Classes 1. Defining a subscriber class : Click File > New. The system displays the Subscriber Class window: Chapter 12. Managing voice messaging resources 185

204 2. Type in the limits to be used for all mailboxes defined by application profiles that are assigned to this subscriber class. Maximum number of guest mailboxes specifies the number of mailboxes that can be assigned to guest users. For example, if one of your customers runs a messaging application for which they buy 10 mailboxes, but then sublease five of those mailboxes to other people, those five mailboxes become guest mailboxes. This limit can be any number between 1 and 9 (the system limit). Maximum number of messages per mailbox specifies how many messages an application can accept and store in one mailbox: any number between 0 and 999 (the system limit). Maximum distribution lists per mailbox specifies how many distribution lists can be created for one mailbox. When a voice application includes the logic for it, callers can use the telephone to create distribution lists to distribute messages from a mailbox. You can also use WebSphere Voice Response to create distribution lists for a mailbox, as explained in Creating a distribution list on page 187). This limit can be any number between 0 and 90 (the system limit). 186 Designing and Managing State Table Applications

205 Maximum distribution list entries specifies how many members a single mailbox distribution list can have. A member can be a mailbox or another distribution list. This limit can be any number between 0 and 90 (the system limit). Maximum record time per message specifies the length of the messages that can be recorded. Don t set this higher than the value of the Record Voice Maximum system parameter in the General parameter group. Maximum number of greetings per mailbox specifies how many different greetings the mailbox owner can record for a mailbox. The maximum number of greetings can be any number between 0 and 20. The system limit is 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 the Subscriber Class window, you will see the new class listed. Done After you have created a new subscriber class, you must shutdown and restart WebSphere Voice Response to make the subscriber class available. To assign a subscriber class to an application, specify the subscriber class in the application profile (see Specifying subscriber classes (optional)). Creating a distribution list Use this procedure to create a distribution list for a mailbox. This procedure assumes that you have already created an application profile that includes mailbox definitions and saved the profile. However, you can combine this procedure with the procedures in Chapter 5, Creating an application profile, on page 89 Chapter 12. Managing voice messaging resources 187

206 on page 89 and Creating mailboxes for application use on page 170 and create a distribution list for each mailbox after you define the mailbox and save the definition. Each distribution list is identified by a four-digit number. The number can be any combination of the digits 0 through 9. A distribution list can be public or private. A private distribution list is reserved for the use of the mailbox owner. A public list can be used by anyone. However, only the person who created the public list can modify it. The system limits the number of distribution lists to 90 per mailbox. There is no limit to the number of members on each distribution list. However, if the application profile is assigned to a subscriber class, the limitations defined by the subscriber class may apply. (For more information on subscriber classes, see What are subscriber classes? on page 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 the mailbox. The system displays the profile information in the Application Profile window. 3. Click Options > Distribution List. The system displays the Distribution List window. 4. Select the button to the left of the number that identifies the mailbox for which you are creating the list. 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. 188 Designing and Managing State Table Applications

207 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. Chapter 12. Managing voice messaging resources 189

208 The system adds the mailbox to the distribution list and displays it as a member. 14. To add more mailboxes, repeat steps 10 on page 189 through 13 on page 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 of Application Profiles on the left. 16. Click the application profile and then click a Mailbox. The system displays all the distribution lists that belong to the selected mailbox: 17. Click the distribution list that you want to add to the current distribution list. 18. Click OK. The system adds the distribution list as a member of the current distribution list. 19. To add more distribution lists, repeat steps 15 through When you are finished, click Close. The system displays the Application Profile window. 21. Save the application profile. Even though the Application Profile window is still displayed, the system has created the distribution list for the mailbox and saved it. 190 Designing and Managing State Table Applications