WebSphere Voice Response for AIX: Deploying and Managing

Transcription

WebSphere Voice Response for AIX with DirectTalk
Technology
Deploying and Managing VoiceXML and
Java Applications
Version 6.1
GC34-7080-07
Note
Before using this information and the product it supports, read the general information under “Notices” on
page 185.
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 2001, 2013.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures .
.
.
.
.
.
.
.
.
.
.
.
. vii
Tables .
.
.
.
.
.
.
.
.
.
.
.
. ix
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. . .
. xi
. xi
. xi
. xi
. xii
. xiii
. xiii
. xiii
. xiv
.
About this documentation . . .
Who should use this information .
How to use this information. . .
Typographic conventions . . . .
Accessibility . . . . . . . .
Notes on terminology . . . .
Where to find more information .
Useful Web sites . . . . .
Making comments on this book .
Chapter 1. Introduction to configuring and
managing VoiceXML, CCXML, and Java
applications . . . . . . . . . . .
What advantages does CCXML offer for call
control? . . . . . . . . . . . . .
How different are VoiceXML and Java
applications from state table applications? .
Application development differences . .
Runtime differences . . . . . . . .
Voice data differences . . . . . . .
Can different types of application co-exist? .
Where do you get VoiceXML, CCXML, and
Java support from? . . . . . . . . .
A network of nodes . . . . . . . . .
Introducing the configuration database . .
Number-to-application mapping . . .
Running applications . . . . . . . .
How languages are identified in VoiceXML
and Java . . . . . . . . . . . .
Why locale is important . . . . . .
Default locale . . . . . . . . . .
Internationalization . . . . . . . .
Defining your own locales . . . . .
Language-only locales . . . . . . .
How locale is used for speech recognition
and text-to-speech . . . . . . . .
Management of application resources . .
Implementing the Secure Socket Layer
(SSL) protocol . . . . . . . . .
. 1
. 2
.
.
.
.
.
3
3
3
4
4
.
.
.
.
.
4
5
5
6
6
.
.
.
.
.
.
7
7
8
8
9
9
. 10
. 10
Chapter 2. System configuration and
management . . . . . . . . . . .
About the configuration database . . . . .
The name of the configuration database. .
Updating the configuration database . . .
How many configurations? . . . . . .
About the HostManager . . . . . . . .
Managing a single voice response node . . .
Starting a single voice response node . .
Monitoring system usage . . . . . .
Stopping a single voice response node . .
Managing a network of nodes . . . . . .
The system management console . . . .
Managing a network of nodes (plex) with
the dtjplex command . . . . . . . .
Adding a new voice response node to the
plex . . . . . . . . . . . . . . .
Example 1: Nodename entry shared by
two hosts . . . . . . . . . . . .
Example 2: Voice response nodes with
different characteristics . . . . . . .
Example 3: Node running on AIX with
reco and text-to-speech . . . . . . .
Example 4: A voice response node running
CCXML . . . . . . . . . . . .
Starting a voice response node remotely from
the system management console . . . . .
Setting up an application node . . . . . .
Why set up an application node? . . . .
Installing an application node . . . . .
Configuring an application node . . . .
Starting an application node . . . . .
Adding telephony capability . . . . . .
Adding a Telephony URL Locale . . . . .
Configuring the listening socket queue size
Adding speech technology . . . . . . .
How speech recognition is configured . .
Specifying RecoDefinitions for an
application . . . . . . . . . . .
How text-to-speech is configured . . . .
Specifying TTSDefinitions for an
application . . . . . . . . . . .
13
14
14
14
18
19
19
19
19
20
20
20
20
23
23
24
24
25
26
26
27
29
29
32
33
38
39
39
41
43
47
49
. 10
Chapter 3. Deploying applications . . . . 55
Preparing for deployment . . . . . . . 55
© Copyright IBM Corp. 2001, 2013
iii
Defining the application . . . . . . . .
Application name . . . . . . . . .
Automatically starting applications in a node
The need for multiple application instances
Running CCXML applications in a node . .
Receiving a telephone call . . . . . .
Receiving telephone calls in the
ALERTING state . . . . . . . . .
Mapping CCXML browsers to a phone
number . . . . . . . . . . . .
Running an application in a node . . . . .
Defining application characteristics . . .
Mapping a VoiceXML or Java application
to a phone number. . . . . . . . .
Ensuring that the call is answered. . . .
Providing a default application . . . .
Starting applications . . . . . . . .
Starting an application in multiple nodes
Starting CCXML services. . . . . . .
Using message logs . . . . . . . .
CCXML and Voice XML application
logging . . . . . . . . . . . .
Putting your application into production . .
Checklist for VoiceXML applications . . .
Deploying VoiceXML applications. . . .
Checklist for CCXML applications . . .
Checklist for Java applications . . . . .
Getting help from IBM Support . . . . .
What do you need to send to IBM Support
to get problems resolved? . . . . . .
Appendix A. The configuration database
Configuration file keywords . . . . . .
Configuration entries . . . . . . . . .
AppName configuration entry . . . . . .
Secondary keywords . . . . . . . .
CCXService configuration entry . . . . .
GroupName configuration entry . . . . .
HostName configuration entry . . . . . .
NodeName configuration entry . . . . .
Secondary keywords for all nodes. . . .
Secondary keywords for application nodes
only. . . . . . . . . . . . . .
Secondary keywords for voice response
nodes only . . . . . . . . . . .
RecoService configuration entry . . . . .
iv
56
57
57
58
58
59
59
60
60
60
62
63
65
67
67
67
68
69
71
71
72
73
74
75
75
77
77
83
83
84
86
86
88
88
89
89
90
90
91
92
95
95
Examples of RecoService entries .
Related information . . . . .
TelURLLocale configuration entry .
Secondary keywords . . . . .
TelephonyService configuration entry
TTSService configuration entry . .
Examples of TTSService entries .
Related information . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Appendix B. Voice segments for Java
applications . . . . . . . . . . .
How to get voice data into Java applications
How voice segments are stored and
identified . . . . . . . . . . .
AIX single system image . . . . . .
Making voice segments available to Java
applications . . . . . . . . . . .
What happens when you install a
language? . . . . . . . . . . .
What if you have already recorded voice
segments on the base WebSphere Voice
Response system? . . . . . . . . .
Managing your voice segments . . . . .
Using dtjplex . . . . . . . . . .
Listing available voice segments . . . .
Exporting voice segments to the file
system . . . . . . . . . . . .
Importing voice segments from the file
system . . . . . . . . . . . .
Adding voice segments from the base
WebSphere Voice Response system . . .
Replacing a voice segment from the
WebSphere Voice Response base system .
Replacing a voice segment with a new
version on your file system . . . . .
Deleting voice segments . . . . . .
Copying voice segments . . . . . .
Moving or renaming voice segments . .
Copying voice segments from one voice
response node to another . . . . . .
Appendix C. Supplied
dtjalarm script . . .
Syntax . . . .
Parameters . . .
Example commands
dtjcache script . . .
Syntax . . . .
Deploying and Managing VoiceXML and Java Applications
scripts
. . .
. . .
. . .
. . .
. . .
. . .
. 97
101
101
101
102
102
105
105
107
111
113
113
113
115
116
117
118
118
118
121
122
124
127
130
130
130
131
133
134
. . . . . 135
. . . . . 135
. . . . . 137
. . . . . 137
. . . . . 137
. . . . . 137
. . . . . 138
Parameters . . . . . . .
Example commands . . . .
dtjconf script . . . . . . .
Syntax . . . . . . . .
Examples . . . . . . .
dtjenv script . . . . . . .
dtjes script . . . . . . . .
Syntax . . . . . . . .
dtjflog script . . . . . . .
Syntax . . . . . . . .
Examples . . . . . . .
dtjlogmon script . . . . . .
Scan mode syntax. . . . .
Scan mode parameters . . .
Scan mode example commands
Test mode syntax . . . . .
Test mode parameters . . .
Test mode example commands
dtjnlsin script . . . . . . .
Syntax . . . . . . . .
Examples . . . . . . .
dtjplex script . . . . . . .
Syntax . . . . . . . .
dtjplex addVS action . . . . .
Syntax . . . . . . . .
Control file keywords . . .
dtjplex copyVS action . . . .
Syntax . . . . . . . .
Control file keywords . . .
Related information . . . .
dtjplex deleteVS action . . . .
Syntax . . . . . . . .
dtjplex exportVoiceHost action .
Syntax . . . . . . . .
dtjplex importVoiceAll action . .
Syntax . . . . . . . .
dtjplex importVoiceHost action .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
138
140
140
141
141
141
142
142
142
142
143
143
143
143
143
144
144
144
145
145
146
146
146
146
146
147
147
147
148
148
148
149
150
150
150
150
151
151
151
151
152
152
152
152
155
155
155
155
158
158
Syntax . . . . . . . .
dtjplex listVS action . . . . .
Syntax . . . . . . . .
dtjplex queryApplications action .
Syntax . . . . . . . .
Shorthand script . . . . .
dtjplex queryCCXML action . .
Syntax . . . . . . . .
dtjplex queryHosts action . . .
Syntax . . . . . . . .
dtjplex queryNodes action . . .
Syntax . . . . . . . .
dtjplex startAll action . . . .
Syntax . . . . . . . .
dtjplex startApplication action .
Syntax . . . . . . . .
dtjplex startHost action . . . .
Syntax . . . . . . . .
dtjplex startNode action. . . .
Syntax . . . . . . . .
dtjplex stopAll action . . . .
Syntax . . . . . . . .
dtjplex stopHost action . . . .
Syntax . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
158
158
161
161
161
161
162
162
162
162
162
162
163
163
163
163
163
163
163
163
164
164
164
164
164
164
164
165
165
165
165
165
165
165
166
166
166
166
166
166
166
166
167
167
167
167
167
167
168
168
Contents
v
Parameters . . . . .
Example commands . .
Shorthand script . . .
dtjplex stopNode action. .
Syntax . . . . . .
dtjplex terminateAll action .
Syntax . . . . . .
dtjplex terminateHost action
Syntax . . . . . .
dtjplex terminateNode action
Syntax . . . . . .
dtjqapps script . . . . .
Syntax . . . . . .
dtjqccx script . . . . .
Syntax . . . . . .
dtjqhost script . . . . .
Syntax . . . . . .
dtjqnode script . . . . .
Syntax . . . . . .
dtjshost script . . . . .
Syntax . . . . . .
dtjstart script . . . . .
Syntax . . . . . .
dtjstop script . . . . .
Syntax . . . . . .
dtjterm script . . . . .
Syntax . . . . . .
dtjuserlog script . . . .
Syntax . . . . . .
dtjver script . . . . . .
Syntax . . . . . .
vxml2 script . . . . .
Syntax . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
168
168
168
168
168
168
169
169
169
169
169
169
169
169
170
170
170
170
170
170
171
171
171
171
171
171
171
171
172
172
172
172
172
172
172
172
172
172
173
173
173
173
173
173
173
174
174
Appendix D. Command syntax. . . . . 175
ConfigManager command . . . . . . . 175
vi
Syntax . . . . . . . .
ConfigManager list action . .
ConfigManager export action .
ConfigManager import action .
Equivalent script . . . . .
HostManagerImpl command . .
Syntax . . . . . . . .
HostManagerImpl example .
PlexManagerImpl command . .
PlexManagerImpl Scripts . .
Syntax . . . . . . . .
PlexManagerImpl example . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
175
175
176
177
177
177
177
178
178
178
178
178
178
178
Appendix E. Changing the Incoming_Call
state table to receive calls in the
ALERTING state . . . . . . . . . .
Using CCXML with other application types
Modifying the Incoming_Call state table . .
Modifying answering application state tables
179
179
179
180
Appendix F. Configuring telephone URI
verification for WebSphere Voice
Response . . . . . . . . . . . .
Fundamental concepts . . . . . . . .
Configuring WebSphere Voice Response . .
Example default.cff entries for TelURLLocale
181
181
182
183
Notices . . . . . . . . . . . . . 185
Trademarks . . . . . . . . . . . . 187
Glossary .
.
.
.
.
.
.
.
.
.
.
. 189
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
WebSphere Voice Server. . . . . . .
Unified Messaging for WebSphere Voice
Response . . . . . . . . . . .
AIX and the IBM pSeries computer . . .
HACMP . . . . . . . . . . . .
SS7 . . . . . . . . . . . . .
Integrated Services Digital Network. . .
Bellcore Specifications for ADSI Telephones
Index
.
.
.
.
.
.
.
.
.
.
.
.
195
195
196
196
196
196
197
197
197
198
199
. 201
Figures
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
VRBE Utilities Window . . . . . . 15
VRBE Configuration window . . . . 16
Using dtjconf . . . . . . . . . . 17
Application node and voice response
node on separate hosts . . . . . . 27
How configuration entries refer to each
other: application running in application
node. . . . . . . . . . . . . 32
Definitions required for voice response
nodes to communicate with CallPath
Enterprise Server . . . . . . . . 36
nodes to communicate with Genesys
T-Server . . . . . . . . . . . 37
nodes to communicate with Genesys
I-Server . . . . . . . . . . . 38
Searching for the RecoType: contrasting
examples . . . . . . . . . . . 44
Searching for the RecoType: more
contrasting examples . . . . . . . 45
The search for the speech recognition
plug-in . . . . . . . . . . . . 47
Searching for the TTSType: contrasting
examples . . . . . . . . . . . 51
Searching for the TTSType: more
contrasting examples . . . . . . . 52
The search for the text-to-speech plug-in 54
Configuration entries for an application
running in the voice response node . . 64
Multiple instances of applications
waiting for calls . . . . . . . . . 65
Voice segment database . . . . . . 114
Voice segments in the Java voice
segment space . . . . . . . . . 114
The Java voice segment space is
divided into locales, which are divided
into categories . . . . . . . . . 115
AIX single system image . . . . . 116
Alternative ways of making voice
segments available to your applications 117
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
Example of control file for AIX
Exporting voice segments from the Java
voice segment space . . . . . . .
Example of control file for exporting
voice segments to another voice
response node on the same operating
system . . . . . . . . . . .
voice segments to any voice response
node . . . . . . . . . . . .
voice segments as WAV files . . . .
Importing voice segments into the Java
Example of control file for importing
voice segments from another voice
response node on the same operating
system . . . . . . . . . . .
Example of control file for importing
WAV files into a T1 system (any
platform) . . . . . . . . . . .
Adding voice segments into the Java
Example of control file for adding
voice segments from a base AIX system
Example of control file for deleting
voice segments (any platform). . . .
Example of control file for copying
voice segments to a different locale
(any platform) . . . . . . . . .
voice segments to a different category
(any platform) . . . . . . . . .
voice segments to different names (any
platform) . . . . . . . . . . .
Example of control file for copying or
moving voice segments from one voice
response node to another on the same
operating system . . . . . . . .
121
122
123
123
124
125
126
126
128
129
131
132
132
132
134
vii
viii
Tables
1.
2.
3.
Summary of running applications
User Logging Java interface write
method parameters . . . . . . .
Index of configuration file keywords
55
4.
. 70
77
5.
Voice segment naming on different
WebSphere Voice Response systems .
dtjalarm message severity categories
. 127
136
ix
x
About this documentation
This documentation provides information about the system management and
configuration of the Java™ and VoiceXML Environment of IBM® WebSphere®
Voice Response for AIX® with DirectTalk® Technology Version 6.1. It includes
guidance for configuring and managing CCXML, VoiceXML 2.1 and Java
applications, together with the corresponding reference information.
For detailed information about the syntax of the VoiceXML language, and
how to create VoiceXML applications, see the WebSphere Voice Response:
VoiceXML Programmer's Guide book.
Who should use this information
This information is for system administrators who are managing a WebSphere
Voice Response system that uses Java, CCXML or VoiceXML applications.
How to use this information
If you want to print this information from Adobe Acrobat, you can print just
the sections you need by selecting appropriate the page numbers.
v Start with Chapter 1, “Introduction to configuring and managing VoiceXML,
CCXML, and Java applications,” on page 1 to provide background
information
v Use Chapter 2, “System configuration and management,” on page 13 for
information about system configuration and management
v Use Chapter 3, “Deploying applications,” on page 55 for information about
deploying applications
v You might also need to refer to the information in:
– Appendix A, “The configuration database,” on page 77
– Appendix C, “Supplied scripts,” on page 135
– Appendix D, “Command syntax,” on page 175
– Appendix B, “Voice segments for Java applications,” on page 113
– Appendix E, “Changing the Incoming_Call state table to receive calls in
the ALERTING state,” on page 179
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.
xi
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).
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.
xii
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
195).
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.
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 195.
Useful Web sites
The following Web sites are useful sources of information about WebSphere
Voice Response and related products:
WebSphere Voice Response
http://www.ibm.com/software/pervasive/voice_response_aix/
IBM WebSphere developerWorks resources (including WebSphere Voice
products)
http://www.ibm.com/developerworks/websphere/zones/voice/
VoiceXML Version 2.0 and 2.1 specifications
http://www.w3.org/TR/voicexml21/
http://www.w3.org/TR/voicexml20/
CCXML Version 1.0 specification
http://www.w3.org/TR/2011/PR-ccxml-20110510/
About this documentation
xiii
Genesys
For more information on Genesys products go to the Genesys Web
site at http://www.genesyslab.com
Making comments on this book
If you especially like or dislike anything about this book, feel free to send us
your comments.
You can comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book. Please
limit your comments to the information that is in this book and to the way in
which the information is presented. Speak to your IBM representative if you
have suggestions about the product itself.
When you send us comments, you grant to IBM a nonexclusive right to use or
distribute the information in any way it believes appropriate without
incurring any obligation to you.
You can get your comments to us quickly by sending an e-mail to
[email protected]. Alternatively, you can mail your comments to:
User Technologies,
IBM United Kingdom Laboratories,
Mail Point 095, Hursley Park,
Winchester, Hampshire,
SO21 2JN, United Kingdom
Please ensure that you include the book title, order number, and edition date.
xiv
Chapter 1. Introduction to configuring and managing
VoiceXML, CCXML, and Java applications
The WebSphere Voice Response Java and VoiceXML environment allows a
Java or VoiceXML voice application to communicate with a base WebSphere
Voice Response system, and can also run CCXML applications for call control
in a CCXML Browser.
The voice dialogs for applications can be written entirely in either VoiceXML
or Java: the recommended approach is to develop the dialogs using
VoiceXML. However, it is also possible to use a Java application to integrate
components written in Java or VoiceXML with legacy state tables and custom
servers. The Java application acts as a glue layer for the VoiceXML dialogs
and existing state table applications.
Incoming calls can be directed to the correct application either using the
routes defined the WebSphere Voice Response Java and VoiceXML
environment configuration database, or they can be routed through a CCXML
document, which can initiate one or more dialog applications as well as call
control operations such as transferring or disconnecting a call.
If you have any applications that use VoiceXML or Java, or are using CCXML
for call control, there are some additional configuration and system
management tasks that you need to do. Almost all of the information in this
documentation applies to applications written in either language, with the
exception of the information about voice segments which applies only to Java.
The following topics are covered in this section:
v “How different are VoiceXML and Java applications from state table
applications?” on page 3
v “Can different types of application co-exist?” on page 4
v “Where do you get VoiceXML, CCXML, and Java support from?” on page 4
v “A network of nodes” on page 5
v “Introducing the configuration database” on page 5
v “Running applications” on page 6
v “How languages are identified in VoiceXML and Java” on page 7.
v “Management of application resources” on page 10
1
What advantages does CCXML offer for call control?
CCXML is a standard call control markup language developed by W3C.
Although the use of CCXML with WebSphere Voice Response for AIX is
optional, it has several advantages for both application development and
management.
WebSphere Voice Response for AIX Version 6.1 implements the latest
published edition of the Voice Browser Call Control: CCXML Version 1.0
specification, published by W3C, is available at http://www.w3.org/TR/2011/
PR-ccxml-20110510/. CCXML is therefore an industry standard supported by
various application development tools.
CCXML is designed to provide telephony call control support for VoiceXML
and other dialog systems. The call control support provided by CCXML
includes:
v Accepting calls
v Rejecting calls
v Transferring calls
v Making outbound calls
v Running VoiceXML dialog applications
v Running dialog and other applications written in Java
A static CCXML document can be used, or dynamic CCXML can be generated
by an application server. A combination of static and dynamic CCXML is also
possible. The advantage of this architecture is that all the application logic can
be controlled by an application server, allowing it to manage which dialog
applications are used in which circumstances.
If CCXML is not used, the fixed WebSphere Voice Response for AIX
WebSphere Voice Response Java and VoiceXML environment routing is used
to start VoiceXML or Java applications. In addition to call control, these
applications must manage not only the voice dialogs, but also the flow to
other dialog applications.
Refer to the WebSphere Voice Response for AIX: Using the CCXML Browser for
further information about using CCXML with WebSphere Voice Response for
AIX .
2
How different are VoiceXML and Java applications from state table applications?
There are several ways in which VoiceXML and Java applications are different
from state table applications:
v “Application development differences”
v “Runtime differences”
v “Voice data differences” on page 4
Application development differences
To create VoiceXML and Java applications, application developers do not need
access to the runtime WebSphere Voice Response system. They can develop
and test their applications independently of the runtime system, using
Rational Application Developer on a different platform. However you should
ensure that all applications are tested with a real runtime system before you
put them into production.
Runtime differences
You will also notice a difference at runtime. With a state table application, all
resources are resident on the runtime system and the application runs within
the AIX system itself. With a Java application, the resources can be stored on
another system, and the application runs in a Java virtual machine that may
be resident either on the AIX system on which WebSphere Voice Response
runs (known as the voice response node) or on another system (known as an
application node). With a VoiceXML application, the dialog and audio files
may be stored on a Web server. A special Java application called the
VoiceXML browser fetches them from the Web server as necessary and caches
the content locally based on the caching directives specified by the Web
server.
In both cases, sufficient instances of the Java application (either the specific
Java application or the VoiceXML browser ) must be running to handle all the
calls you expect to be running simultaneously. This is different from the state
table environment where application instances are started when required.
To ensure that calls are passed to a VoiceXML, CCXML or Java application,
there needs to be one or more application profiles that specify the
JavaApplication state table: the bridge between the WebSphere Voice
Response system and the Java applications and VoiceXML browsers that are
running. When an incoming call is detected by WebSphere Voice Response,
the called number is identified and is used to look up an application profile
corresponding to that number. If the JavaApplication state table is specified,
and if the Java and VoiceXML environment is running, the call is routed to the
Java and VoiceXML environment, and the called number is used to look up
the relevant Java or VoiceXML application or CCXML Browser in the
configuration database.
Chapter 1. Introduction to configuring and managing VoiceXML, CCXML, and Java applications
3
The WebSphere Voice Response for AIX Incoming_Call state table should not
answer telephone calls routed to the Java and VoiceXML environment, which
expects to receive calls in the ALERTING state. The Java and VoiceXML
environment answers telephone calls for Java or VoiceXML applications, but
passes any calls in the ALERTING state to a CCXML Browser. See
Appendix E, “Changing the Incoming_Call state table to receive calls in the
ALERTING state,” on page 179.
Voice data differences
Voice segments to be used by Java applications can be derived from legacy
voice segments used by your state table applications or from audio files: in
both cases, they need to be imported into the Java space in the voice segment
database. VoiceXML applications do not use voice segments: they use simple
audio files.
Can different types of application co-exist?
You can run all types of application with a single WebSphere Voice Response
system. This includes applications written using state tables, supplied
JavaBeans, the Java application programming interface, CCXML and
VoiceXML 2.1.
A single WebSphere Voice Response voice service may include combinations
of one or more of these. It can include multiple speech servers, and (MRCP
V1.0) speech servers from different speech vendors. VoiceXML 1.0 applications
are no longer supported.
Where do you get VoiceXML, CCXML, and Java support from?
To run VoiceXML, CCXML or Java applications you need to ensure that the
Java and VoiceXML environment is installed on the WebSphere Voice
Response system.
To find out whether it is installed, log on as dtuser and type dtjver on the
command line. This should tell you which version you have installed. If
dtjver is not found, you should simply install the Java and VoiceXML
environment from the WebSphere Voice Response installation CD.
The rest of this documentation explains how to deploy and manage
VoiceXML, CCXML and Java applications in the WebSphere Voice Response
Java and VoiceXML Environment. For detailed information about the syntax
of the VoiceXML language, and how to create VoiceXML applications, see the
WebSphere Voice Response: VoiceXML Programmer's Guide, available on the
WebSphere Voice Response Version 6.1 Quick Start CD.
4
A network of nodes
The concept of nodes in a network is a very important one because Java and
VoiceXML support is designed to be distributed.
There are two types of node: voice response nodes and application nodes.
v A voice response node provides the connection to the telephony and voice
processing function on the base WebSphere Voice Response system.
v An application node provides partitioning for your applications. It also
provides a separate Java Virtual Machine (JVM), which can improve
performance. Application nodes do not have to be on the same machine as
the voice response node.
On AIX, a WebSphere Voice Response system with the Java and VoiceXML
environment installed on it can support one, and only one, voice response
node and multiple application nodes.
For information about installing application nodes on hosts that don't have a
WebSphere Voice Response system, see “Setting up an application node” on
page 26.
Introducing the configuration database
The network of nodes is sometimes referred to as the plex. The plex is defined
in a configuration database, config.cfd. Run the configuration tool dtjit to
create automatically a plain text configuration file called vrbecfg.cff that can
be used to populate the configuration database initially or to modify it later.
To modify the configuration database, you import a plain text configuration file,
default.cff, into it. The file default.cff specifies the definitions of all your
nodes, and all your applications. The easiest way to create default.cff from
scratch is to copy the vrbecfg.cff file created by the dtjit configuration tool
to it. You then run a utility, dtjconf, to import the new definitions into the
configuration database.
When you install the WebSphere Voice Response Java and VoiceXML
Environment, a configuration database is created for you, and you don't need
to edit it and run dtjconf to get the sample application running in the default
language. For WebSphere Voice Response for AIX the default language is U.S.
English.
The supplied configuration database includes a definition for the local host,
and a definition for a single node on that host:
NodeName=VRNode1
NodeDefLocale=en_US
5
VRNode=yes
;
HostName=LocalHost
IPName=localhost
Node=VRNode1
;
Number-to-application mapping
When you are just getting started, the item that you almost certainly need to
define in the configuration database is the phone number that is used to call
into a CCXML document or a specific application. This is specified on the
NodeName entry, like this:
NodeName=VRNode1
NodeDefLocale=en_US
VRNode=yes
NumToApp=123455,name
;
where name is the name of a VoiceXML application, a Java application, or a
CCXML service.
When you write one of your own applications, you must either run it from a
CCXML document or add a number-to-application mapping for it either by
using the dtjit configuration tool as described in “Updating the configuration
database” on page 14, or by editing the default.cff file, and then run
dtjconf, to import the new definitions into the configuration database.
When a call is routed to the Java environment, the called number is used to
look up the appropriate action, using the NumToApp mapping. See “Mapping
a VoiceXML or Java application to a phone number” on page 62 and
“Mapping CCXML browsers to a phone number” on page 60 for details.
Running applications
Before running applications you need to understand:
v How applications are defined and configured.
v How to start applications automatically.
v How to optimize your system to handle maximum call frequency.
For full details of these topics and other configuration issues, see Chapter 3,
“Deploying applications,” on page 55.
6
How languages are identified in VoiceXML and Java
All of the base WebSphere Voice Response products use the concept of
“language”, and some languages are defined in terms of language and the
country or region in which it is spoken: for example, Canadian French as
opposed to French spoken in France. In Java, this is explicitly acknowledged,
by using the term locale to refer to both the language and the specific territory.
Each locale is identified by an ISO-defined code, which comprises a language
component and a country or region component: for example, fr_CA for
Canadian French and fr_FR for French in France.
Optionally, you can create your own locale identifiers, including an optional
user-defined variant. For example en_US_FRED. If you are using a locale to
create Java voice segments, there is a limit of 15 characters for the length of
the locale identifier, so the variant part can be up to 9 characters. For
portability across different versions of the JDK, ensure that the locale variant
('US' in the previous example) is specified in uppercase.
In VoiceXML, the locale of the application is identified by the xml:lang
attribute of the <vxml> tag.
This section tells you about
v “Why locale is important.”
v “Default locale” on page 8.
v “Internationalization” on page 8.
v “Defining your own locales” on page 9.
v “Language-only locales” on page 9.
v “How locale is used for speech recognition and text-to-speech” on page 10.
Why locale is important
Locale is used for:
v Identifying precisely what is to be spoken to the caller: the words, accent,
and phrasing used (by using the variant component of the locale identifier,
you can also specify any other characteristics you want). In other words,
locale is used to identify the voice segments to be used.
v Determining the technology to be used for text-to-speech and speech
recognition.
v Optionally, altering the logic of your application.
In VoiceXML, the locale also determines the language of the built-in
grammars, error prompts, and other language-specific features used by the
browser to handle an incoming call.
7
Default locale
The concept of a default locale is an important one, whether you are designing
and writing applications or setting up and managing systems:
v Each voice response node has a default locale, defined in the “NodeName
configuration entry” on page 90. This default locale is used by Java
applications. For VoiceXML 2.1 applications, the default locale is the locale
of the operating system. If the operating system is running in an
unsupported locale, the default will be en_US.
v Optionally, each application can have a default locale, overriding the node
default locale. This must be specified in the AppName entry.
Internationalization
Although applications can be written to run on any supported locale, there
are differences in the way that CCXML, VoiceXML, and Java applications are
internationalized.
VoiceXML
In VoiceXML, resources referenced by URIs are not subject to changes in the
current locale, but built-in resources (such as built-in grammars) are. You
should associate a locale with the document rather than with the execution
environment (by using the <vxml> xml:lang attribute) to ensure that the
correct built-in resources are used.
CCXML
In CCXML, resources referenced by URIs are not subject to changes in the
current locale. There is no mechanism for associating a locale with the
document rather than with the execution environment. CCXML can be written
in any supported code page. There is a charset attribute for the <script>
element that allows the CCXML script to indicate the code page of an ECMA
script to be fetched.
Java
Java applications can be completely language-independent if the locale is not
specified on any individual voice segment objects within the application. To
make the application speak a specific language, simply set the default locale
of the node to that language. You could have several voice response nodes,
each running the same applications in a different language. Provided that
voice segments for the locale are available they are played to the caller in that
language.
Instead of using the node default locale, you could specify a default locale for
each application, and have applications speaking different languages running
8
in the same node. You can have several AppName configuration entries for
the same Java class, each specifying a different application name and a
different locale.
Thus, the current locale provides full internationalization for your Java
applications, provided that each language is installed on the voice response
node.
Defining your own locales
It is up to you how you use the user-defined variant component of the locale
identifier. You might record voice segments for an application using different
voices: male and female, for example. You would identify these voice
segments as, for example, en_US_MALE, en_US_FEMALE).
You might have a different greeting at the beginning of an application,
depending on which branch of your company the call is for, even though the
logic of the application is the same for all branches. To achieve this, invent a
locale identifier for each branch (for example, en_US_CHICAGO,
en_US_WASHINGTO, en_US_NEWYORK). Then name each greeting voice
segment using the appropriate locale identifier, and use different default
locales, in one of the ways described in “Internationalization” on page 8, to
run instances of the application for each branch. The other voice segments in
the application, common to all branches, should be in the base locale (en_US).
Whenever a voice segment for a specific variant cannot be found, a voice
segment for the country or region and language is searched for.
Specifying PREEURO support with existing 3–part locales
As a result of Euro support, five languages (French, Castilian Spanish,
Catalan, German, and Italian) default to saying Euro rather than the national
currency in both new and existing applications. In two–part locales (for
example, fr_FR), you can override this by specifying a variant of PREEURO
(for example, fr_FR_PREEURO) in the locale option of the AudioCurrency
object (see Developing Java applications). However, if you have defined your
own locales with three parts (for example, fr_FR_PARIS), and want to use
preeuro support, you can do this only by specifying dtj.preeuro.support =
true in the dtj.ini file.
Language-only locales
In some cases, you may want to use a language-only locale identifier, such as
“en” or “fr”. One example of this is the use of “en” as a locale identifier for
the voice segments supplied for the tutorial application in Developing Java
applications. These voice segments can be used when the current language of
an application is any derivative of the en locale: en_US, en_GB, en_AU, and
so on. Whenever a voice segment for a specific country or region cannot be
found, a voice segment for the generic language is searched for.
9
How locale is used for speech recognition and text-to-speech
Because some speech recognition and text-to-speech technologies are better at
some languages than others, you can use different technologies for processing
different languages. You specify one technology for “all locales” and then
override this for the exceptional languages. This can be specified on a per
node or per application basis. Specifying the technology for a new language
or switching between technologies for any language is done without altering
the application itself.
If you are using language-only locales, make sure you have speech plug-ins
configured for all locales or the single-part locale.
The current application locale is assumed for all speech recognition attempts,
and is used for text-to-speech unless specified within the application. The
current application locale for VoiceXML 2.1 applications is either the operating
system locale or the application default locale, if one has been specified. The
current application locale for Java applications is the node default locale or
the application default locale, if one has been specified.
Management of application resources
Existing WebSphere Voice Response users will notice the new concept of
having application resources resident on Web or application servers rather
than in WebSphere Voice Response itself. Having resources on web servers
allows for more centralized management.
Resources are generally fetched from the web using the HTTP or HTTPS
protocol (see “Implementing the Secure Socket Layer (SSL) protocol”),
although they can be stored on the WebSphere Voice Response node and
referenced through URIs using the 'file' protocol, if required.
Implementing the Secure Socket Layer (SSL) protocol
This information applies to VoiceXML and CCXML applications only.
The Secure Socket Layer (SSL) protocol provides authentication and data
security. It encapsulates a TCP/IP socket and is used by TCP/IP applications
that require secure communications. SSL is a low-level authentication and
encryption service used by higher-level applications. SSL allows encrypted
and secure exchange transmission between a VoiceXML browser instance and
an HTTPS Web application server. Only SSL version 3 is supported by the
WebSphere Voice Response Java and VoiceXML environment.
To implement secure communications within your deployment environment,
your Web-based voice application must point to a secure Web application
server using the HTTPS protocol.
10
In the WebSphere Voice Response connection environment, specify https as
the transfer protocol in your URIs.
Example of using HTTPS as the transfer protocol in default.cff for a
managed Voice XML application:
AppName=weather
Enabled=yes
Parameter=URI,https://my.secureserver/samples/weather.vxml
AppClass=com.ibm.wvr.vxml2.DTVoicelet2
;
Example of using HTTPS as the transfer protocol in default.cff for a
CCXML application:
#CCXML Service definition
CCXService=ccxml1
Enabled=yes
InitialURI=https://server.name/document.ccxml
DefAppService=Node1
CacheLimit=16M
Example of using HTTPS as the transfer protocol in an unmanaged VoiceXML
application:
vxml2 https://my.secureserver/samples/weather.vxml
Example of using HTTPS as the transfer protocol inside a Voice XML
document:
<goto next="https://my.secureserver/next.vxml" />
The encryption algorithm used for the secure transmission is automatically
negotiated between the VoiceXML or CCXML browser and the Web
application server hosting the Web-based voice application. An optimal
encryption algorithm is chosen.
Supported digital certificates
Server authentication is the only method supported between a Web
application server hosting a Web-based voice application (using HTTPS
protocol) and the VoiceXML browser. For server authentication, the Web
application server must have one of the digital certificates based on the X.509
standard below. The trusted third-parties, or signer certificates, verify the
identification of a certificate holder. The certificate holders that are installed
with WebSphere Voice Response include:
v Thawte Server CA
v Verisign Class 1 Public Primary Certification Authority
v Thawte Personal Basic CA
v Verisign Class 3 Public Primary Certification Authority
11
v
v
v
v
Verisign Test CA Root Certificates
Verisign Class 2 Public Primary Certification Authority
RSA Secure Server Certification Authority
Thawte Premium Server CA
v Thawte Personal Freemail CA
v Thawte Personal Premium CA
The digital certificate is used to authenticate the Web server to the VoiceXML
browser. During the initial SSL handshake, the Web server supplies the
VoiceXML browser with its X.509 certificate. If the VoiceXML browser
validates the Web server's certificate, a secure encrypted communication
channel is established between the Web server and the VoiceXML browser.
You must make sure that the Web server hosting the VoiceXML browser
application supports one of the digital certificates listed above.
12
Chapter 2. System configuration and management
This section tells you about the configuration database and more specialized
installation and configuration tasks, such as setting up a network of nodes or
configuring voice response nodes to support languages other than U.S.
English, telephony, speech recognition, and text to speech:
v “About the configuration database” on page 14
v “About the HostManager” on page 19
v “Managing a single voice response node” on page 19
v “Managing a network of nodes” on page 20
v
v
v
v
“Adding a new voice response node to the plex” on page 23
“Setting up an application node” on page 26
“Adding telephony capability” on page 33
“Configuring the listening socket queue size” on page 39
v “Adding speech technology” on page 39
You also need to refer to the documentation provided with the base
WebSphere Voice Response for AIX system for information about tasks such
as:
v Configuring and monitoring trunks and channels (or telephone lines)
v Configuring and monitoring system resources such as CPU load and
channels in use
v Collecting call statistics
v Responding to alarms raised on the WebSphere Voice Response system.
Attention: Before starting the Java and VoiceXML environment on WebSphere
Voice Response for AIX , ensure that you start the Java and VoiceXML
environment before activating the channels.
Attention: Before stopping the Java and VoiceXML environment on
WebSphere Voice Response for AIX , ensure that you take the channels out of
service before terminating the WebSphere Voice Response Java and VoiceXML
Environment. If you do not do this, an Unexpected socket termination
message may result if the environment is terminated while a call is in
progress.
13
About the configuration database
The configuration database holds the necessary information to enable voice
applications and nodes to locate each other.
“Introducing the configuration database” on page 5 introduces the basic
information you needed to get started. This section provides the following
information:
v “The name of the configuration database”
v “Updating the configuration database”
v “How many configurations?” on page 18
See Appendix A, “The configuration database,” on page 77 for detailed
information about the contents of the configuration database.
The name of the configuration database
The configuration database is normally “config.cfd”. You can rename the
database if you want to, but you’ll have to change the supplied scripts,
commands, or batch files to match. Unless you have a really good reason to
change it, it is inadvisable.
Updating the configuration database
To update the configuration database, you first need to modify a text file
called default.cff, which is located in the directory defined by $DTJ_DIR
(usually /var/dirTalk/DTBE/native/aix). You can do this manually, but the
easiest way to populate the configuration database initially or to modify it
later is to use the configuration tool dtjit.
To run the configuration tool:
1. As dtuser, type dtjit at any AIX command line prompt. The following
window is displayed:
14
Figure 1. VRBE Utilities Window
2. With VRBE configuration selected, press the Enter key. The following
window is displayed:
15
Figure 2. VRBE Configuration window
Before proceeding, you need to know:
v The relative number of telephone calls that you expect to have
processed by each application.
v The details of any URIs that you need to specify. (The paths of file URIs
must be absolute, not relative.)
Note:
v The names of applications must not contain the colon (:) character.
v You can specify only one RecoService and one TTSService for each Java
locale.
v dtjit does not use an existing default.cff file as an input but instead
uses an existing vrbecfg.ser file. You are advised to keep a back-up
copy of this file.
3. To configure the WebSphere Voice Response Java and VoiceXML
Environment from scratch, select each of the menu choices in turn and
press the Enter key to open the window for the selected section of the
configuration. To update a particular section of the configuration, select it
from the menu and press the Enter key.
16
Follow the instructions and answer the questions displayed. If you need
more information, press the F1 key to display help.
4. When you have completed the configuration details that you need to
specify, in the VRBE Configuration window select Generate vrbecfg.cff
file and press the Enter key. A vrbecfg.cff file is created in the directory
defined by $DTJ_DIR.
5. Press the F10 key to exit.
6. Copy the generated vrbecfg.cff file to default.cff in the same directory.
To update the configuration database, you need to import default.cff into
the configuration database using the dtjconf command. This command
replaces the default configuration completely. The dtjconf command can also
be used to export the contents of the configuration database to a text file, and
to list the configurations in the database.
Used by
Java and
VoiceXML
Environment
Import
Configuration
database
(config.cfd)
Configuration
file
(default.cff)
Edit
Export
List
List of
configurations
Figure 3. Using dtjconf
When you install WebSphere Voice Response for AIX, the default.cff file is
located in directory /var/dirTalk/DTBE/native/aix. There is also a
default.sample.cff file located in the same directory.
To update the default configuration in the configuration database, config.cfd
manually rather than use the configuration tool:
1. To be quite sure that the default.cff file is an accurate representation of
the current default configuration in the configuration database, use the
following command:
dtjconf -action export
2. This creates a file called default.exp. Rename it to default.cff.
17
3. Edit the default.cff file to add or change the entries as necessary.
The format of the configuration file is as follows:
v Each line can contain a keyword and a parameter, separated by an
equals (=) sign.
v A pound sign (#) in the first column means that the line is treated as a
comment.
v Blank lines are ignored.
v There are entries identified by their primary keywords, specifying
different resources defined in the file: “AppName configuration entry”
on page 83, “GroupName configuration entry” on page 88, “NodeName
configuration entry” on page 90, “HostName configuration entry” on
page 89, and so on.
v All references must point to something that has already been defined
earlier in the file. This means that:
– All AppName entries must precede all GroupName, RecoService and
TTSService entries.
– All CCXMLService, GroupName, RecoService, TelephonyService, and
TTSService entries must precede all NodeName entries.
– All NodeName entries must precede all HostName entries.
4. Save the default.cff file.
5. To import the new definitions into the configuration database, use the
following command: dtjconf.
6. When you start each node, the changes take effect.
How many configurations?
Throughout this documentation, and in the supplied scripts, commands, and
batch files, we assume that there is only one configuration, named “default”,
defined in the database. However, it is possible to have more than one
configuration defined: when you start the HostManager, you specify the
specific configuration you want to use. If you want to use this feature, you
need to consider the implications for the scripts. For example, dtjconf is
designed to import the default.cff file to create the default configuration.
Again, unless you have a really good reason, having more than one
configuration is inadvisable.
You can list the configurations in the database by using the dtjconf -action
list command.
18
About the HostManager
The HostManager is a process that must be running on each host before the
WebSphere Voice Response Java and VoiceXML Environments can do
anything else, such as starting a node. The dtjshost command is executed
automatically when the base WebSphere Voice Response system is started.
To stop the HostManager, enter the following command:
dtjshost -exit
v On AIX this command provides no visible feedback, but if you want to
check that the command has worked, you can use the dtjqhost command
by entering the following:
dtjqhost
A message similar to the following is displayed if the HostManager has
been stopped successfully:
... I DTJ3033 Host LocalHost is not available
Managing a single voice response node
WebSphere Voice Response Java and VoiceXML Environment provides the
capability to run Java voice applications on a base WebSphere Voice Response
system, so you use the facilities of the base system to manage trunks and
channels, and to monitor system activity.
The instructions in this section are for managing a single node locally from
the command line of the local host. It is assumed in the scripts that the node
is defined as “VRNode1” in the configuration database. For managing nodes
remotely, see “Managing a network of nodes” on page 20.
Starting a single voice response node
1. Start the operating system. This starts the HostManager automatically if
you have followed the instructions in “About the HostManager.”
2. Start the base WebSphere Voice Response system.
3. If necessary, start the HostManager: dtjshost
4. Start VRNode1 on the local host: dtjstart
This starts any applications in groups named in the Group keywords in
the NodeName entry.
5. Finally, on AIX, enable trunks and channels , using the interfaces on the
base WebSphere Voice Response system.
Monitoring system usage
While the system is running you can use the following commands:
v Query the status of the local host: dtjqhost
v Querying the status of all nodes in the local host: dtjqnode
19
v Query the status of Java applications on VRNode1 of the local host:
dtjqapps
v Query the status of CCXML applications: see “Querying the status of all the
applications in a node” on page 22.
To monitor other system resources, such as CPU load, active channels, and
disk space, you need to use the base WebSphere Voice Response system or the
operating system.
Stopping a single voice response node
1. Quiesce and then disable trunks and channels, using the interfaces on the
base WebSphere Voice Response system.
2. Stop VRNode1 on the local host: dtjstop
This waits until each call finishes and stops any applications that are
running.
3. Stop the HostManager: dtjshost -exit
4. Shut down the base WebSphere Voice Response system.
5. Shut down the operating system.
Managing a network of nodes
When you install WebSphere Voice Response Java and VoiceXML Environment
on a host, the installation process creates a configuration database on that
system, but when you have a network of nodes, or plex, you must use only
one configuration database, in which you define all your hosts, nodes, groups,
applications, and other resources, as described in Appendix A, “The
configuration database,” on page 77. You should nominate one node as the
system management console.
The system management console
The system management console can be any of the voice response nodes. On
the system management console:
v You must have access to the configuration database.
v You update the configuration database (repeating the configuration process
using dtjit as described in “Updating the configuration database” on page
14, or by manually editing default.cff, and running dtjconf to import
default.cff)
v You start the nodes, using the dtjplex command.
Note: Make sure you start the HostManager on each host: see “About the
HostManager” on page 19.
Managing a network of nodes (plex) with the dtjplex command
When you had a single voice response node, you used commands such as
dtjstart and dtjstop to manage it locally. When you manage a network of
20
nodes, you can manage them from a central point using the dtjplex
command, which allows you to specify host names, node names, and so on.
You can create your own scripts, command, or batch files that issue dtjplex
commands for common tasks. Here is a quick overview of the dtjplex
commands. Full syntax is given in “dtjplex script” on page 147.
If your configuration node is not AIX, you will have to implement equivalent
scripts using the “PlexManagerImpl command” on page 178.
You must issue all these commands from the system management console,
because the configuration database (config.cfd) must be accessible.
Starting the entire plex
To start all nodes in all hosts, on the host where config.cfd is located, enter
the following command:
dtjplex -action startAll
Starting all the nodes in a host
On the host where config.cfd is located, enter the following command:
dtjplex -host hostname -action startHost
Starting a specific node only
dtjplex -host hostname -node nodename -action startNode
Starting a specific application in a node
dtjplex -host host_name -node nodename -application applicationname
-copies number -action startApplication
Shutting down the entire plex
To prevent new telephone calls from starting, allow telephone calls to
complete, and shut down all the nodes on all the hosts, on the host where
config.cfd is located, enter the following command:
dtjplex -action stopAll
To shut down all applications running in the entire complex immediately, on
the host where config.cfd is located, enter the following command:
dtjplex -action terminateAll
21
Shutting down all the nodes in a host
complete, and shut down the host, on the command line on any of the hosts
defined in the config.cfd, enter the following command:
dtjplex -host hostname -action stopHost
To shut down all applications running on the host immediately, on the
command line of any of the hosts defined in the config.cfd, enter the
following command:
dtjplex -host hostname -action terminateHost
Shutting down a particular node only
complete, and shut down the node, on the command line on any of the hosts
defined in the config.cfd, enter the following command:
dtjplex -host hostname -node nodename -action stopNode
To immediately shut down the node and all applications running on it, on the
command line of any of the hosts defined in the config.cfd, enter the
following command:
dtjplex -host hostname -node nodename -action terminateNode
Querying the status of all hosts
dtjplex -action queryHosts
Querying the status of all the nodes in a host
dtjplex -action queryNodes -host hostname
Querying the status of all the applications in a node
To query the status of all the applications in a node (excluding CCXML
applications), on the host where config.cfd is located, type the following
command:
dtjplex -action queryApplications -host hostname -node nodename
For the status of CCXML applications, on the host where config.cfd is
located, type the following command :
dtjplex -action queryCCXML -host hostname -node nodename
22
Changing the port for communication between nodes
The voice response nodes and the application nodes communicate using
TCP/IP. The default for such communication (RMIport) is on port 26924. You
can change the default RMIport by using the dtjit configuration tool as
described in “Updating the configuration database” on page 14, or by
manually editing default.cff as follows:
1. In default.cff, go to the section for Host definitions that starts with
HostName= .
2. In the line that contains RMIPortNumber=, change the value of the entry
to another valid TCP port number.
3. Run the dtjconf command.
Adding a new voice response node to the plex
When you add a new voice response node to the plex, you must add a
HostName configuration entry to the configuration database on the system
management console.
For Java applications, if the characteristics of the new node are identical to
those on another host, you can use the same NodeName configuration entry
as in Example 1: both voice response nodes have the same default locale, the
same default application, and the same group of applications started on them.
(This approach is not recommended for VoiceXML and will not work with
CCXML applications.) If you are using CCXML as in Example 4 or if the
characteristics of the new node are different from the nodes you already have,
as in Example 2, create a new NodeName entry for it.
Example 1: Nodename entry shared by two hosts
#. AppName entry
..
# Voice response node entry used by both legs11 and lucky7 hosts.
NodeName=VRNode1
VRNode=yes
NodeDefLocale=en_US
NumToApp=*,welcome
NumToApp=123456,pizzas
NumToApp=123457,myapp
;
HostName=legs11
IPName=legs11.hursley.ibm.com
Node=VRNode1
;
HostName=lucky7
IPName=lucky7.hursley.ibm.com
Node=VRNode1
;
23
Example 2: Voice response nodes with different characteristics
In this example, the two voice response nodes are very different:
NodeName=VRNode1
VRNode=yes
NodeDefLocale=en_GB
NumToApp=*,welcome
;
NodeName=VRNode2
VRNode=yes
NodeDefLocale=fr_FR
NumToApp=*,acceuil
NumToApp=122442,paris
NumToApp=122445,nice
;
HostName=england
IPName=england.hursley.ibm.com
Node=VRNode1
;
HostName=france
IPName=france.hursley.ibm.com
Node=VRNode2
;
Example 3: Node running on AIX with reco and text-to-speech
In this example, one voice response node is defined. The Reco and TTS
Service definitions are also not included.
# Voice response node running on AIX
# Using a NodeClassPath because there is a test version of the
# application in mybeans.jar in use on another node.
# The pizzas application is started automatically,
# but the myapp application is not.
NodeName=VRNode1
VRNode=yes
NodeDefLocale=en_US
NumToApp=*,welcome
NodeClassPath=/j/prod/mybeans.jar:/j/prod/pizzas.jar
#
# RECO AND TTS SERVICES AVAILABLE ON THIS NODE
# Two speech recognition services are defined (ViaVoiceAIX and
# ANotherAIX).
# One text-to-speech service is defined (FirstByteAIX).
RecoService=ViaVoiceAIX
RecoService=ANotherAIX
TTSService=FirstByteAIX
#
# RECO AND TTS DEFINITIONS TO BE USED BY APPLICATIONS
# ViaVoice is defined as the speech recognition technology to use for
# all languages, but this example shows how you would specify a
# different technology for one language.
# ViaVoice is used for all other languages.
24
RecoDefinition=*,ViaVoice
RecoDefinition=xx_YY,ANother
#
#
#
#
#
FirstByte is defined as the text to speech technology to use for
all languages, but this example shows how you would specify a
different technology for two languages.
FirstByte is used for all other languages.
TTSDefinition=xx_YY,ANother
TTSDefinition=aa_BB,ANother
TTSDefinition=*,FirstByte
;
HostName=amigo
IPName=amigo.hursley.ibm.com
Node=VRNode1
;
Example 4: A voice response node running CCXML
In this example, one voice response node is running a CCXML application
and the other is running a Java application:
CCXService=ccx1
Enabled=yes
InitialURI = http://calling.hursley.ibm.com/ccxml/testdoc.ccxml
DefAppService=Node1
;
AppName=VerifyInstall
Enabled=yes
AppClass=com.ibm.telephony.wvr.VerifyInstall
;
# This is the definition of a Voice Response node:
NodeName=VRNode1
Enabled=yes
NodeDefLocale=en_US
VRNode=yes
NumToApp=*,VerifyInstall
TTSService=VXML
TTSDefinition=vo_IC_EXML,VXMLTTS
CCXAppService=ccx1
NumToApp=3950?,ccx1
;
NodeName=VRNode2
VRNode=yes
NodeDefLocale=en_GB
NumToApp=*,welcome
;
#-------------------------------------------------------# HostName entries
#-------------------------------------------------------# This is the definition of the host machine storing this
# configuration file and where management is run from
HostName=scotland
Enabled=yes
25
IPName=scotland.hursley.ibm.com
Node=VRNode1
;
# This is the definition of a remote host:
HostName=england
Enabled=yes
IPName=england.hursley.ibm.com
Node=VRNode2
;
Starting a voice response node remotely from the system management console
After adding a voice response NodeName entry to the default.cff file, run
dtjconf to import it into the configuration database.
To start the new node remotely:
1. On the target WebSphere Voice Response system, select Configuration ->
System Configuration -> Change -> General -> Start Java and VoiceXML
Environment Automatically. Set this parameter to Disabled.
2. Shut down the target WebSphere Voice Response system and then restart
it.
3. Start the HostManager on the WebSphere Voice Response host, by running
the dtjshost command.
4. Start the plex from the system management console, by running the
following command:
dtjplex -action startHost -host hostname
Setting up an application node
An application node is exactly like a voice response node, in that it must have
WebSphere Voice Response Java and VoiceXML Environment installed on it,
but it does not need to have a WebSphere Voice Response system installed on
the same host. The application node, and its application groups and
applications, are defined in the same configuration database as the voice
response node.
An application node can be on the same host as the voice response node or it
can be on a different host. There can be only one voice response node within
a host, but there can be multiple application nodes.
Figure 4 on page 27 shows an application node and a voice response node on
separate hosts, with the system management console on the same host as the
voice response node.
The following figure shows the configuration database being used by all
nodes.
26
Host System
Host System
Voice response node
Application node
Java and VoiceXML
Environment
Configuration
database
Java
Java
Java
application
application
application
Java
Java
Java
application
application
application
Java and VoiceXML
Environment
Any
Java-enabled
platform
WebSphere Voice
Response system
Figure 4. Application node and voice response node on separate hosts
v “Why set up an application node?”
v “Installing an application node” on page 29
v “Configuring an application node” on page 29
v “Starting an application node” on page 32
v “Adding telephony capability” on page 33
Why set up an application node?
The purpose of an application node is to run applications outside the voice
response node. Java's remote method invocation (RMI) is used for
communication. All VoiceXML applications must be run in application nodes
rather than the voice response node. CCXML applications can be run on
nodes of either type. For Java applications, the performance of applications
run on an application node is slower than that of applications run in the voice
response node. Nevertheless, application nodes have several potential uses:
v “Testing applications”
v “Updating applications dynamically” on page 28
v “Keeping applications separate” on page 28
v “Improving performance in a high-density system” on page 28
Testing applications
Use an application node to test applications in a “pseudo-production”
environment, before letting them run on a voice response node. This enables
you to check that you have created the correct “AppName configuration
entry” on page 83 for the application. If you are testing a Java application, use
the NodeClassPath keyword on each “NodeName configuration entry” on
page 90
27
page 90 to specify the classpath of the application you are testing. This
enables you to have the same application defined for both production and test
nodes.
Note that you cannot run applications from Rational Application Developer
on an application node. You run the application “in the application node”,
using the services of a voice response node.
Updating applications dynamically
Use an application node to put a new version of an application into
production, without having to stop the voice response node. You simply have
to stop the application node. So, if you have an application node for each
application, you can dynamically update one application without stopping
any of the others.
Keeping applications separate
You can have application nodes on different hosts to keep applications
physically separate from each other. Nevertheless, all the voice segments for
these applications must be located on the voice response node. The only way
to keep applications completely separate is to have more than one voice
response node.
Improving performance in a high-density system
In a high-density system, excessive Java garbage collection can have an
adverse performance impact on your VoiceXML and Java applications. You
can avoid this by setting up multiple application nodes on the same host as
the voice response node, or on a different host.
Note that when you do run multiple application nodes, by default WebSphere
Voice Response creates only one VoiceXML cache directory for use by all the
nodes. However, it is possible for each node to use its own directory, which
can lead to performance improvements. Use the following procedure to
achieve such a configuration:
1. Login as dtuser.
2. Stop the Java and VoiceXML environment from the command line by
entering:
dtjstop
dtjshost -exit
3. Enter the command cd $DTBE_HOME/native/aix
4. Using a text editor, open the file default.cff.
28
5. For each application node (or voice response node) that you want to use
its own cache directory, add the following line to the application
NodeName stanza:
JavaCommand=java -Dwvr.vxml2.cachedir=directory
(where java is name of the Java executable (usr/java16/jre/bin/java),
and directory is the absolute path of the cache directory you want to use.
If you already have a JavaCommand line in default.cff then add
-Dwvr.vxml2.cachedir=directory to the end of the JavaCommand line.
6. Save the file.
7. Verify that the changes are valid, then update config.cfd by entering the
command dtjconf.
8. Restart the Java and VoiceXML environment by entering the following
commands:
dtjshost
dtjstart
The new cache directory is created automatically if it does not already
exist.
Installing an application node
If you are installing the application node on an AIX system:
1. Use SMIT to install the dirTalk.VRBE_XML.rte fileset from the WebSphere
Voice Response for AIX installation CD-ROM.
If the application node is on the same host as the voice response node, there
are no installation tasks to do.
Configuring an application node
Important: Do not configure more than 30 applications to run on the same
application node.
In the configuration database on the voice response node:
1. Create a NodeName entry for the application node.
The NodeName configuration entry for an application node does not have
as many other keywords as a NodeName entry for a voice response node,
for the simple reason that it does not provide services to the applications.
However, there are two keywords that apply to application nodes but not
to voice response nodes: the NodeDefVRNode and the NodeDefHost,
which define the default voice response node and its host, for applications
running on the application node.
2. If the application node is on a different host from the voice response node,
create a HostName entry for the host on which the application node is
located.
29
3. Ensure that the HostName entry for the host on which the voice response
node is located specifies the fully qualified TCP/IP address in the IPName
keyword. This enables the application node to locate the voice response
node.
To start applications on an application node, create a GroupName entry in the
configuration database and refer to it using the Group keyword in the
NodeName entry for the application node. If you want to be sure that the
application node is set up correctly, make sure you do not start the same
application on the voice response node.
The following example shows a configuration file including NodeName
entries and GroupName entries:
# Definition of a banking application
AppName=myapp
AppClass=test.banking
;
# Definition of a pizza-ordering application
AppName=pizzas
AppClass=production.pizzaOrdering
;
# A group that contains the myapp application
GroupName=CurrentTest
Application=myapp
Application=myapp
;
# A group that contains the pizzas application
GroupName=Pizzas
Application=pizzas
Application=pizzas
Application=pizzas
;
# Application node running a group of applications called CurrentTest
# Using a NodeClassPath because there is a production version
of the
# The myapp application is run in this node.
NodeName=Test
VRNode=no
NodeDefVRNode=Node1
NodeDefHost=lucky7
NodeClassPath=/j/test/mybeans.jar
Group=CurrentTest
;
# Voice response node running on AIX
# Using a NodeClassPath because there is a test version of the
# The pizzas application is run in this node,
# but the myapp application is not.
NodeName=VRNode1
VRNode=yes
NodeDefLocale=en_US
30
NumToApp=*,welcome
NodeClassPath=/j/prod/mybeans.jar:/j/prod/pizzas.jar
;
# Host of test system
HostName=legs11
Node=Test
;
# Host of production system
HostName=lucky7
Node=VRNode1
;
After using the dtjit configuration tool as described in “Updating the
configuration database” on page 14, or by manually editing the default.cff
file to make the changes, run dtjconf to import them into the configuration
database. You now have a network of nodes, or plex. To ensure that your
changes have taken effect:
1. Start the HostManager on each host, by running the dtjshost command.
2. Start the plex by running the following command:
3. Make a call to one of the applications you have started on the application
node.
31
Node=Node1
NodeName=Node1
NodeName=Test
NodeDefHost=lucky7
NodeDefVRNode=Node1
VRNode=No
Group=CurrentTest
GroupName=CurrentTest
Application=myapp
Application=myapp
AppName=myapp
AppClass=test.banking
Voice response node
Application node
Figure 5. How configuration entries refer to each other: application running in application node
Figure 5 shows how the voice response node is identified when the
application is started in an application node. Starting an application in an
application node is exactly the same as starting an application in a voice
response node: the node name you specify is the application node, not the
voice response node. If the application node is correctly configured, the
NodeDefHost and NodeDefVRNode keywords are used to identify the voice
response node.
Starting an application node
Run dtjshost to start the HostManager. In the long term, you should arrange
to start the HostManager automatically, as described in “About the
HostManager” on page 19. Then start the node:
dtjplex -action StartNode -node nodename -host hostname.
On other operating systems: Set the CLASSPATH to include ibmcctl.jar and
ibmdtalk.jar. Use the “HostManagerImpl command” on page 177 to start the
HostManager and the “PlexManagerImpl command” on page 178 to start the
node. You can modify the Appendix C, “Supplied scripts,” on page 135 to
create scripts suitable for your operating system.
In the long term, when you’ve configured this application node, you’ll be able
to start the application node when starting the whole plex (dtjplex -action
StartAll).
32
Adding telephony capability
A telephony service is a definition of a host to which a voice response node can
pass requests for call control functions such as call transfer, and from which
call data such as DNIS can be received.
One Genesys CallPath Enterprise Server, Genesys T-Server, or Genesys
I-Server telephony service per voice response node can be configured. If a
telephony service is configured, the voice response node will attempt to use it
for call control and call information in preference to the base WebSphere Voice
Response call control. The advanced Genesys API function RouteRequest is
accessible using the VoiceXML object tag. refer to the WebSphere Voice
Response for AIX: VoiceXML Programmer's Guide information.
Configuring Genesys Version 7.0 Framework and WebSphere Voice Response
to work together is done slightly differently, compared with the configuration
required for earlier versions of Genesys.
To configure Genesys Version 7.0 Framework and WebSphere Voice Response
to work together:
1. On the base WebSphere Voice Response system you must configure all the
phone numbers connecting WebSphere Voice Response to the switch. (In
WebSphere Voice Response for AIX , set the Channel Ids to the phone
numbers.
2. Ensure that the switch allows the Genesys server to monitor and control
the WebSphere Voice Response lines. This may mean selecting a specific
protocol for the connection from WebSphere Voice Response to the switch
(for example, on the Lucent Definity, use FXS Loop Start). For details,
consult the Genesys documentation.
3. If you are using Genesys I-Server you must define each of these phone
numbers in the Configuration Manager by creating a directory number
(DN) for each in the Switch folder, as shown in Figure 8 on page 38. (The
host name and port number shown in this figure are for illustration
purposes only.)
4. If you are using Genesys T-Server you must define each of these phone
purposes only.)
5. To define the telephony service to the voice response node, create a
“TelephonyService configuration entry” on page 102 and add a
TelephonyService keyword to the “NodeName configuration entry” on
page 90.
33
Note: The TelephonyService secondary keywords Password and
UserName, previously supported for Genesys T-Server TelephonyService
configuration, are not required for I-Server TelephonyService configuration.
6. Copy file IServer.dtd to directory/var/dirTalk/DTBE/native/aix from the
directory C:\Program Files\GCTI\IVRIServer\TServer_IVR_720\ where
Genesys Server was installed.
If for some reason a transfer operation using Genesys CTI cannot be
completed satisfactorily, perhaps because there is a problem with the Genesys
CTI server, it is possible to specify that the transfer is made by WebSphere
Voice Response instead. Refer to the section “Re-routing Genesys CTI call
transfers through WebSphere Voice Response” in VoiceXML Programmer's
Guide for WebSphere Voice Response for more information on how to do this.
To configure earlier versions of Genesys and WebSphere Voice Response to
work together:
1. On the base WebSphere Voice Response system you must configure all the
phone numbers connecting WebSphere Voice Response to the switch. (In
WebSphere Voice Response for AIX , set the Channel Ids to the phone
numbers. )
2. Ensure that the switch allows the Genesys server to monitor and control
the WebSphere Voice Response lines. This may mean selecting a specific
protocol for the connection from WebSphere Voice Response to the switch
(for example, on the Lucent Definity, use FXS Loop Start). For details,
consult the Genesys documentation.
3. If you are using the CallPath Enterprise Server JTAPI daemon, you must
specify each of these phone numbers in a user definition. To ensure that the
voice response node can access the CallPath Enterprise Server for the
telephone numbers it uses, while keeping resource usage to a minimum,
create one user definition for each voice response node, as shown in
Figure 6 on page 36.
4. If you are using Genesys T-Server you must define each of these phone
purposes only.)
5. To define the telephony service to the voice response node, create a
“TelephonyService configuration entry” on page 102 and add a
TelephonyService keyword to the “NodeName configuration entry” on
page 90.
6. To enable access to the current Genesys Java Classes you must specify the
two jar files ibmcpath.jar and cpphone.jar in the NodeClassPath of the
NodeName configuration entry in the configuration file (see “NodeName
configuration entry” on page 90). You obtain copies of these jar files from
34
Genesys when you purchase your server software. For example, if you
installed these jar files in /var/genesys, then you would add the following
line to the NodeName configuration entry:
NodeClassPath=/var/genesys/ibmcpath.jar:/var/genesys/cpphone.jar
If for some reason a transfer operation using Genesys CTI cannot be
completed satisfactorily, perhaps because there is a problem with the Genesys
CTI server, it is possible to specify that the transfer is made by WebSphere
Voice Response instead. Refer to the section “Re-routing Genesys CTI call
transfers through WebSphere Voice Response” in VoiceXML Programmer's
Guide for WebSphere Voice Response for more information on how to do this.
TelephonyService=anhingaTS
ServerName=7600@seagull
UserName=anhinga
Password=redred
;
TelephonyService=blackbirdTS
UserName=blackbird
Password=yellow
;
TelephonyService=cormorantTS
UserName=cormorant
Password=blueit
;
NodeName=anhinga
VRNode=yes
NodeDefLocale=en_US
NodeDefAppName=welcome
Group=Pizzas
NodeTelephonyService=anhingaTS
;
NodeName=blackbird
VRNode=yes
NodeDefLocale=en_US
Group=Pizzas
NodeTelephonyService=blackbirdTS
;
NodeName=cormorant
VRNode=yes
NodeDefLocale=en_US
Group=Pizzas
NodeTelephonyService=cormorantTS
;
35
CallPath
Enterprise Server
IP name=Seagull
Port number=7600
JTAPI
daemon configuration
Java and VoiceXML Environment Configuration
TelephonyService
=anhingaTS
UserName=Anhinga
ServerName=7600@Seagull
NodeName=anhinga
NodeTelephonyService
=anhingaTS
Using phone
numbers
8001
through 8024
User=Anhinga
Line numbers
8001 through 8024
User=Blackbird
Line numbers
8025 through 8048
User=Cormorant
Line numbers
8049 through 8072
TelephonyService
=blackbirdTS
UserName=Blackbird
NodeName=blackbird
=blackbirdTS
TelephonyService
=cormorantTS
NodeName=cormorant
UserName=Cormorant
=cormorantTS
Using phone
numbers
8025
through 8048
Using phone
numbers
8049
through 8072
Figure 6. Definitions required for voice response nodes to communicate with CallPath Enterprise Server
36
Java and VoiceXML Environment Configuration
TelephonyService
=anhingaTS
NodeName=anhinga
ServerName=
TSERVER:7600@Seagull
=anhingaTS
TelephonyService
=blackbirdTS
NodeName=blackbird
ServerName=
=blackbirdTS
TelephonyService
=cormorantTS
NodeName=cormorant
ServerName=
=cormorantTS
Using phone
numbers
8001
through 8024
Configuration Manager
Dns 8001 - 8072
Using phone
numbers
8025
through 8048
hostname =seagull
T-Server port = 7600
Using phone
numbers
8049
through 8072
Figure 7. Definitions required for voice response nodes to communicate with Genesys T-Server
37
Figure 8. Definitions required for voice response nodes to communicate with Genesys I-Server
Related information
v “Telephony functionality” in the WebSphere Voice Response: VoiceXML
Programmer's Guide for WebSphere Voice Response manual.
v “Integrating WebSphere Voice Response with Genesys Framework” in the
WebSphere Voice Response: General Information and Planning manual.
v Configuring Genesys I-Server in this manual.
v “Using advanced CTI features” in the WebSphere Voice Response:
VoiceXML Programmer's Guide for WebSphere Voice Response manual.
Adding a Telephony URL Locale
A Telephony URL Locale is a definition of a location within a telephony
network. In simple terms it is a definition of the digits that need to be dialed
in order to reach a Voice Response node.
The Locale is specified by two properties. Firstly there is a "global" definition,
which is the number that can be dialed from anywhere in world in order to
reach a node. Secondly there is a "local" definition, which is the number that
can be dialed in order to reach a node from within a sub-area of the
telephony network.
38
A Telephony URL Locale is required for the evaluation of Telephony URLs
such as may be used by VoiceXML Version 2.1 and CCXML.
To add a Telephony URL Locale, create a TelURLLocale entry in your
configuration file (see “TelURLLocale configuration entry” on page 101), and
add the name of the TelURLLocale to the NodeName configuration entry.
Configuring the listening socket queue size
The server socket that listens for CHP connections is used by WebSphere
Voice Response for AIX to communicate with WebSphere Voice Response Java
and VoiceXML Environment.
The maximum length of the queue on this socket is set to 150 by default. This
means that WebSphere Voice Response can have a maximum of 150 pending
connections to Java before the next connection is refused. It should be
emphasized that the maximum queue length is the number of pending
connections, not the total number of connections.
The problem is that some applications generate a high level of incoming calls,
particularly applications that result in many short calls. In this situation, the
pending socket queue can become full, especially during the period that
garbage collection occurs. If this happens, WebSphere Voice Response writes
the following error message to the error log file:
Could not connect to DirectTalk Beans: call will not be processed. Connect
call failed to port <port number>
To avoid this problem, edit the dtj.ini file to add the following entry:
dta.listen.queue=<queue size>
where <queue size> is the increased queue size that you want to use. Save the
changes.
The default value of 150 is the equivalent of specifying the following in the
dtj.ini file:
dta.listen.queue=150
Adding speech technology
In the WebSphere Voice Response Java and VoiceXML Environment, speech
technology can be used without hard-coding it into the speech application,
making it easier to switch from one technology to another. In addition,
different technologies can be used for different languages, again, without
hard-coding anything in the application. (Java voice applications are fully
language-independent.)
39
To be able to use speech technology, there are several components that you
need to install and configure. Below is a summary of the steps you need to
perform if you want to use the speech technology available in WebSphere
Voice Server.
1. First install the required speech recognition technology on your base
system. If you are using WebSphere Voice Server V5.1, or other
MRCP-V1.0-compliant speech product, see chapter three of the WebSphere
Voice Response for AIX: Installation book for details of how to install the
required WebSphere Voice Server Connector fileset.
2. Then, on each voice response node, install the required plug-in for the
speech technology you want to use, as follows (note that these zip files
contain the plug-ins for both speech recognition and text-to-speech, so you
only have to install the required file once):
a. Change directory to /var/dirTalk/DTBE/plugins and find the
dtjmrcp.zip, plug-in for the WebSphere Voice Server Version 5.1
speech technology.
b. Ensure that WebSphere Voice Response is running, but also that the
host and the Java and VoiceXML environment node are not running.
c. Enter the following command:
dtjplgin dtjmrcp.zip
This action additionally installs required custom server components.
d. When you restart the node, the required speech recognition or
text-to-speech plug-in is available for use.
3. Next, either use the dtjit configuration tool as described in “Updating the
configuration database” on page 14, or manually edit the configuration file
default.cff for either speech recognition or text-to-speech capability, as
described in “How speech recognition is configured” on page 41 and
“How text-to-speech is configured” on page 47.
4. When you have finished amending default.cff, update the configuration
database by running the dtjconf command, as described in “Updating the
configuration database” on page 14.
5. Edit file /var/dirTalk/DTBE/dtj.ini to specify the appropriate confidence
score range for your application. MRCP returns a confidence score in the
range 0 - 100 whereas VXML2 expects a score in the range 0 - 1.
To use the range 0 - 1, set the wvr.use.vxml2.confidencerange parameter
to true:
wvr.use.vxml2.confidencerange=true
To use the range 0 - 100, set the parameter to false, which is the default
value.
6. If you are using WebSphere Voice Server Version 5.1.1, 5.1.2, or 5.1.3 to
provide your speech technology, run the configureWVR utility (.sh on Linux
or .bat on Windows) on the WebSphere Voice Server system. This
40
configuration utility is available as part of an interim fix that can be
downloaded. Please refer to the relevant WebSphere Voice Server support
Technote at http://www.ibm.com/software/pervasive/voice_server/
support/, for further information about downloading and installing the
interim fix.
7. Start the MRCP and the MRCP_Log custom servers, using the WebSphere
Voice Response Custom Server Manager window (at the Welcome window,
select Operations —> Custom Server Manager).
Note: The custom server uses AIX communications ports to send and
receive voice data to the voice server, and the allocation of these ports
grows as needed while the custom server is in operation. The default
allocation at startup is 120 pairs of ports, sufficient for 120 active trunk
channels each using a single language voice recognition or text-to-speech
application. If you need more than this, you can preallocate a number of
ports before starting the custom servers, to ensure their availability, by use
of the 'p' (lower case) parameter on the custom server command line. Note
this parameter does not define the total number of ports allocated, it
merely preallocates them
You can access this parameter by selecting Applications —>Custom
Servers —>Server —>Open —>File —>Properties , then enter p<n>,
where <n> is the number of pairs of ports to preallocate. Note there is no
space between the p and the number. <n> can be in the range 0 to 480. For
example p240 will give 240 pairs of ports. (sufficient for 240 active trunk
channels using a single language).
How speech recognition is configured
As explained below, the plug-in class to be used for any individual
recognition attempt is found using RecoService configuration entries, together
with RecoDefinitions.
How is the RecoService configuration entry used?
As part of the NodeName configuration entry, you should have a
“RecoService configuration entry” on page 95 for each plug-in on each
operating system platform you use in your WebSphere Voice Response Java
and VoiceXML Environment plex. This is simple if you have a homogeneous
system, for example, all your voice response nodes run AIX. It is simpler still
if you have only one speech recognition technology.
If you do have voice response nodes with different operating systems, the
RecoService entries for each one is distinguished by the RecoService=name.
The RecoType=name keyword identifies the technology, which should be the
same on both (or all) RecoService entries.
41
MRCP can be configured so that in the event of a configured MRCP resource
becoming unavailable, a secondary back-up server can take over so that
MRCP activity can continue. The speech recognition session is restored on the
backup server to the same state as the primary server prior to the failure. Any
grammars, or session variables being used are also reinstated, so that the
recovered session functions in the same way as the working primary server.
The URI of the back-up server is specified by the second InitSessionString
keyword in a RecoService entry in configuration file default.cff.
For more information, and an example of a RecoService entry, see
“RecoService configuration entry” on page 95
Each voice response node has a “NodeName configuration entry” on page 90,
in which the relevant RecoService entries are identified. For detailed
information see “NodeName configuration entry” on page 90.
What is a RecoDefinition?
A RecoDefinition contains two items of information: RecoType and locale
identifier. RecoType is a platform-independent name for the speech
recognition technology. The locale identifier identifies the languages for which
this technology is to be used. The locale identifier can be an asterisk (*),
indicating “all locales”. For more information about locale identifiers, see
“How languages are identified in VoiceXML and Java” on page 7.
Hint: It is often convenient to configure a plug-in for a language instead of
the full locale. For example, if you have a German reco engine and configure
it for the "de" locale, applications running in de_DE, de_AT, and de_CH can
all use this reco service for speech recognition. If you configure it for "de_DE",
applications running in de_AT and de_CH will not be able to access the reco
resource.
If you are running VoiceXML applications that use speech recognition, you
must include a RecoDefinition for the language-only part of your locale as
well as a RecoDefinition for the full locale. For example, to run a VoiceXML
application in the en_US locale, you must include the following
RecoDefinition entries:
RecoDefinition=en,recoType
RecoDefinition=en_US,recoType
where recoType is the name of your RecoType.
Applications running in an unsupported locale will use the language-only
RecoDefinition for default behaviour such as error messages. For example, if
you are running a VoiceXML application in New Zealand, with a locale of
en_NZ, your RecoDefinitions will be as follows:
42
RecoDefinition=en,recoType
RecoDefinition=en_NZ,recoType
In the above example, if your application encounters an error which causes it
to play the default error message "Sorry, must exit due to processing error",
this message will play in the 'en' locale, which is American English. The
dialect of the 'en' locale may not be correct for your application, in which
case, you should provide your own default behaviour.
In most cases the full locale is compatible with the language-only locale. The
exception is Chinese, which has locales of 'zh' (simplified Chinese) and
'zh_HK' (traditional Chinese). If your application uses Chinese you must be
careful to use the correct locale because grammars compiled for one locale
will not load in an engine designed for the other.
Where should you put the RecoDefinitions?
There are three places where you can put RecoDefinitions. The simplest is to
put them in the “NodeName configuration entry” on page 90. These
definitions apply to all applications run in the node.
If you need to specify different technologies for different applications, you can
override the RecoDefinitions in the NodeName entry, by putting
RecoDefinitions in the “AppName configuration entry” on page 83. Read
“Specifying RecoDefinitions for an application” if you need to do this.
The bottom line is: put the definitions in the NodeName entry unless your
applications need to use different technologies.
Specifying RecoDefinitions for an application
If all the applications running in a node are to use the same speech
recognition technology, there is no need to specify RecoDefinitions in the
AppName configuration entry. All applications can use the RecoDefinitions in
the NodeName configuration entry. However, if you are using different
technologies for different applications, you need to read this section.
If all the applications running in a node are to use the same speech
recognition technology, there is no need to specify RecoDefinitions in the
AppName configuration entry. All applications can use the RecoDefinitions in
the NodeName configuration entry. However, if you are using different
technologies for different applications, you need to read this section.
When a WebSphere Voice Response application attempts to use speech
recognition, the current locale of the application is used to find the
appropriate RecoDefinition. In VoiceXML, the value of the vxml xml:lang
attribute determines the current locale of the application. The “AppName
43
configuration entry” on page 83 is searched first, and if a RecoDefinition is
found for the locale, or for “all locales”, it is used. If no RecoDefinition is
found for the locale, the “NodeName configuration entry” on page 90 is
searched.
1. RecoDefinitions
in the AppName entry
or in ApplicationProperties
are searched until
the locale, or an
asterisk (*) is found
Application
current locale = fr_CA
Example (a)
Example (b)
AppName entry
AppName entry
RecoDefinition=*,A
RecoDefinition=*,A
RecoDefinition=fr_FR,B
RecoDefinition=fr_CA,B
RecoType B is used
for fr_CA
ED
NodeName entry
Figure 9. Searching for the RecoType: contrasting examples
44
IG
IG
N
N
O
R
ED
RecoType A is used for
all locales
NodeName entry
2. fr_CA is found
O
R
2. The asterisk (*) means
that no further searching
is done
RecoDefinition=*,A
1. RecoDefinitions
are searched until
the locale, or an
Application
Example (c)
Example (d)
Example (e)
AppName entry
AppName entry
AppName entry
RecoDefinition=en_US,A
2. fr_CA is not found
NodeName entry
NodeName entry
NodeName entry
RecoDefinition=*,A
RecoDefinition=*,A
RecoDefinition=fr,B
RecoType A is used
for fr_CA
RecoType B is used
for fr_CA
RecoType B is used
for fr_CA
Figure 10. Searching for the RecoType: more contrasting examples
Figure 9 on page 44 and Figure 10 show five contrasting examples of the
search for a RecoDefinition to be used for Canadian French.
v In example (a) a single RecoDefinition that applies to all locales is found in
the AppName entry. Because of this, the RecoDefinitions in the NodeName
entry are not even considered. RecoType A is used for Canadian French.
v In example (b) a RecoDefinition for Canadian French is found in the
AppName entry, and this overrides the RecoDefinition that applies to all
locales (A,*), so RecoType B is used. Again, the NodeName entry is not
considered.
45
v In example (c), even though there is a specific RecoDefinition for fr_Fr in
the AppName entry, this does not apply if the current locale is fr_CA. There
is no RecoDefinition that applies to all locales, so the NodeName is
searched. Here, a RecoDefinition for all locales is found.
v Example (d) is like example (c), with the difference that a specific
RecoDefinition for Canadian French is found in the NodeName entry.
v Example (e) is like example (c), with the difference that a RecoDefinition for
all French locales is found in the NodeName entry.
If this seems over-complicated, you can avoid any confusion by specifying all
your RecoDefinitions in the “NodeName configuration entry” on page 90.
Once a suitable RecoDefinition is found, the RecoType is used to search for
the “RecoService configuration entry” on page 95. All the RecoServices
specified in the “NodeName configuration entry” on page 90 are searched
until the RecoType is found. Once the RecoService has been found, the name
of the speech recognition plug-in is known, and the plug-in is used to pass
the recognition request to the speech recognizer.
46
Figure 11. The search for the speech recognition plug-in
How text-to-speech is configured
As described below, the plug-in class to be used for converting text to speech
for any individual text-to-speech string is found using TTSService
configuration entries and TTSDefinitions. However for VoiceXML applications
you should specify the locale by including the <vxml> xml:lang attribute in
your VoiceXML documents, to ensure that the correct built-in resources are
used.
47
How is the TTSService configuration entry used?
You should have a “TTSService configuration entry” on page 105 for each
plug-in on each operating system platform you use in your WebSphere Voice
Response Java and VoiceXML Environment plex. This is simple if you have a
homogeneous system, for example, all your voice response nodes run AIX. It
is simpler still if you have only one text-to-speech technology.
If you do have voice response nodes with different operating systems, the
TTSService entries for each one is distinguished by the TTSService=name. The
TTSType=name keyword identifies the technology, which should be the same
on both (or all) TTSService entries.
Each voice response node has a “NodeName configuration entry” on page 90,
in which the relevant TTSService entries are identified.
MRCP can be configured so that in the event of a configured MRCP resource
becoming unavailable, a secondary back-up server can take over so that
MRCP activity can continue. The speech synthesis session is restored on the
backup server to the same state as the primary server prior to the failure. Any
synthesis parameters, or session variables being used are also reinstated, so
that the recovered session functions in the same way as the working primary
server. The URI of the back-up server is specified by the second
InitSessionString keyword in a TTSService entry in configuration file
default.cff.
For more detailed information about the TTSService configuration entry,
including examples, see “TTSService configuration entry” on page 105.
What is a TTSDefinition?
A TTSDefinition contains two items of information: TTSType and locale
identifier. TTSType is a platform-independent name for the text-to-speech
technology. The locale identifier identifies the languages for which this
technology is to be used. The locale identifier can be an asterisk (*), indicating
“all locales”. For more information about locale identifiers, see “How
languages are identified in VoiceXML and Java” on page 7.
Hint: It is often convenient to configure a plug-in for a language instead of
the full locale. For example, if you have a German TTS engine and configure
it for the "de" locale, applications running in de_DE, de_AT, and de_CH can
all use this TTS service for text-to-speech. If you configure it for "de_DE",
applications running in de_AT and de_CH will not be able to access the
resource.
48
If you are running VoiceXML applications that use text-to-speech, you must
include a TTSDefinition for the language-only part of your locale as well as a
TTSDefinition for the full locale. For example, to run a VoiceXML application
in the en_US locale, you must include the following TTSDefinition entries:
TTSDefinition=en,ttsType
TTSDefinition=en_US,ttsType
where ttsType is the name of your TTSType.
Applications running in an unsupported locale will use the language-only
TTSDefinition for default behaviour such as error messages. For example, if
you are running a VoiceXML application in New Zealand, with a locale of
en_NZ, your TTSDefinitions will be as follows:
TTSDefinition=en,ttsType
TTSDefinition=en_NZ,ttsType
In the above example, if your application encounters an error which causes it
to play the default error message "Sorry, must exit due to processing error",
this message will play in the 'en' locale, which is American English. The
dialect of the 'en' locale may not be correct for your application, in which
case, you should provide your own default behaviour.
Where should you put the TTSDefinitions?
There are three places where you can put TTSDefinitions. The simplest is to
put them in the “NodeName configuration entry” on page 90. These
definitions apply to all applications run in the node.
If you need to specify different technologies for different applications, you can
override the TTSDefinitions in the NodeName entry, by putting
TTSDefinitions in the “AppName configuration entry” on page 83. Read
“Specifying TTSDefinitions for an application” if you need to do this.
The bottom line is: put the definitions in the NodeName entry unless your
applications need to use different technologies.
Specifying TTSDefinitions for an application
If all the applications running in a node are to use the same text-to-speech
technology, there is no need to specify TTSDefinitions in either the
ApplicationProperties or the AppName configuration entry. All applications
can use the TTSDefinitions in the NodeName configuration entry. However, if
you are using different technologies for different applications, you need to
read this section.
When a VoiceXML application attempts to use text-to-speech, the value of the
vxml xml:lang attribute is used to find the appropriate TTSDefinition. For Java
49
applications, the current locale of the individual TextToSpeech object is used
to find the TTSDefinition (see Developing Java applications for more information
about the TextToSpeech class). If an individual tag or object does not have a
locale specified, the current locale of the application is used. The
ApplicationProperties or the “AppName configuration entry” on page 83 is
searched first, and if a TTSDefinition is found for the locale, or for “all
locales”, it is used. If no TTSDefinition is found for the locale, the
“NodeName configuration entry” on page 90 is searched.
50
1. TTSDefinitions
are searched until
the locale, or an
Application
Example (a)
Example (b)
AppName entry
AppName entry
TTSDefinition=*,A
TTSDefinition=*,A
TTSDefinition=fr_FR,B
TTSDefinition=fr_CA,B
TTSType A is used for
all locales
TTSType B is used
for fr_CA
NodeName entry
R
O
N
IG
N
IG
O
R
ED
NodeName entry
2. fr_CA is found
ED
2. The asterisk (*) means
that no further searching
is done
RecoDefinition=*,A
Figure 12. Searching for the TTSType: contrasting examples
51
1. TTSDefinitions
are searched until
the locale, or an
Application
Example (c)
Example (d)
Example (e)
AppName entry
AppName entry
AppName entry
TTSDefinition=en_US,A
NodeName entry
NodeName entry
NodeName entry
TTSDefinition=*,A
TTSDefinition=*,A
TTSDefinition=fr,B
TTSType A is used
for fr_CA
TTSType B is used
for fr_CA
TTSType B is used
for fr_CA
Figure 13. Searching for the TTSType: more contrasting examples
Figure 12 on page 51 and Figure 13 show five contrasting examples of the
search for a TTSDefinition to be used for Canadian French.
v In example (a) a single TTSDefinition that applies to all locales is found in
the AppName entry. Because of this, the TTSDefinitions in the NodeName
entry are not even considered. TTSType A is used for Canadian French.
v In example (b) a TTSDefinition for Canadian French is found in the
AppName entry, and this overrides the TTSDefinition that applies to all
locales (A,*), so TTSType B is used. Again, the NodeName entry is not
considered.
52
v In example (c), even though there is a specific TTSDefinition for fr_Fr in the
AppName entry, this does not apply if the current locale is fr_CA. There is
no TTSDefinition that applies to all locales, so the NodeName is searched.
Here, a TTSDefinition for all locales is found.
v Example (d) is like example (c), with the difference that a specific
TTSDefinition for Canadian French is found in the NodeName entry.
v Example (e) is also like example (c), with the difference that a TTSDefinition
for all French locales is found in the NodeName entry.
If this seems over-complicated, you can avoid any confusion by specifying all
your TTSDefinitions in the “NodeName configuration entry” on page 90.
Once a suitable TTSDefinition is found, the TTSType is used to search for the
“TTSService configuration entry” on page 105. All the TTSServices specified in
the “NodeName configuration entry” on page 90 are searched until the
TTSType is found. Once the TTSService has been found, the name of the
text-to-speech plug-in is known, and the plug-in is used to pass the
text-to-speech request to the text-to-speech software.
53
Figure 14. The search for the text-to-speech plug-in
54
Chapter 3. Deploying applications
This section includes detailed information on configuring and deploying
applications:
v “Preparing for deployment”
v “Running an application in a node” on page 60
v “Running CCXML applications in a node” on page 58
v “Putting your application into production” on page 71
v “Deploying VoiceXML applications” on page 72
v “Getting help from IBM Support” on page 75
Preparing for deployment
Before you deploy your application on a production system, it is important
that you have tested your applications using a real telephone, switch, and a
voice response node that has the base WebSphere Voice Response system
running on it.
You must test your applications using a real system because applications may
behave differently when under load.
The following table summarizes the testing of applications running in a node
on a WebSphere Voice Response system.
Table 1. Summary of running applications
How you...
Running in a node
Specify the phone number for
an application
Java and VoiceXML:
Specify the Java class to be
used
Java and VoiceXML:
NodeName configuration entry for the voice response
node: NumToApp=number,name
AppName configuration entry AppClass=name. For
VoiceXML applications this is always
com.ibm.wvr.vxml2.DTVoicelet2 (VoiceXML 2.1)
55
Table 1. Summary of running applications (continued)
How you...
Running in a node
Add your class or jar file to
the CLASSPATH
Java applications only:
NodeName configuration entry NodeClassPath=....
This is appended to the CLASSPATH of the host
where the voice response node is.
Specify the application name
(which is used in the
NumToApp= mapping)
Java and VoiceXML:
Specify the voice response
node to be used
Java and VoiceXML:
Specify the locale (optional: if
not specified, voice response
node locale is assumed)
Java and VoiceXML:
AppName configuration entry AppName=name
This depends on how you start the application: see
“Starting applications” on page 67.
AppName configuration entry Locale=identifier
Specify application parameters Java and VoiceXML:
AppName configuration entry Parameter=name,value.
Specify RecoDefinitions and
TTSDefinitions (optional: can
be specified at node level)
Java and VoiceXML:
Specify RMI port (if
necessary)
Java and VoiceXML:
AppName configuration entry
RecoDefinition=recotype,locale and
TTSDefinition=TTStype,locale
HostName configuration entry
RMIPortNumber=number
Defining the application
When you deploy your application in production, you will be running it in a
node. This allows you to start the application automatically and make sure it
is always ready to answer calls.
56
To run an application in a node, you need to create an AppName entry in the
configuration database. This specifies the properties of the application,
including the application name referred to in the number-to-application
mapping (in this example, “weather”):
AppName=weather
Parameter=URI,https://my.secureserver/samples/weather.vxml
;
CCXML applications require some additional configuration parameters in
default.cff. See “Running CCXML applications in a node” on page 58.
Application name
The application name was introduced in “Defining the application” on page
56. It is the key to:
v Identifying the VoiceXML document or Java class to the voice response
node.
v Including the VoiceXML document or Java class in a group for automatic
startup.
v Associating the VoiceXML document or Java class with the phone number
in the number-to-application mapping.
If you are running the application from Rational Application Developer, the
application name is specified within the application itself. For more
information, see Developing Java applications.
If you are running the application in a node, the application name is specified
in the “AppName configuration entry” on page 83.
Automatically starting applications in a node
When you install the WebSphere Voice Response Java and VoiceXML
Environment, the configuration database contains an entry for the sample
application, “menu”. When you call the number associated with menu, you
should find that the menu application is waiting for your call. How does this
happen? An instance of menu is automatically started with the node.
To start an application in this way, you need to define an application node
with an application group, and specify the name of the group in the
NodeName entry for the application node. You also need to define a voice
response Node, and reference it in the NodeDefVRNode setting of the
application node's NodeName entry.
Here's an example in which four instances of menu are automatically started,
making the node capable of handling four calls for menu simultaneously.
57
The GroupName entry of the application node looks like this:
GroupName=group1
Application=menu
Application=menu
Application=menu
Application=menu
;
The NodeName entry of the application node looks like this:
NodeName=AppNode1
NodeDefLocale=en_US
VRNode=no
NodeDefHost=LocalHost
NodeDefVRNode=VRNode1
Group=group1
;
And the NodeName entry of the voice response node now looks like this:
NodeName=VRNode1
NodeDefLocale=en_US
VRNode=yes
NumToApp=123456,menu
NumToApp=123455,app1
;
The need for multiple application instances
Each instance of a Java application typically handles a single call at one time.
You need to have multiple instances of the application waiting for calls: as
many as you expect to handle during your peak hour. If you have more than
one application, you need a different set of instances for each, or you can
have a “top-level” Java application that greets the caller, asks them what
service they require, and calls other applications as needed. The called
application can be written in Java, VoiceXML, or it can be a state table.
Running CCXML applications in a node
A CCXService must be defined in configuration file default.cff to enable the
CCXML Browser to be run in a node:
CCXService=serviceName
Enabled=yes
InitialURI = ccxml uri
DefAppService=nodeName
;
58
You can do this either by using the dtjit configuration tool as described in
“Updating the configuration database” on page 14, or by manually editing
configuration file default.cff.
You can configure a CCXService in one of two ways:
v So that only one CCXML Browser session is started and all new calls
received are handled by the CCXML document being executed in that
session. In this case, the CCXML document must be designed to handle
multiple calls concurrently.
v So that a new CCXML Browser session is started for each new call received.
It is generally easier to write CCXML documents in this mode because you
do not need to manage state and variables for multiple connection.
However, you must exit the session when it has completed its work for a
call or the system will leak resources.
The default is for all calls to go to the same browser session.
To start a new session for each new call received, the following line is added
to the CCXService definition:
SingleCall=yes
To start a CCXML Browser service in a node, following line is added to the
node definition:
CCXAppService=serviceName
One or more CCXML Browser services can be started in a node.
Receiving a telephone call
When an incoming call is received by a Voice Response node in the
WebSphere Voice Response Java and VoiceXML environment it can be routed
to one of the following:
v A CCXML browser
v A VoiceXML application
v A Java application
The routing is determined by the number that the call is received on.
For a call to be received by the WebSphere Voice Response Java and
VoiceXML environment, the WebSphere Voice Response system must have an
application profile that specifies the call is to be handled by the
JavaApplication state table. See “The phone number” on page 63.
Receiving telephone calls in the ALERTING state
The Java and VoiceXML environment is designed to receive incoming
telephone calls in the CONNECTED state. This means that the new call is
ringing WebSphere Voice Response, but it has not yet been answered.
59
When a call is routed to a CCXML document, it must initially be in the
ALERTING state. The CCXML document can accept or reject the call.
If the call is routed to a VoiceXML application or a Java application by the
Java and VoiceXML environment, it is automatically answered before the
application is started.
Note: For calls to be received in the ALERTING state, the WebSphere Voice
Response AnswerCall action must be removed from the Incoming_Call state
table. See Appendix E, “Changing the Incoming_Call state table to receive
calls in the ALERTING state,” on page 179 for instructions on how to do this.
Mapping CCXML browsers to a phone number
For a CCXML Browser Service to receive incoming calls for a specific
telephone number or line identifier, you must map the phone number or line
identifier to the CCXService name. To do this, add a NumToApp keyword to the
NodeName configuration entry of a Voice Response node that is to launch the
CCXML browser. The service name specified in the NumToApp keyword entry
must match the name specified in the CCXService configuration entry. For
example, if the number is 987654 and the CCXService name is ccxml1, the
entry should be:
NumToApp=987654,ccxml1
The number can contain wildcards. See NumToApp for full details.
Running an application in a node
Running an application in a node (also known as “running a managed
application”) is the normal way of running applications after you have
finished testing them.
Defining application characteristics
When you tested your application using the WebSphere Voice Toolkit you
probably defined the application name, the class, and any other application
details within the application itself. Now you are running the application as a
managed application, you need to specify these application details in an
AppName configuration entry in the configuration file.
VoiceXML applications
The AppClass for a VoiceXML 2.1 application is always
com.ibm.wvr.vxml2.DTVoicelet2
For a VoiceXML 2.1 application that is started from a CCXML document:
60
AppName=vxmlccxml
Enabled=yes
Parameter=DynamicURI, yes
;
This example does not have an application URI defined (hence DynamicURI).
Instead, the CCXML document specifies the document that the VoiceXML
browser is to run.
For a VoiceXML 2.1 application that is located on the voice response node and
is started by a NumToApp mapping:
AppName=weather
Enabled=yes
Parameter=URI, file:///var/dirTalk/DTBE/samples/en_US/Weather.vxml
;
For a VoiceXML 2.1 application that is located on a Web server and is started
by a NumToApp mapping:
AppName=horoscope
Enabled=yes
Parameter=URI, http://www.company.com/apps/horoscope.vxml
;
The protocol (file in the first example, http in the second) is mandatory for
VoiceXML 2.1 applications. Relative URIs are not supported.
Running DTMF-only VoiceXML applications
If your VoiceXML 2.1 application does not use speech recognition or
text-to-speech, and instead relies solely on recorded audio and dual-tone
multi-frequency (DTMF) signals, you must include the DTMFONLY parameter in
the AppName entry, and set it to true. For example:
AppName=defapp
Enabled=yes
Parameter=URI,http://www.company.com/apps/horoscope.vxml
Parameter=DTMFONLY,true
;
Java applications
This is what an AppName entry for a Java application looks like:
AppName=pizzas
AppClass=my.package.pizzaApplication
Locale=en_GB
61
Parameter=branch_id,0123
Parameter=branch_name,Southampton
;
You may want to leave out some of the properties now the application is
going into production. For example, the locale and the RecoDefinitions and
TTSDefinitions can be derived from the NodeName entry for the node where
the application is going to run. The only keyword you must have is AppClass:
AppName=pizzas
AppClass=my.package.pizzaApplication
;
You can create more than one AppName entry for the same class, for example,
if you want to run different language versions of the application.
Making Java applications available to the node
Two keywords in the “NodeName configuration entry” on page 90 are
important here. If the application answers incoming calls, set the NumToApp
keyword, as described in “Mapping a VoiceXML or Java application to a
phone number.” You may also need to set the NodeClassPath keyword to
include the class name or JAR file name containing your application class.
NodeName=Node1
NodeClassPath=/home/dtuser/myapps/pizzas.jar
NodeDefLocale=en_GB
;
Mapping a VoiceXML or Java application to a phone number
For an application that waits for incoming calls for a specific phone number
or line identifier, you must map the phone number or line identifier to the
application name. To do this, you must add a NumToApp keyword to the
NodeName configuration entry of the voice response node. The application
name in the NumToApp= keyword must match the name given in the
AppName configuration entry. For example, if the number is 123456, and the
application name is app1, the entry should look like this:
NumToApp=123456,app1
The number can contain wildcards, for example, "NumToApp=*,default" or
"NumToApp=123?,menu", . See NumToApp for full details.
If a call is received for a number for which there is no NumToApp keyword,
and if a default application has been defined, the default application handles
the call (see “Providing a default application” on page 65).
For more information, see “NodeName configuration entry” on page 90.
62
The phone number
Whenever you specify a new phone number you must make sure that the
base WebSphere Voice Response system knows that this phone number is to
be used by the WebSphere Voice Response Java and VoiceXML environment.
If you have state tables in addition to Java or VoiceXML applications, you
may need to create an application profile for each channel or phone number
you intend to use: from the WebSphere Voice Response Configuration
window, select Application Profiles --> New. Specify JavaApplication as the
State Table to use. Ignore Subscriber Classes.
The dialed number (for example, the number obtained by dialed number
identification service (DNIS)) is used to find the right application. If the dialed
number is not available, the line number configured in base WebSphere Voice
Response system is used.
Ensuring that the call is answered
To ensure that each call for a Java or VoiceXML application is answered, it is
essential that sufficient copies of the application are running all the time. This
means that you need to start the applications as soon as the node is started.
To achieve this, define a “GroupName configuration entry” on page 88 that
identifies the applications to be started, and then add the name of this group
to the NodeName entry of an application node. (Ten identical Application
keywords mean ten instances will be started.)
Important: Do not configure more than 30 applications to run on the same
application node.
# A group that contains two instances of the pizzas application
GroupName=pizza_ordering
Application=pizzas
Application=pizzas
;
NodeName=Node1
NodeClassPath=/home/dtuser/myapps/pizzas.jar
NodeDefLocale=en_GB
Group=pizza_ordering
;
Figure 15 on page 64 shows an example of the configuration entries necessary
as a series of nested boxes. (Figure 5 on page 32 shows the equivalent picture,
when the application is started in an application node.)
63
Figure 15. Configuration entries for an application running in the voice response node
Figure 16 on page 65 shows multiple instances of applications waiting for
calls. Whenever a call comes in for a number for which no application is
waiting, the default application is started up and handles the call.
Note: You must have sufficient copies of VoiceXML or Java applications
running when the application is started. This applies equally to applications
started from a CCXML document and applications started from a NumToApp
mapping.
64
Figure 16. Multiple instances of applications waiting for calls
Providing a default application
Every voice response node should have a default application, which can be
either CCXML, VoiceXML, or Java. The default application is invoked in the
following two situations:
v When there is no application configured for the number dialed by the caller
(that is, there is no NumToApp mapping for the DNIS).
v When there is an application configured for the number dialed by the caller,
but there is no free instance of the application (in a "waitForCall" state)
when the call arrives.
The default application does not have to be started, because it is dynamically
started as required.
1. Add an AppName configuration entry for the application.
2. Specify the default application name using the NodeDefAppName
keyword in the NodeName configuration entry.
The following three parameters are passed to the default application:
v DNIS
v targetAppName
v targetAppClass
Only the first of these parameters is available to VoiceXML and CCXML
applications. The value of the DNIS in a VoiceXML application is stored in the
local.uri session variable. In a CCXML application, you can copy the DNIS
information from the CLGN telephony tag using a <var> element. (Refer to
65
WebSphere Voice Response for AIX: Using the CCXML Browser for further
information.) In a Java application you can access all three parameters by
calling the getParameter() or getParameters() method of the WVR object that
waits for, or makes, the call. These parameters are:
DNIS parameter
The dialed number (also known as the called number) is not the same as the
phone number that you put in the NumToApp mapping. Services such as
Dialed Number Identification Service allow a program to get the actual dialed
number as opposed to the number arbitrarily passed by the switch and
associated with the application.
For example two toll-free numbers may both end up at the same number that
is passed by the switch to WebSphere Voice Response and is then associated
with JavaApplication and thence with a VoiceXML application.
targetAppName and targetAppClass parameters
When there is no application configured for the number dialed by the caller
(that is, there is no NumToApp mapping for the DNIS), the targetAppName
and targetAppClass parameters are undefined (null). When there is an
application configured for the number dialed by the caller, but there is no free
instance of the application when the call arrives, the targetAppName and
targetAppClass parameters tell the default application what should have
happened, and allow it to either simply log the error condition, or solve the
problem by creating an instance of the appropriate application
(targetAppClass) and passing the call to it.
Example configuration entries for the default application
# Default application: Welcome to our information service
# When no instance of the pizzas application is waiting, or
# if a call arrives on a number other than 123456,
# the welcome application is started
AppName=welcome
AppClass=my.package.welcomeapp
;
NodeName=VRNode1
VRNode=yes
NodeDefLocale=en_US
;
66
Starting applications
It’s best to start applications running before you put the channels in service:
otherwise, on AIX, callers hear the message that says “we are experiencing
technical difficulties”. If they call before the channels are in service, then they
simply won’t get through at all, which is preferable.
You can either start an application individually or automatically.
Starting an application individually
Enter the following command:
dtjplex -action startApplication -application name -copies number -host name
-node name
Starting an application automatically
For normal use, you’ll need to start the application automatically. To configure
for this:
1. Add an Application=appname keyword to a GroupName configuration
entry. To start more copies of the application, add this keyword as many
times as you need.
2. Add a Group=groupname keyword to a NodeName configuration entry.
This includes the group in node startup.
3. Start the node. If you are simply starting one node, the command is:
dtjplex -action startNode -host name -node name
Starting an application in multiple nodes
The way to do this is to include the same Group keyword in each NodeName
entry, as described in “Ensuring that the call is answered” on page 63. Once
you have defined a group of applications, you can start the same group on as
many nodes as you want. For Java applications the Java classes need to be
included in the NodeClassPath of each node, and need to be accessible to
each node.
Starting CCXML services
CCXML services provide the CCXML browsers you need to handle telephone
calls. CCXML services can be started on application nodes and Voice Response
nodes, but the nodes must be configured to do so. You can do this using the
dtjit configuration tool as described in “Updating the configuration database”
on page 14, or by manually editing default.cff.
To configure CCXML services manually:
67
1. At the top of the original default.cff, just above the required entry
defining the plug-in to be used for playing cached prerecorded audio in
VoiceXML applications, add a CCXML Service definition entry for the
CCXML Browser:
2. In the NodeName entry for the node on which you wish to run CCXML
applications, add a CCXAppService entry for the CCXML Browser you
defined previously in the CCXML Service definition entry.
To run CCXML applications on a Voice Response node, you also need to
add a NumToApp mapping entry
Using message logs
Message log files contain the messages displayed on stdout, runtime errors
and application logging, if it exists. The following log files are created in the
$DTJ_LOGS directory, which by default, is /var/dirTalk/DTBE/dtj_logs:
v log.n.log, created on each machine running the Java and VoiceXML
environment, where n is a number between 1 and 10 (by default). This file
contains a binary representation of runtime errors and VoiceXML
application logging, if it exists.
v <nodename>.out, created by each node. This file catches messages not caught
by the log.n.log file. It contains messages that are sent to stdout, for
example, Java application messages printed using System.out.println(). It
is a standard text file that does not need to be formatted for viewing.
The log.n.log file is a cyclic file. Logging will initially be output to
log.1.log. When this file reaches a size of 5000 Kb (by default), logging will
be output to log.2.log, and so on. When this process has continued until
log.10.log is full, the first log file will be overwritten and the cycle continues.
You can change the output directory, size, and number of the log files by
using the dtjit configuration tool or by editing the following properties in the
dtj.ini file:
v log.directory
v log.filesize
v log.numberoflogs
Note that the log.filesize property is stored in kilobytes, so to increase the
value to 10000 Kb from the default value of 5000, you would edit the entry to:
log.filesize=10000
Use the dtjflog command to format the log.n.log file so that you can read it.
For example, to format log.2.log to a file called log2.out:
dtjflog -o log2.out log.2.log
This command is explained in full in “dtjflog script” on page 143.
68
Note: The nodename.out file is backed up to nodename.out.bak when the node
starts. This applies to application nodes and voice response nodes when
started. If nodename.out already exists, it is renamed to nodename.out.bak
before the new file is created.
CCXML and Voice XML application logging
By default, <log> element application logging messages from CCXML and
VoiceXML applications are sent to the log.n.log file, created in the
$DTJ_LOGS directory, which by default, is /var/dirTalk/DTBE/dtj_logs. (n is
a number between 1 and 10 (by default). This file is created on each machine
running the Java and VoiceXML environment.
In addition, you can also redirect application logging messages from CCXML
and VoiceXML applications to your own logging application by adding the
following properties in the dtj.ini file:
v user.log.classpath
v user.log.class
For example:
user.log.classpath=/usr/log/log.jar
user.log.class=mypackage.mylogger
These parameters identify a class that implements the WebSphere Voice
Response user logging Java interface. If the jar file defined in
user.log.classpath is not in the Java CLASSPATH, it is loaded dynamically
when the user logging application is started.
WebSphere Voice Response provides an example .jar file
$DTJ_HOME/samples/userlog.jar that contains the class and source file for the
example class examples.UserLog. The example class implements the interface
and provides simple logging to a finite set of files (userlog.0.log through
userlog.9.log) in the /tmp directory that are reused in sequence. You can
customize this application to modify the way that CCXML and VoiceXML
application logging is handled for your system. To use the sample application,
you must add the following properties to dtj.ini:
user.log.classpath=/var/dirTalk/DTBE/samples/userlog.jar
user.log.class=examples.UserLog
If the appropriate parameters are set in dtj.ini file, you can use the following
commands to control user logging.
The dtjshost command starts the redirection of CCXML and VoiceXML
application logging to the user logging application by invoking the
user.log.class defined in dtj.ini and the command dtjshost -exit stops it.
This allows you to control redirection of CCXML and VoiceXML application
69
logging when the HostManager is started and stopped. The dtjshost
command is explained in full in “dtjshost script” on page 171.
To start the redirection of CCXML and VoiceXML application logging without
the need to stop or start the Host Manager, use the dtjuserlog command.
The command dtjuserlog -exit stops the redirection of CCXML and VoiceXML
application logging. The DT_shutdown command also does this.
User Logging Java interface
The user class is instantiated using a constructor with no parameters.
Immediately after the class is instantiated, its open method void open() is
invoked. When the invoking class is closing the user class is called with:
void close();
For each new log message the interface write method is called with the
following parameters:
Table 2. User Logging Java interface write method parameters
Parameter
Data Type
LogData
String (value of log tag)
Type
Integer (VXML_LOG_TYPE or
CCXML_LOG_TYPE)
These are defined in the definition of the
interface.
rootURI
String (root URI of document from which
log was issued)
URI
String (URI from which log was issued)
TrunkNumber
Integer
Currently, TrunkNumber is always passed
by WebSphere Voice Response set to -1
(undefined).
PortID
Integer
Currently, PortID is always passed by
WebSphere Voice Response set to -1
(undefined).
70
callID -used if Type parameter is VXML
Long (unique call ID starting from 1 (at
dtjstart) and increasing for each call)
sessionID - used if Type parameter is
CCXML
String (unique call ID starting from 1 (at
dtjstart) and increasing for each call)
Putting your application into production
This section contains checklists of things to do when putting VoiceXML and
Java applications into production.
Checklist for VoiceXML applications
Checklist for putting a VoiceXML application into production:
1.
If you have developed your application using a third party toolkit or
service creation, you must also test your application using a real
WebSphere Voice Response system.
2.
Make sure you have done adequate capacity planning. You need to
know what your peak volume of calls will be. The base WebSphere
Voice Response system must have adequate channels or lines to
handle this. You may use one or more base WebSphere Voice
Response system, each on the same host as a voice response node. See
the General Information and Planning book for your base WebSphere
Voice Response system.
3.
Install base WebSphere Voice Response systems as necessary: see the
Installation book for your base WebSphere Voice Response system.
Ensure that WebSphere Voice Response has been set up to route calls
to the WebSphere Voice Response Java and VoiceXML environment
and that the Incoming_Call state table does not answer the call. See
“Receiving telephone calls in the ALERTING state” on page 59.
4.
Set up production voice response nodes as necessary: see “Adding a
new voice response node to the plex” on page 23.
5.
Install CallPath support as necessary: see “Adding telephony
capability” on page 33.
6.
Install speech recognition and text-to-speech technologies as necessary:
see “How speech recognition is configured” on page 41 and “How
text-to-speech is configured” on page 47.
7.
Set up application nodes: see “Setting up an application node” on
page 26.
8.
Ensure that other systems running your business applications are
completely set up.
9.
Make sure each production voice response node has a NumToApp
mapping for the new application, and that the number is defined to
the base WebSphere Voice Response system: see “Mapping a
VoiceXML or Java application to a phone number” on page 62.
71
10.
Ensure that you start enough instances of the application to handle
the peak volume of calls. VoiceXML applications are different from
AIX voice applications, in that you have to make sure that a sufficient
number of instances of the VoiceXML browser are waiting to answer
the call. Use GroupName configuration entries to do this, as described
in “Ensuring that the call is answered” on page 63. It's a good idea to
start a few more instances than there are channels or lines. At the end
of a call, a certain amount of time is needed for the VoiceXML
browser to load and process the initial VoiceXML document before it
can handle another call. You should take this recycle time into account
when you calculate the number of instances that you require.
Deploying VoiceXML applications
You can deploy your VoiceXML documents onto any HTTP compliant Web
server when you want to put them into production, but the speech browsers
that request them and download their associated audio must know where to
find them. To ensure this happens, the Web address (URI) of every VoiceXML
document you want the speech browsers to access must be specified in the
default.cff configuration file. To do this, you can use the dtjit configuration
tool as described in “Updating the configuration database” on page 14 or
manually edit default.cff.
URIs that include numeric IPv6 format addresses, must have the numeric part
within [ ] brackets, for example:
rtsp://[2002:914:fc12:195:0000:8a2e:0370:7334]/media/recognizer
This applies to all protocols.
You may want to configure your web server to support the following MIME
types:
v text/x-vxml
v application/x-ibmfsg
v application/srgs
v application/srgs+xml
v application/x-ibm-ngram
You can use the file system on your local machine to hold VoiceXML
documents. In this case you specify the URI using file:// before the filename
using the full path. For example, on AIX this could be:
file:///var/dirTalk/DTBE/samples/en_US/Weather.vxml
In this case, as with Web servers, the VoiceXML document will reference
associated resources (for example, audio files) using a path relative to the
originating document.
72
Note: File names containing illegal or non-ascii characters must be escaped
and encoded in UTF-8 encoding. For example, a space character in the file
name is specified as %20 in the URI.
MIME type
MIME type is a unique identifier used when files are transferred across a
MIME-based protocol such as HTTP. The VoiceXML browser supports the
following MIME types:
File Type
MIME type
VoiceXML documents
v text/vxml
v text/x-vxml
v application/vxml
v application/x-vxml
audio files
v audio/basic = headerless and .au files with µ-law
encoding (audio/basic .au is the default when
recording)
v audio/x-alaw-basic = headerless and .au files with
a-law encoding
v audio/wav = Microsoft wav file
ABNF grammar files
v application/srgs
XML grammar files
v application/srgs+xml
precompiled grammar files
v application/x-ibmfsg
natural language
understanding (NLU)
v application/x-ibm-ngram
Checklist for CCXML applications
Checklist for putting a CCXML application into production:
1.
the General Information and Planning book for your base WebSphere
Voice Response system.
2.
3.
73
4.
Install CallPath support as necessary: see “Adding telephony
5.
page 26.
6.
completely set up.
7.
mapping for the new application, and that the number is defined to
the base WebSphere Voice Response system: see “Mapping CCXML
browsers to a phone number” on page 60.
8.
Ensure that you configure enough application nodes to handle the
number of CCXML browsers required to handle the peak volume of
calls.
Checklist for Java applications
Checklist for putting a Java application into production:
74
1.
If you have only tested your application on the simulator, you must
also test your application using a real WebSphere Voice Response
system.
2.
Ensure that your application will answer more than one call, rather
than just stopping after the first one: see Developing Java applications
for information on how to do this.
3.
the General Information and Planning for your base WebSphere Voice
Response system.
4.
5.
6.
Install language support as necessary: see “dtjnlsin script” on page
146.
7.
Install Genesys CallPath support as necessary: see “Adding telephony
8.
Install speech recognition and text-to-speech technologies as necessary:
see “How speech recognition is configured” on page 41 and “How
text-to-speech is configured” on page 47.
9
page 26.
10.
Ensure that all necessary software is installed on every node. For
example, other bean sets such as MQSeries, JDBC, SecureWay, and
LDAP.
11.
completely set up.
12.
Export voice segments from the simulator, or the test voice response
node, to the production voice response nodes, as described in
“Copying voice segments from one voice response node to another”
on page 134. Voice segments must be imported into each base
WebSphere Voice Response system. In an AIX single system image,
the voice segments can be imported (using the WebSphere Voice
Response for AIX interface) into any SSI node.
13.
mapping for the new application: see “Mapping a VoiceXML or Java
application to a phone number” on page 62.
14.
Ensure that you start enough instances of the application to handle
the peak volume of calls. Java voice applications are different from
AIX voice applications, in that you have to make sure that a sufficient
number of instances are waiting to answer the call. Use GroupName
configuration entries to do this, as described in “Ensuring that the call
is answered” on page 63. It's a good idea to start a few more instances
than there are channels or lines.
Getting help from IBM Support
If you have a problem with the VoiceXML or Java support in one of the
WebSphere Voice Response products, report it to IBM using your normal
support channel.
What do you need to send to IBM Support to get problems resolved?
It makes it much easier to help you with problems if you give us precise
information, for example:
v The version number of WebSphere Voice Response Java and VoiceXML
Environment (use the dtjver command to get this)
v
v
v
v
v
v
The exact command you issued
The exact message you saw (DTJnnnn)
The exact exception condition
What the CLASSPATH is set to
The operating system where you are running the application
The operating system where the base WebSphere Voice Response system is
running
It can also be useful if you send:
75
v A copy of your default.cff file
v vrbeProblem output
Providing a simple test case for the problem will aid problem determination
greatly.
76
This section gives you more detail about the configuration database and its
keywords. The following sections tell you about:
v “Configuration file keywords”
v “Configuration entries” on page 83
v “AppName configuration entry” on page 83
v “GroupName configuration entry” on page 88
v “HostName configuration entry” on page 89
v “NodeName configuration entry” on page 90
v “RecoService configuration entry” on page 95
v “TelURLLocale configuration entry” on page 101
v “TelephonyService configuration entry” on page 102
v “TTSService configuration entry” on page 105
You can run the configuration tool dtjit to create automatically a plain text
configuration file called vrbecfg.cff that can be used to populate the
configuration database initially or to modify it later, and this is recommended.
See “Updating the configuration database” on page 14.
However, you can also manually edit default.cff to create or modify
particular configuration entries as described in this section.
Configuration file keywords
The keywords for the configuration file are explained briefly here. An index to
more detailed explanations and examples is also included.
Table 3. Index of configuration file keywords
Keyword
Specified in
Explanation
AAIKeys
“TelephonyService
configuration entry” on page
102
Used by Genesys I-Server
to hold user call data
AAIKVPSeparator
“TelephonyService
102
The separator character to
be used by AAIKeys.
77
Table 3. Index of configuration file keywords (continued)
78
Keyword
Specified in
Explanation
AIXPortNumber
“HostName configuration
entry” on page 89
The port number to use for
an AIX system.
AppClass
“AppName configuration
entry” on page 83
Java class to be used.
Application
“GroupName configuration
entry” on page 88
Add an application to a
group.
AppName
entry” on page 83
Specify the name of an
application.
CacheLimit
“CCXService configuration
entry” on page 86
The size of the CCXML
memory cache in MB or
KB.
CallIDRange
“TelephonyService
102
A numeric range of call IDs
used to help identify
individual machines for
Genesys I-Server logging
purposes.
CCXAppService
“NodeName configuration
entry” on page 90
The name of the CCXML
service as defined
previously in “CCXService
configuration entry” on
page 86
CCXHTTPServer
CCXHTTPServer
Switches CCXML external
component event
processing on or off.
CCXHTTPServerPort
CCXHTTPServerPort
Overrides the CCXML
default listener port
number for external
component event
processing.
CCXService
entry” on page 86
The definition of a CCXML
service.
Keyword
Specified in
Explanation
ClientName
“TelephonyService
102
A unique client
identification label for a
voice response node
machine defined as an
authorized Genesys
I-Server client.
DefAppService
entry” on page 86
The node on which to start
the initial CCXML
document.
Enabled {=yes or =no}
All entries
Allow or prevent an object
to be used. Default is yes.
GlobalContext
“TelURLLocale configuration
entry” on page 101
The global prefix of a
location.
Group
entry” on page 90
Add a group to a node.
GroupName
“GroupName configuration
entry” on page 88
Specify the name of a
group.
HostName
entry” on page 89
Specify the name of a host.
InitialAddresses
“TelephonyService
102
With CCXML, pre-defines
the IVR ports to use with
Genesys T-Server
InitTechnologyString
“RecoService configuration
entry” on page 95, “TTSService
105
The speech recognition or
text-to-speech plug-in
technology initialization
string.
InitSessionString
The speech recognition or
entry” on page 95, “TTSService text-to-speech session
initialization string.
105
InternationalAccess
The digits to dial for an
international call.
79
80
Keyword
Specified in
Explanation
PlugInClass
105
The fully-qualified class
name of the speech
recognition or
text-to-speech plug-in.
IPName
entry” on page 89
Specify the TCP/IP address
of a host.
JavaCommand
entry” on page 90
Contains the Java
invocation command used
to start the node.
LocalContext
The local prefix of a
location.
Locale
entry” on page 83
Allows an application to
have a default locale that is
different from the default
locale of the voice response
node.
MediaIPAddress
105
IP address to be used for
the media with machines
having more than one
ethernet adapter
Node
entry” on page 89
Add a node to a host.
NodeClassPath
entry” on page 90
Required for Java
applications if you want to
specify different class paths
for different nodes.
NodeDefAppName
entry” on page 90
Default application or
CCXML service.
NodeDefHost
entry” on page 90
The host name of the voice
response node specified by
NodeDefVRNode.
NodeDefLocale
entry” on page 90
The default locale to be
used by the node.
Keyword
Specified in
Explanation
NodeDefVRNode
(formerly NodeDefTS) entry” on page 90
NodeName
entry” on page 90
Default voice response
node in the host defined by
NodeDefHost, to be used
by all applications running
in the node.
Specify the name of the
node.
NodeTelephonyService “NodeName configuration
(formerly
entry” on page 90
NodeCallPathService)
The name of the telephony
service to be used by this
node.
NumToApp= number,
application
entry” on page 90
Phone number to be dialed
by callers, and the
VoiceXML or Java
application to answer calls
made to this number.
NumToApp= number,
service
entry” on page 90
Phone number to be dialed
by callers, and the CCXML
service to handle calls
made to this number.
Parameter
entry” on page 83
A parameter name and
value to be passed to the
application. It can also be
used to specify the URI of
a VoiceXML application.
Password
“TelephonyService
102
The password defined in
the CallPath Enterprise
Server JTAPI configuration.
RecoDefinition
Defines the speech
entry” on page 83, “NodeName recognition technology to
configuration entry” on page 90 use, either for all languages
or one specific language.
81
82
Keyword
Specified in
Explanation
RecoService
entry” on page 90,
entry” on page 95
The identifier of a
RecoService entry.
Distinguishes between
entries for the same
technology on different
platforms.
RecoType
entry” on page 95
A platform-independent
label for the RecoService
entry, used as a key to find
the required speech
recognition service.
RetrieveCommand
entry” on page 90
The name of a command
string used to retrieve a
call.
RMIPortNumber
entry” on page 89
The port number to use for
the RMI registry.
InitialURI
entry” on page 86
The URI of an initial
CCXML document.
ServerName
“TelephonyService
102
The port number and IP
address of the CallPath
Enterprise Server.
SingleCall
entry” on page 86
Specifies whether or not a
separate browser instance
handles each new inbound
call to the CCXML service.
TelephonyService
(formerly
CallPathService)
“TelephonyService
102
Identifies a telephony
service.
TelURLLocale
Defines a location within a
telephony network.
TTSDefinition
Defines the text-to-speech
entry” on page 83, “NodeName technology to use, either
configuration entry” on page 90 for all languages or one
specific language.
Keyword
Specified in
Explanation
TTSService
105
The identifier of a
TTSService entry.
Distinguishes between
entries for the same
technology on different
platforms.
TTSType
“TTSService configuration
A platform-independent
label for the TTSService
entry, used as a key to find
the required text-to-speech
service.
UserName
“TelephonyService
102
The user name defined in
the CallPath Enterprise
Server JTAPI configuration.
VRNode (formerly
TSNode) {=yes or =no} entry” on page 90
Specifies whether the node
is a voice response node.
Configuration entries
This section provides reference information about the entries in the
configuration, in alphabetical order:
v “AppName configuration entry”
v “CCXService configuration entry” on page 86
v “GroupName configuration entry” on page 88
v “HostName configuration entry” on page 89
v “NodeName configuration entry” on page 90
v “RecoService configuration entry” on page 95
v “TelephonyService configuration entry” on page 102
v “TTSService configuration entry” on page 105
AppName configuration entry
This keyword defines an application, which is essentially a pointer to the Java
class that provides the main entry point to a voice response service.
This Java class can invoke other classes to do some of the work, but these do
not have to be defined in the configuration. The name of the entry must
83
match the name specified in the NumToApp mapping in the NumToApp
keyword of the “NodeName configuration entry” on page 90.
All applications that you want to run in a node, as opposed to running them
from Rational Application Developer, must be defined in the configuration. If
you are running a Java application, the information specified in the AppName
entry overrides the information specified in the ApplicationProperties. For
more guidance, see “Putting your application into production” on page 71.
Secondary keywords
Enabled
Yes or No. Default is Yes. Optional.
AppClass
The name of the Java class to run the application. You must include
the package name but not the “.class”. Case-sensitive. Mandatory.
# Minimal AppName entry
AppName=pizzas
AppClass=mypackage.pizzas
;
For VoiceXML 2.1 applications, the AppClass is always
com.ibm.wvr.vxml2.DTVoicelet2 as follows:
AppName=defapp
Parameter=URI,http://www.myserver.com/applications/sorry.vxml
;
Note: The previous version of the Java and VoiceXML environment
supported VoiceXML 1.0 applications with an AppClass of
com.ibm.speech.vxml.DTVoicelet, but this is no longer supported.
Configuration files that include these entries will fail to import.
VoiceXML 1.0 applications must be updated to VoiceXML 2.1
Locale This property does not apply to VoiceXML 2.1 applications. The
application locale property allows a Java application to have a default
locale that is different from the default locale of the voice response
node. For example, you might want to run an English version, a
French version, and a Spanish version of an application on the same
voice response node. The application locale for each version
determines the default language and country or region (and
optionally a user-defined variant) of all voice segments and other
media types in the application. Optional.
# Pizza-ordering application in U.S. English
AppName=pizzasEnglish
Locale=en_US
;
84
# Pizza-ordering application in Canadian French
AppName=pizzasFrench
Locale=fr_CA
;
Parameter
A parameter name and value to be passed to the application. The
syntax is parametername,value. All parameter values are treated as
strings. Specify this keyword once for each parameter-value pair.
Optional.
# Application that has two parameters
AppName=banking
AppClass=mypackage.banking
Parameter=branch_id,0123
Parameter=branch_name,Southampton
;
Use the Parameter keyword to specify the URI of a VoiceXML
application as follows:
AppName=defapp
;
Note that an absolute URI containing the protocol (http in the above
example) is mandatory for VoiceXML 2.1. URIs that include numeric
IPv6 format addresses, must have the numeric part within [ ] brackets,
for example:
http://[2002:914:fc12:195:0000:8a2e:0370:7334]/welcome.vxml
If a VoiceXML application is started from a CCXML document, the
CCXML document specifies the VoiceXML document to be processed.
In this case, the Parameter keyword must be used to set the
DynamicURI parameter to yes. For example:
AppName=ccxmldialog1
Parameter=DynamicURI=yes
;
If a VoiceXML 2.1 application does not use speech recognition or
text-to-speech, you must include the DTMFONLY parameter in the
AppName entry, and set it to true. For example:
AppName=defapp
Parameter=DTMFONLY,true
;
85
Use the MAX_WAITERS parameter to restrict the number of instances of
an application that can be waiting for a call at any one time. If you
are running a large number of applications this can increase the
efficiency of your system. This limit only applies if your application
does not have a wait time specified. The limit applies to individual
application nodes. For example to limit an application called 'demo' to
three instances waiting for a call at any one time:
AppName=demo
AppClass=com.abc.demo
Parameter=MAX_WAITERS, 3
;
If there are, for example, 4 instances of the demo application running,
the last instance must wait for one of the first three to leave the
waitForCall state before it can wait for an incoming call.
RecoDefinition
Speech recognition definition (recotype,locale) to override a
RecoDefinition for the same locale in the “NodeName configuration
entry” on page 90. Optional.
TTSDefinition
Text-to-speech definition (TTStype,locale) to override a TTSDefinition
for the same locale in the “NodeName configuration entry” on page
90. Optional.
CCXService configuration entry
This keyword defines a CCXML Service, which manages CCXML browsers.
Within a CCXML Service, all browsers start with the same initial document.
The same CCXML Service can be started on one or more nodes.
To route a call to a CCXML Service, you must set the service name in a
NumToApp keyword of the NodeName configuration entry as described in
“NodeName configuration entry” on page 90.
The CCXService entry must be near the top of the default.cff, before any
reference to the service name.
Secondary keywords
Enabled
InitialURI
The URI specifying the location of the CCXML document that is to be
the initial document processed by the CCXML browser. An absolute
86
URI containing the protocol must be specified. URIs that include
numeric IPv6 format addresses, must have the numeric part within [ ]
brackets, for example:
http://[2002:914:fc12:195:0000:8a2e:0370:7334]/ccxml/testdoc.ccxml
This applies to all protocols. Mandatory.
DefAppService
When SingleCall is set to no, DefAppService indicates the node on
which the CCXML browser running the initial CCXML document is to
be started. (In this mode, all new calls routed to this CCXService are
handled by a single browser session.) If the initial document creates
another CCXML session, it will be created on one of the nodes
running this CCXService.
When SingleCall is set to yes, a new browser session using the
InitialURI is started for each new call. The first of these will be
started on the node indicated by this parameter, but for subsequent
browser sessions, the Java and VoiceXML environment determines
which one of the nodes running this CCXService should start a new
CCXML browser session.
If the DefAppService is not specified, the Java and VoiceXML
environment determines the node on which the CCXML browser
running the initial CCXML document starts.
You can specify a maximum on one DefAppService entry. Optional.
CacheLimit
The size of the CCXML memory cache. You can specify a value in
megabytes or kilobytes by using a suffix of M or K, respectively. Any
value without a suffix is assumed to be in megabytes. The default
value is sixteen megabytes. Optional.
Note: The memory cache stores documents that are referenced by
their URI and their fetch ID (generated during by a <fetch> element).
Consequently the size of the cache is a factor in determining how long
after a <fetch> has completed that the fetchid remains valid and
usable in a <goto> element. Do not set CacheLimit to zero or a small
value in an attempt to prevent caching as this will prevent <goto>
elements from functioning.
SingleCall
This parameter alters the behavior of the CCXML Service. If set to no
(the default), a single browser instance handles each new inbound call
to the service. The browser document must therefore be able to handle
multiple concurrent calls.
87
If set to yes, a separate browser instance handles each new inbound
call to the service. As a new browser is started for each new call, the
CCXML document must exit when it has completed to ensure that
memory is freed and the optimum use is made of memory and other
resources.
CCXService=ccx1
Enabled=yes
InitialURI = file:///calling.hursley.ibm.com/ccxml/testdoc.ccxml
DefAppService=Node1
SingleCall=yes
CacheLimit=8M
;
GroupName configuration entry
A group definition can be added to more than one node in a configuration,
and the node definition can be added to more than one host in a
configuration. This means that you can allow the same groups of applications
or individual applications to run on more than one host, providing
redundancy in your system. Groups are optional, but they are the only way to
get applications started automatically.
A group is a set of applications that you want to start when the node is
started. Typically a group would contain multiple instances of the same
application. This is the way to ensure that there are enough copies of your
application waiting for incoming calls. The GroupName entry must precede
the “NodeName configuration entry” on page 90 for any node that refers to it
(using the Group keyword). You can add related applications to the same
group to ensure that they are all started at once.
Secondary keywords
Enabled
Yes or No. Optional. Default is Yes.
Application
The name of an application. There must be an “AppName
configuration entry” on page 83 for the application, and it must
precede this entry in the file. Specify this keyword once for each
instance of an application to be started. It’s a good idea to start more
instances of the application than there are channels or lines assigned
to it. Mandatory.
# A group that contains four instances of the pizzasEnglish application
# and four instances of the pizzasFrench application
GroupName=group1
Application=pizzasEnglish
88
Application=pizzasFrench
;
HostName configuration entry
A host is a system with a TCP/IP address. There should be one HostName
entry for each host on which you have installed WebSphere Voice Response
Java and VoiceXML Environment.
Every time you install WebSphere Voice Response Java and VoiceXML
Environment on a host, a configuration file is created, including an entry for
HostName=LocalHost. However, when you start adding hosts together to
create a plex, you need to create a HostName entry for each host in one single
configuration file: see “Managing a network of nodes” on page 20. Warning:
Make sure that no applications are running before you change the TCP/IP
address of a host.
Secondary keywords
Enabled
IPName
The IP name of this host. The IP name can be in any form that the
name server can resolve. Mandatory.
Node
The name of a node on this host to start when you start up the host.
There must be a “NodeName configuration entry” on page 90 for the
node, and it must precede this entry in the file. You need one Node
keyword for each node to be started. Mandatory.
AIXPortNumber
The port number to use for an AIX system. This must match the
CHPM Socket Port Number parameter in the Application Server
Interface group of system parameters in the base WebSphere Voice
Response for AIX system configuration. Optional. The default value is
26923.
RMIPortNumber
The port number to use for the RMI registry. Optional. The default
value is 26924. You must also change the rmi.port number in the
dtj.ini file.
# A minimal HostName entry for a host with nodes called Node1 and Test
HostName=legs11
Node=Node1
89
Node=Test
;
# A host that already used ports 26923 and 26924 for something Else
HostName=lucky7
Node=Node1
AIXPortNumber=30000
RMIPortNumber=30001
# Remember to change the rmi.port number in the dtj.ini file!
;
NodeName configuration entry
This keyword defines a node. There must be one NodeName entry for each
node in the system.
The NodeName entry must precede the “HostName configuration entry” on
page 89 for any host that refers to it (using the Node keyword).
Each voice response node definition must include definitions of all the phone
numbers to be associated with applications that wait for incoming calls.
For each voice response node, you can specify a default application, which is
used to handle incoming calls for a number for which there is no application
currently in a waitForCall state, or for which there is no specificNumToApp
entry. Typically, this application would say something like “Sorry, this service
is not available at the moment, please try later” or it could transfer the caller
to an agent. This application does not have to be started, because it is
dynamically started as required. Nevertheless, you might find it useful to start
several instances of it, for performance reasons. The default application must
have an “AppName configuration entry” on page 83.
Secondary keywords for all nodes
CCXAppService
The name of a CCXML service that can be run on this node. There
must be a CCXService entry for the service, preceding this entry in the
file. (See “CCXService configuration entry” on page 86). One or more
CCXAppService entries can be defined for a single node. Optional
Enabled
Group The name of an application group to start when the node is started.
Optional. There must be a “GroupName configuration entry” on page
88 for the group, preceding this entry in the file. You need one Group
keyword for each group to be started.
90
Note: Although you can use application groups with voice response
nodes, this is not recommended.
JavaCommand
The value of this keyword contains the Java invocation command
used to start this node, and overrides the java.command option on the
dtj.ini file on the system where the node is to be started. This
keyword is platform and JVM specific. Any options specified in this
keyword must be acceptable on the machine where the node is to be
started.
NodeClassPath
Applies to Java applications only. One or more class paths, to
concatenate to the beginning of the host's CLASSPATH. For example,
c:\mybeans\mybeans.jar. Optional. You need only set this if you want
to specify different class paths, for example, to use different versions
of a class in different nodes. Make sure you run all the applications
that need the same class path in the same node. This must match the
specification for the CLASSPATH variable on the base operating
system, for example on AIX it must be separated with a colon (:).
VRNode
Specifies whether the node is to be used as a voice response node.
Optional.
The default is No, which means that this node is an application node:
you can specify the “Secondary keywords for application nodes only.”
If you specify Yes, this node is a voice response node: you can specify
the “Secondary keywords for voice response nodes only” on page 92.
Note: This was formerly known as TSNode.
Secondary keywords for application nodes only
The NodeDefHost and NodeDefVRNode keywords allow you to write an
application without having to worry about where the voice response node is.
If an application is started in an application node, it uses the voice response
node specified by NodeDefVRNode and NodeDefHost in the application
node's NodeName entry.
NodeDefHost
The host name of the voice response node specified by
NodeDefVRNode. Mandatory for application nodes, but ignored for
voice response nodes.
NodeDefVRNode
The name of the default voice response node to be used by all
applications running in this node. The host name is specified by
NodeDefHost. Mandatory for application nodes, but ignored for
voice response nodes.
91
Note: This was formerly known as NodeDefTS.
# Application node running a group of applications called CurrentTest
# Using a NodeClassPath because there is a production version of the
NodeName=Test
VRNode=no
NodeDefVRNode=VRNode1
NodeDefHost=legs11
NodeClassPath=/j/test/mybeans.jar
Group=CurrentTest
;
Secondary keywords for voice response nodes only
CCXHTTPServer
With CCXML basichttp event I/O processor that uses HTTP to
transport events between a CCXML implementation and external
components, the CCXHTTPServer keyword switches external
component event processing on (value of yes) or off (value of no). The
default is no. For more information, refer to WebSphere Voice Response
for AIX: Using the CCXML Browser. Optional.
CCXHTTPServerPort
The port number that overrides the default listener port number
(1971) for external component event processing. If you override the
default port number, the port number used must be included in the
URI. Optional.
NodeDefAppName
The name of the default application, to be used to handle incoming
calls for which there is no application currently in a waitForCall state,
or for which there is no NumToApp entry. The application must also
have an “AppName configuration entry” on page 83. Optional.
Note: Where possible, use a non-specific NumToApp entry such as
"NumToApp=*,default" instead of a NodeDefAppName entry.
The default.cff configuration should include enough application
instances based on the expected call volume and the NumToApp
mapping. NodeDefAppName should only be used for failover
applications. It should not be used to start additional application
instances to handle general calls as this can cause the VRNode to run
out of heap space.
NodeDefLocale
The default locale, in the form ll_CC_variant, where ll is the ISO code
for the language, and CC is the ISO code for the country or region;
variation can be any string. Mandatory.
92
The name of the telephony service to be used by this node. There
must be a “TelephonyService configuration entry” on page 102
preceding this entry in the file. If a NodeTelephonyService is defined
and the TelephonyService is available then the voice response node
will use the TelephonyService for certain call control functions (such
as transfer) and call information in preference to the functions and
information provided by the voice response node itself. Optional.
Note: This was formerly known as NodeCallPathService.
NumToApp
The mapping of phone number to application. The format is phone
number and either a CCXML service name or an application name,
separated by a comma (for example "NumToApp=1234,ccx1" or
"NumToApp=1234,menu").
NumToApp can contain wildcards at any position in the number:
?
Replaces exactly one digit. For example 200? would match
2001, 2003 but would not match 200 or 20001.
*
Replaces 0 to any number of digits. 20* would match 2001,
20, 20000000, 2099999999, for example.
Overlapping ranges are not allowed when using wildcard characters.
For example, the following mapping would cause an error to be
reported when the configuration is imported:
NumToApp=200?,app1
NumToApp=20*,app2
You can specify an exact number (without a wildcard) that is within
the range covered by a number including a wildcard, for example:
NumToApp=200?,app1
NumToApp=2000,app2
The exact number takes priority when a call is routed. Consequently,
in the above example, a call received on 2000 would be routed to
app2.There must be one and only one NumToApp keyword for each
phone number for which the voice response node is to answer calls. If
a call arrives for a number for which there is no NumToApp keyword,
the default application is invoked to handle the call. The application
name must match either the CCXService name for a CCXML browser
or the application name in the ApplicationProperties of the application
or the AppName configuration entry for the application. For more
information, see “Mapping CCXML browsers to a phone number” on
page 60 and “Mapping a VoiceXML or Java application to a phone
number” on page 62.
93
RecoDefinition
Defines the speech recognition technology to use, for applications
using the services of this node. Specify a valid locale followed by the
recotype to which it applies. The syntax is
RecoDefinition=locale,recotype. The recotype is the key to the
“RecoService configuration entry” on page 95 (RecoType keyword).
You can specify an asterisk (*) to mean “all languages”. You can
specify multiple RecoDefinitions, with the restriction that each locale
(or *) can be specified only once. These RecoDefinitions can be
overridden by the RecoDefinitions in the “AppName configuration
entry” on page 83 or in the ApplicationProperties. Optional.
#
#
#
#
ViaVoice is defined as the speech recognition technology to use for
all languages, but this example shows how you would specify a
different technology for one language
ViaVoice is used for all other languages.
RecoDefinition=xx_YY,ANother
RecoService
The name of a “RecoService configuration entry” on page 95 as
described on “RecoService configuration entry” on page 95. You need
one of these to define each speech recognition technology available on
the node. Optional.
TelURLLocale
The name of the TelURLLocale of this node. There must be a
TelURLLocale configuration entry for the name preceding this entry in
the file. Optional, but is required if the node is to be used for any
processing that requires the evaluation of a Telephony URL. For
example if the node is to be used to action a VoiceXML 2.1 <transfer>
element.
TTSDefinition
Defines the text-to-speech technology to use for applications using the
services of this node. Specify a valid locale followed by the ttstype to
which it applies. The syntax is TTSDefinition=locale,ttstype. The
ttstype is the key to the “TTSService configuration entry” on page 105
(TTSType keyword). You can specify an asterisk (*) to mean “all
languages”. You can specify multiple TTSDefinitions, with the
restriction that each locale (or *) can be specified only once. These
TTSDefinitions can be overridden by the TTSDefinitions in the
“AppName configuration entry” on page 83 or in the
ApplicationProperties. Optional.
# FirstByte is defined as the text-to-speech technology to use for all
# languages, but this example shows how you would specify a different
# technology for two languages. FirstByte is used for all other
94
# languages.
TTSDefinition=xx_YY,ANother
TTSDefinition=aa_BB,ANother
TTSDefinition=*,FirstByte
TTSService
The name of a “TTSService configuration entry” on page 105, as
described on “TTSService configuration entry” on page 105. You need
one of these to define each text-to-speech technology available on the
node. Optional.
RecoService configuration entry
This entry defines a specific plug-in for speech recognition . There is at least
one RecoService configuration entry for each plug-in, and there is likely to be
one plug-in for each technology on each supported platform.
A RecoService entry must precede any AppName or NodeName entries that
refer to it.
The typical format of a RecoService entry is as follows:
RecoService=identifier
PlugInClass=technology-specific string
InitSessionString=technology-specific string
InitTechnologyString=technology-specific string
RecoType=identifier
;
Secondary keywords
RecoService
Identifies the entry and is activated by the RecoService keyword in
the NodeName entry for any node that wants to use the service. (If
you have the same technology on different platforms, this keyword
distinguishes between them.)
Enabled
The initialization string of the plug-in technology. This is not required
for all technologies. The value of the string is dependent on the
speech technology being used. It is not required for MRCP.
Note: If you have multiple instances of a technology (for example, to
configure engines for multiple languages), you must ensure that all
the InitTechnologyStrings are identical to each other.
InitSessionString
The speech recognition session initialization string, which is not
95
required for all technologies. The value of the string is dependent on
the technology being used, but often includes a URI. URIs that
include numeric IPv6 format addresses, must have the numeric part
For an MRCP configuration the value of InitSessionString should
include the URI of the speech server’s recognition engine. You can
also specify an additional URI for a back-up speech server’s
recognition engine in an MRCP configuration, for example:
RecoService=Reco_GB
PlugInClass=com.ibm.telephony.directtalk.mrcp.MRCPReco
InitSessionString=URI=rtsp://myasrserver.example.com:554/media/recognizer
InitSessionString=URI=rtsp://mybackupasrserver.example.com:554/media/recognizer
RecoType=Recoen_GB
;
The first InitSessionString entry must reference the primary server,
and the second entry must reference the backup server.
To specify speech recognition using dynamic engine allocation, so that
speech recognition engines are not assigned for the duration of call,
but instead are allocated only for the duration of each period of
speech recognition, append ,keepsessionforcall=no to the end of the
InitSessionString URI value. The default setting is
keepsessionforcall=yes. Refer to the section “Allocating speech
recognition and TTS engines” in WebSphere Voice Response for AIX:
General Information and Planning for more information. The vendor of
your speech product may not support the use of dynamic engine
allocation.
PlugInClass
Mandatory. The fully-qualified name of the plug-in Java class for the
speech technology being used. For an MRCP configuration the
PlugInClass is com.ibm.telephony.directtalk.mrcp.MRCPReco
RecoType
Mandatory. Identifies the RecoService entry in the following contexts:
v The Reco Definition specification in the application properties of the
application (for applications run from the Java command or from a
visual builder).
v The RecoDefinition keyword in the AppName entry (if different
applications running in the node require different engines or
context profiles).
96
v The RecoDefinition keyword in the NodeName entry (if all
applications running in the node require the same engine and
context profile).
The RecoType keyword is a platform-independent label for the
RecoService entry. RecoService entries for the same technology on
different platforms must therefore share the same RecoType.
Examples of RecoService entries
The examples below show how to configure RecoService entries for use with:
v WebSphere Voice Server Version 5.1. Note that there are differences when
using WebSphere Voice Server Version 5.1.1 or 5.1.2 compared to
WebSphere Voice Server Version 5.1.3. This is because WebSphere Voice
Server Version 5.1.3 supports the use of multiple recognition languages on a
single machine. The examples also show that the InitTechnologyString
keyword is not required when using any of these versions of WebSphere
Voice Server speech technology.
v Nuance Recognizer V9.0.3
Configuring for use with WebSphere Voice Server Version
5.1.1 or 5.1.2
In this example, two WebSphere Voice Server languages are needed: US
English and Latin American Spanish. US English is installed on the
WebSphere Voice Server machine with host name wvsenglish.demo.ibm.com.
Latin American Spanish is installed on the WebSphere Voice Server machine
with host name wvslaspanish.demo.ibm.com. The RecoService entry in the
default.cff file would include the following values:
RecoService=WVS_Recoen_US
PluginClass=com.ibm.telephony.directtalk.mrcp.MRCPReco
InitSessionString=URI=rtsp://wvsenglish.demo.ibm.com/media/recognizer
RecoType=Recoen_US
;
RecoService=WVS_Recoes_MX
InitSessionString=URI=rtsp://wvslaspanish.demo.ibm.com/media/recognizer
RecoType=Recoes_MX
;
On a WebSphere Voice Response machine with more than one ethernet
adapter you also need to define the local IP address to be used for the media
streaming by specifying a MediaIPAddress value for the InitSessionString
parameter:
InitSessionString=URI=rtsp://wvsenglish.demo.ibm.com/media/recognizer, MediaIPAddress=9.20.123.456
RecoType=Recoen_US
;
97
InitSessionString=URI=rtsp://wvslaspanish.demo.ibm.com/media/recognizer, MediaIPAddress=9.20.123.456
RecoType=Recoes_MX
;
In each case, this speech recognition configuration would be reflected in the
NodeName configuration entry as follows:
NodeName=VRNode1
Enabled=yes
NodeDefLocale=en_US
VRNode=yes
RecoDefinition=en_US,Recoen_US
RecoDefinition=es_MX,Recoes_MX
;
5.1.3
WebSphere Voice Server Version 5.1.3 allows a single machine to support
multiple speech recognition languages. This means that default.cff needs to
contain only a single reference to a WebSphere Voice Server machine for each
speech recognition resource type.
In this example, a machine with host name wvs.demo.ibm.com has installed
US English and Latin American Spanish. The RecoService entry in the
RecoService=RecoAll
InitSessionString=URI=rtsp://wvs.demo.ibm.com/media/recognizer
RecoType=Recolan_All
;
parameter:
RecoService=RecoAll
InitSessionString=URI=rtsp://wvs.demo.ibm.com/media/recognizer, MediaIPAddress=9.20.123.456
RecoType=Recolan_All
;
In each case, this speech recognition configuration would be reflected in the
NodeName=VRNode1
Enabled=yes
NodeDefLocale=en_US
98
VRNode=yes
RecoService=RecoAll
RecoDefinition=*,Recolan_All
;
Using load-balancing with WebSphere Voice Server
For larger deployments handling more than one trunk of calls, it may be
necessary to use more than one speech server to process text-to-speech and
speech recognition requests. To do this a load-balancing application such as
WebSphere Edge Server is used to distribute text-to-speech and speech
recognition requests to two or more speech servers. All text-to-speech and
speech recognition initialization requests are sent to a load-balancing address.
The load balancer receives these requests and forwards them to one of a
cluster of speech servers. For more information, refer to the WebSphere Voice
Server information center topic “Multiple machine topology”.
Note: WebSphere Edge Server V5.1 is bundled with WebSphere Voice Server
V5.1.3.
For instructions on installing WebSphere Edge Server, refer to the WebSphere
Voice Server information center topic “Installing the WebSphere Edge
Component: Load Balancer”.
Configuring for use with Nuance Recognizer V9.0.3
WebSphere Voice Response uses MRCP V1.0 to connect to voice servers.
Nuance Speech Server V5 provides an MRCP V1.0 interface to text-to-speech
and speech recognition components. The default RTSP port number to use to
connect to the Nuance Speech Server must match the Nuance Server
configuration. By default this value is 4900.
An example of the VRBE RecoService entry configuration settings required for
speech recognition in configuration file /var/dirTalk/DTBE/native/aix/
default.cff are shown below:
RecoService=Reco_GB
InitSessionString=URI=rtsp://1.23.45.678:4900/media/speechrecognizer
RecoType=Recoen_GB
;
Using load-balancing with Nuance Recognizer V9.0.3
99
cluster of speech servers. To use Nuance speech servers in this way, a number
of changes to WebSphere Voice Response and Nuance configuration need to
be made.
An example of the Java and VoiceXML environment RecoService entry
configuration settings required for speech recognition in configuration file
default.cff when using a load-balanced systems are shown below:
RecoService=Reco_GB
InitSessionString=URI=rtsp://1.23.45.678:554/media/speechrecognizer
RecoType=Recoen_GB
;
With load-balanced systems, port 554 is used instead of 4900. The changes
required to the Nuance configuration file NSSserver.cfg are:
Variable
Value
server.transport.bindrtptoip
The IP address of the speech server
server.rtp.strictSdpMediaPortUse
0
server.mrcp1.transport.port
554
Speech recognition requests are forwarded to one of a number of Nuance
voice servers using the same port number (554). When a speech recognition
session has been set up on a Nuance voice server and WebSphere Voice
Response has received a response, speech recognition traffic passes to and fro
directly (not through the load balancer machine).
Configuring for use with Loquendo ASR V7.9
Loquendo 7 provides an MRCP V1.0 interface to text-to-speech and speech
recognition components. The default RTSP port number to use to connect to
the Loquendo Speech Server must match the Loquendo Server configuration.
By default this value is 554.
An example of the VRBE RecoService entry configuration settings required for
speech recognition in configuration file /var/dirTalk/DTBE/native/aix/
default.cff are shown below:
RecoService=Reco_GB
InitSessionString=URI=rtsp://1.23.45.678:554/recognizer
RecoType=Recoen_GB
;
100
In the Loquendo Management Console, the following two configuration
settings need to be set:
Configuration > Advanced > MRCPv1Server > nlsmlResult >
enableWordInputElements:
disabled
Configuration > Advanced > MRCPv1Server > speechRecognition >
lasrDefaultTagFormat:
SISR-semantics (2)
To use remote DTMF grammars, the following two configuration settings also
need to be set:
Configuration > Basic > MRCPv1Server > dtmfCodec:
101
Configuration > Basic > MRCPv1Server > dtmfCodecAlwaysOffered:
enabled (1)
After changing configuration settings, it may be necessary to restart
Loquendo.
Related information
For general information about the role of the RecoService entry, see “How is
the RecoService configuration entry used?” on page 41.
TelURLLocale configuration entry
This keyword provides information used by a voice response node to
determine its telephony URL location so that it can dial calls correctly. It must
be defined if Telephone URIs are used in VoiceXML or CCXML applications.
Secondary keywords
GlobalContext
The global prefix of a location. For example, a node situated in New
Mexico in the USA could have GlobalContext=+1505, or a node
situated in Winchester in the UK could have GlobalContext=+441962.
Note the use of the "+", which indicates that the number is an
international number starting with the country code of the location.
LocalContext
A local prefix of a location. For example a node situated in New
Mexico in the USA could have LocalContext=505, or a node situated
in Winchester in the UK could have LocalContext=1962. Note that the
LocalContext is not an absolute definition of a location, it is relative to
101
an assumed and undefined sub-area of a network. For example
LocalContext=505 defines a location in any sub-area of a network
where a local access code can be followed by a string of digits starting
with 505 in order to reach the node.
InternationalAccess
The digits that need to be dialed from the node in order to make an
international telephone call. For example for a Voice Response node
that is connected directly to the public telephone network you might
have InternationalAccess=011 for a node in the USA, or
InternationalAccess=00 for a node in the UK.
For more information, see also Appendix F, “Configuring telephone URI
verification for WebSphere Voice Response,” on page 181.
TelephonyService configuration entry
This keyword provides information used by a voice response node to access a
Telephony service, to which a voice response node can optionally pass
requests for call control functions such as call transfer.
Note: This was formerly known as a CallPathService entry.
Secondary keywords
AAIKeys
For Genesys I-Server, this is user call data used by Genesys in the
form of a string array of key value pairs, for example:
Name=Agent:Customer:Bank
The key value pairs are arbitrary, and it is the responsibility of
developers to extract and handle information contained in the fields.
The values are supplied by the Genesys I-Server at the start of a call
within:
v VoiceXML session variable session.connection.aai
v CCXML connection class aai field during connection.alerting and
connection.connected transitions.
The AAIKeys information is changed when the VXML <transfer> tag
updates call data. The information used to update the user date is
held in the aai attribute of the tag. Mandatory
Example showing getting the AAI call data from CCXML:
<transition event="connection.alerting" name="evt">
<log expr="’[connection.alerting] connectionid = ’+ evt.connectionid "/>
<log expr="’[connection.alerting] aai = ’+ evt.connection.aai "/>
<accept connectionid="evt.connectionid"/>
</transition>
102
An example of setting using a CCXML dialog.transfer request
(Generated from VXML):
<transition event="dialog.transfer" name="evt">
<var name="purpose" expr="’transfer’"/>
<var name="wait_for_answer" expr="true"/>
<var name="target" expr="evt.URI"/>
<var name="aai" expr="evt.aai"/>
<send target="evt.connectionid" targettype="’connection’"
name="’ibmwvr.consult’" namelist="purpose wait_for_answer target aai"/>
</transition>
Example showing how to get the AAI call data from VoiceXML:
<log> aai : <value expr="session.connection.aai"/></log>
Example showing how to set the AAIKeys in VoiceXML for a Transfer
from VXML:
<transfer dest="tel:21199;phone-context=1962"
aai="Name=J Doe:Bank=National" bridge="true"/>
AAIKVPSeparator
Defines the separator character to be used in AAIkeys key value pairs.
(See “AAIkeys”, above.) Valid separator characters are:
: ; , . | ! ^ * + - ~ #
The default value is a colon (:).
The separator character defined by AAIKVPSeparator is overridden
by any optional AAI separator character specified using the <object>
element to access the advanced Genesys API function RouteRequest.
(Refer to the section “Using advanced CTI features” in WebSphere Voice
Response for AIX: VoiceXML Programmer's Guide.)
CalledNumberType
For Genesys I-Server, this is an optional parameter that specifies the
source of the number presented as the called number. The valid
options are CalledNumber or Address. The default is CalledNumber.
CalledNumber uses the called number as presented by the call (from
signaling, or configured channel phone number). This is the ideal
option to use in a TDM-based environment as every channel has a
unique called number.
Address uses a calculated number based on the incoming trunk and
channel. This is the ideal option to use in a VoIP/SIP-based
environment as the real called number is often the same across calls,
and is thus unsuitable for Genesys I-Server. The Address number is
calculated using the formula trunk * 30 + channel, where both trunk
and channel are 1-based numbers. For example, a call arriving at
103
trunk 1, channel 1 presents the called number as 31 to Genesys
I-Server. A call arriving at trunk 7, channel 18 presents the called
number as 228 to Genesys I-Server.
Enabled
InitialAddresses
Allows the IVR port numbers to be recorded within file default.cff
rather than when the first call arrives on a given channel, which can
delay the registering of local/remote values (ANI/DNIS) when using
CCXML. To pre define the IVR ports, add the InitialAddresses line to
the existing TelephonyService definition for the Tserver. Addresses
can be listed individually and delimited by a semicolon (;) or ranges
can be defined by the use of a hyphen (-) as shown is following
example:
TelephonyService=Tserver
Enabled=yes
ServerName=TSERVER:3009@lvl3cti
InitialAddresses=20801-20803;20804
;
Optional
Password
For Genesys CallPath, this is the password defined in the CallPath
Enterprise Server JTAPI configuration. Optional.
For Genesys T-Server, this is required when you are using a
multi-tennant T-Server environment. Enter the tennant name and
tennant password separated by a slash (/). For example:
Password=somename/somepassword
ServerName
For Genesys CallPath this is the port number and IP address of the
CallPath Enterprise Server. For example:
7600@blackbird
Mandatory.
For Genesys T-Server this is the port number and IP address of the
T-Server, preceded by 'TSERVER:'. For example:
TSERVER:7600@blackbird
Mandatory.
For Genesys I-Server this is the port number and IP address of the
I-Server, preceded by 'ISERVER:'. For example:
104
ISERVER:7600@blackbird
Mandatory.
UserName
For Genesys CallPath, this is the user name defined in the CallPath
Enterprise Server JTAPI configuration. Optional.
For Genesys T-Server, this is an arbitrary name that T-Server will use
to represent the voice response node. Optional.
Related information
v “Telephony functionality” in the WebSphere Voice Response: VoiceXML
Programmer's Guide for WebSphere Voice Response manual.
v “Integrating WebSphere Voice Response with Genesys Framework” in the
WebSphere Voice Response: General Information and Planning manual.
v Adding telephony capability in this manual.
v “Using advanced CTI features” in the WebSphere Voice Response:
VoiceXML Programmer's Guide for WebSphere Voice Response manual.
TTSService configuration entry
This entry defines a specific text-to-speech plug-in. There is at least one
TTSService configuration entry for each plug-in, and there is likely to be one
plug-in for each technology on each supported platform.
A TTSService entry must precede any AppName or NodeName entries that
refer to it.
The typical format of a TTSService entry is as follows:
The TTSType keyword is also used to identify the entry, as described in the
following section.
TTSService=Identifier
PlugInClass=technology-specific string
InitSessionString=technology-specific string
InitTechnologyString=technology-specific string
TTSType=Identifier
;
Secondary keywords
TTSService
Identifies the entry, and is activated by the TTSService keyword in the
NodeName entry for any node that wants to use the service. (If you
have the same technology on different platforms, this keyword
distinguishes between them.)
105
Enabled
The initialization string of the plug-in technology. This is not required
for some speech technologies. The value of the string is entirely
dependent on the technology being used. It is not required for MRCP.
InitSessionString
The text-to-speech session initialization string, which is not required
for some speech technologies. The value of the string is entirely
dependent on the technology being used, but often includes a URI.
URIs that include numeric IPv6 format addresses, must have the
numeric part within [ ] brackets, for example:
rtsp://[2002:914:fc12:195:0000:8a2e:0370:7334]/media/speechsynthesizer
For an MRCP configuration the value of InitSessionString should
include the URI of the speech server's text-to-speech engine. You can
also specify an additional URI for a back-up speech server's
text-to-speech engine in an MRCP configuration, for example:
TTSService=Tts_GB
PlugInClass=com.ibm.telephony.directtalk.mrcp.MRCPTTS
InitSessionString=URI=rtsp://myasrserver.example.com:554/media/speechsynthesizer
InitSessionString=URI=rtsp://mybackupasrserver.example.com:554/media/speechsynthesizer
TTSType=Ttsen_GB
;
The first InitSessionString entry must be the primary server, and the
second entry must be the backup server.
To specify text-to-speech using dynamic engine allocation, so that TTS
engines are not assigned for the duration of call, but instead are
allocated only for the duration of each period of text-to-speech,
append ,keepsessionforcall=no to the end of the InitSessionString
URI value. The default setting is keepsessionforcall=yes. Refer to the
section “Allocating speech recognition and TTS engines” in WebSphere
Voice Response for AIX: General Information and Planning for more
information. The vendor of your speech product may not support the
use of dynamic engine allocation.
PlugInClass
Mandatory. The fully-qualified name of the plug-in Java class for the
technology being used. For an MRCP configuration the PlugInClass is
com.ibm.telephony.directtalk.mrcp.MRCPTTS
TTSType
Mandatory. The TTSType keyword identifies the TTSService entry in
the following:
106
v The TTS Definition specification in the application properties of the
application (for applications run from the Java command or from a
visual builder)
v The TTSDefinition keyword in the AppName entry (if different
applications running in the node require different engines or
context profiles)
v The TTSDefinition keyword in the NodeName entry (if all
applications running in the node require the same engine and
context profile).
(The TTSType keyword is a platform-independent label for the
TTSService entry. TTSService entries for the same technology on
different platforms must therefore share the same TTSType.)
Examples of TTSService entries
The examples below show how to configure TTSService entries for use with:
v WebSphere Voice Server Version 5.1. Note that there are differences when
using WebSphere Voice Server Version 5.1.1 or 5.1.2 compared to
WebSphere Voice Server Version 5.1.3. This is because WebSphere Voice
Server Version 5.1.3 supports the use of multiple synthesis languages on a
single machine. The examples also show that the InitTechnologyString
keyword is not required when using any of these versions of WebSphere
Voice Server speech technology.
v Nuance Vocalizer V5.1
5.1.1 or 5.1.2
In this example, two WebSphere Voice Server languages are needed for
text-to-speech: US English and Latin American Spanish. US English is
installed on the WebSphere Voice Server machine with host name
wvsenglish.demo.ibm.com. Latin American Spanish is installed on the WebSphere
Voice Server machine with host name wvslaspanish.demo.ibm.com. The
TTSService entry in the default.cff file would include the following values:
TTSService=WVS_TTSen_US
PluginClass=com.ibm.telephony.directtalk.mrcp.MRCPTTS
InitSessionString=URI=rtsp://wvsenglish.demo.ibm.com/media/synthesizer
TTSType=TTSen_US
;
TTSService=WVS_TTSes_MX
InitSessionString=URI=rtsp://wvslaspanish.demo.ibm.com/media/synthesizer
TTSType=TTSes_MX
;
107
parameter:
InitSessionString=URI=rtsp://wvsenglish.demo.ibm.com/media/synthesizer, MediaIPAddress=9.20.123.456
TTSType=TTSen_US
;
InitSessionString=URI=rtsp://wvslaspanish.demo.ibm.com/media/synthesizer, MediaIPAddress=9.20.123.456
TTSType=TTSes_MX
;
In each case, this text-to-speech configuration would be reflected in the
NodeName=VRNode1
Enabled=yes
NodeDefLocale=en_US
VRNode=yes
TTSDefinition=en_US,TTSen_US
TTSDefinition=es_MX,TTSes_MX
;
5.1.3
WebSphere Voice Server Version 5.1.3 allows a single machine to support
multiple text-to-speech languages. This means that default.cff needs to
contain only a single reference to a WebSphere Voice Server machine for each
text-to-speech resource type.
In this example, a machine with host name wvs.demo.ibm.com has installed
US English and Latin American Spanish. The TTSService entry in the
TTSService=TtsAll
InitSessionString=URI=rtsp://wvs.demo.ibm.com/media/synthesizer
TTSType=Ttslan_All
;
This text-to-speech configuration would be reflected in the NodeName
configuration entry as follows:
NodeName=VRNode1
Enabled=yes
NodeDefLocale=en_US
108
VRNode=yes
TTSService=TtsAll
TTSDefinition=*,Ttslan_All
;
Using load-balancing with WebSphere Voice Server
cluster of speech servers. For more information, refer to the WebSphere Voice
Server information center topic “Multiple machine topology”.
Note: WebSphere Edge Server V5.1 is bundled with WebSphere Voice Server
V5.1.3.
For instructions on installing WebSphere Edge Server, refer to the WebSphere
Voice Server information center topic “Installing the WebSphere Edge
Component: Load Balancer”.
Configuring for use with Nuance Vocalizer V5.1
Nuance Speech Server V5 provides an MRCP V1.0 interface to text-to-speech
and speech recognition components.
To configure WebSphere Voice Response to connect to a Nuance Speech
Server, the default RTSP port number used must match that used for the
Nuance Server configuration. By default this value is 4900. An example of the
VRBE TTSService entry configuration settings required for text-to-speech in
configuration file /var/dirTalk/DTBE/native/aix/default.cff are shown
below:
TTSService=Tts_GB
InitSessionString=URI=rtsp://1.23.45.678:4900/media/speechsynthesizer
TTSType=Ttsen_GB
;
To use dynamic engine allocation for text-to-speech, append
,keepsessionforcall=no to the end of the InitSessionString URI value, as
shown in the following example:
109
TTSService=Tts_GB
InitSessionString=URI=rtsp://1.23.45.678:4900/media/speechsynthesizer,keepsessionforcall=no
TTSType=Ttsen_GB
;
Using load-balancing with Nuance Vocalizer V5.1
cluster of speech servers. To use Nuance speech servers in this way, a number
of changes to WebSphere Voice Response and Nuance configuration need to
be made.
An example of the Java and VoiceXML environment TTSService entry
configuration settings required for text-to-speech in configuration file
default.cff when using a load-balanced systems are shown below:
TTSService=Tts_GB
InitSessionString=URI=rtsp://1.23.45.678:554/media/speechsynthesizer
TTSType=Ttsen_GB
;
With load-balanced systems, port 554 is used instead of 4900. The changes
required to the Nuance configuration file NSSserver.cfg are:
Variable
Value
server.transport.bindrtptoip
The IP address of the speech server
server.rtp.strictSdpMediaPortUse
0
server.mrcp1.transport.port
554
Text-to-speech requests are forwarded to one of a number of Nuance voice
servers using the same port number (554). When a text-to-speech session has
been set up on a Nuance voice server and WebSphere Voice Response has
received a response, text-to-speech traffic passes to and fro directly (not
through the load balancer machine).
110
Configuring for use with Loquendo TTS V7.20
Loquendo Speech Server V5.1.2 provides an MRCP V1.0 interface to
text-to-speech and speech recognition components.
To configure WebSphere Voice Response to connect to a Loquendo Speech
Server, the default RTSP port number used must match that used for the
Loquendo Server configuration. By default this value is 554. An example of
the VRBE TTSService entry configuration settings required for text-to-speech
in configuration file /var/dirTalk/DTBE/native/aix/default.cff are shown
below:
TTSService=Tts_GB
InitSessionString=URI=rtsp://1.23.45.678:554/synthesizer
TTSType=Ttsen_GB
;
In the Loquendo Management Console, the following two configuration
settings need to be set:
Configuration > Advanced > MRCPv1Server > nlsmlResult >
enableWordInputElements:
disabled
Configuration > Advanced > MRCPv1Server > speechRecognition >
lasrDefaultTagFormat:
SISR-semantics (2)
After changing, it may be necessary to restart Loquendo.
Related information
For general information about the role of the TTSService entry, see “How is
the TTSService configuration entry used?” on page 48.
111
112
Appendix B. Voice segments for Java applications
How to get voice data into Java applications and manage voice segments for
them.
This section applies to Java applications only. It contains the following
information:
v “How to get voice data into Java applications”
v “Managing your voice segments” on page 118
How to get voice data into Java applications
Voice segments are the prerecorded sounds that callers hear when they listen
to a voice application. A voice segment has a category and a name, these
together with the locale uniquely identify the voice segment stored on the
telephony server.
This section contains the following information:
v “How voice segments are stored and identified.”
v “Making voice segments available to Java applications” on page 116.
v “What happens when you install a language?” on page 117.
How voice segments are stored and identified
Voice segments are stored in the voice segment database of the base
WebSphere Voice Response system on the voice response node.
113
Host System
Voice response node
Java
Java
Java
application
application
application
Java and VoiceXML
Environment
WebSphere Voice
Response system
Voice
segment
database
Figure 17. Voice segment database
However, any voice segments that are required by Java voice applications
must be located in a special Java voice segment space within the voice segment
database, as shown in Figure 18. Utility commands are provided for adding
your voice segments to this space.
Voice segments
available to Java
applications
Java voice
segment space
Voice
segment
Voice segment database
database
Base WebSphere Voice
Response system
Figure 18. Voice segments in the Java voice segment space
This space is divided into locales, which are, in turn, divided into categories.
Figure 19 on page 115 shows an example where there are three locales,
English (en), U.K. English (en_GB), and German (de_DE). There is a Menu
and a System category in both U.K. English and German, and a Tutorials
114
category in English.
Figure 19. The Java voice segment space is divided into locales, which are divided into categories
Note: If a voice segment for a specific country or region is not found, the
search continues among voice segments for the language. So, the "en" voice
segments can be used by an application whose locale is either en_GB or
en_US, or any other locale whose language component is "en".
AIX single system image
With AIX single system image (SSI), you do not need to install WebSphere
Voice Response Java and VoiceXML Environment on the SSI server but you
must install it on the clients, as shown in Figure 20 on page 116.
115
Host System
Voice
segment
database
WebSphere Voice
Response system
Host System
Single System Image
(SSI) Server
Host System
Voice response node
Voice response node
Java
Java
Java
application
application
application
Java
Java
Java
application
application
application
Java and VoiceXML
Environment
Java and VoiceXML
Environment
WebSphere Voice
Response system
WebSphere Voice
Response system
Single System Image (SSI) Client
Single System Image (SSI) Client
Figure 20. AIX single system image
On SSI all the voice files are shared, so the segments installed on each client
node must be the same. For example, if you had a voice segment called
'Hello', it must the same voice segment, with the same name, on each client.
Making voice segments available to Java applications
When you run the Java and VoiceXML environment for the first time, System
and Menu segments for en_US are imported automatically. To import
segments for other languages, see the Installation book. You can also make
voice segments available to your Java voice applications in any of the
following ways (as shown in Figure 21 on page 117):
1. Record new voice segments in a studio or using a sound recorder utility,
and import them from your file system, either singly or “in batch”. See
“Importing voice segments from the file system” on page 124.
2. Use voice segments that are already on your base WebSphere Voice
Response system, and add them to the Java voice segment space. See
“Adding voice segments from the base WebSphere Voice Response
system” on page 127.
116
3. Use the Call.record() method to record new voice segments in a Java voice
application. refer to the Developing Java applications book for more
information.
4. Transfer them from the database on one voice response node to the
database on another voice response node by exporting and then importing
them. See “Copying voice segments from one voice response node to
another” on page 134.
5. Use the WVR.importVoiceSegment() and WVR.exportVoiceSegment()
methods to import and export voice segments from a file or audio stream.
See Developing Java applicationsfor more information.
Note: These voice segments are used by Java applications only, not by
VoiceXML applications.
1. Record new voice
segments in a studio
or using a sound
recorder utility, and
import them "in batch"
2. Use voice segments
from your base
Voice Response system
dtjplex
-action addVS
3. Use the Call.record()
method to record new
voice segments in a
Java application.
Record
File
system
dtjplex -action
exportVoiceHost
dtjplex -action
importVoiceHost
Java voice
segment space
Voice
segment
Voice
database
segment
database
File
system
4. Transfer from
one voice response
node to another
5. Use the WVR.import Voice Segment() and WVR.export Voice Segment() methods in a
Java application to import and export voice segments from or to a file or audio stream
Figure 21. Alternative ways of making voice segments available to your applications
What happens when you install a language?
Whenever you install a language in the Java environment, new voice
segments are imported from the language zip file. All these voice segments
are located in the System and Menu categories. You do not need to install a
language to run VoiceXML applications in that language.
117
What if you have already recorded voice segments on the base
WebSphere Voice Response system?
On AIX, for U.S. English (en_US) and U.K. English (en_GB), you can use the
System voice segments on your base WebSphere Voice Response system
instead of the new voice segments. This is an option you can select when you
install the language.
For all other languages on AIX, you cannot use existing System voice
segments, because the voice segment names used by the Java language
mappers are different from those used by WebSphere Voice Response for AIX .
You must either use the supplied ones, or record new System voice segments.
Managing your voice segments
“How to get voice data into Java applications” on page 113 introduced the
voice segment database. This section tells you how to manage voice segments
for Java voice applications (this information does not apply to VoiceXML
applications) :
v “Using dtjplex”
v “Listing available voice segments” on page 121
v “Exporting voice segments to the file system” on page 122
v “Importing voice segments from the file system” on page 124
v “Adding voice segments from the base WebSphere Voice Response system”
on page 127
v “Replacing a voice segment from the WebSphere Voice Response base
system” on page 130
v “Replacing a voice segment with a new version on your file system” on
page 130
v “Deleting voice segments” on page 130
v “Copying voice segments” on page 131
v “Moving or renaming voice segments” on page 133
v “Copying voice segments from one voice response node to another” on
page 134
Using dtjplex
Use the dtjplex script, command, or batch file to make voice segments
available to voice applications. To use dtjplex, the HostManager must be
running and, for many of the actions, the voice response node and base
WebSphere Voice Response system must also be running. The actions take
effect immediately.
This is a summary of the dtjplex actions:
v dtjplex -action importVoiceHost -controlfile filename
118
v dtjplex -action addVS -controlfile filename
v dtjplex -action exportVoiceHost -controlfile filename
You can also list available voice segments
v dtjplex -action listVS -voicesegmentfile filename
Copy or rename them
v dtjplex -action copyVS -controlfile filename
And delete them
v dtjplex -action deleteVS -controlfile filename
Full reference information is given in “dtjplex script” on page 147.
dtjplex control file
To use many of the dtjplex actions (addVS, copyVS, deleteVS,
exportVoiceHost, importVoiceHost, importVoiceAll), you also need a dtjplex
control file to specify the names and other relevant attributes of the voice
segments you want to operate on. Specify the control file using the
-controlfile parameter. For example, dtjplex -action addVS -controlfile
pizzavsegs.txt.
The name of the control file:
You can specify the name of the control file using the -controlfile parameter
in the dtjplex command. The default name depends on the action:
v For addVS, copyVS, and deleteVS, it is control.cfv
v For exportVoiceHost, importVoiceHost, and importVoiceAll, it is
impexp.cfv
Syntax:
The control file contains one or more entries each of which is ended by a line
containing only a semicolon (;). The action is performed for each entry.
Each entry contains one or more lines. If the first nonblank character on a line
is a pound or hash symbol (#), the remainder of the line is ignored (treated as
a comment). Otherwise, the line must contain one, and only one,
“parameter=value” pair. The parameters are not case sensitive but the values
are. The parameters and their values are listed in detail in “dtjplex script” on
page 147 and the sections that follow it.
119
For each entry, parameter values are gathered from top to bottom and then
the action is performed: if you do not specify a mandatory parameter in an
entry, the value last specified for it in a previous entry is used.
To unset a parameter value, set it to null (“parameter=”): in this case, the
default value is used.
Voice segments with names that use national characters:
You can use the character_encoding keyword in the control file to specify the
encoding of the content of control file: see individual action information in
“dtjplex script” on page 147.
The dtjplex command displays messages which you should check need to be
sure you have operated on the correct voice segments. If you are using
national characters (8-bit ASCII or DBCS encoding), the messages may display
the “wrong” characters. If you are worried that, for example, you have not
added the correct voice segments to the Java voice segment space, use the
dtjplex listVS command to list the voice segments.
You can use the -encoding parameter to specify the character encoding used
by the listvs action to list the voice segments.
Syntax errors in the control file:
If there is a syntax error in the control file an error message is displayed and
processing stops. Entries in the control file are processed up to the syntax
error, but no further entries are processed. If the action fails on the target host
for an entry, an error message is displayed, and processing continues to the
next entry in the control file.
Example
Figure 22 on page 121 shows a dtjplex control file that could be used to add
three voice segments from the Pizzas voice segment directory to the Pizzas
category in the Java voice segment space. After this, three voice segments are
added from the Sandwiches voice segment directory to the Sandwiches
category. The purpose of this example is to show how parameter values are
used repeatedly until a new value is specified.
120
# Example of control file for adding base voice segments
# from two voice directories and two languages
# to the Java voice
segment space
#
# Set overall parameter values for Italian Pizza voice segments:
base_voice_directory=Pizzas
segment_category=Pizzasbase_language_identifier=10
base_language_compression=uncompressed
segment_locale=it_IT
# Set parameter values for individual segments:
base_segment_identifier=1
segment_name=1;base_segment_identifier=2
segment_name=2;base_segment_identifier=3
segment_name=3;
# Set overall parameter values for American Sandwich voice segments:
base_voice_directory=Sandwiches
segment_category=Sandwiches
base_language_identifier=1
segment_locale=en_US# Set parameter values for individual segments:
base_segment_identifier=1segment_name=1;
base_segment_identifier=2segment_name=2;
Figure 22. Example of control file for AIX
Listing available voice segments
To list all the voice segments available to Java applications on a specific host,
use the following command:
dtjplex -action listVS [-host name] [-VoiceSegmentFile filename] -replace
The output is in the format used for input to the other dtjplex actions.
Examples
To list all voice segments on the local host to a file called vseglist.txt,
replacing the file if it already exists:
dtjplex -action listVS -VoiceSegmentFile vseglist.txt -replace
To list all voice segments on a specified host to a file called vseglist.txt,
replacing the file if it already exists:
dtjplex -action listVS -host annapurna -VoiceSegmentFile vseglist.txt -replace
To list all voice segments on the local host to a specified file, but do not
replace the file if it already exists:
dtjplex -action listVS -host annapurna -VoiceSegmentFile vseglist.txt
To list all voice segments on the local host to a specified file, but do not
replace the file if it already exists:
121
dtjplex -action listVS -VoiceSegmentFile vseglist.txt
Related information
For information about the parameter values, see “dtjplex listVS action” on
page 161.
Exporting voice segments to the file system
To move voice segments to another host, you must export them from the Java
voice segment space to your file system. You can then import them into
another host: see “Importing voice segments from the file system” on page
124.
dtjplex -action
exportVoiceHost
File
system
dtjplex -action
importVoiceHost
To
another
host
export_type=as_is
or
export_type=interchange
Java voice
segment space
Voice
Voice
segment
Voice
segment
database
segment
database
database
Response system
dtjplex -action
exportVoiceHost
File
system
To a sound
editing program,
for example
export_type=raw
Figure 23. Exporting voice segments from the Java voice segment space
Create a dtjplex control file, as shown in Figure 24 on page 123 or Figure 25
on page 123, change to the directory containing the files to be exported
(because the file names in the dtjplex control file are relative to the current
directory), and then execute the following command:
dtjplex -action exportVoiceHost -controlfile filename
Use the export_type parameter in the dtjplex control file, to specify the
format in which the data is to be exported. The value you choose depends on
what you intend to do with the data.
v If you want to import the voice segments into a voice response node system
on the same operating system and with the same voice encoding
configuration (E1 or T1), specify as_is.
v If you want to import the voice segments into any voice response node,
specify interchange.
v If you want to open the voice segments in a utility, such as a sound editing
program, specify raw. If you specify raw, you also need to set the
122
file_encoding parameter to ulaw, alaw, adpcm, gsm, wav or au. If
file_encoding is ulaw, alaw or adpcm, you need to specify a file_rate of
either 6000 or 8000.
It is a good idea to use a file extension that identifies the export type.
Knowing the export type is useful when importing the files again. For
reference information, see “dtjplex exportVoiceHost action” on page 152.
Examples
# Set overall parameter values:
# Source:
export_type=as_is
segment_category=Pizzas
segment_locale=en_US
# Destination: no parameters needed
file_name=hello.asi
segment_name=hello
;
file_name=goodbye.asi
segment_name=goodbye
;
file_name=help.asi
segment_name=help
;
Figure 24. Example of control file for exporting voice segments to another voice response node on the same operating
system
# Source:
export_type=interchange
# Destination:
file_name=hello.int
segment_name=hello
;
file_name=goodbye.int
;
file_name=help.int
segment_name=help
;
Figure 25. Example of control file for exporting voice segments to any voice response node
123
# Source:
export_type=raw
# Destination:
file_encoding=wav
file_name=hello.wav
;
file_name=goodbye.wav
;
file_name=help.wav
segment_name=help
;
Figure 26. Example of control file for exporting voice segments as WAV files
To export the voice segments specified in the file called pizzas.txt from the
local host:
dtjplex -action exportVoiceHost -controlfile pizzas.txt
To export the voice segments specified in the file called pizzas.txt from the
host called annapurna:
dtjplex -action exportVoiceHost -host annapurna -controlfile pizzas.txt
Related information
v “dtjplex control file” on page 119
v “dtjplex exportVoiceHost action” on page 152
Importing voice segments from the file system
If you have sound files recorded in a studio or using a sound recorder utility,
you must import them from your file system into the Java voice segment
space. You can also import voice segments that have been exported from
another voice response node: see “Exporting voice segments to the file
124
Record
sound files
Export from
another voice
response node
File
system
dtjplex -action
importVoiceHost
Java voice
segment space
Voice
Voice
segment
Voice
segment
database
segment
database
database
Response system
Figure 27. Importing voice segments into the Java voice segment space
on page 126, change to the directory containing the files to be imported
(because the file names in the dtjplex control file are relative to the current
directory), and then execute one of the following commands:
v To import into a single host:
dtjplex -action importVoiceHost -controlfile filename
v To import into all hosts:
dtjplex -action importVoiceAll -controlfile filename
Attention: if you specify the name, category and locale of a voice segment
that is already in the Java voice segment space it is always overwritten.
You can import the following types of audio data into any base WebSphere
Voice Response system:
v WAV files containing linear PCM data: see file_encoding
v .au files
v Serialized voice objects that have previously been exported in the
interchange format: see “Control file keywords” on page 153
The data is converted, at the same time as the import, to the appropriate
format for that WebSphere Voice Response system.
You can also import data in ulaw, alaw, adpcm, gsm format, if the base
WebSphere Voice Response system supports that format. For example, you can
import an alaw file into an E1 WebSphere Voice Response system but not into
a T1 WebSphere Voice Response system. Use the file_encoding parameter to
specify this.
125
For reference information, see “dtjplex importVoiceHost action” on page 158.
Examples
# Source:
# Destination:
import_hints=Q0S0
file_name=hello
segment_name=hello
;
file_name=goodbye
;
Figure 28. Example of control file for importing voice segments from another voice response node on the same
operating system
# Source:
file_encoding=wav
# Destination:
segment_encoding=ulaw
segment_rate=8000
file_name=hello.wav
segment_name=hello
;
file_name=goodbye.wav
;
Figure 29. Example of control file for importing WAV files into a T1 system (any platform)
To import the voice segments specified in the file called pizzas.txt into the
Java voice segment space on the local host:
dtjplex -action importVoiceHost -controlfile pizzas.txt
Java voice segment space on the host called annapurna:
dtjplex -action importVoiceHost -host annapurna -controlfile pizzas.txt
Java voice segment space on all hosts:
dtjplex -action importVoiceAll -controlfile pizzas.txt
126
Related information
v “dtjplex importVoiceAll action” on page 155
v “dtjplex importVoiceHost action” on page 158
Adding voice segments from the base WebSphere Voice Response
system
To use voice segments that are already on your base WebSphere Voice
Response system, you must add them to the Java voice segment space. Some
of the voice segments from the System database or directory can be added at
installation time, but there are others you may want to add yourself: see
“What happens when you install a language?” on page 117 The other voice
segments that you need to add are those that you are going to use in a Java
application.
When you add a voice segment, a copy of the base voice segment is made. If
you subsequently make a change to the base voice segment, you must add it
to the Java voice segment space again, using the -replace parameter: see
“Replacing a voice segment from the WebSphere Voice Response base system”
on page 130. If you subsequently make a change to the Java voice segment,
and you want to use the changed segment in your base voice applications,
you can export it to create a sound file and then import it into the base
WebSphere Voice Response system: see “Exporting voice segments to the file
Why you have to add voice segments to the Java voice
segment space
All Java voice applications identify voice segments using the locale, category,
and voice segment name. This enables the same Java voice application to run
on different WebSphere Voice Response systems that use different schemes to
identify voice segments. Table 4 compares how voice segments are identified
in Java, and on AIX. In most cases, you can continue to use your existing
names for existing voice segments.
Table 4. Voice segment naming on different WebSphere Voice Response systems
AIX
Java
Segment ID
Numeric in range 0
to 65535
Name
1 to 20 alphanumeric
characters
Voice Directory
characters
Category
characters
127
Table 4. Voice segment naming on different WebSphere Voice Response
systems (continued)
AIX
Java
Language database
(AIX only)
Numeric in range 1
to 255
Locale
characters
Compression Type
Compressed or
Uncompressed
--
--
Adding the segments to the Java voice segment space
dtjplex
-action addVS
Java voice
segment space
Voice
segment
Voice
database
segment
database
Response system
Figure 30. Adding voice segments into the Java voice segment space
Create a dtjplex control file, as shown in Figure 31 on page 129, and then
execute the following command:
dtjplex -action addVS [-host hostname | -allHosts] -controlfile filename
For reference information, see “dtjplex addVS action” on page 148.
Examples
Figure 31 on page 129 shows an example of a dtjplex control file for adding
voice segments from a base AIX system. In this example, new names have
128
been invented for the voice segments, but you can use the numeric identifiers
as segment names if you want to.
# Source:
base_voice_directory=Pizzas
base_segment_compression=compressed
base_language_identifier=1
# Destination:
segment_name=hello
;
;
segment_name=help
;
Figure 31. Example of control file for adding voice segments from a base AIX system
To add the voice segments specified in the file called pizzas.txt to a host
called annapurna:
dtjplex -action addVS -host annapurna -controlfile pizzas.txt
To add the voice segments specified in the file called pizzas.txt to the local
host:
dtjplex -action addVS -controlfile pizzas.txt
To add the voice segments specified in the file called pizzas.txt to all hosts:
dtjplex -action addVS -allHosts -controlfile pizzas.txt
Note: All hosts must already have the voice segments in their voice segment
databases.
Related information
v
v
v
v
“dtjplex control file” on page 119
“dtjplex addVS action” on page 148
“What happens when you install a language?” on page 117
“Replacing a voice segment from the WebSphere Voice Response base
system” on page 130
129
Replacing a voice segment from the WebSphere Voice Response base
system
When you add a voice segment, a copy of the base voice segment is made. If
you subsequently make a change to the base voice segment, and you want the
change to be picked up by Java voice applications, you must add the voice
segment to the Java voice segment space again, using the -replace parameter.
In all other respects, this is just like adding the voice segment the first time:
see “Adding voice segments from the base WebSphere Voice Response
Create a dtjplex control file, as shown in Figure 31 on page 129, and then
execute the following command:
dtjplex -action addVS [-host hostname | -allHosts] -controlfile filename -replace
Examples
To replace the voice segments specified in the file called pizzas.txt on a host
called annapurna:
dtjplex -action addVS -host annapurna -controlfile pizzas.txt -replace
To replace the voice segments specified in the file called pizzas.txt on the local
host:
dtjplex -action addVS -controlfile pizzas.txt -replace
Related information
v
v
v
v
“dtjplex control file” on page 119
“dtjplex addVS action” on page 148
“What happens when you install a language?” on page 117
“Adding voice segments from the base WebSphere Voice Response system”
on page 127
Replacing a voice segment with a new version on your file system
If you import a voice segment from your file system, and subsequently make
a change to it, and you want the change to be picked up by Java voice
applications, you must import the voice segment into the Java voice segment
space again. This is exactly like importing the voice segments the first time:
see “Importing voice segments from the file system” on page 124.
Deleting voice segments
You can use dtjplex -action deleteVS to delete voice segments from the Java
voice segment space. (Note that if you added a voice segment from the base
WebSphere Voice Response system, this action does not delete the base voice
segment.) Create a dtjplex control file, as shown in Figure 32 on page 131, and
then execute the following command:
dtjplex -action deleteVS [-host hostname | -allHosts] -controlfile filename
130
Examples
segment_name=hello
;
;
segment_name=help
;
Figure 32. Example of control file for deleting voice segments (any platform)
To delete the voice segments specified in the file called pizzas.txt from all
hosts:
dtjplex -action deleteVS -allHosts -controlfile pizzas.txt
To delete the voice segments specified in the file called pizzas.txt from a host
called annapurna:
dtjplex -action deleteVS -host annapurna -controlfile pizzas.txt
To delete the voice segments specified in the file called pizzas.txt from the
local host:
dtjplex -action deleteVS -controlfile pizzas.txt
Related information
v “dtjplex deleteVS action” on page 151
v Developing Java applications, for information about deleting voice segments
dynamically
Copying voice segments
You can use dtjplex -action copyVS to copy voice segments within the Java
voice segment space.
on page 132, and then execute the following command:
dtjplex -action copyVS [-host hostname | -allHosts] -controlfile filename
131
Examples
target_segment_locale=en_GB
segment_name=hello
;
;
segment_name=help
;
Figure 33. Example of control file for copying voice segments to a different locale (any platform)
target_segment_category=Sandwiches
segment_name=hello
;
;
segment_name=help
;
Figure 34. Example of control file for copying voice segments to a different category (any platform)
segment_name=hello
target_segment_name=HelloAndWelcome
;
target_segment_name=GoodbyeAndComeBackSoon
;
segment_name=help
target_segment_name=ForHelpMenuPressStar
;
Figure 35. Example of control file for copying voice segments to different names (any platform)
To copy the voice segments specified in the file called pizzas.txt from all
hosts:
dtjplex -action copyVS -allHosts -controlfile pizzas.txt
To copy the voice segments specified in the file called pizzas.txt from a host
called annapurna:
dtjplex -action copyVS -host annapurna -controlfile pizzas.txt
132
To copy the voice segments specified in the file called pizzas.txt from the local
host:
dtjplex -action copyVS -controlfile pizzas.txt
Related information
v “dtjplex copyVS action” on page 150
v “Moving or renaming voice segments”
Moving or renaming voice segments
To move voice segments from one category to another or from one locale to
another, or rename voice segments, use dtjplex -action copyVS immediately
followed by dtjplex -action deleteVS, specifying the same control file.
Whether the voice segment is moved or renamed depends on the parameters
specified in the control file. For control file examples, see “Copying voice
segments” on page 131.
To move or rename the voice segments specified in the file called pizzas.txt on
all hosts:
dtjplex -action copyVS -allHosts -controlfile pizzas.txt
dtjplex -action deleteVS -allHosts -controlfile pizzas.txt
a host called annapurna:
dtjplex -action copyVS -host annapurna -controlfile pizzas.txt
dtjplex -action deleteVS -host annapurna -controlfile pizzas.txt
the local host:
dtjplex -action copyVS -controlfile pizzas.txt
dtjplex -action deleteVS -controlfile pizzas.txt
Related information
v “Moving or renaming voice segments”
133
Copying voice segments from one voice response node to another
To copy voice segments, use dtjplex -action exportVoiceHost on the original
host, and then dtjplex -action importVoiceHost on the new host.
# Source:
export_type=as_is
# Destination:
import_hints=Q0S0
file_name=hello
segment_name=hello
;
file_name=goodbye
;
file_name=help
segment_name=help
;
Figure 36. Example of control file for copying or moving voice segments from one voice response node to another on
the same operating system
To copy the voice segments specified in the file called pizzas.txt from a host
called annapurna to a host called matterhorn:
dtjplex -action exportVoiceHost -host annapurna -controlfile pizzas.txt
dtjplex -action importVoiceHost -host matterhorn -controlfile pizzas.txt
To copy the voice segments specified in the file called pizzas.txt from the local
host to a host called matterhorn:
dtjplex -action exportVoiceHost -controlfile pizzas.txt
dtjplex -action importVoiceHost -host matterhorn -controlfile pizzas.txt
134
Appendix C. Supplied scripts
This section provides reference information for supplied scripts that you can
use to perform utility functions.
You can change these to suit your installation. The scripts are in
/var/dirTalk/DTBE/native/aix.
Detailed information is available for the following scripts:
v “dtjalarm script”
v “dtjcache script” on page 137
v “dtjconf script” on page 140
v “dtjenv script” on page 142
v “dtjes script” on page 142
v “dtjflog script” on page 143
v “dtjlogmon script” on page 144
v “dtjnlsin script” on page 146
v “dtjplex script” on page 147.
v “dtjqapps script” on page 170.
v “dtjqccx script” on page 171
v “dtjqhost script” on page 171.
v “dtjqnode script” on page 171.
v “dtjshost script” on page 171.
v “dtjstart script” on page 172.
v “dtjstop script” on page 172.
v “dtjterm script” on page 172.
v “dtjuserlog script” on page 172
v “dtjver script” on page 173.
v “vxml2 script” on page 173
dtjalarm script
Starts and stops the sending of alarms from the Java and VoiceXML
environment based on the alarm properties files.
The dtjalarm command runs shell script /var/dirTalk/DTBE/native/aix/
dtjalarm which starts the sending of alarms from the Java and VoiceXML
environment based by default on the internal alarm properties file
com/ibm/hursley/trace/dtjalarm.properties, or optionally, by user-defined
external properties file.
dtjalarm does not generate a base WebSphere Voice Response alarm for each
log message sent to the log file log.X.log. During startup, a list of alarms that
135
are to be treated as base WebSphere Voice Response alarms is created. The
severity of each listed alarm is also referenced by associating it with the
appropriate WebSphere Voice Response alarm color to be used (RED,
YELLOW, GREEN, WHITE). Refer to Meaning of the alarm colors for details.
Individual listed alarms can also be given a severity of SUPPRESS to prevent
the alarm, or a severity of DEFAULT to indicate that the alarm color of the
dtjalarm message is determined by the severity category used for logging to
log file log.X.log, as follows:
Table 5. dtjalarm message severity categories
Severity Logged in log.X.log
Severity of Corresponding Base
WebSphere Voice Response Alarm
ERROR
RED
WARNING
YELLOW
NOTIFY
WHITE
In addition to the internal properties file supplied with the product, an
external properties file called dtuseralarm.properties can also be used to
override the IBM-defined settings or expand the alarmed log messages to
include messages not deemed by IBM as alertable. This file can be found in
$DTJ_DIR (by default, /var/dirTalk/DTBE/native/aix/
dtuseralarm.properties) The dtuseralarm.properties file is not installed
with the product, but instead an example version called
dtuseralarm.properties.example is installed in $DTJ_DIR. If you want to
modify alarm behavior, copy this file and rename it. This properties file and
the internal properties file both use the same formatting conventions. Java and
VoiceXML environment messages, which are typically logged as DTJnnnn
where nnnn represents a four-digit error code are listed in the properties files
without the DTJ prefix. Similarly, VXML browser messages which are typically
logged as VXInnnnn are listed without the VXI prefix as a five-digit error
code, and Java and VoiceXML environment trace messages are listed as a
seven-digit error code. Comment lines are preceded by the # character. For
example:
# legacy DTJ messages (4 digit range)
2001 DEFAULT
2003 RED
2006 GREEN
# VoiceXML browser log messages (5 digit range)
50106 SUPPRESS
# New VRBE trace log messages (7 digit range)
1007002 DEFAULT
In the above example, the alarm for message 50106 has been suppressed.
136
This script can also be used to stop the sending of alarms from the Java and
VoiceXML environment, by adding the -exit switch.
Syntax
dtjalarm [parameters]
Parameters
-exit
Stops the sending of alarms from the Java and VoiceXML
environment.
Example commands
To stop the sending of alarms from the Java and VoiceXML environment, type
the following line command:
dtjalarm -exit
dtjcache script
Displays or expires the contents of one or all of the WebSphere Voice
Response voice segment, VoiceXML or CCXML caches. New versions of any
expired contents will be fetched when an application next requests the file
from the cache . Content in the process of being loaded cannot be expired
until fully loaded. Optionally, it can also expire and delete from the disc one
or more VoiceXML documents older than a specified age or date.
The dtjcache command runs shell script /var/dirTalk/DTBE/native/aix/
dtjcache which:
v Lists the contents of one or all of the WebSphere Voice Response voice
segment, VoiceXML, or CCXML caches.
v Expires a single VoiceXML document or CCXML document, identified by
URL.
v Expires one or more audio files, VoiceXML documents, or CCXML
documents, older than a specified age or date.
v Expires and deletes from the disc one or more VoiceXML documents, older
than a specified age or date.
v Expires one audio file identified by URL, or all audio files in the audio file
cache.
Expiry messages from dtjcache are written to the DTJ log.n.log files under
message DTJ3139. List actions do not log messages.
Audio files specified by file:// URIs may not expire immediately from the
audio cache. They may be delayed until the next audio recycle time, which by
default, is 30 minutes-separated. http:// files work immediately. Grammar
files can be displayed in the VoiceXML cache, but expiring them may not have
the desired effect, as some speech recognition servers such as the WebSphere
137
Voice Server server caches a compiled version. If the grammar caching needs
to change, ensure that you also expire the WebSphere Voice Server entry on
that server.
Even if the -delete option is specified, because previously cached documents
have been pre-loaded, expiring something in a cache will only have an effect
on the program in memory when the internal processes try to fetch it again
from the cache.WebSphere Voice Response may well have current copies
loaded into memory, which will not be affected until those preloaded versions
are used up. For example, on a 30-browser system, it might take 31 calls to
see the change reflected. The expiry value displayed attempts to take the
max-age and max-stale into account. However, applications that specify
max-age and max-stale could override this. The -delete option expires the
specified VoiceXML document or documents from the cache immediately and
deletes deletes their cached file contents from the disc.
Expiring a file in the cache does not affect copies of the file already loaded
from the cache. For example, a multi-call CCXML document will not be
affected unless it uses a <goto> element, or a <createccxml> element, or
anything else that starts up a new CCXML browser. VoiceXML browsers will
not be updated until they are loaded, and because VoiceXML browsers can
preload, it may take longer for updated files to be used by VoiceXML
applications. Even expired VoiceXML files deleted from the disc can still be
available in memory until a browser is used and reloads. Audio files are not
updated until it is safe to do so without overwriting the resource (which
could be being used by another application).
Syntax
dtjcache [parameters]
Parameters
-action list
Lists the file names stored in all caches (default) or a cache specified
by the -cache parameter.
-action listDetails
Lists all files in all caches (default) or a cache specified by the -cache
parameter, with full details including expiry time, file size and
creation time.
-action expire
Expires everything in all caches (default) or in a cache specified by the
-cache parameter. You will be prompted for confirmation.
-age numberOfMinutes
Expires all resources in the caches that are older than a certain age
expressed in minutes. The -age option cannot be used with the
-olderThan option.
138
-cache Specifies the type of cache to expire or display file names for. Valid
values are:
v audio
v vxml
v ccxml
v all
The default is all.
-force When used with -action expire, expires without prompting for
confirmation. When used with the -delete option, suppresses the
warning message displayed by default.
-delete vxml
When used with the expire action, any resources in the VoiceXML
cache will be marked as expired and deleted from the system (disk).
Unless suppressed by also specifying the -force option, a warning is
displayed when this option is set. The -delete vxml option is
designed for disposing of VoiceXML cache items from dynamically
generated URIs that include a date-timestamp or other unique
identifier, which makes re-fetching such cached items difficult. It
should not be used with resources that are likely to be re-fetched by
an application in the near future. It cannot be used with Audio cache
or CCXML cache resources.
By default, WebSphere Voice Response retains expired cache items so
that they can be re-fetched easily if modified. With dynamic
documents, the HTTP header Cache-Control value can be set to
no-cache to avoid caching resources that cannot be re-fetched.
-olderThan date
Expires all resources in the caches that are older than a certain date
and time in the format DAY Mon dd hh:mm:ss LOC YYYY, where:
DAY
Day of the week
Mon
Month
dd Date in the month
hh Hour
mm Minute
LOC
Local timezone
YYYY
Year
139
The -olderThan option cannot be used with the -age option.
-batchFile fileName
When used with the expire action, reads a specified ASCII file listing
the names of cached files (one per line) and expires each entry.
whitespace-separated list of cached files
When used with the expire action, expires each entry in the list.
-h
Prints this help information.
-?
Prints this help information.
Example commands
To list all files in the voice segment cache with full details including expiry
time, file size, and creation time:
dtjcache -action listDetails -cache audio
To expire everything in all caches after confirmation:
dtjcache -action expire -cache all
To expire everything in all caches without prompting for confirmation:
dtjcache -action expire -cache all -force
To expire any resource older than an hour old from the VoiceXML cache and
delete them from the system without displaying any confirmation or warning
dialogs:
dtjcache -action expire -cache vxml -age 60 -force -delete vxml
To expire any resource from any cache older than the specified date of
Thursday 11th October 2012 at 10:49:13 hours, British Standard Time:
dtjcache -action expire -olderThan "Thu Oct 11 10:49:13 BST 2012"
To read a file named file.txt, treating each line as something that should be
expired in the VoiceXML cache:
dtjcache -action expire -cache vxml -batchFile file.txt
To expire a specified CCXML document (/var/dirTalk/DTBE/invoked.ccxml)
in the CCXML cache:
dtjcache -action expire -cache ccxml file:///var/dirTalk/DTBE/invoked.ccxml
dtjconf script
The default action is to import a configuration file (that is, a text file
containing definitions for a single configuration) into the configuration
database.
140
Whenever you modify the default.cff file, you need to run this to make the
changes affect the system. The script can also export a configuration from a
configuration database, to create a configuration file, or list the configurations
in a database.
Syntax
dtjconf [parameters]
Parameters
-action [import|export|list]
Use the import action to import your configuration file to update the
entries in the database.
The export action creates a file named filename.exp, where filename is
the name of the configuration. To use this configuration, for example
on a different system, you first need to rename the file to filename.cff
and then import it using dtjconf import.
The list action lists the configurations in the database. It is not really
recommended that you use a configuration other than “default”,
because you would have to specify it when using supplied scripts
such as dtjplex.
-configuration configurationname
The name of the configuration to use. If you do not specify this, it
defaults to default.
-database databasename
The fully qualified name of the configuration database. You should
not need to specify this.
-help
Displays a list of valid parameters.
-replace
Optional. Replaces an existing configuration on import or file on
export. If you don’t specify this, existing configurations or files are not
replaced.
Examples
To import the default configuration into the database called config.cfd, enter
the following:
dtjconf
To import the default configuration into the database called
/var/dirTalk/DTBE/native/aix/config.cfd, when you are not in that
directory, enter the following:
dtjconf -action import -database /var/dirTalk/DTBE/native/aix/config.cfd
141
dtjenv script
This script is called by all the other scripts to set the local environment
variables.
Although you can add your own Java classes to the DTJ_CLASSPATH, it is
recommended that you use the NodeClassPath keyword in the “NodeName
configuration entry” on page 90 for this purpose.
dtjes script
Reconfigures WebSphere Voice Response to use the edition of ECMAScript in
version 1.7 of the Mozilla Rhino Java package instead of the default version
1.3.
The dtjes command runs shell script /var/dirTalk/DTBE/native/aix/dtjes
which reconfigures WebSphere Voice Response to use the edition of
ECMAScript in version 1.7 of the Mozilla Rhino Java package instead of the
default version 1.3, and deletes any VoiceXML caches to remove cached scripts
that used the previous ECMAScript version.
Existing CCXML and VoiceXML applications using the <script> element
should continue to run as normal as ECMAScript version 1.7 is designed to be
compatible with previous versions. However, if you do change the
configuration to use version 1.7, you are advised to check that there are no
problems.
Note: Java and VoiceXML environment must be stopped before running the
dtjes command, and you must be logged on as root to run dtjes.
Syntax
dtjes [-list | -change version]
Parameters
-list
Lists the ECMAScript library version that WebSphere Voice Response
is using.
-change version
Updates the library so that WebSphere Voice Response uses the
version of ECMAScript specified in the command. To prevent possible
errors on restarting VRBE, the contents of the VoiceXML cache or
caches defined by the wvr.vxml2.cachedir property or by default,
/var/dirTalk/DTBE/native/aix/VXML2Cache, are deleted to remove
cached serialized scripts.
version can be 1.3 or 1.7.
142
Note: To run the dtjes -change command, you must be logged on as
user root.
Example commands
To list the edition of ECMAScript currently being used byWebSphere Voice
Response:
dtjes -list
To use the edition of ECMAScript in version 1.7 of the Mozilla Rhino Java
package instead of the default version 1.3:
dtjes -change 1.7
dtjflog script
Formats a message log file so that you can read it. The log file contains a
binary representation of runtime errors and application logging, if it exists.
Output from the VoiceXML <log> tag also appears in this file.
The name of the log file is log.n.log, where n is a number between 1 and 10
(by default). The log file is created in directory /var/dirTalk/DTBE/dtj_logs.
Syntax
dtjflog [parameters] filename
Where filename is the name of the log file to be formatted. If not specified,
this defaults to stdin.
Parameters
You can display the parameters by typing
dtjflog -?
on the command line.
-a
Sets the output encoding to the system default. If not specified the
default is UTF–8. If your editor cannot view unicode characters, use
the a flag to change the output encoding.
-o filename
The name of the output formatted file. If the file already exists it is
overwritten. If not entered this defaults to stdout.
Examples
To format the log.2.log message log in ASCII mode to log.2.out:
dtjflog -a -o log.2.out log.2.log
To format the log.1.log message log dynamically and output to the screen:
tail -f -b 20 log.1.log | dtjflog
143
Using -b 20 to specify a buffer of 20 blocks of 512 bytes prevents a partial log
being sent to dtjflog.
dtjlogmon script
The dtjlogmon script can be run in two modes: scan mode or test mode. In
scan mode, the dtjlogmon script runs a command automatically when a
specified error is logged to the VRBE log (.log) files or the WebSphere Voice
Response trace (.trc) files. The default command run is dtbeProblem -s
$DTJ_HOME/dtj_logs which collects a dtbeProblem output in the
$DTJ_HOME/dtj_logs directory. In test mode, the dtjlogmon script inserts
specified text in the active VRBE log file or active WebSphere Voice Response
trace file to check that a specified command is triggered.
The dtjlogmon command runs shell script /var/dirTalk/DTBE/native/aix/
dtjlogmon.
For information on using dtbeProblem to gather information about Java and
VoiceXML environment, Refer to the section “Collecting Java and VoiceXML
environment specific information” in the WebSphere Voice Response: Problem
Determination manual.
Scan mode syntax
In scan mode:
dtjlogmon [-l|-t|-a] -s searchString [-y] [-c command] [-i interval] [-o]
dtjlogmon -?
Scan mode parameters
In scan mode:
-l
Scans the log.n.log files for the text specified by the -s parameter.
-t
Scans the wvrtrace.n.trc files for the text specified by the -s
parameter.
-a
Scans the Node output files as specified in VRBE configuration file
default.cff for the text specified by the -s parameter. File
default.cff must be consistent with the current config.cfd file.
At least one of the above parameters must be present together with the -s
parameter.
-s searchString
Specifies the string that will trigger the command or commands
specified by the -c parameter. A search string that includes spaces
must be enclosed within double quotation marks. The search string
144
can be a regex as for the egrep utility. The search string is CASE
SENSITIVE, so “send ANNOUNCE” will not trigger a search string of
“SEND ANNOUNCE”.
-c command
Specifies the command or commands to run when the text is
generated. The default is "dtbeProblem -s $DTJ_HOME/dtj_logs".
Commands that includes spaces must be enclosed within double
quotation marks. You can run multiple commands by separating them
with a semicolon (;) for example,
-c "command1 ; command2; command3"
-i interval
Specifies the interval in seconds that the command is to wait between
scans of the files. The default is 5.
-y
Forces the script to run without prompting the user for confirmation
of the supplied parameters.
-o
Specifies that the command should loop back around and continue to
execute the command or commands specified by the -c parameter on
new instances of the search string until terminated. This parameter is
required for scripted invocations of dtjlogmon.
-?
Prints the help information for the command.
Scan mode example commands
dtjlogmon -l -s "Starting applications for node AppNode1 at host LocalHost"
Scans the log.n.log files for the text "Starting applications for node
AppNode1 at host LocalHost" and runs the command "dtbeProblem -s
$DTJ_HOME/dtj_logs"
dtjlogmon -a -s LocalHost -c "ls ; ls -l ; pwd"
Scans the Node output files as specified in VRBE configuration file
default.cff for the text "LocalHost" and runs the commands ls, ls -l, and
pwd sequentially in the same thread.
dtjlogmon -l -s "foo|bar"
Scans the log.n.log files for the text “foo” and “bar” and runs the command
"dtbeProblem -s $DTJ_HOME/dtj_logs" if a line being written to the log
includes the text “foo” or “bar” or “foo” and “bar”.
Test mode syntax
In test mode:
dtjlogmon [-l|-t] -w -s "insertString"
dtjlogmon -?
145
Test mode parameters
In test mode:
-l
Inserts the text specified by the -s parameter in the active log.n.log
file.
-t
Inserts the text specified by the -s parameter in the active
wvrtrace.n.trc file.
At least one of the above parameters must be present together with the -s
and -w parameters.
-s insertString
Specifies the string that is to be inserted in the active log or trace file.
A string that includes spaces must be enclosed within double
quotation marks.
-w
Writes out the specified text to the active log or trace file.
-?
Prints the help information for the command.
Test mode example commands
dtjlogmon -l -w -s "Starting applications for node AppNode1 at host LocalHost"
Inserts the text “Starting applications for node AppNode1 at host LocalHost”
in the active log.n.log file.
dtjlogmon -t -w -s LocalHost
Inserts the text “LocalHost” in the active wvrtrace.n.trc file.
dtjnlsin script
Imports voice segments from a language pack (a zip file containing voice
segments for a particular language) into the Java voice segment space.
Syntax
dtjnlsin [parameters] languagepack.zip
Where languagepack.zip is the name of the language file.
Note: Do not unpack the language file.
Parameters
-b
146
Imports System voice segments from the base WebSphere Voice
Response system rather than the language pack. Use this parameter
when you have already recorded System voice segments on the base
WebSphere Voice Response system, and you want to use these
segments rather than the segments supplied in the language pack.
Note: For WebSphere Voice Response for AIX , this parameter only
applies to U.S. English (en_US) and U.K. English (en_UK). For other
languages you must either use the System segments supplied in the
language pack, or record new ones.
Examples
To import the French voice segments into the Java voice segment space:
dtjnlsin fr_FR.zip
To import French, using System segments from the base WebSphere Voice
Response system:
dtjnlsin -b fr_FR.zip
dtjplex script
The dtjplex script performs numerous utility actions by executing
PlexManagerImpl utility commands.
To use dtjplex you must have access to the configuration database (config.cfd)
and, for many of the tasks, the voice response node specified in the command
must be running.
To use many of the dtjplex actions (addVS, copyVS, deleteVS,
exportVoiceHost, importVoiceHost, importVoiceAll), you also need a control
file to specify the names and other relevant attributes of the voice segments
you want to operate on. Specify the control file using the -controlfile
parameter. For example, dtjplex -action addVS -controlfile pizzavsegs.txt.
For more information, see “Using dtjplex” on page 118.
This section outlines the basic syntax of the command.
Syntax
dtjplex -action actionname [parameters]
actionname
The available actions and their parameters are listed in the following
sections:
v “dtjplex addVS action” on page 148
v “dtjplex exportVoiceHost action” on page 152
v
v
v
v
“dtjplex
“dtjplex
“dtjplex
“dtjplex
importVoiceAll action” on page 155
importVoiceHost action” on page 158
listVS action” on page 161
queryApplications action” on page 162
147
v
v
v
v
“dtjplex
“dtjplex
“dtjplex
“dtjplex
queryCCXML action” on page 163
queryHosts action” on page 163
queryNodes action” on page 164
startAll action” on page 165
v
v
v
v
v
v
v
“dtjplex
“dtjplex
“dtjplex
“dtjplex
“dtjplex
“dtjplex
“dtjplex
startApplication action” on page 165
startHost action” on page 166
startNode action” on page 166
stopAll action” on page 167
stopHost action” on page 168
stopNode action” on page 168
terminateAll action” on page 169
v “dtjplex terminateHost action” on page 169
v “dtjplex terminateNode action” on page 170
dtjplex addVS action
Make voice segments from the base WebSphere Voice Response system
available to Java voice applications.
Syntax
dtjplex -action addVS [parameters]
Parameters
-allHosts
The action will be performed on all hosts in the complex. Optional. If
not entered the action is performed on a single host.
-controlfile filename
The fully qualified name of the dtjplex control file. If you do not
specify this, it defaults to control.cfv in the current directory.
-host hostname
The name of the host on which to perform the action. If not entered
this will default to the local host.
-replace
If a voice segment already exists with the specified segment name,
148
category and locale, it is replaced. Optional. If not specified the voice
segment will not be replaced if it already exists.
Control file keywords
base_language_identifier
Values: Numeric, in the range 1 to 255
Description: The language identifier of the voice segment on the base
base_voice_directory
Values: Alphanumeric, up to 15 characters
Description: The voice directory of the segment on the base
base_segment_compression
Values: compressed or uncompressed
Description: The compression type of the voice segment on the base
base_segment_identifier
Values: Numeric; in the range 0 to 65535
Description: The segment identifier of the voice segment on the base
character_encoding
The character encoding used in the control file. You need to set this
only if your voice segment names use national characters (that is, 8-bit
ASCII encoding or DBCS) and you are planning to share the control
file across multiple systems. The name must be one of the “canonical
names” listed on Sun’s “Supported Encodings” Web site at
http://java.sun.com/products/jdk/1.1/docs/guide/intl/encoding.doc.html
segment_category
Description: The category that Java applications will use to identify
the voice segment.
segment_locale
Values: Alphanumeric, up to 15 characters (ll_CC or ll_CC_VARIANT)
Description: The locale that Java applications will use to identify the
voice segment.
segment_name
Description: The name that Java applications will use to identify the
voice segment.
149
dtjplex copyVS action
Copy Java voice segments.
Syntax
dtjplex -action copyVS [parameters]
Parameters
-allHosts
-host hostname
-replace
If a voice segment already exists with the specified segment name,
category and locale it is replaced. Optional. If not specified the voice
segment will not be replaced if it already exists.
character_encoding
segment_category
Description: The category of the voice segment to be copied.
segment_locale
Description: The locale of the voice segment to be copied.
150
segment_name
Description: The name of the voice segment to be copied.
target_segment_category
Description: The category of the new voice segment. Optional. If not
specified, segment_category is used.
target_segment_locale
Description: The locale of the new voice segment. Optional. If not
specified, segment_locale is used.
target_segment_name
Description: The name of the new voice segment. Optional. If not
specified, segment_name is used.
Related information
v “Copying voice segments” on page 131
dtjplex deleteVS action
Delete voice segments.
Syntax
dtjplex -action deleteVS [parameters]
Parameters
-allHosts
151
-host hostname
character_encoding
segment_category
Description: The category of the voice segment to be deleted.
segment_locale
Description: The locale of the voice segment to be deleted.
segment_name
Description: The name of the voice segment to be deleted.
Related information
dtjplex exportVoiceHost action
Export voice segments from the voice response node on a specified host.
Syntax
dtjplex -action exportVoiceHost [parameters]
Parameters
specify this, it defaults to impexp.cfv in the current directory.
152
-host hostname
character_encoding
export_type
Values: as_is, interchange, raw
Description: The format in which a voice segment is exported:
as_is
Exports a voice segment as a Java serialized object in the encoding
format used on the voice response node. This is an efficient option if
the export data is to be re-imported to a WebSphere Voice Response
system with the same hardware and voice encoding configuration.
The exported object contains the voice segment descriptor within it,
thus removing the need to specify it in the control file if it is later
re-imported into the WebSphere Voice Response Java and VoiceXML
Environment.
interchange
Exports a voice segment as a Java serialized object in the interchange
format, allowing it to be re-imported later into the WebSphere Voice
Response Java and VoiceXML Environment. This is the recommended
export option if you wish to re-import the voice data to a complex
containing a variety of voice response node hardware. The exported
object contains the voice segment descriptor within it, removing the
need to specify it in the control file if it is later re-imported into the
WebSphere Voice Response Java and VoiceXML Environment.
raw
This exports the voice segment as a raw audio file. The data encoding
is specified in the file_rate and file_encoding parameters. This option
should only be used if the exported voice is to be used by third-party
utilities, such as a sound editing program. You need to keep a record
of the audio encoding format, sample size and sampling rate
associated with the data, because this information is not included in
153
the exported object. The exception is if file_encoding is set to wav and
au whose file format holds the encoding information in its header.
file_encoding
Values: ulaw, alaw, gsm, wav, au
Description: Audio encoding format of the audio file. Required if
export_type is raw.
You must ensure that the audio data stored in the file matches the
format specified in the control file. Unintelligible sound will result at
playback if the data is incorrectly specified.
ulaw or alaw
Single-channel, 8-bit sample size, 8kHz sampling rate. Supported on
all platforms.
gsm
Single-channel, compressed format used on WebSphere Voice
Response for AIX only. The sampling rate is ignored.
wav
A file encoding of wav indicates that the audio file is a Microsoft
WAV file. When importing a WAV file the encoding, sample size, and
sampling rate information is taken from in the WAV file itself. The
data stored in the WAV file must be either in u-law, a-law or linear
encoding. For ulaw and alaw, it must be single-channel with 8-bit
sample size and 6kHz or 8kHz sampling rates. For linear encoding, it
must be mono or stereo and 8 or 16-bit sample size. When exporting
to a WAV file, the data format used is always 16-bits, mono and 8kHz
sampling rate.
au
When you import an au file, the encoding, sample size and sample
rate information is taken from the au file itself. The data stored in the
au file can be u-law, a-law or PCM. For u-law and a-law it must be
single channel with 8-bit sample size. It may have any sampling rate.
For PCM it may be 8-bit or 16-bit sample size (mono or stereo). When
you export to an au file the data format used is 8-bit, 8kHz, m-law.
Non-PCM au files must be mono.
file_name
Values: A valid file name
Description: The name of the file to which audio data is to be
exported. The file name is relative to the directory from which the
exportVoiceHost action is executed.
154
file_rate
Values: 6000 or 8000
Description:Data sampling rate in Hz of the data in the audio file.
Required if export_type is raw and file_encoding is ulaw, alaw or
adpcm.
segment_category
Description: The category of the voice segment to be exported.
segment_locale
Description: The locale of the voice segment to be exported. Defaults
to the locale in which you run the command (not the locale of the
voice response node).
segment_name
Description: The name of the voice segment to be exported.
Related information
v “Exporting voice segments to the file system” on page 122
page 134
dtjplex importVoiceAll action
Import voice segments into all running voice response nodes.
Syntax
dtjplex -action importVoiceAll [parameters]
Parameters
155
Note: You must specify either import_hints or segment_encoding and
segment_rate.
character_encoding
file_name
Values: Any file name
Description: The name of the file containing the audio data to be
imported. The file name is relative to the directory from which the
action is executed.
file_encoding
Description:Audio encoding format of the audio file. Required if the
audio data has not been exported as_is or interchange.
ulaw or alaw
all platforms.
gsm
wav
data stored in the WAV file must be either in ulaw, alaw or linear
sampling rate.
156
au
au file may be u-law, a-law or PCM. For u-law and a-law it must be
file_rate
Required if file_encoding is ulaw, alaw or adpcm.
import_hints
Values: a string of the format QxSy where x and y represent the
quality and size measures of the imported voice segment. A value of 1
means low, 2 means medium and 3 means high while a value of 0
means “don't care”.
Description: An alternative to specifying explicitly the voice segment
data encoding format is to hint at the desired audio quality and size
of imported voice segment.
These values are interpreted differently on different WebSphere Voice
Response systems. On systems where only one audio encoding format
is supported, the values of the hints have no effect. The use of
import_hints is particularly useful if audio data is to be imported into
systems with different voice encoding configurations.
Required if you don’t specify segment_encoding and segment_rate.
(If you specify import_hints, any existing values in
segment_encoding and segment_rate are unset.)
segment_category
Description: The category of the voice segment to be imported.
Required if the audio data has not been exported as_is or
interchange, or if an as_is or interchange voice object is to be
re-imported as a different voice segment.
segment_encoding
Values: ulaw, alaw, adpcm, or gsm
Description: Required if you don’t specify import_hints. (If you
specify this, any existing value in import_hints are unset.)
segment_locale
Values: Alphanumeric, up to 15 characters (ll_CC or ll_CC_variant)
157
Description: The locale of the voice segment to be imported. Defaults
segment_name
Description: The name of the voice segment to be imported. Required
if the audio data has not been exported as_is or interchange, or if an
as_is or interchange voice object is to be re-imported as a different
voice segment.
segment_rate
Description: Data sampling rate in Hz of the voice segment. Required
if you don’t specify import_hints. (If you specify this, any existing
value in import_hints are unset.)
Related information
page 134
dtjplex importVoiceHost action
Import voice segments into a voice response node.
Syntax
dtjplex -action importVoiceHost [parameters]
Parameters
-host hostname
158
Note: You must specify either import_hints or segment_encoding and
segment_rate.
character_encoding
file_name
Values: Any file name
Description: The name of the file containing the audio data to be
imported. The file name is relative to the directory from which the
action is executed.
file_encoding
Description: Audio encoding format of the audio file. Required if the
audio data has not been exported as_is or interchange.
ulaw or alaw
all platforms.
gsm
wav
data stored in the WAV file must be either in ulaw, alaw or linear
sampling rate.
159
au
au file may be u-law, a-law or PCM. For u-law and a-law it must be
file_rate
Required if file_encoding is ulaw, alaw or adpcm.
import_hints
Values: a string of the format QxSy where x and y represent the
quality and size measures of the imported voice segment. A value of 1
means low, 2 means medium and 3 means high while a value of 0
means “don't care”.
Description: An alternative to specifying explicitly the voice segment
data encoding format is to hint at the desired audio quality and size
of imported voice segment.
These values are interpreted differently on different WebSphere Voice
Response systems. On systems where only one audio encoding format
is supported, the values of the hints have no effect. The use of
import_hints is particularly useful if audio data is to be imported into
systems with different voice encoding configurations.
Required if you don’t specify segment_encoding and segment_rate.
(If you specify import_hints, any existing values in
segment_encoding and segment_rate are unset.)
segment_category
Description: The category of the voice segment to be imported.
Required if the audio data has not been exported as_is or
interchange, or if an as_is or interchange voice object is to be
re-imported as a different voice segment.
segment_encoding
Values: ulaw, alaw, adpcm, or gsm
Description: Required if you don’t specify import_hints. (If you
specify this, any existing value in import_hints are unset.)
segment_locale
Values: Alphanumeric, up to 15 characters (ll_CC or ll_CC_variant)
160
Description: The locale of the voice segment to be imported. Defaults
segment_name
Description: The name of the voice segment to be imported. Required
if the audio data has not been exported as_is or interchange, or if an
as_is or interchange voice object is to be re-imported as a different
voice segment.
segment_rate
Description: Data sampling rate in Hz of the voice segment. Required
if you don’t specify import_hints. (If you specify this, any existing
value in import_hints are unset.)
Related information
page 134
dtjplex listVS action
List all the voice segments available to Java applications on a specific host.
Syntax
dtjplex -action listVS [parameters]
Parameters
-host hostname
-VoiceSegmentFile
The name of the file that the details of the voice segments will be
output to. The file will be in the same format as the control file used
for input to the other dtjplex actions. Optional; default is vseglist.txt.
161
-Encoding
The character encoding to be used to write to the VoiceSegmentFile.
Optional; if not specified, the platform encoding is used. For valid
encodings, see Sun’s Java Web site at
http://www.javasoft.com/products/jdk/1.1/docs/guide/intl/encoding.doc.html
-replace
If the file already exists, replace it. Optional; if not specified, the
action fails if the VoiceSegmentFile already exists.
Related information
v “Listing available voice segments” on page 121
dtjplex queryApplications action
Find out the status of all the non-CCXML applications in a node.
Syntax
dtjplex -action queryApplications [parameters]
Parameters
-host hostname
-node nodename
The node on which to perform the action. There is no default.
Example commands
To find out the status of applications in a node called Node1, in a host called
host1, enter the following line command:
dtjplex -action queryApplications -host host1 -node Node1
Shorthand script
To find out the status of applications in a node called Node1, in the local host,
enter the following line command:
dtjqapps
This is equivalent to:
dtjplex -action queryApplications -node Node1
162
dtjplex queryCCXML action
Find out the status of all the CCXML applications in a node.
Syntax
dtjplex -action queryCCXML [parameters]
Parameters
-host hostname
-node nodename
Example commands
To find out the status of CCXML applications in a node called Node1, in a
host called host1, enter the following line command:
dtjplex -action queryCCXML -host host1 -node Node1
Shorthand script
To find out the status of applications in a node called Node1, in the local host,
enter the following line command:
dtjqccx
dtjplex -action queryApplications -node Node1
dtjplex queryHosts action
Find out the status of all the hosts.
Syntax
dtjplex -action queryHosts [parameters]
Parameters
163
Example commands
To find out the status of all hosts, enter the following line command:
dtjplex -action queryHosts
Shorthand script
A shorthand equivalent of this script is:
dtjqhost
dtjplex queryNodes action
Find out the status of all the nodes in a host.
Syntax
dtjplex -action queryNodes [parameters]
Parameters
-host hostname
Example commands
To find out the status of nodes in a host called host1, enter the following line
command:
dtjplex -action queryNodes -host host1
Shorthand script
To find out the status of nodes in the local host, enter the following line
command:
dtjqnode
dtjplex -action queryNodes
164
dtjplex startAll action
Start all hosts.
Syntax
dtjplex -action startAll [parameters]
Parameters
Example commands
To start all hosts, enter the following line command:
dtjplex startApplication action
Start one or more instances of a specific application in a node.
Syntax
dtjplex -action startApplication [parameters]
Parameters
-application applicationname
The name of the application to start.
-copies number
The number of instances to start. If not entered this defaults to 1.
There is no maximum.
-host hostname
-node nodename
165
Example commands
To start 40 copies of an application called orderapp in a node called Node1, in
a host called host1, enter the following line command:
dtjplex -action startApplication -host host1 -node Node1 -application
orderapp -copies 40
dtjplex startHost action
Start a host.
Syntax
dtjplex -action startHost [parameters]
Parameters
-host hostname
Example commands
To start a host called host1, enter the following line command:
dtjplex -action startHost -host host1
Shorthand script
To start the local host, enter the following line command:
dtjstart
dtjplex -action startHost
dtjplex startNode action
Start a node.
Syntax
dtjplex -action startNode [parameters]
166
Parameters
-host hostname
-node nodename
Example commands
To start a node called Node1, in a host called host1, enter the following line
command:
dtjplex -action startNode -host host1 -node Node1
To start a node called Node1, in the local host, enter the following line
command:
dtjplex -action startNode -node Node1
dtjplex stopAll action
Quiesces all hosts, waiting for all calls to finish before shutting down the
nodes.
Syntax
dtjplex -action stopAll [parameters]
Parameters
Example commands
To stop all hosts, enter the following line command:
dtjplex -action stopAll
167
dtjplex stopHost action
Quiesce a host, waiting for all calls to finish before shutting down the nodes.
Syntax
dtjplex -action stopHost [parameters]
Parameters
-host hostname
Example commands
To stop a host called host1, enter the following line command:
dtjplex -action stopHost -host host1
Shorthand script
To stop the local host, enter the following line command:
dtjstop
dtjplex -action stopHost
dtjplex stopNode action
Quiesce a node, waiting for all calls to finish before shutting down the node.
Syntax
dtjplex -action stopNode [parameters]
Parameters
168
-host hostname
-node nodename
Example commands
To quiesce a node called Node1, in a host called host1, enter the following
line command:
dtjplex -action stopNode -host host1 -node Node1
To quiesce a node called Node1, in the local host, enter the following line
command:
dtjplex -action startNode -node Node1
dtjplex terminateAll action
Stop all hosts, immediately, without waiting for calls to finish.
Syntax
dtjplex -action terminateAll [parameters]
Parameters
Example commands
To start all hosts, enter the following line command:
dtjplex -action terminateAll
dtjplex terminateHost action
Stop a host, immediately, without waiting for calls to finish.
Syntax
dtjplex -action terminateHost [parameters]
Parameters
169
-host hostname
Example commands
To stop a host called host1, enter the following line command:
dtjplex -action terminateHost -host host1
dtjplex terminateNode action
Stop a node immediately, without waiting for calls to finish.
Syntax
dtjplex -action terminateNode [parameters]
Parameters
-host hostname
-node nodename
Example commands
To stop a node called Node1, in a host called host1, enter the following line
command:
dtjplex -action terminateNode -host host1 -node Node1
To stop a node called Node1, in the local host, enter the following line
command:
dtjplex -action terminateNode -node Node1
dtjqapps script
Queries waiting non-CCXML applications on Node1 of the local host. Note
that this script does not display applications that are recycling.
170
Syntax
dtjqapps
dtjqccx script
Queries running CCXML applications on Node1 of the local host.
Syntax
dtjqccx
dtjqhost script
Queries the local host.
Syntax
dtjqhost
dtjqnode script
Queries all nodes in the local host.
Syntax
dtjqnode
dtjshost script
Starts remote method invocation (RMI) and the HostManager.
The HostManager enables communication between all the hosts in the
WebSphere Voice Response Java and VoiceXML Environment. A HostManager
must be running in each host on which you are running a voice response
node or an application node. This script must be run on every host in the
complex, before you can do anything else, such as starting the nodes or
applications, or importing voice segments.
The dtjshost script also does the following:
v Starts the redirection of CCXML and VoiceXML application logging to a
user logging application by invoking the user.log.class defined in
dtj.ini, if both of the following properties in the dtj.ini file are
configured and active (not commented out):
user.log.classpath
user.log.class
v Starts the sending of alarms from the Java and VoiceXML environment
based on the alarm properties files.
171
By adding the -exit switch, the dtjshost script can also be used to stop the
HostManager, the user logging application, and Java and VoiceXML
environment alarm monitoring. You must stop any nodes that are running
before you stop the HostManager.
Syntax
dtjshost [parameters]
Parameters
-exit
Stops the HostManager, Java and VoiceXML environment alarm
monitoring, and the optional user logging application.
Example commands
To stop the HostManager, Java and VoiceXML environment alarm monitoring,
and the optional user logging application, type the following line command:
dtjshost -exit
dtjstart script
Starts all applications and all nodes on the local host.
Syntax
dtjstart
dtjstop script
Quiesces (that is, it waits until all calls have finished and then stops) all
application and all nodes on the local host.
Syntax
dtjstop
dtjterm script
Stops immediately all applications and all nodes on the local host.
Syntax
dtjterm
dtjuserlog script
Starts the additional routing of application logging messages from CCXML
and VoiceXML applications to a user logging application.
The dtjuserlog command runs shell script /var/dirTalk/DTBE/native/aix/
dtjuserlog which starts the additional routing of CCXML and VoiceXML
application logging to a user logging application by invoking the
172
user.log.class defined in dtj.ini. Prior to running the command, the
following properties in the dtj.ini file must be configured and active (not
commented out):
user.log.classpath
user.log.class
See “CCXML and Voice XML application logging” on page 69 for information
on how to use and customize the user logging application..
This script can also be used to stop application logging to a user logging
application , by adding the -exit switch.
Syntax
dtjuserlog [parameters]
Parameters
-exit
Stops application logging to a user logging application
Example commands
To stop VoiceXML and CCXML application logging to a user logging
application, enter the following line command:
dtjuserlog -exit
dtjver script
Tells you the current version of WebSphere Voice Response Java and
VoiceXML Environment.
Syntax
dtjver
vxml2 script
Allows you to start running voicexml 2.1 applications remotely.
Syntax
vxml2 [parameters] uri
where uri is the first page of VoiceXML to be loaded. The URI must be
absolute and must include the protocol, for example
http://www.company.com/apps/horoscope.vxml
URIs that include numeric IPv6 format addresses, must have the numeric part
173
Parameters
-appname
The name to use when connecting to voice response node. The default
value is VXML2Browser.
-debug
Causes diagnostic output to be printed.
-ipaddr
The TCP/IP address of the machine hosting the voice response node.
The default value is localhost.
-dtmfonly
Specify this flag if you do not have IBM WebSphere Voice Server
installed and speech plugins defined in the configuration file
default.cff. Additionally, you must not use speech recognition or
text-to-speech in your application.
-loop
Causes the browser to wait for another incoming call when a call
ends.
-nodename
The name of the voice response node to use. The default value is
VRNode1.
-rmiport
The TCP/IP port number to be used for RMI communication. The
default value is 26924.
Example commands
To start a voicexml 2.1 application called weather remotely:
vxml2 -appname weather -debug file:///var/dirTalk/DTBE/samples/Weather.vxml
174
Appendix D. Command syntax
This section provides reference information about the command line utilities.
There are scripts that execute each of these commands, making them easier to
use: see Appendix C, “Supplied scripts,” on page 135. There is a supplied
script on AIX called dtjconf. If you want to write your own scripts, the full
syntax is given in the following sections:
v “ConfigManager command”
v “HostManagerImpl command” on page 177
v “PlexManagerImpl command” on page 178
Note: If you have not set the CLASSPATH variable, run the dtjenv script.
On AIX, you need to run the script using the . (dot) command."
ConfigManager command
The ConfigManager command creates entries in the configuration database
from the text file you can edit.
This command must be run every time you make changes to the text file, if
you want those changes to take effect in the database. In addition, you can
use the ConfigManager command to create a text file from the configuration
database, or to list the configurations in the database.
Syntax
java -Ddtj.home="installpath" com.ibm.telephony.directtalk.ConfigManager parameters
installpath
The pathname of the directory where WebSphere Voice Response Java
and VoiceXML Environment is installed, for example,
/var/dirTalk/DTBE.
parameters
Without any parameters, the system displays a list of the actions you
can use with ConfigManager and waits for input. Alternatively, use
the -action parameter to specify the actionname, together with any
other appropriate parameters.
ConfigManager list action
List the names of all the configurations in the configuration database.
Syntax
java -Ddtj.home="installpath" com.ibm.telephony.directtalk.ConfigManager
-action list [parameters]
175
Command parameters
Example commands
To list configurations in the database called /var/dirTalk/DTBE/native/aix/
config.cfd, when you are not in that directory, enter the following line
command:
java -Ddtj.home="/var/dirTalk/DTBE" com.ibm.telephony.directtalk.ConfigManager
-action list -database /var/dirTalk/DTBE/native/aix/config.cfd
ConfigManager export action
Create a configuration file (that is, a text file containing definitions for a single
configuration) from the configuration database. The resulting text file is called
configuration_name.cff, for example, default.cff.
Syntax
-action export [parameters]
Command parameters
-replace
Replaces a text file of the same name (for example, default.cff) if it
already exists. Optional. If not specified the file is not replaced.
Example commands
To export the default configuration from the database called
directory, using the default RMI port number, enter the following line
command:
-action export -database /var/dirTalk/DTBE/native/aix/config.cfd -replace
176
ConfigManager import action
Import a configuration file (that is, a text file containing definitions for a
single configuration) into the configuration database.
Syntax
-action import [parameters]
Command parameters
-replace
Replaces a configuration of the same name (for example, default) if it
already exists. Optional. If not specified the configuration is not
replaced.
Example commands
To import the default configuration into the database called
directory, using the default RMI port number, enter the following line
command:
-action import -database /var/dirTalk/DTBE/native/aix/config.cfd -replace
Equivalent script
On AIX you can use the “dtjconf script” on page 140 to execute this
command.
HostManagerImpl command
The HostManagerImpl command starts the HostManager.
This command must be run on every host in the complex, before you can do
anything else, such as starting the nodes or applications, or importing voice
segments.
Syntax
java -Ddtj.home="installpath" com.ibm.telephony.directtalk.HostManagerImpl
Appendix D. Command syntax
177
HostManagerImpl example
To start the HostManager, using the default configuration file and the default
configuration name, enter the following line command:
java -Ddtj.home="/var/dirTalk/DTBE" com.ibm.telephony.directtalk.HostManagerImpl
Equivalent script
On AIX you can use the “dtjshost script” on page 171 to execute this
command.
PlexManagerImpl command
The PlexManagerImpl command performs numerous utility actions.
This section outlines the basic syntax of the command. The actions and all the
parameters for each action are listed in “dtjplex script” on page 147 and the
sections following it.
To use the PlexManagerImpl command, you must be on the system that has
access to the configuration database (config.cfd).
PlexManagerImpl Scripts
dtjplex is a simple line command that issues PlexManagerImpl actions. It is
supplied as a script and a command: see “dtjplex script” on page 147.
Syntax
java com.ibm.telephony.directtalk.PlexManagerImpl [parameters]
parameters
Without any parameters, the system displays a list of the actions you
can use with PlexManagerImpl and waits for input. Alternatively, use
the -action parameter to specify the actionname, together with any
other appropriate parameters. The actions are the same as those of the
“dtjplex script” on page 147
PlexManagerImpl example
To start a node called mynode in a host called host1, using the default
configuration file and the default configuration name, enter the following line
command:
java com.ibm.telephony.directtalk.PlexManagerImpl -host host1
-node mynode -action startNode
Equivalent script
On AIX you can use the “dtjplex script” on page 147 to execute this
command.
178
Appendix E. Changing the Incoming_Call state table to
receive calls in the ALERTING state
New calls routed to CCXML must be in the ALERTING state to conform to
the CCXML specification. It is recommended that all calls passed to the Java
and VoiceXML environment are passed in the ALERTING state, but this is
only essential if CCXML is being used.
By default, calls are answered by WebSphere Voice Response for AIX before
they are passed to the Java and VoiceXML environment. The Incoming_Call
state table must be modified to pass calls through without answering them.
Using CCXML with other application types
If the Java and VoiceXML environment routes a call (as specified by the
NumToApp mapping) to a Java or VoiceXML application, the Java and VoiceXML
environment will automatically answer the call before handing it on to the
application.
If you intend to run state table applications as well as VoiceXML, Java, or
CCXML applications, you need to consider how these state tables and Java
applications operate before changing the way in which incoming calls are
handled. Your existing state table applications probably expect to receive calls
in the ANSWERED state. If you modify the Incoming_Call state table to
accommodate CCXML, you must also modify the state table applications that
expect to receive calls in the ANSWERED state so that they now answer calls
themselves.
Modifying the Incoming_Call state table
To modify the Incoming_Call state table to receive calls in the alerting state:
1. If it is not already running, start WebSphere Voice Response for AIX .
2. From the Welcome window, click Applications —> State Tables to display
the State Tables window.
3. From the list of state table applications displayed, select the
Incoming_Call state table and open it for editing. The state table contains
one AnswerCall action.
4. Select the line including the AnswerCall action and click Edit —> Delete
to remove it.
5. Click File —> Validate and Save to update the state table.
6. Click File —> Close to close the editor window.
179
Modifying answering application state tables
To modify the state tables for existing applications so that they can answer
calls:
1. If it is not already running, start WebSphere Voice Response for AIX .
2. From the Welcome window, click Applications —> State Tables to
display the State Tables window.
3. From the list of state table applications displayed, select the state table
for the application that you want to modify and open it for editing.
Note: Do not modify the JavaApplication state table as this is used to
route all calls to the Java and VoiceXML environment, which includes
CCXML.
4. Select Options —> Show Action Palette.
5. Select the AnswerCall icon in the PhoneLine folder of the Action Palette
and drag it to the work area. The AnswerCall action establishes a
connection between the caller and WebSphere Voice Response for an
incoming call.
6. Double-click on the AnswerCall action in the state table to display the
Action AnswerCall window.
7. Type a label name for the action in the State Label field.
8. Type a meaningful description for the action in the Description field.
9. Type a label name in the Not Ringing field so that your application can
deal with the situation where a connection cannot be established.
10. Click File —> Validate and Save to update the state table.
11. Click File —> Close to close the editor window.
180
Appendix F. Configuring telephone URI verification for
CCXML and VXML specify the use of a "telephone URI" that should conform
to RFC 2806.(http://www.ietf.org/rfc/rfc2806.txt). For example: .
CCXML
VXML
CCXML
CCXML
<createcall> "dest=" attribute.
<transfer>
"dest=" attribute.
dialog.transfer event.
<redirect>
"dest=" attribute.
The information given here explains how RFC 2806 is implemented for
CCXML and VXML on WebSphere Voice Response, and should be read in
conjunction with RFC 2806.
Fundamental concepts
Essentially RFC 2806 specifies that there are two types of telephone URL:
v Global URLs begin with the "+" character and are followed by a digit string
that is unique worldwide.
v Local URLs do NOT begin with "+" and are a digit string that MUST be
followed by a "context" definition. The context of a Local URL specifies the
Network area (or areas) from which the digits of the URL are a proper
dialing number (i.e the area from which the digits will reach the desired
destination)
So, most telephone numbers can be referenced by either a global or local URL.
For example, the global URL for a telephone might be:
tel:+441234567890
Which is made up of:
tel:
This is a telephone URL
+
A global URL
44 Country code for United Kingdom (UK)
1234
Area code
567890
The telephone number in the local area.
181
This telephone URL could also be written as a local URL:
tel:01234567890;phone-context=+44 or tel:567890;phone-context=01234. It is
important to understand that if a local URL is used, it is necessary to define
the context within in which the number will work. The dialed number
01234567890 will only work properly if it is dialed from a phone inside the
UK Network. The dialed number 567890 will only work if it is dialed from a
phone in the 01234 area.
Thus in order to support telephone URLs on WebSphere Voice Response it is
necessary to have configuration data that enables two functions:
v Validation of the context of URLs.
v Access to the international dialing network.
Configuring WebSphere Voice Response
Configuration data is supplied using a node TelURLLocale entry in the
configuration file. (usually default.cff).
The Secondary keywords of this configuration entry are used as follows:
InternationalAccess
The digits that should be inserted in place of the ‘+’ character in a global
URL, when dialing from the WebSphere Voice Response system. These
digits that should to be inserted depend on how the WebSphere Voice
Response system is connected to the International network (direct or
through a PBX) and the country in which the WebSphere Voice Response
system is operating. For example if a WebSphere Voice Response system is
connected directly to the network in UK the InternationalAccess is 00. If
the system is attached to a PBX where you need to dial 9 for an external
call the InternationalAccess is 900.
LocalContext
The digits that define the Local Area within the Network to which the
WebSphere Voice Response system is connected. For example if a
WebSphere Voice Response system is connected to the Winchester area of
the UK network, the LocalContext is 01962.
GlobalContext
The digits that define the global area within which the WebSphere Voice
Response system is connected. For example +44 indicates that the
WebSphere Voice Response system is connected somewhere in the UK. Or
+441962 indicates it is connected in the Winchester area in the UK
WebSphere Voice Response relates these fields to the URL in the following
ways:
182
Global URLs
If a global URL does not have a context specifier, WebSphere Voice
Response simply replaces the "+" character with the
InternationalAccess digits. If the global URL does have a context
specifier (it is allowed but not mandatory for global URLs) WebSphere
Voice Response checks for a match between the global URL context
specifier and the digits in the GlobalContext field, and if they don’t
match, the global URL will be invalid.
Local URLs
Must have a context specifier (RFC 2806). WebSphere Voice Response
checks that the context specifier of a local URL exists, otherwise the
URL will be invalid. If the context specifier exists it MUST match the
digits of the LocalContext or GlobalContext field otherwise the URL
will be invalid.
A Local URL can have more than one context specifier.
Example default.cff entries for TelURLLocale
A set of named TelURLLocale definitions can be specified in the main part of
the configuration file.
For example:
TelURLLocale=WashingtonDCUSA
GlobalContext=+1
LocalContext=202
InternationalAccess=011
;
TelURLLOcale=MoscowRussia
GlobalContext=+095
LocalContext=956
;
TelURLLOcale=ArizonaUSA
GlobalContext=+1
LocalContext=602
;
TelURLLocale=WinchesterUK
GlobalContext=+44
LocalContext=01962
;
When configuring a specific Voice Response node, one of the named
TelURLLocale entries is then used to define the Locale of the VR node, for
example:
Appendix F. Configuring telephone URI verification for WebSphere Voice Response
183
NodeName=VRNode1
VRNode=yes
TelURLLocale=WashingtonDCUSA
Given this configuration (a VR Node an Washington DC) consider the
following telephone URLs. These are valid telephone URLs when specified
from this VR Node:
tel:+441234567890
tel:+441234567890;phone-context=+1
tel:011441234567890;phone-context=+1
tel:567890;phone-context=202
tel:567890;phone-context=202;phone-context=602
tel:2025886500;phone-context=+1
tel:+12025886500
These are invalid telephone URLs when specified from this VR Node:
tel:+441234567890;phone-context=+44
tel:011441234567890
tel:2025886500
tel:5886500;phone-context=602
184
[global context mismatch]
[local URL requires phone-context]
[local URL requires phone-context]
[local context mismatch]
Notices
This information was developed for products and services offered in the
U.S.A.
IBM may not offer the products, services, or features discussed in this
document in other countries. Consult your local IBM representative for
information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or
imply that only that IBM product, program, or service may be used. Any
functionally equivalent product, program, or service that does not infringe
any IBM intellectual property right may be used instead. However, it is the
user’s responsibility to evaluate and verify the operation of any non-IBM
product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give
you any license to these patents. You can send license inquiries, in writing, to:
The IBM Director of Licensing, IBM Corporation,
North Castle Drive,
Armonk,
NY 10504-1785,
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the
IBM Intellectual Property Department in your country or send inquiries, in
writing, to:
Intellectual Property Licensing,
Legal and Intellectual Property Law,
IBM Japan, Ltd.,
19-21, Nihonbashi-Hakozakicho, Chuo-ku,
Tokyo 103-8510, Japan.
The following paragraph does not apply to the United Kingdom or any
other country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY
185
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow
disclaimer of express or implied warranties in certain transactions, therefore,
this statement may not apply to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will
be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s)
described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those
Web sites. The materials at those Web sites are not part of the materials for
this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the
purpose of enabling: (i) the exchange of information between independently
created programs and other programs (including this one) and (ii) the mutual
use of the information which has been exchanged, should contact: IBM UK
Limited, Department 88013, 4NW, 76/78 Upper Ground, London, SE1 9PZ,
England. Such information may be available, subject to appropriate terms and
conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer
Agreement, IBM International Programming License Agreement, or any
equivalent agreement between us.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available
sources. IBM has not tested those products and cannot confirm the accuracy
of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be
addressed to the suppliers of those products.
COPYRIGHT LICENSE: This information contains sample application
programs in source language, which illustrate programming techniques on
various operating platforms. You may copy, modify, and distribute these
sample programs in any form without payment to IBM, for the purposes of
developing, using, marketing or distributing application programs conforming
to the application programming interface for the operating platform for which
the sample programs are written. These examples have not been thoroughly
186
tested under all conditions. IBM, therefore, cannot guarantee or imply
reliability, serviceability, or function of these programs.
For country-specific notes on the use of WebSphere Voice Response, refer to
the README file located in the directory /usr/lpp/dirTalk/homologation.
The file name is in the format README_homologation.xxxx, where xxxx is
the country/region identifier.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions
worldwide. Other product and service names might be trademarks of IBM or
other companies. A current list of IBM trademarks is available on the Web at
Copyright and trademark information at http://www.ibm.com/legal/
copytrade.shtml.
Adobe, is a registered trademark of Adobe Systems Incorporated in the
United States, and/or other countries.
Java and all Java-based trademarks and logos are trademarks of Oracle
and/or its affiliates.
Microsoft, Windows, and the Windows logo are trademarks of Microsoft
Corporation in the United States, other countries, or both.
Linux is a registered trademark of Linus Torvalds in the United States, other
countries, or both.
Notices
187
188
Glossary
The following terms and abbreviations are defined as they are used in the context of this
book. If you do not find the term or abbreviation you are looking for, see IBM Dictionary of
Computing, McGraw-Hill, 1994 or the IBM: AIX Version 4.3: Glossary, SC23"2513.
A
annotation
An alphanumeric string used to
mark a grammar when it is defined.
When the grammar is used in an
application, both the word and the
alphanumeric string are returned to
the application.
ACD
Automatic call distribution or
automatic call distributor. A feature
that enables incoming calls to one
dialed number to be routed to any
member of the ACD group, all of
whom can provide the same service
to the calling party. Automatic call
distribution enables the efficient
distribution of a high volume of
incoming calls.
agent
A call center employee whose job it
is to handle incoming and outgoing
telephone calls. Synonym for service
representative.
ANI
Automatic Number Identification. A
service offered by commercial
telephone networks, which provides
the directory billing number
associated with a calling party. This
is the telephone number of the
incoming call, which can be used
for call setup or passed by the
switch to WebSphere Voice
Response, which can then use it to
retrieve data from business
databases. Often used as a synonym
for calling number.
announcement
A message played to callers,
without expecting any response
from them. For example: (1)
“Welcome to our Telephone Banking
Service.” (2) “Please wait while your
order is being processed.”
application
A pointer to the Java class that
provides the main entry point to a
voice response service or voice
application.
application group
Contains one or more applications.
application name
The name by which the Java and
VoiceXML environment knows the
application.
application node
A logical entity associated with a
single Java virtual machine (JVM),
which can be used to run Java and
VoiceXML applications. The
application node can be local to the
voice response node, or remote from
it. Contrast with voice response node.
See also remote application system.
au
Format for audio files. When
importing an au file, the encoding,
sample size and sample rate
information is taken from the au file
itself. The data stored in the au file
may be µ-law, a-law or PCM. For
µ-law and a-law it must be single
189
channel with 8-bit sample size. It
may have any sampling rate. For
PCM it may be 8-bit or 16-bit
sample size (mono or stereo). When
exporting to an au file the data
format used is 8-bit, 8kHz, µ-law.
B
base WebSphere Voice Response system
The WebSphere Voice Response
system that provides voice
processing support for voice
applications.
bean
Short for JavaBean, a reusable Java
component.
C
call
Telephone call.
(1) Any person, device, or system
that makes a telephone call. (2)
Often used to refer to any user of a
voice application, even when
WebSphere Voice Response has
made an outbound call and the user
is really the called party.
calling number
The number from which a call is
made.
CallPath
Genesys product that provides
support for call center applications.
CallPath Enterprise Server
Genesys product that provides
support for call center applications.
configuration
The definition of your Java and
190
configuration database
An object in which information
about the Java and VoiceXML
environment is recorded, including
the mapping of called number to
application name. Contains one or
more configurations.
configuration file
A text file used to edit and update
the configuration database.
D
called number
The number dialed by callers to
reach the voice application, or the
number dialed when making a call.
caller
VoiceXML environment, including
the mapping of called numbers to
application names, hosts, nodes,
application groups, applications,
speech recognition services, and
text-to-speech services.
delimiter key
Any of the keys on the telephone
keypad, which a voice application
can designate for use to terminate
input in the same way as the enter
key is used on a computer
keyboard.
disconnect
Terminate a call.
DNIS Dialed number identification
service. A service supplied by the
public telephone network to identify
the number actually dialed. For
example, calls placed to two or
more 1-800 numbers will arrive at
the same call center switch. Upon
arrival, DNIS tells the switch which
one of the 1-800 numbers was
actually dialed. DNIS can be used
by WebSphere Voice Response to
automatically select between several
business database applications.
Often used as a synonym for called
number.
DTMF key
One of the keys on the telephone
keypad. See dual-tone multifrequency
signal.
DTMF sequence
One or more dual-tone multifrequency
signals, which can be sent by an
application.
DTMF signal
See dual-tone multifrequency signal.
dual-tone multifrequency signal
A signal sent by pressing one of the
telephone keys. Each signal is
composed of two different tones.
IP hostname
The name of a host used by Internet
Protocol. In Java and VoiceXML
environment dialogs, specify a name
that is resolvable by your name
server.
Java and VoiceXML environment
The code that allows a Java or
VoiceXML voice application to
communicate with a base
J
E
entry field
An opportunity for the caller to
enter data, by pressing keys or
speaking. A voice application entry
field includes both the voice
description (the “message”) and the
length of time allowed, and, if
necessary, the key to be recognized
as an enter key.
G
group See application group.
H
hang up
Terminate a call.
host
IP address
Internet Protocol address. See IP
hostname
A system with an IP address.
Contains one or more nodes.
I
interactive voice response (IVR)
application
See voice application.
JavaBean
See bean.
Java Development Kit (JDK)
The set of Java technologies made
available to licensed developers by
Sun Microsystems. Each release of
the JDK contains the following: the
Java Compiler, Java Virtual
Machine, Java Class Libraries, Java
Applet Viewer, Java Debugger, and
other tools.
Java Runtime Environment (JRE)
Software comprising the Java virtual
machine and some class libraries,
which enables you to run (as
opposed to develop) Java
applications.
Java Telephony API (JTAPI)
Java Telephony Application
Programming Interface. A portable,
object-oriented application
programming interface for
Java-based computer-telephony
applications, ranging from call
center applications, through voice
response applications, to web page
applications.
Glossary
191
Java Virtual Machine
The platform-specific software that
translates Java instructions into
platform-specific instructions,
thereby allowing a Java program to
run on any platform.
JDK
See Java Development Kit (JDK).
JRE
See Java Runtime Environment (JRE).
JTAPI See Java Telephony API (JTAPI).
JTAPI configuration
A user interface for configuring the
JTAPI section of the CallPath
Enterprise Server profile
initialization file and telephony
applications.
Fred's voice. The locale is used to
select voice segments to play in a
voice application.
M
menu A set of items from which the caller
must select one.
message
Voice or other audio output played
to the caller. Each message is
represented by a MediaType object.
N
node
JtapiPeer
A specific implementation, by a
vendor, of the Java Telephony API
(JTAPI).
JVM
See Java Virtual Machine.
K
key
One of the keys on the telephone
keypad. In some contexts, the
DTMF signal that corresponds to a
key.
L
line identifier
Identifier used for the channel or
line on which an outgoing call is
made.
locale An industry-standard identifier for
language and country, with an
optional use-defined variant. For
example, en_UK is English in the
United Kingdom. You could define
a locale “en_UK_fred” for a
company called Fred, or recorded in
192
(1) In WebSphere Voice Response for
Windows, a physical workstation
that has either a runtime system or a
non-runtime system installed on it.
These nodes can be managed by the
node manager. (2) In WebSphere
Voice Response for AIX, a physical
system in a single system image
(SSI) cluster: see also voice server
node. (3) When running Java and
VoiceXML applications, a logical
entity associated with a single Java
virtual machine (JVM). These nodes
can be managed using the dtjplex
command: see voice response node,
application node.
nodename
The name by which the Java and
VoiceXML environment knows the
node.
P
plug-in
An accessory program used to alter,
enhance or extend the operation of
a parent application program.
Plug-ins are used in the Java and
VoiceXML environment to provide
text-to-speech and speech
recognition services.
V
prompt
Used only as a verb, as in “to
prompt the caller for input”. The
noun for what the application says
is message.
R
RecoService entry
The definition of a speech recognition
technology in the Java and VoiceXML
environment configuration.
RecoType
The name of a speech recognition
technology.
S
single system image (SSI)
A cluster of WebSphere Voice
Response for AIX systems connected
together using a local area network.
Each system (known as a node) in
the cluster is configured as either a
client or a server. See also voice
server node.
variant
See locale.
voice application
A computer application that
communicates information and
interacts with the caller via the
telephone voice channel.
voice recorder
An opportunity for the caller to
record voice data. Contrast with
entry field.
voice response node
A logical entity associated with a
single Java virtual machine (JVM),
which provides for Java and
VoiceXML applications the
connection to the telephony and
voice processing function on the
base WebSphere Voice Response
system. The voice response node
can also be used to run Java and
VoiceXML applications. Contrast
with application node.
speech recognition technology
The software or hardware that
provides speech recognition
capability for your application.
Voice Response simulator
A telephony simulator for testing
Java and VoiceXML applications.
T
voice segment
Recorded voice data to be played to
callers.
text-to-speech technology
The software or hardware that
provides speech synthesis capability
for your application.
TTSService entry
The definition of a text-to-speech
technology in the Java and VoiceXML
environment configuration.
TTSType
The name of a text-to-speech
technology
voice server node
In an AIX single system image (SSI),
the system that contains the voice
segments for all clients in the single
system image.
W
IBM product that provides support
for voice applications.
wav
Format for audio files. A file
Glossary
193
encoding of wav indicates that the
audio file is a Microsoft WAV file.
When importing a WAV file the
encoding, sample size, and
sampling rate information is taken
from in the WAV file itself. The data
stored in the WAV file must be
either in µ-law, a-law or linear
encoding. For µ-law and a-law, it
must be single-channel with 8-bit
sample size and 6kHz or 8kHz
sampling rates. For linear encoding,
it must be mono or stereo and 8 or
16-bit sample size. When exporting
to a WAV file, the data format used
is always 16-bits, mono and 8kHz
sampling rate.
194
List of WebSphere Voice Response and associated
documentation
Here is a list of the documentation for WebSphere Voice Response for AIX and
associated products. PDF and HTML versions of the documentation are
available from the IBM Publications Center at http://www.ibm.com/shop/
publications/order. Hardcopy books, where available, can be ordered through
your IBM representative or at this Web site.
WebSphere Voice Response for AIX documentation can also be found by going
to the IBM Pervasive software Web site at http://www.ibm.com/software/
pervasive, selecting the WebSphere Voice products link, and then selecting
the library link from the WebSphere Voice Response page.
PDF and HTML versions of the WebSphere Voice Response for AIX
publications are available on the CD-ROM supplied with the product. In
addition, WebSphere Voice Response for AIX, WebSphere Voice Response for
Windows, Unified Messaging, and other WebSphere Voice publications are
available together in PDF and HTML formats on a separately-orderable
CD-ROM (order number SK2T-1787).
Note: To read PDF versions of books you need to have the Adobe Acrobat
Reader (it can also be installed as a plug-in to a Web browser). It is available
from Adobe Systems at http://www.adobe.com .
WebSphere Voice Response software
v WebSphere Voice Response for AIX: General Information and Planning,
GC34-7084
v WebSphere Voice Response for AIX: Installation, GC34-7095
v WebSphere Voice Response for AIX: User Interface Guide, SC34-7091
v WebSphere Voice Response for AIX: Configuring the System, SC34-7078
v WebSphere Voice Response for AIX: Managing and Monitoring the System,
SC34-7085
v WebSphere Voice Response for AIX: Designing and Managing State Table
Applications, SC34-7081
v WebSphere Voice Response for AIX: Application Development using State Tables,
SC34-7076
v WebSphere Voice Response for AIX: Developing Java applications, GC34-7082
195
v WebSphere Voice Response
Applications, GC34-7080
SC34-7088
SC34-7089
Protocol, GC34-7093
for AIX: Deploying and Managing VoiceXML and Java
for
for
for
for
for
AIX:
AIX:
AIX:
AIX:
AIX:
Custom Servers, SC34-7079
3270 Servers, SC34-7075
Problem Determination, GC34-7087
Fax using Brooktrout , GC34-7083
Cisco ICM Interface User's Guide, SC34-7077
for AIX: MRCP for State Tables, SC34-7086
for AIX: Programming for the ADSI Feature,
for AIX: Programming for the Signaling Interface,
for AIX: Voice over IP using Session Initiation
for AIX: Using the CCXML Browser, SC34-7092
for AIX: VoiceXML Programmer's Guide, SC34-7117
IBM hardware for use with WebSphere Voice Response
v IBM Quad Digital Trunk Telephony PCI Adapter (DTTA): Installation and User's
Guide, part number 00P3119 (DTTA card)
WebSphere Voice Response related products
WebSphere Voice Server
The documentation for Version 5.1 of WebSphere Voice Server is provided in
the form of an HTML-based information center, and can be found at:
http://publib.boulder.ibm.com/pvc/wvs/51/en/infocenter/index.html
Unified Messaging for WebSphere Voice Response
v Unified Messaging: General Information and Planning, GC34-6398
v Unified Messaging: Subscriber's Guide (Types 0, 1, 2, 3, 4 and 9), SC34-6403
v
v
v
v
Unified
Unified
Unified
Unified
Messaging:
Messaging:
Messaging:
Messaging:
Subscriber's Guide (Types 5, 6, 7 and 8), SC34-6400
Administrator's Guide, SC34-6399
Voice Interface, GC34-6401
Web Services Voicemail API, SC34-6975
Unified Messaging publications can be found by going to the IBM Pervasive
software Web site at http://www.ibm.com/software/pervasive, selecting the
products link, and then selecting the library link from the Unified Messaging
page.
196
AIX and the IBM pSeries computer
For information on AIX Version 6.1, refer to the AIX V6.1 infocenter
For information on System p5 and BladeCenter computers, refer to the IBM
Power hardware infocenter
HACMP
v HACMP for AIX: HACMP 5.4 Concepts and Facilities, SC23-4864-09
v HACMP for AIX: HACMP 5.4 Planning Guide, SC23-4861-09
v HACMP for AIX: HACMP 5.4 Installation Guide, SC23-5209-00
v HACMP for AIX: HACMP 5.4 Administration Guide, SC23-4862-09
v HACMP for AIX: HACMP 5.4 Smart Assist for DB2, SC23-5179-03
v HACMP for AIX: HACMP 5.4 Troubleshooting, SC23-5177-03
v HACMP for AIX: Enhanced Scalability Installation and Administration Guide,
Volume 1, SC23-4284
v HACMP for AIX: Enhanced Scalability Installation and Administration Guide,
Volume 2, SC23-4306
For more information on HACMP, refer to the HACMP Library and the AIX
V6.1 infocenter.
SS7
v SS7 Support for WebSphere Voice Response: SS7 User's Guide, GC34-7090
IBM SS7 Support for WebSphere Voice Response observes the applicable parts
of the following specifications for ISUP:
v CCITT Blue book (1988) Q.701 - Q.707
v ITU-T (formerly CCITT) Recommendations Q.700 - Q.716, Volume VI Fascicle
VI.7
v ITU-T White book (1993) Q.711 - Q.714
v ITU-T (formerly CCITT) Recommendations Q.721 - Q.725, Volume VI Fascicle
VI.8
v ITU-T White book (1992) Q.730 group
v ITU-T White book (1992) Q.761 - Q.764
v ITU-T (formerly CCITT) Recommendations Q.771 - Q.775, Q.791, Volume VI
Fascicle VI.9
ADC
v ADC NewNet AccessMANAGER™: Installation and Maintenance
Manual
List of WebSphere Voice Response and associated documentation
197
v ADC NewNet AccessMANAGER™: User Manual
Integrated Services Digital Network
WebSphere Voice Response ISDN support observes the applicable parts of the
following standards for User Side protocol:
Custom ISDN Standards:
v Northern Telecom DMS/250 Primary Rate Interface NIS A211-4 Release
8, July 1995. (IEC05 level)
v Northern Telecom DMS/100 Primary Rate Interface NIS A211-1 Release
7.05, May 1998. (NA007 & RLT)
v AT&T 5ESS Switch. ISDN Primary Rate Interface Specification. 5E7 and
5E8 Software Release AT&T 235-900-332. Issue 2.00 December 1991
v AT&T 5ESS Switch. ISDN Primary Rate Interface Specification. 5E9
Software Release AT&T 235-900-342. Issue 1.00 November 1993
(National ISDN only)
v Lucent 5ESS-2000 Switch ISDN Primary Rate Interface, Interface
Specification, 5E9(2) and Later Software Releases, 235-900-342. Issue
5.00 January 1997 (National ISDN only)
v AT&T ISDN Primary Rate Specification TR41449 July 1989
v AT&T ISDN Primary Rate Specification TR41459 August 1996
Euro-ISDN
The following documents refer to the specifications required for
observing ISDN:
v TBR4-ISDN; Attachment Requirements For Terminal Equipment To
Connect To An ISDN Using ISDN Primary Rate Access, Edition 1, Nov.
95, English
v CTR 4 - European Communities Commission Decision 94/796/EC
published in the Official Journal of the European Communities L
329, 20 December 94 (ISDN PRA)
National ISDN
National ISDN is described in the following publications:
v National ISDN, SR-NWT-002006, Issue 1, August 1991, published by
Bellcore
v National ISDN-1, SR-NWT-001937, Issue 1, February 1991, published
by Bellcore
v National ISDN-2, SR-NWT-002120, Issue 1, May 1992, published by
Bellcore
INS Net Service 1500
INS Net Service is described in the following publications:
198
v Interface for the INS Net Service Volume 1 (Outline), 7th Edition,
published by Nippon Telegraph and Telephone Corporation
v Interface for the INS Net Service Volume 2 (Layer 1 & 2 Specifications),
4th Edition, published by Nippon Telegraph and Telephone
Corporation
v Interface for the INS Net Service Volume 3 (Layer 3 Circuit Switching),
5th Edition, published by Nippon Telegraph and Telephone
Corporation
Bellcore Specifications for ADSI Telephones
The following Bellcore specification documents contain technical details of the
requirements for ADSI telephones, and the interface to voice response systems
such as WebSphere Voice Response:
v SR-INS-002461: CustomerPremises Equipment Compatibility Considerations for
the Analog Display Services Interface
v TR-NWT-001273: Generic Requirements for an SPCS to Customer Premises
Equipment Data Interface for Analog Display Services
List of WebSphere Voice Response and associated documentation
199
200
Index
A
AAIKeys keyword 102
AAIKVPSeparator keyword 103
accessibility xii
adding voice segments from the base WebSphere Voice
Response system 127
addVS action 148
AIX single system image 115
AIXPortNumber keyword 89
alaw audio encoding format 154, 156, 159
AppClass keyword 84
application
default 65
in an application node
starting 32
in node on local host
querying status 19
starting 19
stopping 20
international 8
keeping separate 28
languages, countries and styles 7
mapping to phone number 62
properties
example configuration entries 60
specifying for application running in a node 60
querying status 22
running
in a node 60
specifying RecoDefinitions 43
starting 21
starting in a node 67
starting in multiple nodes 67
testing and deployment 55
testing on an application node 27
application group
Application keyword 88
application name
purpose 57
specifying in AppName entry 57
application node
configuring 29
installing 29
NodeName keywords 91
purpose 27
setting up 26
starting 32
application node (continued)
starting an application 32
Application Profile
WebSphere Voice Response for AIX
applications
running 55
AppName configuration entry 83
au 154, 156, 157, 159, 160
63
B
base voice segments 118
base_language_identifier parameter 149
base_segment_compression parameter 149
base_segment_identifier parameter 149
base_voice_directory parameter 149
C
call
ensuring that it is answered 63
incoming, mapping to phone number 62
CalledNumberType keyword 103
CallPath
adding support for 33
configuration of voice response node 33, 101, 102
definitions required 36, 37, 38
example configuration entries 33, 34
CallPathService configuration entry
See TelephonyService configuration entry 102
See TelURLLocale configuration entry 101
category, voice segment
definition 115
CCXAppService keyword 90
CCXHTTPServer keyword 92
CCXHTTPServerPort keyword 92
CCXML application logging 69
CCXService configuration entry 86
character_encoding parameter 149, 150, 152, 153, 156,
159
CHPM Socket Port Number 89
config.cfd 14
ConfigManager command
details 175
example 176
configuration database
introduction 5
name 14
purpose 14
required for managing the plex 21
updating 14
201
configuration entries
AppName 83
CCXService 86
example
application group 63
application node 30
application properties 60
CallPath support 33, 34
default application 66
number to application mapping
speech recognition 94
text-to-speech 94
voice response node 23, 24, 25
for speech recognition 41
GroupName 88
HostName 89
NodeName 90
RecoService 95
TelephonyService 102
TelURLLocale 101
TTSService 105
configuration file
editing 14
introduction 5
keywords 77
configuration file, location 17
configuration node
managing the plex from 21
purpose 20
configuration tool 5
configurations, multiple 18
control file, dtjplex 119, 120
copying voice segments 131
copyVS action 150
custom-recorded voice segments 118
D
DefAppService keyword 87
default application
example configuration entries
purpose 65
default locale
introduction 8
default.cff 14
default.cff, location 17
deleteVS action 151
deleting voice segments 130
dtjalarm
purpose 135
dtjcache
purpose 137
dtjconf
details 141
export option 17
import option 18
202
66
62
dtjconf (continued)
introduction 5
list option 18
dtjenv 142
dtjes
purpose 142
dtjflog 143
dtjit 5
dtjlogmon
purpose 144
dtjnlsin 146, 147
dtjplex
addVS action 148
complete list of actions 147
copyVS action 150
deleteVS action 151
details 147
exportVoiceHost action 152
for managing a network of nodes 20
for voice segment operations 118
importVoiceAll action 155
importVoiceHost action 158
listVS action 161
queryApplications action 162
queryCCXML action 163
queryHosts action 163
queryNodes action 164
startAll action 165
startApplication action 165
startHost action 166
startNode action 166
stopAll action 167
stopHost action 168
stopNode action 168
terminateAll action 169
terminateHost action 169
terminateNode action 170
dtjplex control file
example for AIX 120
introduction 119
dtjqapps 19, 171
dtjqhost 19, 171
dtjqnode 19, 171
dtjshost 19, 171
dtjstart 19, 172
dtjstop 20, 172
dtjterm 172
dtjuserlog
purpose 172
dtjver 173
E
Enabled keyword 84, 86, 88, 89, 90, 95, 104, 106
example
ConfigManager command 176
example (continued)
dtjflog 143
dtjnlsin 147
HostManagerImpl command 178
PlexManagerImpl command 178
export_type parameter 122, 153
exporting voice segments to the file system
exportVoiceHost action 152
122
installing
application node 29
speech technology plug-ins 40
text-to-speech plug-ins 47
InternationalAccess keyword 102
internationalization
introduction 8
IPName keyword 89
F
J
failover
MRCP 42, 48
file_encoding parameter 154, 156, 159
file_name parameter 154, 156, 159
file_rate parameter 155, 157, 160
Java voice segment space
definition 114
G
getting help 75
GlobalContext keyword 101
Group keyword 90
GroupName configuration entry 88
gsm audio encoding format 154, 156, 159
H
host
local
querying status 19
querying status of nodes 19
starting voice response node 19
stopping voice response node 20
querying status 22
querying status of nodes 22
starting 21
stopping 22
HostManager 19
purpose 171
starting automatically 19
HostManagerImpl command
details 177
example 178
HostName configuration entry 89
I
IBM support 75
importing voice segments from the base WebSphere
Voice Response system 127
importing voice segments from the file system 124
importVoiceAll action 155
importVoiceHost action 158
incoming call
mapping to application 62
InitialAddresses keyword 104
InitSessionString keyword 95, 106
InitTechnologyString keyword
on RecoService entry 95
on TTSService entry 106
L
language-only locales 9
languages
Java terminology 7
overview 117
See also locale 117
listing voice segments 121
listVS action 161
LocalContext keyword 101
locale
default 8
defining your own variants 9
for speech recognition and text-to-speech 10
introduction 7
language-only 9
purpose 7
used for dividing the Java voice segment space
Locale keyword 84
log files
managing 68
logging
CCXML and Voice XML applications 69
115
M
managing
a network of nodes 20
a single voice response node 19
mapping application to phone number 62
message logs
See log files 68
monitoring
all applications in a node 22
all applications in node on local host 19
all hosts 22
all nodes in a host 22
all nodes on the local host 19
local host 19
voice response node on the local host 19
moving voice segments 133
moving voice segments from one voice response node
to another 134
MRCP
failover 42, 48
Index
203
N
national characters in voice segment names 120
node
adding to a plex 23
application
setting up 26
starting applications 32
log files created by 68
on local host
querying status 19
querying status of applications in 19
starting 19
stopping 20
querying status 22
querying status of applications in 22
running application in 60
starting 21
stopping 22
Node keyword 89
NodeCallPathService keyword
See NodeTelephonyService keyword 93
NodeClassPath keyword 91
NodeDefApp keyword 65
NodeDefAppName keyword 92
NodeDefHost keyword
details 91
purpose 32
NodeDefLocale keyword 92
NodeDefTS keyword
See NodeDefVRNode keyword 91
NodeDefVRNode keyword
details 91
purpose 32
NodeName configuration entry 90
NodeTelephonyService keyword 93
Nuance Recognizer V9.0.3 97
number to application mapping
number-to-application mapping
introduction 6
NumToApp keyword
details 93
purpose 62
O
on RecoService entry
95
P
Parameter keyword 85
Password keyword 104, 105
phone number
adding to base WebSphere Voice Response
system 63
204
phone number (continued)
mapping application to 62
mapping to application name 6
plex
definition 5
PlexManagerImpl command
details 178
example 178
PlugInClass keyword
on RecoService entry 96
on TTSService entry 106
port number
See AIXPortNumber keyword, RMIPortNumber
keyword 89
Port Number, CHPM Socket 89
purpose 65
Q
queryApplications action 162
queryCCXML action 163
queryHosts action 163
querying
status of all applications in a node 22
status of all applications in node on local host
status of all hosts 22
status of all nodes in a host 22
status of all nodes on the local host 19
status of local host 19
queryNodes action 164
R
rc.DTalk4J
purpose 19
RecoDefinition
examples 45
introduction 42
location 43
purpose 43
RecoDefinition keyword
on AppName entry 86
on NodeName entry 94
RecoService configuration entry 95
RecoService entry
purpose 41
RecoService keyword 94
RecoType keyword 96
renaming voice segments 133
replacing voice segments from the base WebSphere
Voice Response system 130
replacing voice segments from the file system 130
RMIPortNumber keyword 89
RootDoc keyword 86
running applications 60
See also starting applications 67
summary of 55
19
S
sample configuration file, location 17
segment_category parameter 149, 150, 152, 155, 157,
160
segment_locale parameter 149, 150, 152, 155, 157, 160
segment_name parameter 149, 151, 152, 155, 158, 161
segment_rate parameter 158, 161
ServerName keyword 104
single system image, AIX 115
Socket Port Number, CHPM 89
speech recognition
installing 40
speech technology, adding 40
SR-INS-002461 Bellcore specification 199
startAll action 165
startApplication action 165
startHost action 166
starting
application node 32
applications
in a node 21, 67
in a node on local host 19
in an application node 32
in multiple nodes 67
nodes 21
startNode action 166
stopAll action 167
stopHost action 168
stopNode action 168
stopping
application in node on local host 20
nodes 22
support, IBM 75
T
target_segment_category parameter 151
target_segment_locale parameter 151
target_segment_name parameter 151
telephone number
See phone number 62
telephony capability, adding 33
TelephonyService
example configuration entries 33, 34
TelephonyService configuration entry 102
TelURLLocale configuration entry 101
terminateAll action 169
terminateHost action 169
terminateNode action 170
testing applications
on an application node 27
text-to-speech
installing 47
TR-NWT-001273 Bellcore specification
TSNode keyword
See VRNode keyword 91
TTSDefinition
examples 51
introduction 48
location 49
purpose 49
TTSDefinition keyword
on AppName entry 86
on NodeName entry 94
TTSService configuration entry 105
TTSService entry
purpose 48
TTSService keyword 95
TTSType keyword 106
199
U
ulaw encoding format 154, 156, 159
updating the configuration database 14
UserName keyword 105
V
variant, locale 9
definition 7
version
Java and VoiceXML environment 173
voice data for applications 113
voice response beans
introduction 1
voice response node
adding to a plex 23
example configuration entries 23, 24, 25
moving voice segments from one to another 134
NodeName keywords 92
on local host
monitoring 19
starting 19
stopping 20
stopping an application 20
running application in 60
used by applications in application node 32
voice segments
adding from the base WebSphere Voice Response
system 127
control file 119, 120
copying 131
deleting 130
exporting to the file system 122
identification and storage 113
Index
205
voice segments (continued)
importing from the file system 124
listing 121
managing 118
moving from one voice response node to
another 134
moving or renaming 133
names that use national characters 120
overview 113
replacing from the base WebSphere Voice Response
system 130
replacing from the file system 130
VoiceXML application logging 69
VRNode keyword 91
vxml 173
W
wav audio encoding format 154, 156, 159
WebSphere Voice Server speech technology
WebSphere Voice Server Version 5.1 97
206
40
Product Number: 5724-I07
GC34-7080-07

WebSphere Voice Response for AIX: Deploying and Managing

Transcription

Similar documents

VBWG Overview and Goals 25 Feb 2010

Java Central Update 1-9-14

Cover

Portfolio Christoph Gerstner - game

Succeeding in Mobile Advertising

Part 2 - SAOUG

Cut Sheet for CPICS-100 family