VoiceXML Studio User Guide
for Cisco Unified Customer Voice Portal
Release 4.0(1)
February, 2007
Corpora te Headquarters
Cisco Systems, Inc.
170 West Tasman D rive
San Jo se, CA 95134-1706
USA
http://www.cisco .com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 526-4100
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL
STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED
WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY
PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET
THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE
SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s
public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS”
WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING,
WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM
A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES,
INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS
MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
CCVP, the Cisco Logo, and the Cisco Square Bridge logo are trademarks of Cisco Systems, Inc.; Changing the Way We Work, Live, Play, and Learn is a service
mark of Cisco Systems, Inc.; and Access Registrar, Aironet, BPX, Catalyst, CCDA, CCDP, CCIE, CCIP, CCNA, CCNP, CCSP, Cisco, the Cisco Certified
Internetwork Expert logo, Cisco IOS, Cisco Press, Cisco Systems, Cisco Systems Capital, the Cisco Systems logo, Cisco Unity, Enterprise/Solver, EtherChannel,
EtherFast, EtherSwitch, Fast Step, Follow Me Browsing, FormShare, GigaDrive, GigaStack, HomeLink, Internet Quotient, IOS, IP/TV, iQ Expertise, the iQ logo, iQ
Net Readiness Scorecard, iQuick Study, LightStream, Linksys, MeetingPlace, MGX, Networking Academy, Network Registrar, Packet, PIX, ProConnect, RateMUX,
ScriptShare, SlideCast, SMARTnet, StackWise, The Fastest Way to Increase Your Internet Quotient, and TransPath are registered trademarks of Cisco Systems, Inc.
and/or its affiliates in the United States and certain other countries.
All other trademarks mentioned in this document or Website are the property of their respective owners. The use of the word partner does not imply a partnership
relationship between Cisco and any other company. (0609R)
Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in
the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.
VoiceXML Studio User Guide for Cisco Unified Customer Voice Portal
© 2007 Cisco Systems, Inc. All rights reserved.
ii
TABLE OF CONTENTS
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Table of Contents
PREFACE .................................................................................................................................................................. VI
PURPOSE .................................................................................................................................................................. VI
AUDIENCE ............................................................................................................................................................... VI
ORGANIZATION ....................................................................................................................................................... VI
RELATED DOCUMENTATION ................................................................................................................................... VII
CONVENTIONS ....................................................................................................................................................... VIII
OBTAINING DOCUMENTATION ................................................................................................................................. IX
Cisco.com............................................................................................................................................................ix
Product Documentation DVD .............................................................................................................................ix
Ordering Documentation ....................................................................................................................................ix
DOCUMENTATION FEEDBACK ................................................................................................................................... X
FIELD ALERTS AND FIELD NOTICES .......................................................................................................................... X
CISCO PRODUCT SECURITY OVERVIEW .................................................................................................................... X
Reporting Security Problems in Cisco Products .................................................................................................xi
OBTAINING TECHNICAL ASSISTANCE ..................................................................................................................... XII
Cisco Technical Support & Documentation Web Site........................................................................................xii
Submitting a Service Request ............................................................................................................................xiii
Definitions of Service Request Severity.............................................................................................................xiii
OBTAINING ADDITIONAL PUBLICATIONS AND INFORMATION ................................................................................ XIV
CHAPTER 1: INTRODUCTION.............................................................................................................................16
LICENSING ...............................................................................................................................................................16
Online Activation ...............................................................................................................................................17
Manual Activation..............................................................................................................................................18
Trial Period........................................................................................................................................................18
PREFERENCES ..........................................................................................................................................................19
CHAPTER 2: BUILDER FOR VOICEXML STUDIO .........................................................................................20
PROJECT INTRODUCTION .........................................................................................................................................21
Creating a Cisco Unified CVP Project. .............................................................................................................21
Importing an Existing Cisco Unified CVP Project.............................................................................................26
Renaming a Cisco Unified CVP Project ............................................................................................................29
Deleting a Cisco Unified CVP Project...............................................................................................................31
Backing Up a Cisco Unified CVP Project..........................................................................................................33
PROJECT PROPERTIES ..............................................................................................................................................34
General Settings.................................................................................................................................................35
Audio Settings ....................................................................................................................................................37
Endpoint Settings ...............................................................................................................................................39
Root Document Settings .....................................................................................................................................41
DOCUMENTER..........................................................................................................................................................43
Documenter Output............................................................................................................................................47
VERSION CONTROL INTEGRATION ...........................................................................................................................49
Using Version Control to Support Multiple Developers ....................................................................................49
Using CVS from within Cisco Unified CVP VoiceXML Studio ..........................................................................51
Links to Additional Version Control Plug-ins....................................................................................................52
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE..........................................................................................53
ELEMENTS VIEW .....................................................................................................................................................54
Standard Versus Configurable ...........................................................................................................................54
Configurable Element Types ..............................................................................................................................55
Configurable Action Elements ...........................................................................................................................55
Definition ............................................................................................................................................................................ 55
iii
TABLE OF CONTENTS
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Configurable Decision Elements........................................................................................................................56
Definition ............................................................................................................................................................................ 56
Voice Elements...................................................................................................................................................56
Definition ............................................................................................................................................................................ 56
STANDARD ELEMENTS .............................................................................................................................................57
Standard Action Elements ..................................................................................................................................57
Definition ............................................................................................................................................................................ 57
Configuring a Standard Action Element ............................................................................................................................ 58
Standard Decision Elements ..............................................................................................................................59
Definition ............................................................................................................................................................................ 59
Configuring a Standard Decision Element......................................................................................................................... 59
Decision Editor ................................................................................................................................................................... 61
FLAG ELEMENTS......................................................................................................................................................64
Definition ...........................................................................................................................................................64
Defining a Flag Element ....................................................................................................................................64
VOICEXML INSERT ELEMENTS ...............................................................................................................................65
Definition ...........................................................................................................................................................65
Defining a VoiceXML Insert Element ................................................................................................................66
HOTEVENT ...............................................................................................................................................................67
Definition ...........................................................................................................................................................67
Defining a Hotevent ...........................................................................................................................................68
HOTLINKS ................................................................................................................................................................68
Definition ...........................................................................................................................................................68
Defining a Hotlink..............................................................................................................................................69
APPLICATION TRANSFER .........................................................................................................................................70
Definition ...........................................................................................................................................................70
Defining an Application Transfer ......................................................................................................................70
PAGE ENTRIES & CONNECTORS ...............................................................................................................................71
Definition ...........................................................................................................................................................71
Defining a Page Entry........................................................................................................................................72
Defining a Page Connector................................................................................................................................72
COMMENT ...............................................................................................................................................................73
Definition ...........................................................................................................................................................73
Defining a Comment ..........................................................................................................................................73
HANG UP .................................................................................................................................................................74
Definition ...........................................................................................................................................................74
Defining a Hang Up...........................................................................................................................................74
START OF CALL .......................................................................................................................................................74
Definition ...........................................................................................................................................................74
Defining the Start of Call ...................................................................................................................................75
ERROR ELEMENT .....................................................................................................................................................75
Definition ...........................................................................................................................................................75
Defining an Error Element.................................................................................................................................76
SUBDIALOG ELEMENTS............................................................................................................................................77
Definition ...........................................................................................................................................................77
Defining a Subdialog Start.................................................................................................................................77
Defining a Subdialog Return..............................................................................................................................78
Importing Voice Applications from Previous Versions ......................................................................................79
THE CALLFLOW EDITOR ..........................................................................................................................................79
Selecting, Resizing, and Repositioning Elements ...............................................................................................80
Element Naming.................................................................................................................................................80
Connecting Elements..........................................................................................................................................81
Angled Lines....................................................................................................................................................................... 83
Skipping Call Flow.............................................................................................................................................84
Using Skip Call Flow .........................................................................................................................................85
Cut, Copy, and Paste..........................................................................................................................................88
iv
TABLE OF CONTENTS
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Undo and Redo...................................................................................................................................................89
Zoom In/Zoom Out .............................................................................................................................................89
Element Groups..................................................................................................................................................90
Creating an Element Group ................................................................................................................................................ 90
Configuring an Element Group .......................................................................................................................................... 91
Element Group Exit States.................................................................................................................................................. 92
Element Group Templates .................................................................................................................................................. 94
Element Comments.............................................................................................................................................95
ELEMENT CONFIGURATION VIEW ............................................................................................................................96
Element Configuration Tabs ..............................................................................................................................97
The General Tab ................................................................................................................................................97
Dynamic Configurations..................................................................................................................................................... 97
Custom Logging ................................................................................................................................................................. 98
Associating a UID With the Call........................................................................................................................................ 99
The Settings Tab.................................................................................................................................................99
Settings................................................................................................................................................................................ 99
VoiceXML Properties (Voice Elements Only) ................................................................................................................ 100
The Audio Tab (Voice Elements Only).............................................................................................................101
Audio Groups.................................................................................................................................................................... 101
Audio Items....................................................................................................................................................................... 104
The Data Tab ...................................................................................................................................................107
Creating Element Data...................................................................................................................................................... 107
Creating Session Data....................................................................................................................................................... 108
Substitution ......................................................................................................................................................109
PROMPT MANAGER ...............................................................................................................................................112
Prompt Manager View .....................................................................................................................................112
Using the Prompt Manager..............................................................................................................................113
Validating Applications....................................................................................................................................114
Deploying Applications....................................................................................................................................115
Local Deploy..................................................................................................................................................................... 116
Remote Deploy ................................................................................................................................................................. 117
Archive Deploy................................................................................................................................................................. 118
v
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Preface
Purpose
This document describes the full range of functionality provided by Cisco Unified CVP VoiceXML Studio. It is a
hands-on user guide, providing detailed information about each feature that Studio provides, as well as information
about the overall functionality of Studio for voice application development.
Audience
This document is intended for voice application designers who are using Cisco Unified CVP VoiceXML Studio.
Organization
Chapter
Description
Chapter 1: Introduction
Explains the licensing process for Cisco Unified CVP
VoiceXML Studio and how to set preferences.
Chapter 2: Builder for VoiceXML Studio
Explains how to create and work with a Builder project;
how to set project properties; how to use the documenter
feature; and how to implement version control.
Chapter 3: Cisco Unified CVP Workspace
Describes the elements and features of Cisco Unified CVP
VoiceXML Studio and how to validate and deploy
applications.
vi
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Related Documentation
Planning Guide for Cisco Unified Customer Voice Portal provides a product overview and describes how
to plan a Unified CVP deployment.
Installation and Upgrade Guide for Cisco Unified Customer Voice Portal describes how to install Unified
CVP software, perform initial configuration, and upgrade.
Configuration and Administration Guide for Cisco Unified Customer Voice Portal describes how to set up,
run, and administer the Cisco Unified CVP product, including associated configuration.
Operations Console Online Help for Cisco Unified Customer Voice Portal describes how to use the
Operations Console to configure Unified CVP solution components.
Troubleshooting Guide for Cisco Unified Customer Voice Portal describes how to isolate and solve
problems in the Unified CVP solution.
Reporting Guide for Cisco Unified Customer Voice Portal describes the Reporting Server, including how to
configure and manage it, and discusses the hosted database.
Element Specifications for Cisco Unified Customer Voice Portal provides specifications for the elements
included with Cisco Unified CVP VoiceXML Server.
VoiceXML Server User Guide for Cisco Unified Customer Voice Portal describes the Unified CVP
VoiceXML software.
Say It Smart Specifications for Cisco Unified Customer Voice Portal describes in detail the functionality
and configuration options for all Unified CVP VoiceXML Say It Smart™ plug-ins included with the
software.
Programming Guide for Cisco Unified Customer Voice Portal describes how to build components that run
on the Unified CVP VoiceXML Server.
Javadocs for Cisco Unified Customer Voice Portal are a group of HTML pages fully describing the entire
Java application programming interfaces (APIs) to Unified CVP VoiceXML. Developers use Javadocs in
conjunction with the Programming Guide to understand how to build custom components that run on the
Unified CVP VoiceXML Server.
For additional information about Unified ICME, see the Cisco Web site
(http://www.cisco.com/en/US/products/sw/custcosw/ps1001/tsd_products_support_series_home.html).
vii
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Conventions
This manual uses the following conventions:
Convention
Description
boldface font
Boldface font is used to indicate commands, such as user entries, keys, buttons, and folder and
submenu names. For example:
italic font
window font
<>
Choose Edit > Find.
Click Finish.
Italic font is used to indicate the following:
To introduce a new term. Example: A skill group is a collection of agents who share
similar skills.
For emphasis. Example:
Do not use the numerical naming convention.
A syntax value that the user must replace. Example:
IF (condition, true-value, false-value)
A book title. Example:
See the Cisco CRS Installation Guide.
Window font, such as Courier, is used for the following:
Text as it appears in code or that the window displays. Example:
<html><title>Cisco Systems,Inc. </title></html>
File names. Example: tserver.properties.
Directory paths. Example:
C:\Program Files\Adobe
Angle brackets are used to indicate the following:
For arguments where the context does not allow italic, such as ASCII output.
A character string that the user enters but that does not appear on the window such as a
password.
viii
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Obtaining Documentation
Cisco documentation and additional literature are available on Cisco.com. Cisco also provides several ways to
obtain technical assistance and other technical resources. These sections explain how to obtain technical information
from Cisco Systems.
Cisco.com
You can access the most current Cisco documentation at this URL:
http://www.cisco.com/techsupport
You can access the Cisco Web site at this URL:
http://www.cisco.com
You can access international Cisco Web sites at this URL:
http://www.cisco.com/public/countries_languages.shtml
Product Documentation DVD
The Product Documentation DVD is a comprehensive library of technical product documentation on a portable
medium. The DVD enables you to access multiple versions of installation, configuration, and command guides for
Cisco hardware and software products. With the DVD, you have access to the same HTML documentation that is
found on the Cisco Web site without being connected to the Internet. Certain products also have .PDF versions of
the documentation available.
The Product Documentation DVD is available as a single unit or as a subscription. Registered Cisco.com users
(Cisco direct customers) can order a Product Documentation DVD (product number DOC-DOCDVD= or DOCDOCDVD=SUB) from Cisco Marketplace at this URL:
http://www.cisco.com/go/marketplace/
Ordering Documentation
Registered Cisco.com users may order Cisco documentation at the Product Documentation Store in the Cisco
Marketplace at this URL:
http://www.cisco.com/go/marketplace/
Nonregistered Cisco.com users can order technical documentation from 8:00 a.m. to 5:00 p.m. (0800 to 1700) PDT
by calling 1 866 463-3487 in the United States and Canada, or elsewhere by calling 011 408 519-5055. You can also
order documentation by e-mail at tech-doc-store-mkpl@external.cisco.com or by fax at 1 408 519-5001 in the
United States and Canada, or elsewhere at 011 408 519-5001.
ix
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Documentation Feedback
You can rate and provide feedback about Cisco technical documents by completing the online feedback form that
appears with the technical documents on Cisco.com.
You can submit comments about Cisco documentation by using the response card (if present) behind the front cover
of your document or by writing to the following address:
Cisco Systems
Attn: Customer Document Ordering
170 West Tasman Drive
San Jose, CA 95134-9883
We appreciate your comments.
Field Alerts and Field Notices
Cisco products may be modified or key processes may be determined important. These are announced through use
of the Cisco Field Alert mechanism. You can register to receive Field Alerts through the Field Alert Tool on
Cisco.com. This tool enables you to create a profile to receive announcements by selecting all products of interest.
Log into www.cisco.com; then access the tool at
http://tools.cisco.com/Support/PAT/do/ViewMyProfiles.do?local=en.
Cisco Product Security Overview
Cisco provides a free online Security Vulnerability Policy portal at this URL:
http://www.cisco.com/en/US/products/products_security_vulnerability_policy.html
From this site, you will find information about how to:
Report security vulnerabilities in Cisco products.
Obtain assistance with security incidents that involve Cisco products.
Register to receive security information from Cisco.
A current list of security advisories, security notices, and security responses for Cisco products is available at
this URL:
http://www.cisco.com/go/psirt
To see security advisories, security notices, and security responses as they are updated in real time, you can
subscribe to the Product Security Incident Response Team Really Simple Syndication (PSIRT RSS) feed.
Information about how to subscribe to the PSIRT RSS feed is found at this URL:
http://www.cisco.com/en/US/products/products_psirt_rss_feed.html
x
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Reporting Security Problems in Cisco Products
Cisco is committed to delivering secure products. We test our products internally before we release them, and we
strive to correct all vulnerabilities quickly. If you think that you have identified a vulnerability in a Cisco product,
contact PSIRT:
For Emergencies only—security-alert@cisco.com
An emergency is either a condition in which a system is under active attack or a condition for which a
severe and urgent security vulnerability should be reported. All other conditions are considered
nonemergencies.
For Nonemergencies—psirt@cisco.com
In an emergency, you can also reach PSIRT by telephone:
1 877 228-7302
1 408 525-6532
We encourage you to use Pretty Good Privacy (PGP) or a compatible product (for example, GnuPG) to encrypt any
sensitive information that you send to Cisco. PSIRT can work with information that has been encrypted with PGP
versions 2.x through 9.x.
Never use a revoked or an expired encryption key. The correct public key to use in your correspondence with PSIRT
is the one linked in the Contact Summary section of the Security Vulnerability Policy page at this URL:
http://www.cisco.com/en/US/products/products_security_vulnerability_policy.html
The link on this page has the current PGP key ID in use.
If you do not have or use PGP, contact PSIRT at the aforementioned e-mail addresses or phone numbers before
sending any sensitive material to find other means of encrypting the data.
xi
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Obtaining Technical Assistance
Cisco Technical Support provides 24-hour-a-day award-winning technical assistance. The Cisco Technical Support
& Documentation Web site on Cisco.com features extensive online support resources. In addition, if you have a
valid Cisco service contract, Cisco Technical Assistance Center (TAC) engineers provide telephone support. If you
do not have a valid Cisco service contract, contact your reseller.
Cisco Technical Support & Documentation Web Site
The Cisco Technical Support & Documentation Web site provides online documents and tools for troubleshooting
and resolving technical issues with Cisco products and technologies. The Web site is available 24 hours a day, at
this URL:
http://www.cisco.com/techsupport
Access to all tools on the Cisco Technical Support & Documentation Web site requires a Cisco.com user ID and
password. If you have a valid service contract but do not have a user ID or password, you can register at this URL:
http://tools.cisco.com/RPF/register/register.do
Note
Use the Cisco Product Identification (CPI) tool to locate your product serial number before
submitting a Web or phone request for service. You can access the CPI tool from the Cisco
Technical Support & Documentation Web site by clicking theTools & Resources link under
Documentation & Tools. Choose Cisco Product Identification Tool from the Alphabetical
Index drop-down list, or click the Cisco Product Identification Tool link under Alerts &
RMAs. The CPI tool offers three search options: by product ID or model name; by tree view;
or for certain products, by copying and pasting show command output. Search results show
an illustration of your product with the serial number label location highlighted. Locate the
serial number label on your product and record the information before placing a service call.
xii
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Submitting a Service Request
Using the online TAC Service Request Tool is the fastest way to open S3 and S4 service requests (S3 and S4 service
requests are those in which your network is minimally impaired or for which you require product information). After
you describe your situation, the TAC Service Request Tool provides recommended solutions. If your issue is not
resolved using the recommended resources, your service request is assigned to a Cisco engineer. The TAC Service
Request Tool is located at this URL:
http://www.cisco.com/techsupport/servicerequest
For S1 or S2 service requests, or if you do not have Internet access, contact the Cisco TAC by telephone (S1 or S2
service requests are those in which your production network is down or severely degraded). Cisco engineers are
assigned immediately to S1 and S2 service requests to help keep your business operations running smoothly.
To open a service request by telephone, use one of the following numbers:
Asia-Pacific: +61 2 8446 7411 (Australia: 1 800 805 227)
EMEA: +32 2 704 55 55
USA: 1 800 553-2447
For a complete list of Cisco TAC contacts, go to this URL:
http://www.cisco.com/techsupport/contacts
Definitions of Service Request Severity
To ensure that all service requests are reported in a standard format, Cisco has established severity definitions.
Severity 1 (S1)—An existing network is down, or there is a critical impact to your business operations. You and
Cisco will commit all necessary resources around the clock to resolve the situation.
Severity 2 (S2)—Operation of an existing network is severely degraded, or significant aspects of your business
operations are negatively affected by inadequate performance of Cisco products. You and Cisco will commit fulltime resources during normal business hours to resolve the situation.
Severity 3 (S3)—Operational performance of the network is impaired, while most business operations remain
functional. You and Cisco will commit resources during normal business hours to restore service to satisfactory
levels.
Severity 4 (S4)—You require information or assistance with Cisco product capabilities, installation, or
configuration. There is little or no effect on your business operations.
xiii
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Obtaining Additional Publications and Information
Information about Cisco products, technologies, and network solutions is available from various online and printed
sources.
The Cisco Product Quick Reference Guide is a handy, compact reference tool that includes brief product
overviews, key features, sample part numbers, and abbreviated technical specifications for many Cisco
products that are sold through channel partners. It is updated twice a year and includes the latest Cisco
offerings. To order and find out more about the Cisco Product Quick Reference Guide, go to this URL:
http://www.cisco.com/go/guide
Cisco Marketplace provides a variety of Cisco books, reference guides, documentation, and logo
merchandise. Visit Cisco Marketplace, the company store, at this URL:
http://www.cisco.com/go/marketplace/
Cisco Press publishes a wide range of general networking, training and certification titles. Both new and
experienced users will benefit from these publications. For current Cisco Press titles and other information,
go to Cisco Press at this URL:
http://www.ciscopress.com
Packet magazine is the Cisco Systems technical user magazine for maximizing Internet and networking
investments. Each quarter, Packet delivers coverage of the latest industry trends, technology breakthroughs,
and Cisco products and solutions, as well as network deployment and troubleshooting tips, configuration
examples, customer case studies, certification and training information, and links to scores of in-depth
online resources. You can access Packet magazine at this URL:
http://www.cisco.com/packet
iQ Magazine is the quarterly publication from Cisco Systems designed to help growing companies learn
how they can use technology to increase revenue, streamline their business, and expand services. The
publication identifies the challenges facing these companies and the technologies to help solve them, using
real-world case studies and business strategies to help readers make sound technology investment
decisions. You can access iQ Magazine at this URL:
http://www.cisco.com/go/iqmagazine
or view the digital edition at this URL:
http://ciscoiq.texterity.com/ciscoiq/sample/
Internet Protocol Journal is a quarterly journal published by Cisco Systems for engineering professionals
involved in designing, developing, and operating public and private internets and intranets. You can access
the Internet Protocol Journal at this URL:
http://www.cisco.com/ipj
Networking products offered by Cisco Systems, as well as customer support services, can be obtained at
this URL:
http://www.cisco.com/en/US/products/index.html
xiv
PREFACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Networking Professionals Connection is an interactive Web site for networking professionals to share
questions, suggestions, and information about networking products and technologies with Cisco experts
and other networking professionals. Join a discussion at this URL:
http://www.cisco.com/discuss/networking
World-class networking training is available from Cisco. You can view current offerings at this URL:
http://www.cisco.com/en/US/learning/index.html
xv
CHAPTER 1: INTRODUCTION
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Chapter 1: Introduction
Cisco Unified CVP VoiceXML Studio is a platform for creating, managing, and deploying
sophisticated voice applications. Studio is built using the Eclipse framework, though no
knowledge of Eclipse is necessary to work with Studio.
VoiceXML Studio acts as a container in which features—called plug-ins—are encapsulated.
Unified CVP VoiceXML Studio currently comes with a single plug-in, Cisco Unified CVP
Builder for VoiceXML Studio, which is used to construct voice applications. The only
components that need to be constructed outside VoiceXML Studio are those that require
programming (see the Programming Guide for Cisco Unified Customer Voice Portal for more
details).
This guide describes the features of Unified CVP VoiceXML Studio and shows you how to
create world-class voice applications.
Licensing
When you install Cisco Unified CVP VoiceXML Studio and start it for the first time, the
software will prompt you to activate it. Additionally, each time Cisco Unified CVP VoiceXML
Studio is started without an active license, you will be prompted to activate the software.
16
CHAPTER 1: INTRODUCTION
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Online Activation
On machines with Internet access, activation can be performed on line. You will be prompted for
an installation key and Cisco Unified CVP VoiceXML Studio will automatically download the
most recent license associated with the key you provide.
17
CHAPTER 1: INTRODUCTION
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Manual Activation
There is also a way to activate the product when an Internet connection is unavailable. You can
request a license key from Cisco Software License Registration
(http://www.cisco.com/go/license) by using a different computer with Internet access. In order to
do so, an installation key and system ID are required. This information can be obtained by
navigating to Help->Activation... within Cisco Unified CVP VoiceXML Studio.
Once the Cisco Software License Registration website validates the information provided, a
license will be presented. This license can be entered manually into Cisco Unified CVP
VoiceXML Studio to activate the software.
Trial Period
Cisco Unified CVP VoiceXML Studio can be used for a trial period of 7 days before it needs to
be activated.
18
CHAPTER 1: INTRODUCTION
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Preferences
Items within the Preferences menu can be set by choosing Window->Preferences from the
menu bar. Most of the settings listed here apply to the Eclipse platform; however, those listed
under Cisco Unified CVP are specifically intended for Cisco Unified CVP VoiceXML Studio
(see below). You may wish to change some of these from their default settings. If you change
any of them, it is recommended that you exit and restart Cisco Unified CVP VoiceXML Studio
so your new settings can take effect.
Expand elements in Elements View. This setting controls whether elements in the
Elements View appear fully expanded or collapsed (the default).
Expand call flow elements in Outline View. This setting controls whether call flow
elements in the Outline View appear fully expanded (the default) or collapsed.
Call Flow Theme. This setting controls which look and feel (theme) to use for elements
in the Callflow Editor. There are two options:
o VoiceXML Studio v4.0 is the new look and feel introduced in the Cisco Unified
CVP VoiceXML Studio v4.0 release. This is the default setting.
o Classic is the old look and feel from the previous Cisco Unified CVP VoiceXML
Studio releases.
19
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Chapter 2: Builder for VoiceXML Studio
Cisco Unified CVP Builder for VoiceXML Studio is a graphical user interface for creating and
managing voice applications for deployment on Cisco Unified CVP VoiceXML Server, the
runtime framework for Cisco Unified CVP voice applications.
A complete dynamic voice application can be constructed within the Builder, including call flow
and audio elements. The philosophy behind the Cisco Unified CVP Builder is to provide an
intuitive, easy-to-use tool for building complex voice applications.
The conception and design of voice applications makes use of flowcharts to represent the
application call flow. Because flowcharts outline actions that are performed, not the processes
behind these actions, they are an effective tool for representing the overall logic of the call flow.
The flowcharting process is useful for mapping all the permutations of a call to ensure that all
possible outcomes are handled appropriately. The schematic nature of flowcharts also make it
easier for you to see where callers can get lost or stuck as well as how the call flow can be
improved.
The Cisco Unified CVP Builder works as a flowcharting program tailored specifically for
building voice applications. Most of the familiar features of a flowcharting tool are present in the
Builder, such as a palette of shapes that can be dragged and dropped onto a workspace and
labeled, lines connecting those shapes, multiple pages, and much more. The Builder fulfills
almost all the needs of a voice application designer and greatly accelerates the development of
even the most complex call flows.
Cisco Unified CVP Projects
Cisco Unified CVP VoiceXML Studio uses a "project" paradigm to gracefully manage voice
applications and their associated resources. The following section shows you how to create,
configure, import and modify Cisco Unified CVP projects. It also provides instructions for
importing applications created in previous versions of Cisco Unified CVP Studio.
20
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Project Introduction
A Cisco Unified CVP Project contains all the resources required to build and deploy Cisco
Unified CVP voice applications that will run on Cisco Unified CVP VoiceXML Server.
The callflow folder contains all the xml files which make up that applications call flow and
element configurations. The app.callflow file will open the Callflow Editor and recreate the
call flow based on the information found in these files. Every time the application is saved, these
files are updated.
The deploy folder contains any extra resources required for deployment; for example, local
custom elements and Say It Smart™ plug-ins.
Creating a Cisco Unified CVP Project.
1. To create a Cisco Unified CVP Project, choose File->New->Cisco Unified CVP Project.
21
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
2. Enter a name for the new Cisco Unified CVP Project and select Next.
Leave Use default checked to create the new project in the default workspace directory.
3. Enter the General Settings for the new Cisco Unified CVP Project and select Next.
General Settings can always be changed later.
22
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
4. Enter the Audio Settings for the new Cisco Unified CVP Project and select Next. Audio
Settings can always be changed later.
5. Enter the Endpoint Settings for the new Cisco Unified CVP Project and select Next.
Endpoint Settings can always be changed later.
23
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
6. Enter the Root Document Settings for the new Cisco Unified CVP Project and select
Finish. Root Document Settings can always be changed later.
The new Cisco Unified CVP Project will appear in the Navigator View.
24
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
The new application’s call flow will automatically open in the Callflow Editor.
25
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Importing an Existing Cisco Unified CVP Project
Importing an existing Cisco Unified CVP Project into the workspace will make the project
available in the Navigator View; however, it will not copy the contents of that Cisco Unified
CVP Project to the workspace directory.
It is recommended that all Cisco Unified CVP Projects be kept in the workspace directory for
ease of management, so be sure to copy projects to the
CVP_HOME\VXMLStudio\eclipse\workspace directory before importing them.
1. To import an existing Cisco Unified CVP Project, choose File->Import.
2. Select Existing Cisco Unified CVP Project into Workspace and select Next.
26
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
3. Enter the location of the existing Cisco Unified CVP Project you wish to import or select
Browse to locate it within your file system.
4. Once you locate your existing Cisco Unified CVP Project, select Finish.
27
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
The imported Cisco Unified CVP Project will appear in the Navigator View.
The imported application’s call flow will automatically open in the Callflow Editor.
28
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Renaming a Cisco Unified CVP Project
1. To rename a Cisco Unified CVP Project, right-click on the project folder in the Navigator
View and select Rename.
29
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
2. Enter in a new name for the project and press Enter.
30
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Deleting a Cisco Unified CVP Project
1. To delete a Cisco Unified CVP Project, right-click on the project folder in the Navigator
View and select Delete.
31
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
2. To permanently delete the Cisco Unified CVP Project's files as well as remove it from the
Navigator View, choose Also delete contents under.... Alternatively, to remove the
Cisco Unified CVP Project from the Navigator View but leave its files on the file system,
choose Do not delete contents. This option is the default.
3. Click Yes to delete the Cisco Unified CVP Project.
32
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Backing Up a Cisco Unified CVP Project
The files contained in a Cisco Unified CVP Project store all the information about the voice
application that is needed for it to be deployed to Cisco Unified CVP VoiceXML Server,
imported to another VoiceXML Studio instance, or edited in the current VoiceXML Studio
environment.
To back up a Cisco Unified CVP Project, the Cisco Unified CVP Project's files can be copied
anywhere within the file system. By default, Cisco Unified CVP Projects are created in the
CVP_HOME\VXMLStudio\eclipse\workspace directory. Copy the Cisco Unified CVP Project's
files from this directory to the desired backup location.
When a Cisco Unified CVP Project is deployed, a separate set of files is created for use on Cisco
Unified CVP VoiceXML Server. This VoiceXML Server version of the voice application cannot
be imported to the VoiceXML Studio environment and is only for use on Cisco Unified CVP
VoiceXML Server. Therefore, when creating a backup of a voice application, it is strongly
suggested that you store the VoiceXML Studio version of the application.
33
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Project Properties
Cisco Unified CVP Project properties can be set on project creation or modified anytime during
the project development cycle.
Properties are easily accessible by right-clicking on a project's folder in the Navigator View and
selecting Properties from the menu.
34
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
General Settings
The following describes the General Settings of a Cisco Unified CVP voice application.
Deploy Version. This sets the version of Cisco Unified CVP VoiceXML Server to
which to deploy an application. As Cisco Unified CVP VoiceXML Studio applications
can run on different versions of VoiceXML Server, this field must match the version of
VoiceXML Server running in the deployment environment. Refer to the VoiceXML
Server User Guide for Cisco Unified Customer Voice Portal for more information on
running an application deployed to VoiceXML Server.
Maintainer. This contains the e-mail address of the application administrator. If the
voice browser encounters errors (usually caused by missing audio files or other
configuration problems) it sends a message to this e-mail address. Since the voice
browser is not part of Cisco Unified CVP VoiceXML Server, this is a convenient way to
learn the details of any errors that occurred while the voice browser was interpreting the
VoiceXML document.
Language. This contains the language to specify in each VoiceXML document's
xml:lang attribute. By default it is blank, indicating that the voice browser's default
language will be used. The information here must conform to the format required in
XML for specifying languages (e.g. "en-US").
35
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Encoding. This contains the encoding to use when creating the VoiceXML document.
By default it is blank, indicating the use of the operating system / application server
default encoding.
Subdialog. This defines whether an application will be invoked as a subdialog (true) or
not (false). If the Subdialog setting is set to true, the application must begin and end with
Subdialog Start and Subdialog Return elements, respectively.
Session Timeout. This value sets the length of time a session on the application server is
allowed to linger if no activity is detected. Cisco recommends that this value not be
changed from the default unless the designer understands sessions and application
servers.
VoiceXML Gateway. This sets the voice browser the application will be hosted on.
There can only be a single voice browser per application. Cisco Unified CVP supports
various commercial voice browsers. Adding support for a voice browser involves
installing a Gateway Adapter for that browser. Refer to the Hardware and Software
System Specification for Cisco Unified CVP Customer Voice Portal for a list of
supported browsers.
User Management. Clicking on the check box activates the User Management system
for the application. When set, the database type must be given and the JNDI name
identifying the database provided in the text box. Currently, SQLServer and MySQL
databases are supported. By default, the User Management system is off.
Loggers. The Loggers section provides the ability to configure the logging levels for the
voice application. Configurations for Cisco Unified CVP logging plug-ins are specified
by choosing Add.... This will bring up a dialog box where the logging configuration file
reference and logging plug-in types are defined. The Edit... button enables modification
of previously defined loggers and Remove will delete the selected logger configuration.
Defined loggers will be executed in the order that they appear. The logging order can be
changed by moving particular configurations up or down within the loggers section.
Refer to the VoiceXML Server User Guide for Cisco Unified Customer Voice Portal for
more information on specific loggers.
36
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Audio Settings
The following describes the Audio Settings of a Cisco Unified CVP voice application.
Generic Error Message. This TTS message will be played if Cisco Unified CVP
VoiceXML Server encounters an unexpected error during the course of a call. The idea is
to avoid abruptly hanging up on a caller when an error occurs that prevents the
application from continuing. The system will hang up after this message is played, so it
should be tailored accordingly. This setting is required.
Error Audio URI. This is a pre-recorded audio file containing the error message to be
played when the server encounters an unexpected error during the course of a call. When
the audio file is provided, the TTS message specified in the Generic Error Message
setting will only be used as a backup when this audio file cannot be found or is corrupted.
A URI to the audio file is required, since it must be made available to the voice browser.
For example, http://my.domain.com/audio/error.wav. By default, Cisco Unified CVP
VoiceXML Studio references an audio file provided by Cisco.
37
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Suspended Message. This is a TTS message that will be played to the caller when the
application is suspended. This message typically says that the service is temporarily
down and asks the caller to call back. This setting is required.
Suspended Audio URI. This is a URI to a pre-recorded audio file containing the
message to play when the application is suspended. The TTS message specified in the
Suspended Message setting above is played only when the audio file specified here is not
found or corrupted. By default, Cisco Unified CVP VoiceXML Studio references an
audio file provided by Cisco.
Initial On-Hold Audio URI / Main On-Hold Audio URI. Each simultaneous call to
Cisco Unified CVP VoiceXML Server takes up a Cisco Unified CVP VoiceXML Server
port. The license purchased from Cisco specifies how many ports the system can support.
If a call is received when all ports are taken, Cisco Unified CVP VoiceXML Server puts
the caller on hold, playing the initial designer-specified pre-recorded audio referenced in
the setting named Initial On-Hold Audio URI. When done playing, Cisco Unified CVP
VoiceXML Server checks if a port is available. If not, it will play the designer-specified
pre-recorded audio referenced in the setting named Main On-Hold Audio URI followed
by another check. The cycle continues by repeatedly playing the main on hold audio and
checking for a port. Once a port is available, the caller starts interacting with the
application. The initial on-hold message is intended to be a greeting and a notice to hold.
The main on-hold message is intended to be a "filler" message that is suitable for
repeating multiple times. The length of these messages determines the frequency which
the server checks for an available port. By default, Cisco Unified CVP VoiceXML Studio
references audio files provided by Cisco that contain a 30-second pause within it to
lengthen the amount of time it takes between checks.
Default Audio Path URI. This setting contains a partial URI to a path containing the
audio content for this voice application. If set, the designer need only provide the audio
file name while building the application, knowing that this path will be prepended. If the
audio for this application is stored in multiple areas this field should be left blank. In this
case, the developer will have to provide the full URI for each audio file used by the
application. The default audio path can save a lot of time when moving applications
across disparate systems since only the default audio path need change rather than the
URI for each audio file in the application.
38
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Endpoint Settings
The following describes the Endpoint Settings of a Cisco Unified CVP voice application.
On Application Start. The On Application Start section specifies the Java classes that
are executed when the voice application is started on the target application server.
Configurations for On Application Start classes are specified by choosing Add.... This
will bring up a dialog box where the classes are added. The Edit... button enables
modification of previously defined On Application Start classes. Remove will delete the
selected class. Defined classes will be executed in the order that they appear in the On
Application Start section. The execution order can be changed by moving particular
classes up or down within the section.
39
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
On Application End. The On Application End section specifies the Java classes that are
executed when the voice application is stopped on the target application server.
Configurations for On Application End classes are specified by choosing Add.... This
will bring up a dialog box where the classes are added. The Edit... button enables
modification of previously defined On Application End classes. Remove will delete the
selected class. Defined classes will be executed in the order that they appear in the On
Application End section. The execution order can be changed by moving particular
classes up or down within the section.
On Call Start. This specifies a Java class or URI to be accessed when the application is
entered. For a Java class, the full name, including package, should be entered. For a URI,
the absolute URI for the system implementing the Cisco Unified CVP XML API should
be entered. If Run In Background is checked, then the Java class or URI is accessed in
the background and the call starts right away. If unchecked, the Java class or URI must
complete before the call flow for the application begins.
On Call End. This specifies a Java class or URI to be accessed when the application
visit ends. For a Java class, the full name, including package, should be entered. For a
URI, the absolute URI for the system implementing the Cisco Unified CVP XML API
should be entered.
40
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Root Document Settings
The following describes the Root Document Settings of a Cisco Unified CVP voice application.
JavaScript. The JavaScript section is used to specify custom JavaScript content that will
be inserted into the application root document. Selecting Add... will open up a dialog box
where a label for the JavaScript must be specified along with the desired JavaScript
content. The name of the JavaScript is used to identify particular script content in the
Root Doc Settings properties dialog. All script content listed in the edit box is inserted
within VoiceXML <script> tags by VoiceXML Server and therefore, <script> tags
should not be defined in the script content. VoiceXML Studio does not execute the script
or validate the script syntax. Multiple scripts can be specified with unique labels. The
order of the scripts listed in the Root Doc Settings properties is the order that they appear
in the root document. The order can be modified by using the Up and Down buttons.
VoiceXML Property. This table is used to enter all VoiceXML properties the developer
wishes to appear in the root document. By placing them in the root document, the
developer applies the properties to the entire application. Each property's name is entered
alongside its value. If a property's value is left blank, its value will be set to an empty
string in the root document.
41
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
VoiceXML Variable. This table is used to enter all VoiceXML variables the developer
wishes to appear in the root document. By placing them in the root document, the
developer ensures that they are available to all VoiceXML pages produced by the
application (essentially "global" VoiceXML variables).
42
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Documenter
This feature generates a Rich Text Format (RTF) document that outlines and describes the
content of a Cisco Unified CVP voice application. This document can serve as the basis for an
application specification, or as a prompt listing for use in an audio recording studio.
1. Documenter is accessed by right-clicking on a Cisco Unified CVP Project folder in the
Navigator View and selecting Documenter.
2. The first of four Application Document Content dialogs will appear. The first dialog
allows you to specify which Call Flow Diagrams sections will appear in the generated
document. Choose the desired content and select Next.
43
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
3. The next Application Document Content dialog to appear is for Global Configurations,
which allows the developer to decide which Application Settings and Global Commands will
appear in the generated document. It also allows the developer to choose whether to include
or exclude settings that have not been configured. This option can reduce clutter in the
generated document by eliminating settings that have not been specified. Choose the desired
content and select Next.
44
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
4. The third Application Document Content dialog allows the developer to specify which
Element Configurations will appear in the generated document. It also allows the developer
to choose whether to include or exclude settings that have not been configured. Finally, the
developer can choose the order in which the application pages will appear in the generated
document. Choose the desired content and select Next.
5. The final Application Document Content dialog allows the developer to configure a
prompt Recording List. This dialog also allows the developer to choose the order in which
the prompts will appear in the generated document. Choose the desired content and select
Next.
45
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
6. Next, the Application Document Revision History dialog will appear. Revision numbers,
change notes, reviser names, and dates can be specified here. Managing this information is
the responsibility of the developer, it will be included verbatim in the resulting document.
Choose the desired content and select Next.
7. Finally, the Application Document File dialog will appear. The developer is prompted to
provide a path and filename for the RTF document that will be produced. Enter a path and
filename or click Browse to choose one.
8. Once the developer is satisfied with the chosen Documenter options and the Finish button
is clicked, the document is generated. It is then available to be edited in a word processor of
46
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
the developer's choosing. For example, the developer may wish to add their company logo to
the document, change fonts, resize graphics, etc.
Documenter Output
The following sections are included in the generated document:
Field
Description
Revision History
A list of developer-specified document revisions and history notes.
Table of Contents
A list of all of the chapters included in the document.
To generate the table of contents:
1. Open the document in Microsoft Word
2. Right-click on the field that reads RIGHT CLICK HERE AND
SELECT “UPDATE FIELD” TO UPDATE
3. Choose Update Field.
Supported with Microsoft Word. If Microsoft Word is not available, this
section can either be entered manually or deleted.
Call Flow Diagrams
Call Flow Diagram Legend
A list of all element types, including the element shapes and a brief
description of what each element type does.
Application Call Flow Diagrams
An image of the voice application's call flow.
Global Configurations
Application Settings
General Settings
A table that lists the value of each of the documented application's
General Settings.
Audio Settings
A table that lists the value of each of the documented application's Audio
Settings.
Endpoint Settings
A table that lists the value of each of the documented application's
Endpoint Settings.
Root Document Settings
A table that lists the value of each of the documented applications’ Root
Document Settings.
47
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
Field
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Description
Global Commands
Hotlinks
A list of Hotlink elements used in the documented application, including
the configuration of each.
Hotevents
A list of Hotevent elements used in the documented application, including
the configuration of each.
Element Configurations
General
A table that lists each element’s general configuration in the documented
application.
Settings
A table that lists each element’s settings configuration in the documented
application.
Audio
A table that lists each element’s audio configuration in the documented
application.
Data
A table that lists each element’s data configuration in the documented
application.
Recording List
Prompts
A table that lists detailed information about each audio item in the
documented application. This list can be used by a recording studio
to determine expected filenames as well as the transcript for each
prompt.
48
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Version Control Integration
Version control software facilitates multiple developers working on a single voice application,
and also allows developers to revert their applications to an earlier state should the need arise.
Cisco Unified CVP VoiceXML Studio is built on top of Eclipse, which allows developers to
leverage the version control support that Eclipse offers. Cisco Unified CVP VoiceXML Studio
includes support for Concurrent Versions System (CVS); other version control systems are
supported by adding additional plug-ins to Cisco Unified CVP VoiceXML Studio's Eclipse
foundation.
Using Version Control to Support Multiple Developers
Once Cisco Unified CVP VoiceXML Studio is configured to access your source control system,
it can be used to support multiple developers working on a single voice application. Each
developer can work on a different part of a voice application simultaneously. However, it is
recommended that only one developer work on any given page of the application at any given
time. If this guideline is followed, only the page folders listed under the pages subfolder of the
callflow folder should be checked in (not individual elements).
For example, if a developer makes a change on page32, no one else should be working on
page32 concurrently. The developer can safely check-in the page32 folder when he or she is
done. Other developers can then check-out the page32 folder, close and reopen their callflows,
and the changes will be reflected.
49
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
It is recommended that extra empty pages be added to a project when it is first started to allow
for future growth. If new pages are required in the voice application, a single developer should
add them. To add pages, follow these steps:
Disable the filter that blocks .callflow items from being displayed in the Navigator View
(click on the down-arrow icon on top of the view, choose Filters, and then deselect .callflow).
1. A file named .callflow should now be listed as a child of the pages folder in the
Navigator View.
2. Add the new page(s) to the Cisco Unified CVP voice application and save it.
3. Check in the .callflow file and the new page folders (per the procedure of your version
control system).
4. Other developers can check out the callflow folder (which includes the .callflow file
and the new page folders), and then close and reopen their call flows. The new pages
will then be available.
Note that it is possible for multiple developers to concurrently add new pages to an application,
but it will require the .callflow file to be merged. It is an XML file, and should not pose much
difficulty. However, for simplicity, it is recommended that one person manage adding pages (and
that several extra pages be added to allow for growth), to avoid having to merge this file
manually.
50
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Using CVS from within Cisco Unified CVP VoiceXML Studio
To configure Cisco Unified CVP VoiceXML Studio to access an existing CVS server, follow
these steps:
1. Click on Window->Open Perspective->Other....
2. Open the CVS Repository Exploring perspective by choosing it from the dialog and
clicking OK.
51
CHAPTER 2: BUILDER FOR VOICEXML STUDIO
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
3. Right-click in the CVS Repositories View, and choose New->Repository Location....
4. Fill in your CVS server connection information in the Add CVS Repository dialog.
5. Click Finish.
Links to Additional Version Control Plug-ins
For a current list of version control plug-ins that are available for Eclipse, please refer to Team
Repository Projects and Plug-ins (http://www.eclipse.org/community/team.php). Additionally,
your version control vendor may have an Eclipse plug-in available.
52
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Chapter 3: Cisco Unified CVP Workspace
The Cisco Unified CVP Workspace contains four areas:
Elements View
Callflow Editor
Element Configuration View
Prompt Manager
53
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Elements View
The Elements View contains the elements used to construct a voice application. This pane can be
seen as a "palette" of raw parts that can be dragged to the Callflow Editor while building the
application. The Elements folder contains pre-built configurable elements built by Cisco and
third-parties. The rest of the elements represent types with unique features that are used in
constructing voice applications. Each element is described in this section.
Standard Versus Configurable
A configurable element is one that has been pre-built and whose developer has exposed a
configuration to allow the application designer to control how it functions. Configurable
elements appear within the Elements folder in the Element Pane. Standard elements are elements
that are built by the application designer to be used for a specific application function. Standard
elements do not have configurations and therefore are not expected to be very reusable.
54
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Configurable Elements
Configurable elements are pre-built, pre-tested elements that are designed for reusability. In
order to make an element reusable, it must have a mechanism to modify its behavior according to
the wishes of the application designer. This is done via a configuration. Each element defines its
own configuration and that configuration is available to the designer via the Element
Configuration pane, which is displayed when the element is selected in the workspace.
Configurable Element Types
Configurable elements come in three flavors; Voice elements, Action elements, and Decision
elements. There are four parts to an element’s configuration:
Settings
Audio groups
VoiceXML properties
Data
Voice elements use all four parts while Action and Decision elements use only Settings and
Data. Refer to the following sections for a more complete description.
Configurable Action Elements
Definition
Many voice applications require actions to occur “behind the scenes” at some point in the call. In
these cases, the action does not produce VoiceXML. Instead, an Action element makes a
calculation, interfaces with a back-end system such as a database or legacy system, stores data to
a file or notifies an outside system of a specific event. All of these potentialities are built into
Action elements.
Action Element
Encapsulates business logic and performs tasks which do
not branch the call flow.
An Action element can be thought of as a way to insert custom code directly in the call flow. For
example, an Action element could retrieve and store a current stock price or serve as a mortgage
rate calculator, storing the rate after using information entered by the caller.
Since Action elements do not affect the call flow, they will always have a single exit state.
The configuration for a configurable Action element contains two components: settings and
variables.
55
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
A configurable action element is rendered as a parallelogram.
Configurable Decision Elements
Definition
Even the simplest voice applications require some level of decision-making during the call flow.
These “crossroads” are encapsulated in Decision elements.
Decision
Element
Encapsulates business logic that makes decisions with at
least two exit states.
A Decision element is like a traffic cop, redirecting the flow of calls according to built-in
business rules. Examples of business rules include decisions such as whether to play an ad to a
caller, which of five different payment plans to offer to the caller, or whether to transfer a caller
to an agent or hang up.
The results of a Decision element are represented as exit states. Although many decisions are
Boolean in nature, (e.g., has the caller registered? or is the caller new to the application?),
Decision elements can have as many exit states as desired, as long as at least two are specified.
The configuration for a Decision element contains two components: settings and variables.
Additionally, the Java class that defines the configurable decision sets the exit states it can
return. The designer must map each exit state to another call flow component to handle its
consequences.
A configurable Decision element is rendered as a diamond.
Voice Elements
Definition
Almost all voice applications must utilize a number of dialogs with the caller, playing audio
files, interpreting speech utterances, capturing data entered by the user, etc. The more these
dialogs can be contained in discrete components, the more they can be reused in a single
application or across multiple applications. These dialog components are encapsulated in Voice
elements.
Voice Element
A reusable, VoiceXML-producing dialog with a fixed or
56
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
dynamically produced configuration.
Voice elements are used to assemble the VoiceXML sent to the voice browser. Each Voice
element constitutes a discrete section of a call, such as making a recording, capturing a number,
transferring a call, etc. These pre-built components can then be reused throughout the call flow
wherever needed.
Voice elements are built using the Cisco Unified CVP Voice Foundation Classes (VFCs), which
produce VoiceXML compatible with multiple voice browsers (see the Programming Guide for
Cisco Unified Customer Voice Portal for more on the VFCs and constructing custom voice
elements).
Voice elements are complete dialogs in that they can encompass just a single action or an entire
interaction with the caller. Depending on its function, a Voice element can contain almost as
much dialog as a small application. However, because of the pre-built nature of Voice elements,
application designers do not need to worry about their complexity. Each voice element is simply
a “black box” which can be treated as a single object. As a result, by combining many Voice
elements, a complex call flow can be reduced significantly.
To fully configure Voice elements, developers must specify values for four components: settings,
VoiceXML properties, audio groups, and data. Additionally, each Voice element defines the exit
states it can return and the designer must map each exit state to another call flow component to
handle all its consequences.
A voice element is rendered as a square
Standard Elements
Standard Action Elements
Definition
Many voice applications require actions to occur “behind the scenes” at some point in the call. In
these cases, the action does not produce VoiceXML (and thus has no audible effect on the call)
or perform an action that branches the call flow (like a Decision element). Instead the action
makes a calculation, interfaces with a backend system such as a database or legacy system, stores
data to a file or notifies an outside system of a specific event. All of these processes are built into
Action elements.
Action Element
Encapsulates business logic that performs tasks not
affecting the call flow (i.e., has only one exit state).
57
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
An Action element can be thought of as a way to insert custom code directly in the call flow of a
voice application. A few examples of Action elements could be one which retrieves and stores
the current stock market price. Another example might be a mortgage rate calculator that stores
the rate after using information entered by the caller.
Since Action elements do not affect the call flow, they will always have a single exit state.
An Action element is rendered as a parallelogram.
Configuring a Standard Action Element
A standard Action element is defined by specifying the source of the action. There is no need to
specify exit states like a standard Decision element because Action elements always have a
single exit state.
Choose the source of a standard Action element:
Class. The action is executed by a Java class whose full name (including package name)
is specified in the text box. Note that substitution can be used to dynamically assemble
the Java class name.
URI. The action is executed by communicating via XML with a script accessed via the
URI provided in the text box. Note that substitution can be used to dynamically assemble
the URI.
58
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Standard Decision Elements
Definition
Even the simplest voice applications require some decisions within the call flow. These
“crossroads” are encapsulated in Decision elements.
Decision
Element
Encapsulates business logic that makes decisions with at
least two exit states.
A Decision element is like a traffic cop, redirecting the flow of callers according to built-in
business rules. Examples might include whether to play an ad to a caller, which of five different
payment plans should be offered to the caller, or whether to transfer a caller to an agent or hang
up.
The results of a Decision element are represented as exit states. Although many decisions are
Boolean in nature, (e.g., has the caller registered?, or, is the caller new to the application?),
Decision elements can have as many exit states as desired, as long as at least two are specified.
A Decision element is rendered as a diamond.
Configuring a Standard Decision Element
A standard Decision element is defined by specifying the source of the decision as well as all
possible exit states it can return. This is necessary in order to provide it exit states in the
workspace (configurable Decision elements already provide this information).
First, choose the source of a standard Decision element:
Decision Editor. The decision is a Cisco Unified CVP XML Decision whose definition
is created using the Decision Editor. This is the recommended way to set up most
standard decisions.
59
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
XML. The decision is a Cisco Unified CVP XML Decision whose definition is an XML
file created within the Builder. The designer writes this XML within the Builder
according to the Cisco-specified specification.
Class. The decision is made by a Java class whose full name (including package name) is
specified in the text box. Note that substitution can be used to dynamically assemble the
Java class name.
URI. The decision is made by communicating via XML with a script accessed via the
URI provided in the text box. Note that substitution can be used to dynamically assemble
the URI.
60
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
For XML, Class, and URI decisions, all the exit states returned by the decision must be created.
Type the name of the exit state and press Add to add an exit state. The exit state name must
match the values returned by the decision source. Any number of exit states can be added in this
manner. Exit states can be deleted and renamed by clicking on them in the list box and clicking
on the appropriate button.
Finally, when using an XML decision, click on the Edit XML button to bring up a text editor in
which the XML content is written. The Builder automatically begins with the skeleton of a Cisco
Unified CVP XML Decision that can be modified as desired. This is the reason that exit states
must be defined first; the skeleton content refers to the exit states as entered.
Decision Editor
Decision Editor enables developers to create decision logic for Decision elements using a
graphical tool. Knowledge of Cisco Unified CVP XML Decision syntax is not required. It allows
developers to easily create and configure new expressions, and then associate them with
particular exit states of a Decision element.
To Start Decision Editor for a New Element:
Drag a new Decision element into the call flow and click on the Use Decision Editor Button in
the Element Configuration View. Decision Editor is the default decision configuration method
for new elements.
61
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
To Start Decision Editor for an Existing Element:
Click on an existing Decision element, and change the decision type to Decision Editor. Then,
click on the Use Decision Editor Button.
The Decision Editor dialog is split into two sections. The top section displays a table with
information about the decision as it has been configured thus far. The bottom section includes
various settings that can be adjusted to change the behavior of one of the decision's expressions.
When settings in the bottom section are changed the selected expression in the table (top section)
updates to reflect the changes.
Creating a decision:
First, add a Decision element to the call flow. Then bring up Decision Editor to edit its decision.
Follow these steps to configure the decision:
1. Select the only expression (row) in the table. Decision Editor pre-populates the table with
this initial row; more can be added later.
62
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
2. Choose an argument type for the first argument. Configure any settings that appear once
the argument type is selected; different types of arguments require different settings to be
satisfied.
3. Choose an operator that will be used to compare the first and second arguments.
4. Choose an argument type for the second argument and configure any settings that appear
once it is selected.
5. Double-click on the Exit State cell for the selected row of the table and enter the name of
the exit state that should be followed when the expression for this row is true.
6. To add additional expressions and exit states, right-click on an existing expression and
choose Add New Expression.
63
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
To remove an expression right-click on it and select Delete Selected Expression.
Flag Elements
Definition
Flag elements provide a mechanism by which application designers can analyze the activities of
callers to determine such things as which part of the application is the most popular, which part
creates confusion, or which part is difficult to navigate. Additionally, an analysis of which Flag
elements have been triggered can be used during a call to change the application’s behavior
dynamically.
Flag Element
Records when a caller reached a certain point in the call
flow.
Flag elements can be seen as “beacons” that are triggered when a caller visits a part of the call
flow. Application designers can place these flags in parts of the call flow that need to be tracked.
When the flag is tripped, the application log is updated so that post-call analysis can determine
which calls reached that flag. The flag trigger is also stored within the call data, so an application
can make decisions based on flags triggered by the caller.
Flag elements have a single exit state and do not directly affect the call flow.
Defining a Flag Element
All that is required to define a Flag element is to provide its name. This value will be stored in
the application log and call data when the flag is triggered.
A Flag element is rendered as a sideways triangle.
64
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
VoiceXML Insert Elements
Definition
There are certain situations in a voice application where a developer may wish to include prewritten VoiceXML into their Cisco Unified CVP voice application. The developer may desire
fine-level control over a specific voice function at the VoiceXML tag level without having to get
involved with constructing a custom configurable element in Java. Additionally, the developer
may wish to integrate VoiceXML content that has already been created and tested into a Cisco
Unified CVP voice application. These situations are handled by a VoiceXML Insert element.
VoiceXML
Insert Element
A custom element, built in VoiceXML, providing direct
control of lower-level voice dialog at the price of
decreased flexibility.
VoiceXML Insert elements contain VoiceXML code that the developer makes available as the
content of a VoiceXML <subdialog>. The content can be in the form of static VoiceXML
files, JSP templates, or even dynamically generated by a separate application server. A
framework is provided to allow seamless integration of VoiceXML Insert elements with the rest
of the call flow.
The use of VoiceXML Insert elements has its consequences such as the loss of being able to
seamlessly switch between different voice browsers, some greater processing overhead involved
with integration with the rest of the call flow, as well as the added complexity of dealing with
VoiceXML itself rather than creating an application with easy to use configurable elements.
VoiceXML Insert elements can have as many exit states as the developer requires, with a
minimum of one.
VoiceXML Insert elements can have as many exit states as required, with a minimum of one.
A VoiceXML Insert element is rendered as a page shape.
65
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Defining a VoiceXML Insert Element
Defining a VoiceXML Insert Element is very much like defining a generic Decision element in
that you must first provide the source of the VoiceXML Insert element as well as defining the
exit states the element can return. Unlike a Decision element, a VoiceXML Insert element can
have a single exit state.
You can elect to pass only some runtime information to the VoiceXML Insert element in order to
avoid the overhead involved in passing information that may not be used. The choices are:
Passing all Element and Session data to the VoiceXML Insert element. In a large
application, Element and Session data make up the bulk of runtime information and
passing it all can slow down the performance of the system. It is recommended that you
turn this option off and use the Data tab to select the Element and Session data variables
that will be needed from within the VoiceXML Insert element. For Element data, the
name of the VoiceXML variable that will contain the value is renamed to start with the
element name followed by an underscore, then the name of the element data. Session data
names are unchanged. Any Java objects passed in Session data will pass the result of
calling the toString() method on it.
Telephony information such as the ANI, DNIS, etc.
Call data such as the start time, name of the application, session ID, etc.
Element history indicating which elements have been visited in the call and the
corresponding exit states of those elements.
66
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Information about the current user. This is only applicable if the User Management
System is activated for the application.
Hotevent
Definition
There are times when the occurrence of a VoiceXML event is expected to trigger an action. The
event can be user-triggered (such as a noinput event), asynchronous (thrown by the voice
browser), or developer-defined (such as a Hotlink that throws an event). In each case, the
developer may wish to play audio, store data, or move to another part of the call flow when the
event is triggered. Cisco Unified CVP refers to these events as Hotevents.
Hotevent
A global event that, when caught, executes developerspecified actions.
Like Hotlinks, Hotevents can act as pointers to direct the call somewhere else. They may also
specify VoiceXML to execute when the event is triggered. An application can use any number of
Hotevents, each activated by a different event.
67
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Note that a Hotevent is triggered by a VoiceXML event, not a server-side event such as a Java
exception or an error such as an inaccessible database.
A Hotevent is rendered as an upside-down trapezoid.
Defining a Hotevent
To define a Hotevent, the VoiceXML event that activates it must first be entered in the Event
text box. The Class text box optionally contains the fully qualified name of the Java class that
will produce the VoiceXML to be executed when the event is triggered. This VoiceXML can
contain anything you desire, such as playing audio, performing browser-level logging, etc. Note
that this Java class is called only once per call, when the call first comes in. The VoiceXML that
it produces will appear in the application’s root document, which means that it will be active for
the remainder of the call (i.e. the VoiceXML is not generated ad hoc when the event occurs; the
initially-generated VoiceXML is used throughout the call).
If the Hotevent defines a Java class, it can be configured to have no exit state. The VoiceXML
defined by the class will execute and the call will continue without further interruption. You can
configure the Hotevent to have an exit state by clicking on the Has Exit State checkbox. In this
case, the VoiceXML defined in the Java class will execute and once completed, will follow the
exit state to the appropriate location in the call flow. A class does not need to be given if the
Hotevent has an exit state, it will simply act like a Hotlink and move to the appropriate place in
the call flow when the Hotevent is activated.
Hotlinks
Definition
Hotlinks allow a caller to say an utterance or press a key at any time to have the application
perform a specific action. The most common example is saying the word "operator" (and / or
pressing “0”) to transfer to a live representative.
68
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
A globally-accessible utterance and / or key press that
immediately transitions the call to a specific part of the
call flow, or throws an event.
Hotlink
Hotlinks are not elements in that they do not generate VoiceXML or execute any custom code.
A Hotlink acts as a pointer (or link) to direct the call somewhere else or to throw a VoiceXML
event when the specified word or key press is detected. An application can use any number of
Hotlinks.
A Hotlink is rendered as a trapezoid.
Defining a Hotlink
A Hotlink can be activated by a spoken keyword or keywords, a DTMF entry or entries, or a
combination of both. Choosing the Inline option for either input type allows all key presses or
keywords that activate the Hotlink to be entered in the provided text box, as a comma-delimited
list. For more sophisticated grammars, choose the External URI option from the drop-down box
and provide the URI to an external grammar.
By default, a Hotlink is configured to point to a location in the call flow that will be visited when
the Hotlink it activated. The Hotlink is given a single exit state that the developer must connect
to the place in the call flow to visit when it is activated. A Hotlink can alternatively throw a
VoiceXML event instead. In this case, the Hotlink does not have an exit state. When choosing
the option to throw an event, the full name of the VoiceXML event must be entered in the
provided text box.
69
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Application Transfer
Definition
Cisco Unified CVP VoiceXML Server can support many concurrent voice applications. While
each of these applications is expected to stand alone, there may be instances where a caller in one
application wants to visit or “transfer to” another application. This is accomplished with an
Application Transfer.
Application
Transfer
A transfer from one voice application to another running
on the same VoiceXML Server system. An Application
Transfer simulates a new phone call.
Application Transfers do not require telephony routing; they are a server-side simulation of a
new call to another application running on the same VoiceXML Server. Callers are not aware
that they are visiting a new application, but VoiceXML Server treats it as if it were a separate
call with separate logging, administration, etc. Data captured in the source application can be
sent to the destination application to avoid asking the caller for the same information multiple
times.
An example of this might be a voice portal application whose main menu sends callers to various
independent applications, depending on their choices.
Because an Application Transfer moves the caller to a different application, it has no exit states.
An application transfer is rendered as a circle.
Defining an Application Transfer
Defining an Application Transfer involves two steps. The first is to choose the application to
transfer to. A drop down box contains a list of all other applications loaded in VoiceXML Studio.
Should the desired destination application not appear in the list or the name of the application is
not known until runtime, press the Substitution button to reach the substitution dialog box and
either enter the name of the destination application manually or use substitution to obtain it from
dynamic content.
70
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Use the Data tab to identify which Element and/or Session data to pass from the source
application to the destination application. In order to avoid namespace conflicts, the data passed
is renamed before being sent to the destination application.
Element data is saved as Session data whose name is “APPNAME_ELEMNAME_VARNAME”
Where APPNAME is the name of the source application.
Where ELEMNAME is the name of the element.
Where VARNAME is the name of the element data variable.
Session data remains Session data but is renamed to “APPNAME_SESSIONNAME”
Where SESSIONNAME is the name of the session data.
Page Entries & Connectors
Definition
Large-scale voice applications have call flows that are too large to fit on a single page. Cisco
Unified CVP VoiceXML Studio provides the ability to define an application on as many pages
as desired. The mechanisms by which application designers can connect call flow across pages
are Page Entries and Page Connectors. Page entries denote an entrance point to a page and page
connectors are exit points from a page.
Page Entry
The entrance point to a page or to a specific part of the
71
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
call flow.
Page Connector
The means by which the call flow moves to a specific
page entry.
Page Entries and Page Connectors form the “glue” for a multi-page application. They can also be
used to create a cleaner call flow by reducing the number of lines within a single page.
A page entry is rendered as an inverse
arrow.
A page connector is rendered as an
arrow.
Defining a Page Entry
A Page Entry is automatically generated when a new page is created. You can also drag a new
Page Entry to the workspace, even if the page already has other page entries. Page Entries do not
have configurations, though they can be renamed. A Page Entry is not complete until its single
exit state points to a component.
Defining a Page Connector
A Page Connector must be configured to point to a corresponding Page Entry. All available Page
Entries are offered for selection via a drop-down box. Any number of Page Connectors can point
to the same Page Entry. A Page Connector has no exit states; call flow moves to a Page
Connector.
By default, a Page Connector does not point to any Page Entries and will not be complete until it
does so. If a Page Entry is deleted, all Page Connectors that point to it will become incomplete
until they are configured to point to other Page Entries.
72
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Comment
Definition
You may wish to add notes to the call flow itself for informational purposes. A Comment is used
to make a voice application’s call flow more understandable.
Comment
A note added to the call flow used for informational
purposes only.
Comments do not affect the call flow; they are used only to improve call flow readability.
Defining a Comment
To enter a Comment, right-click on it and select Edit. A dialog box appears in which the
Comment can be typed.
The comment box will not automatically wrap content, therefore carriage returns should be
added manually. The comment appears as text within the workspace, but not within the call flow.
73
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Hang Up
Definition
A Hang Up defines places within a voice application where you wish the application to hang up
on the caller.
A location at which to hang up on the caller.
Hang Up
A Hang Up element will cause the VoiceXML returned to the voice browser to contain the
<exit/> tag, which in most cases causes the browser to hang up on the caller. Some browsers
may perform other actions before hanging up.
A hang up is rendered as an octagon (stop sign).
Defining a Hang Up
Hang Up elements do not have configurations or exit states. A voice application designer can use
as many Hang Up elements as desired; application performance is not affected by the presence of
Hang Up elements.
Start of Call
Definition
The Start of Call is the first element visited when the call begins.
Start of Call
A special type of Page Entry which points to the
component that is to be visited at the start of the call.
A start of the call is rendered as a circle.
74
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Defining the Start of Call
By default, every new Cisco Unified CVP Project is created with a single page and a Start of
Call element.
A Page Entry element can be converted into a Start of Call element if no Start of Call element
currently exists. To do this, right-click on it, select Start of Call, and then select Yes. Similarly,
you can convert a Start of Call element into a Page Entry element by following the same steps,
and choosing No instead.
Error Element
Definition
When an unexpected error occurs, a voice application must be able to handle the situation
gracefully by transferring the caller to an agent or playing a message before ending the call. This
is accomplished by defining an Error element.
Error Element
A Voice element whose purpose is to handle the caller
when an unexpected error occurs.
The Error element does not handle the error itself, it is only responsible for managing the caller.
Typically, the Error element will play an error message or initiate a transfer to a live agent. Since
the error is unexpected, the call will end after the Error element completes. An application can
have only one Error element and that element must be a Voice element.
Applications should be constructed so that they can handle anticipated errors within the call
flow. The Error element handles only those errors that are not caught and managed by the call
flow. These errors can include both VoiceXML errors (such as error.badfetch) as well as Java
exceptions thrown by custom code.
75
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Defining an Error Element
To define an Error element, drag a new Voice element from the Elements View into the
workspace. The Voice element can be configured normally. You may wish use a dynamic
configuration, allowing it to modify its behavior depending on where the error occurs in the call
flow.
To convert the Voice element into an Error element, right-click on it, choose the Error Element
option, and select Yes. The shape of the element will change to a triangle.
An Error element has no exit states, but you can view and edit its configuration as if it were a
regular Voice element.
To make another Voice element the Error element instead, right-click on the current Error
element, choose the Error Element option, and select No. Then, repeat this procedure for the
intended Error element, and select Yes.
The Error element can appear on any page, but there can only be one Error element per
application.
76
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Subdialog Elements
Definition
Cisco Unified CVP voice applications may be invoked via a subdialog call from another
VoiceXML application. Applications that will be invoked as a subdialog must use the Subdialog
Start and Subdialog Return elements.
Subdialog
Start
The entrance point to an application that will be invoked
as a subdialog.
Subdialog
Return
An exit point from an application that returns control and
data back to its calling application.
In addition to the use of the Subdialog Start and Subdialog Return elements, the application
should be configured for subdialog invocation through the General Settings properties of a Cisco
Unified CVP Project.
A Subdialog Start element is rendered as a document surrounding a
green circle.
A Subdialog Return element is rendered as a document surrounding a
red octagon (stop sign).
Defining a Subdialog Start
For a voice application that will be invoked as a subdialog, drag a Subdialog Start element from
the root level of the element palette to the workspace. The Subdialog Start element should be
placed at the entrance point of the application, immediately after the Start of Call element.
The "done" exit state from the Subdialog Start element can then be mapped to the first element of
the application.
77
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
This element receives data passed from the calling dialog and creates corresponding element or
session data. Data can be passed from the calling dialog to the application as HTTP parameters
and/or as VoiceXML parameters (using the <param> tag).
If data from the calling dialog is passed as HTTP parameters, Cisco Unified CVP VoiceXML
Server will automatically create session data using the name of the data that is sent.
However, if data is passed using VoiceXML parameters, the Subdialog Start element should be
configured appropriately in order for the data to be available as element or session data for the
duration of the call session. For each parameter that is passed to the application from the calling
subdialog, the "Parameter" setting should be configured with the name of the data being passed.
The "Store As" setting allows developers to choose to store all passed values either as session or
element data.
The "Enable Digits Bypass" setting is used to activate a VoiceXML workaround to ensure
expected functionality for a particular TDM or analog phone. When this setting is set to "true", a
new setting named "Audio Filler URI" will appear in VoiceXML Studio and can be configured
to set a reference to the file "Flash: silence_.1s.wav". For IP phones the "Enable Digits Bypass"
setting should be set to "false".
Defining a Subdialog Return
For a Cisco Unified CVP voice application that will be invoked as a subdialog, Subdialog Return
elements should be used in place of Hang Up elements throughout the call flow. This element
can be found at the root level of the element palette. The Subdialog Return element is used to
return data back to the calling dialog.
This element has no exit states, much like a Hang Up element. It should be used in place of a
Hang Up element in applications that will be invoked as subdialogs; these applications should
not use any Hang Up elements.
The settings for this element are used to define what data to pass back to the calling dialog. This
data is returned using ICM ECC variables, therefore the data must conform to requirements
associated with ICM ECC variables. Refer to the Cisco Unified CVP documentation for further
78
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
details. Each element setting corresponds to the ICM ECC external variable name. The settings
should be configured with the data that is to be passed back to ICM.
The "Caller Input" setting must be assigned a value in order for the application to validate, since
Cisco Unified CVP requires this variable to have a value.
Importing Voice Applications from Previous Versions
When an application that was created in a previous version of VoiceXML Studio is imported, its
existing Subdialog Start and Subdialog Return elements (if any are present) will be automatically
converted to the newer versions described here. Note that while these elements are located in a
new location in the element palette (i.e. at the root level instead of in a folder named "Cisco")
they are functionally equivalent to the older elements.
If the application was checked out from a version control system, rather than being imported
from the file system, there is an additional step that should be taken to ensure that the application
is properly converted. Once checked out, the project should then be deleted from the Navigator
View and then imported from its location on the file system. When deleting projects from the
Navigator View, be sure to choose Do not delete contents, so that a copy of the project is left on
the file system and can be imported.
The Callflow Editor
The Callflow Editor is where the voice application is built. Elements are dragged from the
Elements View to the Callflow Editor and lines are connected between the elements, defining the
call flow. This process builds a diagram representing the call flow of the application.
79
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Selecting, Resizing, and Repositioning Elements
Elements in the workspace can be selected, resized and repositioned in much the same way that
shapes are manipulated in many graphics programs. When selected, an element is highlighted
with small boxes at the corners and edges. Click and drag the boxes to resize the element.
To select an element, click on it.
o Multiple elements can be selected by holding down the Shift key during selection
or drawing an enclosing box around them.
To de-select an element, click anywhere on the workspace background or on another
element.
To move an element, click and drag it.
To delete an element, select it and press the delete button.
Element Naming
All elements receive a default name when they are dragged to the Callflow Editor. The default
name consists of the name of the element type followed by a number with an underscore in
between. For example, the first Audio element is named "Audio_01.”
Once an element is added to the call flow, you can rename it, as long as another element with the
same name does not already exist in the call flow.
80
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
An element name can only contains letters, numbers, underscores and spaces.
An element can be renamed by right-clicking on the element in the Callflow Editor and choosing
Rename or by single-clicking on an already selected element (similar to "Windows Explorer"
functionality for renaming files).
Connecting Elements
To connect elements within the call flow, right-click on the source element and a drop-down box
will appear. Then select the Exit States menu and choose one of the exit states.
81
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Once you select an exit state, a line appears from the source element that can be dragged and
connected to the target element.
A connection is made by clicking on the target element.
82
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
A line can be deleted by selecting it and pressing the delete key, or by right-clicking on
the line and selecting Undo Connection.
When elements are moved, their connections move with them.
If you right-click on an element that has some exit states mapped, these exit states will
appear grayed-out in the "Exit States" menu. When all exit states are mapped, the element
color will turn from yellow to gray.
o Hang Up elements start out gray because they have no exit states.
o Application Transfer and Page Connector elements also have no exit states but
start out yellow and only turn gray when they are configured correctly.
o Hotlinks and Hotevents can have an exit state based on their configurations. They
will appear yellow or gray according to these configurations.
Angled Lines
An angled line can be created by using the bend points of a line. Select a connected line and a
dot will appear in the middle of the line. Drag this dot to create the desired angle. The line is now
drawn at an angle, with the apex at this bend point. You can repeat this procedure to add as many
bend points as desired.
83
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
A bend point can be removed by dragging it to create a straight line.
An angled line can be deleted in the same way as a straight line, by selecting it and
pressing the delete key, or by right-clicking on the line and selecting Undo Connection.
Skipping Call Flow
Use Skip Call Flow to:
Test part of the application when other parts have not been completed.
Test a part of the voice application by jumping to the desired place without having to visit
the entire call flow.
Once an element is skipped, it no longer has the same configuration format. When the skipped
element is selected, it displays a configuration containing just a Data Tab in the Configuration
Pane. This allows you to manually enter the Element and/or Session data normally produced by
the skipped element. See the Data Tab section for more information on manually creating
Element and Session data.
When Cisco Unified CVP VoiceXML Server encounters an element slated to be skipped, it does
not execute the code that defines the element. Instead, it creates the Element and Session data
specified in the Data Tab and returns the desired hardcode exit state. This is done
instantaneously, without input from the caller. In this way, portions of the call flow can be
skipped to reach any part of an application.
84
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Using Skip Call Flow
To Skip Call Flow, select the Skip and > menu option, which appears when certain elements are
right-clicked. The menu displays a submenu with two choices:
Skip the element and treat it as an orphan.
Skip the element and keep it within the call flow by hard coding its exit state.
If no exit states are mapped, only skipping as an orphan is available. Some elements, such as
Hotlinks and Hotevents, can only be skipped as an orphan.
Some elements cannot be skipped (such as Page Entry and Page Connector elements) and will
not have this menu option.
Once the Skip and > option is selected, the element and its exit state lines will be rendered in
gray, except for the hard-coded exit state.
85
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
If the element is treated as an orphan, all lines pointing to it are deleted and all exit state lines are
rendered in gray.
When you no longer need to skip an element, right-click on the skipped element and choose
Don't Skip from the "Skip and >" menu.
86
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
87
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Cut, Copy, and Paste
Elements can be cut or copied, along with the connections between them. Once pasted, the
configurations are identical.
When copying within the same application, element names are changed to avoid duplication,
which is not permitted. Cut operations do not change the names of elements.
Elements can be cut, copied, and pasted within the same page, across different pages, and even
across applications.
To cut or copy elements from one application to another, select the elements, cut or copy them,
then open the workspace of the destination application and select paste. Element names will
change only if there are already elements in the application with the same name as those that are
being pasted.
Cut, copy, and paste can be performed by selecting from the Edit menu, right-clicking in the
Callflow Editor or using keyboard shortcuts (Cut: Ctrl-X, Copy: Ctrl-C, Paste: Ctrl-V).
88
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Undo and Redo
Any modification made to the Callflow can be undone and redone. An unlimited number of steps
can be undone. To use Undo or Redo, right-click anywhere within the Callflow Editor, or use the
keyboard shortcuts (Undo: Ctrl-Z, Redo: Ctrl-Y).
Zoom In/Zoom Out
Zoom in and zoom out can be performed by selecting Zoom In or Zoom Out from the Callflow
menu or right-clicking on the background of the Callflow Editor and choosing these options from
the context menu. The call flow can be manipulated no matter what the zoom level is set to.
89
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Element Groups
Element Groups provide developers with the ability to group elements, and then treat the new
groups as reusable call flow components. These new components are created by grouping
existing built-in elements available within Cisco Unified CVP VoiceXML Studio as well as
custom voice, action, and decision elements. Element Groups enable the voice application
developer to consolidate large sections of call flow into a single entity. Additionally, Element
Groups can be saved as templates that can be transported to other applications for reuse.
Element Groups are created by selecting existing elements within the call flow and defining
those elements as part of a new Element Group. The new Element Group is then displayed as a
single shape in the call flow. The components that make up the Element Group can be edited and
configured within the workspace by double-clicking on the Element Group shape.
Creating an Element Group
Element Groups are created by first selecting elements in the call flow editor that should be part
of the new group. Multiple elements can either be selected by dragging a box around elements in
the call flow editor or by clicking on the elements while holding down the Ctrl key.
Once the elements have been selected, a new group can be created by right-clicking on one of the
selected elements and choosing Group Elements. The selected elements will be replaced by a
single new shape representing the new Element Group. Element Groups can only be made from
90
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
elements from the same page in the call flow and the Element Group itself can only have one
page. All exit states into and out of the group are preserved.
Configuring an Element Group
Once the Element Group has been created, the name of the group can be changed as with any
other call flow component. The contents of an element group can be viewed by double-clicking
on the Element Group shape. The Element Group Editor (EGE) will take up the call flow editor
area and the application's page tabs will temporarily disappear.
91
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
In the EGE, all of the elements that are part of the Element Group will appear in the same
configuration they were in before they were grouped. The EGE has the same functionality and
features as the call flow editor. Any element from the Elements View can be dragged into the
EGE and configured, with the exception of Page Entry and Page Connector elements (as Element
Groups only span a single page). To go back to the call flow editor, click the Go Back button at
the bottom-right of the editor.
Element Group Exit States
Existing exit states between elements are preserved when an Element Group is created.
Additionally, exit states that led to elements that are now part of the Element Group appear as
entry points coming from the Group Start element.
Entry points maintain the original exit state mapping of the voice application's call flow when an
Element Group is created. The destination of entry points can be remapped by configuring the
exit states of the Group Start element. Since there are often multiple entry points into an Element
Group, the exit states that match these entry points are differentiated by using the following
naming convention:
Element Name:Exit State Name
Optionally, the entry points of an Element Group can be consolidated into a single exit state from
the Group Start element. This can be used to easily map all entry points to one element within
92
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
the Element Group. This can be useful when there are many entry points into the Element Group
and all of the exit states associated with these entry points are intended to lead to the same
element. To choose either "Single" or "Multiple" exit states for Group Start, right-click on the
Group Start element and select Entry Points->Single or Entry Points->Multiple.
By default, if there are no entry points going into the Element Group, the Entry Point value will
be "Single". If there are existing exit states configured to elements in the Element Group when it
is created, the Entry Point value will be "Multiple" (to maintain the exit states when creating the
group).
Unsatisfied exit states of elements within the Element Group are available as exit states for the
Element Group shape in the call flow editor. The exit states are accessible by right-clicking on
the Element Group shape as would be done with any call flow component. The Element Group
exit state naming convention is the same as the naming convention of exit states for entry points,
since exit states may come from multiple elements within the Element Group.
93
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Element Group Templates
Element Group Templates (EGTs) allow developers to turn Element Groups into reusable call
flow components. Once an Element Group has been saved as an EGT, it can be added to other
Cisco Unified CVP voice applications where it will be available as a drag-and-drop component
from within the Elements View. Custom code, such as dynamic configuration classes and custom
elements, can be included within an EGT. When an EGT is saved, a single file with an ".egt"
extension is created. Since EGTs are templates, changes (including the addition of elements,
configuration modifications, etc.) made within instances of an EGT do not change the reusable
template file.
Saving an Element Group Template:
To create an EGT from an Element Group, right-click on the Element Group and select Save As.
A wizard will pop up that includes several options related to saving the EGT. Options include:
Name - The name of the new EGT.
Location - The location that the EGT will be stored in; the default value is suitable for all
but the most advanced EGT uses.
Description - A description of the EGT, which will be displayed in Cisco Unified CVP
VoiceXML Studio as a tooltip.
Display Folder - The folder under "Element Groups" in the Elements View that this EGT
will be stored in.
Resources - Resources to include in the template archive (custom elements, dynamic
configuration classes, etc.).
94
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Once the EGT is saved, it will appear in the Elements View within the "Element Groups" folder.
If a display folder was defined when saving, the EGT will be located within the defined folder
structure. Since EGTs appear in the Elements View, they can easily be dragged and dropped into
any Cisco Unified CVP voice application's call flow.
Exporting/Importing an Element Group Template:
An EGT is saved as a single archive file with a file extension of ".egt". This archive contains all
of the files that are required by the EGT, ensuring that it will be transportable to other Cisco
Unified CVP voice applications. To export an EGT, find the .egt file for the EGT in this folder:
CVP_HOME\VXMLStudio\eclipse\plugins\com.audiumcorp.studio.library.commo
n_5.1.0\templates
Copy the .egt file from this folder to this same location under another instance of Cisco Unified
CVP VoiceXML Studio.
NOTE: If the "templates" folder does not exist, create the folder manually.
Start the instance of Cisco Unified CVP VoiceXML Studio where the EGT was copied. The
EGT will now be available in the Elements View as a reusable component.
Element Comments
In addition to comments appearing in the call flow, each element can also have comments
specicfically associated with it. Element comments are entered free-form into the Element
Comment Dialog.
95
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
To enter a comment for an element, right-click on it and choose Edit Comment. A small red
triangle will appear on any element that contains a comment.
NOTE: Some element types cannot have comments (for example, Page Connectors and Hang
Up elements).
Element Configuration View
Each time an element is selected in Builder for VoiceXML Studio, its configuration appears in
the Element Configuration View. The Element Configuration View can contain up to four tabs:
General, Settings, Audio, and Data, depending on the element selected.
96
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Element Configuration Tabs
The General Tab: The general tab of an element configuration is used to set up how the
element will be executed. Every configurable element type contains a general tab.
The Settings Tab: The settings tab contains all the element settings that determine how a
configurable Voice, Action or Decision element performs its task. Voice element
configurations can additionally specify VoiceXML properties in the settings tab.
The Audio Tab: The audio tab is found in Voice element configurations only. It is used
to configure the audio assets to be used in the Voice element, including pre-recorded
audio content, Text to Speech (TTS) phrases, and dynamically configured Say It Smart™
phrases. Each Voice element contains various points where audio is to be played. These
points are called audio groups and have appropriately assigned names. Some simple
Voice elements have only a single audio group, while more complex ones may have
dozens. Each audio group can contain any number of audio items. It is up to the
developer to configure all audio items.
The Data Tab: The data tab of an element configuration is used create Element and
Session data for other elements to access later in the call for configurable Voice, Action
or Decision elements and any element skipped with a hard-coded exit state. It is also used
to determine what Element and Session data to pass from the current application to the
destination application during an Application Transfer or to pass from the current
application to an external VoiceXML document during a VoiceXML Insert.
The General Tab
All configurable elements will have some general options that can be set displayed in a tab
named General.
Dynamic Configurations
Most of the time, the configuration for an element will be fixed, meaning that each time the
element is visited in the call flow it acts the same. In this case, the Dynamic Configuration check
box should remain unchecked.
Dynamic configurations allow some or the entire configuration to be determined at runtime. This
allows for ultimate flexibility as the behavior for the element can change as often as the designer
wishes. To dynamically configure an element, check the Dynamic Configuration check box.
97
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
There are two ways that a dynamic configuration can be delivered: by either a Java class using a
Cisco-specified Java API or by an online process using a Cisco-specified API for sending XML
data over HTTP. The Java API approach is a high performance solution because all actions are
run by compiled Java code. The Java class that returns the element configuration must be
specified in full (including package name). The XML-over-HTTP approach affords developers
the ability to utilize any programming language for generating element configurations. The only
requirement is the use of a system that can return XML based on an HTTP request made by
Cisco Unified CVP VoiceXML Server. The URI to the online system that uses the XML API
must be specified.
A dynamic configuration does not have to generate the entire configuration, a fixed base
configuration can be made in Builder for VoiceXML Studio that is then accessed by the dynamic
configuration and modified to yield the final configuration. This way, an element with only a few
dynamic configuration options can define all static content in Builder for VoiceXML Studio
using the element configuration pane and write the dynamic configuration Java class or URI to
add only those few options in addition to it. In this case, check the Create Base Configuration
checkbox. There are, however, times when the configuration needs to be completely dynamic
and a base configuration is not needed. In this case, Builder for VoiceXML Studio will not create
a fixed configuration, regardless of what is entered in the element configuration pane.
For more information on writing dynamic element configurations, see the VoiceXML Server
User Guide for Cisco Unified Customer Voice Portal and Programming Guide for Cisco Unified
Customer Voice Portal.
Custom Logging
Any element can add custom data to the log produced by Cisco Unified CVP VoiceXML Server.
This data can be used for analysis purposes or for help during the development and debugging
process.
The text given in the name and value columns will be stored in the action and description
columns of the application’s activity log, respectively. The value can also include a substitution
string to allow for dynamic data to be inserted into the log. For each name/value pair, the
designer can choose whether to add to the log before the element is entered or after the element
has returned an exit state. This would be applicable only if the value used substitution that
referred to element or session data created or modified by the element itself.
See the VoiceXML Server User Guide for Cisco Unified Customer Voice Portal for more on
logging with Cisco Unified CVP VoiceXML Server.
98
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Associating a UID With the Call
In order to utilize the user management features of Cisco Unified CVP, a phone call to the
system must be linked to a user in the user management database. Users are identified in the
system with a user ID (UID). Only then can the application make decisions such as sending the
caller directly to their favorite section of the application. In most cases, the UID is set by the
developer in custom code by analyzing telephony data (e.g., the caller’s phone number) or data
entered by the caller (e.g., account number and pin).
This functionality exists in fixed element configurations primarily to aid in application
development where the developer has not yet built the user verification component but would
still like to test the process once the user is identified. By setting a UID in a fixed configuration,
the developer can unhinge the application-testing phase from development. This text box also
supports substitution to allow for more dynamic content.
The Settings Tab
Settings
Settings allow the application designer to customize the way the element behaves without
exposing them to its underlying complexity. The element itself defines which settings its
configuration contains. The more flexible an element is, the more settings it will expose. Settings
can be used to specify simple concepts such as the duration of a recording to more fundamental
concepts such as whether the element expects input from the caller using speech, DTMF, or both.
Placing the cursor over each setting name will bring up a tooltip containing text describing the
setting and what role it performs. Icons to the left of the setting indicate if the setting is required
( ) or repeatable ( ). Builder for VoiceXML Studio will not allow the application to be deployed
until all elements have values for their required settings. A repeatable setting is a setting that can
have more than one value. To add a new value to the setting, right-click on the setting and
choose to add a new value. A repeatable setting value can be deleted by selecting it from the list
when it is right-clicked. There are no limits to the number of values a repeatable setting can
have.
Each setting has a different data type that can be seen when clicking on the setting value box.
One type is a dropdown box, where the value can be only one of a finite set of options.
99
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Another type accepts string content. Other types accept integer or floating point values. One last
type, the text field, is used when the setting value can contain a large amount of text (such as an
e-mail message). The setting when selected displays a button that when clicked brings up a large
dialog box in which the content can be entered.
An element defines whether a setting allows substitution. If it does, the substitution button to the
right of the element listing will be clickable like so: . If it is not, the substitution button is
deactivated like so:
and the setting cannot have substitution in its value.
When values are chosen for a setting, other settings may appear or disappear. This is because
there are correlations between the value of some settings and the existence of other settings.
These dependencies are determined by the element and are used to simplify the process of
configuring the element. For voice elements, there can also be dependencies between setting
values and audio groups so when a setting is changed to a value that would remove an audio
group, a dialog box appears asking for confirmation.
For even more in-depth descriptions of each Cisco Unified CVP Element setting, refer to the
Element Specifications for Cisco Unified Customer Voice Portal.
VoiceXML Properties (Voice Elements Only)
In the VoiceXML specification, properties are defined as values that affect platform behavior.
Many voice browsers make use of custom properties to expose particular voice browser settings.
These properties can be placed throughout a VoiceXML document.
Unified CVP provides a mechanism to place custom properties directly in the VoiceXML pages
produced by a voice element. The VoiceXML property names and values are simply entered in
the VoiceXML property table exactly as they are to look in the resulting VoiceXML (Unified
CVP does no validation or modification of the data). For example, the sensitivity property is
used in some voice browsers to specify how sensitive the speech recognition engine is to input.
Note that property values can use substitution to obtain their values from dynamic content.
Alternatively, a property's value can be left blank to set it to an empty string. For example, to
specify that no termination character should be used, set the "termchar" property to an empty
value.
100
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Note that Unified CVP Voice elements use VoiceXML properties internally as well. The
VoiceXML properties entered by the developer in the configuration are given document-level
scope, so the form-level scope properties used by the voice elements themselves take
precedence. So entering a property in a voice element’s configuration will not change the
behavior of the element if it uses the same property.
It is up to the developer to understand the consequences of using VoiceXML properties and
Cisco suggests that they not be used unless the developer possesses at least moderate familiarity
with both VoiceXML and the specific voice browser to be used when the application is
deployed.
The Audio Tab (Voice Elements Only)
The Audio tab is used to configure the audio assets to be used in the voice element, including
pre-recorded audio content, Text to Speech (TTS) phrases, and dynamically configured Say It
Smart™ phrases.
Each voice element contains various points where audio is to be played. These points are called
audio groups and have appropriately assigned names. Some small voice elements have only a
single audio group, while more complex ones may have dozens. Each audio group can contain
any number of audio items. It is up to the developer to configure all audio items.
Audio Groups
When the Audio tab is first opened, the required audio groups appear in the audio group window.
Most voice elements have at least one required initial audio group that is used to introduce the
voice element or ask for the desired input. Each audio group has a single audio item to start. At
least this single audio item must be defined in order for the voice element to be successfully
configured. Additional audio groups are added by right-clicking the Audio Groups root folder,
selecting the audio group set in the submenu, then the audio group to add from within the next
submenu. Once added, placing the cursor over the audio group folder will display a tooltip
containing a description of that audio group.
101
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Some audio groups are repeatable. This means that they can be assigned multiple values, each
with a unique count. The count of a group is shown in its name and below the audio group
window when the group is selected. Counts are used to separate the audio to play when certain
events occur multiple times. For example, a nomatch event can occur multiple times and each
count identifies the audio to play when the corresponding nomatch count is reached. An audio
group with a count of 1 defines the audio to play the first time the event it represents occurs. The
next time the event occurs, the audio group with a count of 2 will play, etc. Even though it is
good dialog design to specify separate audio for all counts in an audio group, it does not
necessarily have to be the case. If no audio group with a count is defined, the audio group from
the previous count is used (or the initial prompt if there is no previous count). The developer can
change the count of a repeatable audio group as desired.
Bargein allows the caller to interrupt audio that is being played to either skip it completely or to
begin entering data if the instructions are known. Bargein is a function of an audio group, not an
audio item. How the caller barges in is determined by the way the voice element captures its
data. For example, if a voice element is configured to capture a currency value using DTMF (key
press) input only, to barge into an audio group, the caller would need to press any key (saying
something will not barge in). If the voice element is to capture the currency value using speech
input only, the caller barges into an audio group by saying anything (pressing a DTMF value will
not barge in). When bargein is enabled, all audio items defined in the audio group will be
skipped.
102
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Some other notes related to audio groups and audio items:
Optional audio groups can be removed by right-clicking on them and selecting Delete
Audio Group (all audio items inside are deleted as well).
Audio items can be added to audio groups by right-clicking on the audio group and
choosing Add Audio Item.
Audio items can be pasted into audio groups by right-clicking on the audio group and
choosing Paste Audio Item.
Audio items can be copied by right-clicking on the audio item and choosing Copy Audio
Item.
Audio items can be deleted by right-clicking on the audio item and choosing Delete
Audio Item.
Audio items can be renamed by right-clicking on the audio item and choosing Rename
Audio Item or by double-clicking on the audio item and typing the new name.
Audio items comments can be added/edited by right-clicking on the audio item and
choosing Edit Comment. These comments also appear in Prompt Manager in the
comment field.
The order of both audio groups and audio items within groups can be changed by
dragging them up or down. For audio groups, the order changes how they appear in
103
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Builder for VoiceXML Studio, it does not affect the voice element behavior in any way.
For audio items, its visual order determines the order the audio items are played.
Many voice elements are set up with dependencies between setting values and the
existence of an audio group. A confirmation dialog box will appear whenever a setting
value is chosen which would remove an audio group.
Audio Items
When an audio item is selected, the audio item configuration panel appears below the audio
group window. Audio items can be two types; an audio file with a TTS backup, or a Say It Smart
value. Configuration data is not saved when switching back and forth between the two audio
item types.
Static Audio:
Most of the audio in a voice application will consist of pre-recorded audio files and TTS phrases
given as a backup in case the audio file cannot be played. These are defined when the Audio
File/TTS radio button is selected.
The URI for the audio file is given in the URI text box and the content of the TTS phrase is
given in the TTS text field. If the URI is not specified, the TTS will be read all the time. If a TTS
phrase is not provided, the audio file will be played all the time unless the voice browser cannot
find the file or it is corrupted, in which case it will throw an error that will end the call. If both
are provided, the audio file will play using the TTS phrase as a backup in case the file cannot be
found or is corrupted.
When Use Default Audio Path is checked, the default audio path is prepended to the URI
entered by the designer. By using the default audio path, the designer need only enter the
filename of the target audio file instead of the complete URI; the default audio path will supply
the common path in which to find the file.
Unchecking Use Default Audio Path requires the developer to enter the absolute URI of the
target audio file.
104
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Say It Smart Audio:
Say It Smart audio items are used for situations where data with a specific format is to be
presented to the caller and that format is manageable enough to allow pre-recorded audio to be
used by “stitching” them together to generate the phrase. Examples where Say It Smart audio
items should be used include numbers, dates, times, US state names, etc. Each of these must be
read in a certain way by taking predetermined audio file components and assembling them
together to produce the value. For example, if the data “02171971” is considered a date in the
format of “MMDDYYYY”, then using the Say It Smart type for handling dates, the value would
be read as “February seventeenth nineteen seventy one”. As developers add additional Say It
Smart types, more formatted data will be able to be rendered using pre-recorded audio.
When the Say It Smart radio button is selected, the Say It Smart panel is displayed. There are
three steps to creating a Say It Smart audio item: data source definition, data format definition
and audio file information.
Data source definition: First, the data to be read is to be determined. The data can either
be entered statically in the text box, or substitution should be used if the data is dynamic.
Data format definition: The second part of defining a Say It Smart audio item is to
specify what the data represents, in what format the data appears, and in what format the
data should be read. Cisco Unified CVP ships with a standard set of Say It Smart types.
Developers are given the ability to create their own Say It Smart types or even extend
types created by Cisco using a plug-in mechanism. See the Programming Guide for Cisco
105
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Unified Customer Voice Portal for more on building custom Say It Smart plug-ins.
A Say It Smart type has at least one input format associated with it. An input format
defines how the data looks. A type may have from one to many input formats (dates, for
example, can be expressed as MMDDYY, DDMMYY, MMYY, etc.). Output formats are
dependent on the input format chosen and allow the developer to choose how to present
the data (for example, when reading back a date in the format MMDDYY, the output
format can define if the date is considered in the 1900s or the 2000s).
Audio file information: The third part of Say It Smart deals with the audio files needed
to construct the Say It Smart audio item. If the Use Recorded Audio checkbox is
unchecked, the data will be played in TTS only and there is no further configuration
required. If checked, the URI specified in the text box labeled Audio Path should point to
the directory in which all the audio files are stored. Checking the Use Default Audio Path
box will assume the URI where all the audio files used by Say It Smart are stored within
the default audio path. The Say It Smart path accepts substitution.
The audio fileset is used to determine which of a possible group of audio files to use. Many Say
It Smart types have only one set of files to render its data (for example, reading back a phone
number only requires files for the numbers 0 through 9). Other types may be able to render the
data differently using separate groups of files. Typically, these different groups are split into ones
that contain more files to produce a better sounding rendering of the data versus less files. For
example, when using the Cisco Unified CVP Number Say It Smart type for rendering the number
25962, one fileset that uses fewer files would play it back as “twenty” “five” “thousand” “nine”
“hundred” “sixty” “two” versus an enhanced fileset using more files that plays it back as “twenty
five” “thousand” “nine hundred” “sixty two”. When pre-recorded audio files are read back to
back, the latter phrase will sound more natural. Filesets are dependent on the output format
chosen for the type.
Finally, the audio file type for these files is specified by the Audio Type dropdown box. Note
that all audio files used to render the data must be of a single file type. The most common file
types (wav, vox, and au) are listed in the dropdown box, but the designer can enter any other
supported file type extension such as “ulaw” or “raw” by clicking on the substitution button and
entering the desired type manually. When entering the file type manually, enter just the
extension, there is no need for the dot.
Note that the names of the audio files are determined by the Say It Smart plug-in itself. The
system will automatically append all given information to point to the desired audio file URI. For
example if the default audio path is “http://myserver.com/audio/” and the path given is
“sayitsmart/”, then if the Say It Smart plug-in requires a file named “10” and the audio type is
given as “ulaw”, the system will assemble the following URL for the file:
“http://myserver.com/audio/sayitsmart/10.ulaw”.
The Say It Smart Specifications for Cisco Unified Customer Voice Portal document has a
comprehensive list of all Unified CVP Say It Smart types, their input formats, output formats,
106
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
and filesets, as well as a list of the audio files each one needs to be recorded to render each of its
filesets.
The Data Tab
All elements, using the Unified CVP SDK, can create element and session data that can be
accessed later in the call. Most configurable elements do this to store data captured from the
caller or calculated. The designer does not need to worry about this because the configurable
element automatically produces the element or session data. There are times, however, when the
designer wishes to manually create element or session data without having to resort to the
Unified CVP SDK. This is possible by using the Data tab found on any configurable element’s
configuration pane.
Any number of element and session variables can be created. The left column contains a list of
all custom element data variables created and the right column contains all the custom session
data variables. The variables can be edited and deleted by selecting them, making the desired
changes, and clicking on the appropriate buttons.
There are several situations where the Data tab has its uses. One can use hardcoded variables set
in an element’s Data tab to allow a non-developer to control parts of the application where code
would normally be needed. For example, a developer could design an element to get information
on a database to come from session data that is manually entered in an element’s Data tab so a
non-developer can alter it. Another situation would be to take advantage of substitution by
creating derivative variables or even modifying the element’s own variables. For example, a
variable can be created to take the value of another variable that contains a floating point value
and prepend a dollar sign to it.
The most common use of the Data tab is when an element is skipped. Refer to the section on
skipping elements for more information.
Creating Element Data
To create element data, select the radio button labeled Element, enter the desired name and value,
choose the data type, and select when the variable is to be created. Note that the value can
107
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
contain substitution allowing, for example, a variable to be created from the contents of another
variable or variables.
The data type indicates what kind of information is stored in the element data variable. The
supported types are String (“this is a string”), Integer (“242”), Float (“15.46”), and Boolean
(“true” / “false”). The data type is provided for informational purposes only for the designer and
any developers. When the developer retrieves element data, it will always arrive as a string value
so the data type can provide the developer a clue as to what the information contains.
Choosing Before for the Create option will cause the element data to be created before the
element is visited and choosing After will create the variable after the element returned its exit
state. Creating the variable before the element is entered would be useful if the element refers to
that variable. Creating the variable after the element exits would be useful if the new variable
referenced any variables created by the element itself via substitution.
When the Store this in log checkbox is checked, the element data is stored in the log (otherwise
it is not). If the variable holds data to be used within the application only, or as temporary storage
of data, there is little sense in storing it in the log. Additionally, data containing personal or
secure data should not appear in a log file, hence this being turned off by default.
Creating Session Data
To create session data, select the radio button labeled Session, enter the desired name and value,
and select when the variable is to be created. Note that the value can contain substitution
allowing, for example, a variable to be created from the contents of another variable or variables.
Session data does not require a data type and no session data is ever logged by the system.
108
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Substitution
button near a setting means that substitution can be employed.
The presence of the
Substitution allows something to be given a value that is not known until runtime, without
resorting to programming.
Data is “assembled” from static content and tags representing dynamic content, such as ANI, the
starting date, or Element and Session data created by elements. At runtime, the text that
represents the substitution value will be replaced (“substituted”) for its actual value. Substitution
is an excellent way for a designer to create dynamic content without the help of a developer.
Substitution is available wherever the substitution button appears, including:
Dynamically configured Java class names or URIs
Log entry values (not names)
Within the set UID section
Element settings
VoiceXML property values (not names)
Audio file URIs, TTS backup content, Say It Smart input data, audio path, fileset, and
audio types
Custom Element and Session data values (not names)
Application Transfer destinations
VoiceXML Insert source URI
Standard Action and Decision element Java class names or URIs
When a configuration option allows substitution, the substitution button becomes clickable.
Clicking on this button brings up a dialog box providing all substitution options and a text box
where the value can be assembled out of substitution tags.
When substitution is chosen and the appropriate data entered, clicking Add Tag will add the tag
to the value. You can continue to add additional substitution tags or static content by typing into
the text box. All static content will be concatenated with the substitution tags at runtime to yield
the final value of the configuration option. Substitutions tags are simply open and close braces
encapsulating a unique keyword identifying the data it represents.
If data represented by the tag ends up as null or empty, it will be rendered as an empty string and
a warning will be added to the VoiceXML Server Error Log.
For example, if a setting contains source = {CallData.SOURCE} and there is no application
that transferred to the current application, the setting would be evaluated as source =.
109
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
The available substitution options are:
Element Data. To substitute the value of Element data into a configuration option, select
the element from the drop-down box and type in the name of the Element data variable in
the text box Element Data.
Session Data. To substitute the value of Session data into a configuration option, type
the Session data variable name in the text box Session Data.
Call Data. To substitute information about the call into a configuration option, select the
appropriate option from the drop-down box. The available options include ANI, DNIS,
UUI, and IIDIGITS (the value will be “NA” if not available). Additional options include
“source” which holds the name of the Unified CVP voice application that transferred to
this one, “application name” which holds the name of the current application, and
“duration” which indicates the number of seconds that have elapsed since the beginning
of the call.
Caller Activity. To substitute into a configuration option either the name of an element
(or exit state) visited in the call flow or the number of times an element (or an exit state)
was visited in the call flow. For the former, the number of the visited element must be
known. For example, to get the name of the third element visited by the caller, enter 3
under the text box Where N is. For the latter, the element must be chosen from the dropdown box and if it is to indicate the number of times the element’s exit state is returned,
the desired exit state must also be selected.
110
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
User Management Options. These options are available only when the User
Management System is activated for the application. These options relate to the current
user and will cause an error unless the call is linked to a user ID (UID).
o Demographics. The choices in this drop-down box represent the demographic
information about the current user such as name, zip code, etc.
o Account Info. The choices in this drop-down box represent the account
information about the current user such as account number, PIN, and external
UID.
o Phone Number. The first choice will return a true or false, depending on
whether the caller is using one of the phone numbers registered under his/her
account. The second choice will return either the first number registered for the
caller, the total number of phone numbers the caller has registered, or the number
of calls made by that caller from the provided phone number.
o Date and Time information (available from the Date/Time tab). Returns the
last time the user called, when the caller’s account was created, and when the
caller’s account was last modified.
o Date / Time Information. These options allow for the substitution of date and
time information about the call. The choices are the current time, the start of the
call, and the last time a call was received from the current ANI. Other choices
depend on the User Management System. The substitution value can only include
a single part of the time or date (the hour, minute, day, month, year, and day of
the week). To use multiple parts, use multiple substitution tags as shown below.
The hour is in the range 0-23, minute is in the range 0-59, month is in the range 112, day of the month is in the range 1-31, the day of the week is in the range 1-7
(where 1 is Sunday), and the year is represented as a four-digit number.
111
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Prompt Manager
Prompt Manager allows developers to interact with a voice application's audio prompts in table
format. It is available as a separate view within Cisco Unified CVP VoiceXML Studio, and can
be open at the same time as the call flow editor. This view can be used to add, delete, and modify
the prompts in a voice application. Changes made through Prompt Manager are also reflected in
the Element Configuration View for each affected element.
Prompt Manager View
The Prompt Manager View is open by default in the Cisco Unified CVP VoiceXML Studio
perspective. It will appear in the bottom portion of the screen as a separate view tab. If this tab is
closed, the Prompt Manager View can be reopened by navigating to the menu option Window>Show View->Prompt Manager.
A Prompt Manager perspective is also available within the Cisco Unified CVP VoiceXML
Studio environment that will expand the Prompt Manager view to fill the entire Cisco Unified
CVP VoiceXML Studio workspace. The Prompt Manager Perspective can be opened by
navigating to the menu option Window->Open Perspective->Cisco Unified CVP Prompt
Manager.
112
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Using the Prompt Manager
Once either the Prompt Manager View or perspective has been activated, the prompts in the
application can be viewed and manipulated via the table. Fields in the table that represent
editable content are modifiable and include support for substitution where appropriate.
Additionally, the following row manipulation functions are available by right-clicking on a table
row:
Copying
Pasting (Above, Below, or Replace)
Adding/deleting audio items
Adding/deleting audio groups
When the Prompt Manager view is first opened, the rows are sorted first by page order (per the
call flow editor) then alphabetically by element name. Within each element, the audio group and
audio item display order matches that of the Element Configuration View for the element. Each
column in the table supports alphabetical sorting. A column can be toggled between ascending
and descending alphabetical sort by clicking on the column header in the table. To revert to the
default sort, click on the Default Sort button (the house icon, ) at the top-right of Prompt
Manager.
Columns can either be shown or hidden to change the content that is displayed in Prompt
Manager. Select the Choose Columns button (the three-down-arrows icon) at the top-right of
Prompt Manager. A drop-down list will appear with several pre-built column sets that can be
applied. Additionally, custom column sets can be created by choosing 'Custom...'.
Validate and Deploy
Cisco Unified CVP VoiceXML Studio provides two functions to validate and deploy
applications created in the Builder for VoiceXML Studio workspace. The VoiceXML Studio
development environment stores application descriptions and configurations in your application
project folder as XML files. These files are the source for your application. The Validate and
113
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Deploy functions act on these file sources and can be accessed by right-clicking on the project of
your choice from within the Navigator View. This section describes each in more detail.
NOTE: Any changes to the application must be saved before the Validate and Deploy
commands are used.
Validating Applications
Validation lets you check for errors in an application during development and before deploying
the application to a Cisco Unified CVP VoiceXML Server platform. Every Cisco Unified CVP
voice application created or modified within VoiceXML Studio must be validated before it can
be deployed and run on the VoiceXML Server platform.
In the Navigator View, right-click on the project you wish to validate. Select Validate. A
progress indicator will appear, indicating that the application is in the process of being validated.
If the application is free of errors, VoiceXML Studio will return to the workspace. If errors are
present, a dialog box will appear.
114
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
If you click OK you will be returned to the workspace and the Cisco Unified CVP Problems
window will indicate all errors present in the application.
If you click on the individual items in this list, VoiceXML Studio will automatically select the
corresponding element in the workspace that caused the error. After fixing the errors, check to
see if they have been corrected by running the Validation command again.
Deploying Applications
To run a Cisco Unified CVP voice application that has been created in VoiceXML Studio, the
application needs to go through a two-step process:
1. Successful validation.
2. Conversion of the "development-time" application files to "run-time" application files
using the Deploy option.
Once the application is validated (see above), you can access the Deploy function by rightclicking on the project in the Navigator View. This will open the Deploy dialog window. There
are three deployment options: Local, Remote and Archive, discussed below. The application will
automatically be validated again before being deployed and it must pass with no errors.
115
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Local Deploy
This is the default setting for the Deploy dialog box. The current active application is displayed
at the top of the box, but other projects that are open in the Navigator View will also be shown.
The check box next to the project indicates whether or not the application(s) will be deployed
when Finish is pressed. By default, only the project you right-clicked will be selected.
116
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Before you can deploy your application, you must enter the location of your Cisco Unified CVP
VoiceXML Server directory. Most of the time this value will be automatically entered for you
(see the Installation and Upgrade Guide for Cisco Unified Customer Voice Portal for additional
information).
There are multiple mechanisms for entering this information:
1. If you know the location of your Cisco Unified CVP VoiceXML Server directory, type it
in the text box (for example: CVP_HOME\VXMLServer). Or:
Click on Browse and locate your Cisco Unified CVP VoiceXML Server directory.
If the deployment tool has been previously used on this installation, the Deploy dialog
will have a stored history of local deploy targets. Left-click on the down arrow next
to the text box to see the history. If the desired location exists, left-click on the
location to select it.
2. Once you have chosen your desired local target, left-click Finish.
NOTE: The destination directory for Local Deployment is not limited to volumes that
are located on your machine. Any network folder that is mountable by your Windows
operating system can be selected for the local deployment option.
3. Your application(s) are now deployed and can be run. If VoiceXML Server is running,
use the appropriate administration script to load the new application.
If VoiceXML Server is not running, start the application server on which VoiceXML
Server is installed (see the VoiceXML Server User Guide for Cisco Unified Customer
Voice Portal for details).
Remote Deploy
You can deploy applications to a remote VoiceXML Server platform by choosing the Remote
Deploy option. This option uses the FTP protocol, in passive mode. An FTP server with proper
access privileges must be available and configured before you can use this option. In the Deploy
dialog, check the box next to Deploy Remotely. Once checked, the three previously-grayed-out
text fields will become active.
Enter the remote location of your Cisco Unified CVP VoiceXML Server directory in the Cisco
Unified CVP Home text box. Also enter the address of your server, your user name, and your
password. Click Finish and your application will be deployed.
If VoiceXML Server is running, use the appropriate administration script to load the new
application.
117
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
If VoiceXML Server is not running, start the application server on which VoiceXML Server is
installed. (See the VoiceXML Server User Guide for Cisco Unified Customer Voice Portal for
details.)
Archive Deploy
This option will result in producing the Cisco Unified CVP VoiceXML Server deployment files
in a zip archive file. This option is useful when the application may be distributed to other
machines for deployment. The archive file is provided as an alternative to the Local Deploy
option. In the top section of the dialog you will see the current active application (the dialog box
will also show other projects that are actively open in the Navigator View.) The status of the
check box next to the project indicates whether or not the application will be deployed when the
Finish button is pressed.
By default only the project you right-clicked to invoke this dialog will be selected. If multiple
applications are checked, all of the selected applications will be added to the archive file in
separate application folders. Before you can proceed and create the archive file, the location
where the archive file should be created must be entered. A path can be entered manually, or
navigated to by using the Browse button.
118
CHAPTER 3: CISCO UNIFIED CVP WORKSPACE
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Once you have chosen the desired archive name, click on Finish. The archive file will be created
and saved to the defined location.
If the archive file option is used, remote deployment by FTP will not be permitted
119
INDEX
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
.
D
.callflow file......................................................................50
Data format definition .................................................... 105
Data source definition .................................................... 105
Data tab .................................................................... 97, 107
Date / Time Information................................................. 111
Date and Time ................................................................ 111
Decision Editor........................................................... 59, 61
Default audio path URI .................................................... 38
Default sort..................................................................... 113
Deleting............................................................................ 31
Demographics ................................................................ 111
Deploy............................................................................ 113
Deploy folder ................................................................... 21
Deploy version ................................................................. 35
Deploying applications.......................................See Deploy
Documenter...................................................................... 43
Documenter Output .......................................................... 47
Dynamic Configurations .................................................. 97
A
Application specification ..................................................43
Account info ...................................................................111
Activation .........................................................................17
Adding/deleting audio groups.........................................113
Adding/deleting audio items ...........................................113
Angled lines......................................................................83
app.callflow file ................................................................21
Application Transfer .........................................................70
Archive deploy ...............................................................118
Audio file information ....................................................106
Audio file/TTS................................................................104
Audio groups ..................................................................101
Audio items.....................................................................104
Audio settings ...................................................................37
Audio tab ..................................................................97, 101
Audio type ......................................................................106
B
Backing up........................................................................33
Bend points .......................................................................84
Builder .........................................................................vi, 20
C
Call flow ...........................................................................20
Call data..........................................................................110
Call flow theme.................................................................19
Caller Activity ................................................................110
Callflow folder............................................................21, 49
Callflow editor ............................................................53, 79
Choose columns..............................................................113
Cisco Software License Registration ................................18
Cisco Unified CVP Home...............................................117
Cisco Unified CVP VoiceXML Server.............................20
Comment ..........................................................................73
Concurrent Versions System.................See Version Control
Integration
Configurable elements ................................................54, 55
Connecting elements.........................................................81
Copy .................................................................................88
Creating a Decision...........................................................62
Creating Element Data....................................................108
Creating Session Data.....................................................108
Custom logging.................................................................98
Cut ....................................................................................88
CVP Home............................See Cisco Unified CVP Home
CVS ................................... See Version Control Integration
E
Element comments ........................................................... 95
Element configuration tabs............................................... 97
Element Configuration view ...................................... 53, 96
Element data....................................................... 66, 71, 110
Element Group exit states................................................. 92
Element Group templates ................................................. 94
Element Groups................................................................ 90
Element naming ............................................................... 80
Elements view ............................................................ 53, 54
Encoding .......................................................................... 36
Endpoint settings.............................................................. 39
Error audio URI................................................................ 37
Error element.................................................................... 75
Expand call flow elements in Outline View ..................... 19
Expand elements in Elements View ................................. 19
F
Flag elements ................................................................... 64
G
General settings................................................................ 35
General tab ....................................................................... 97
Generic error message...................................................... 37
H
Hang Up ........................................................................... 74
Hotevents ......................................................................... 67
Hotlinks............................................................................ 68
120
INDEX
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
I
RTF ....................................................See Rich Text Format
Installation key .................................................................17
Importing ..........................................................................26
Initial on-hold audio URI..................................................38
S
J
JavaScript .........................................................................41
L
Language ..........................................................................35
Licensing ..........................................................................16
Local deploy ...................................................................116
Loggers .............................................................................36
M
Main on-hold audio URI...................................................38
Maintainer.........................................................................35
Manual activation .............................................................18
Multiple developers ..........................................................50
O
On Application End ..........................................................40
On Application Start .........................................................39
On Call End ......................................................................40
On Call Start .....................................................................40
Online activation...............................................................17
P
Saving an Element Group template .................................. 94
Say It Smart.................................................................... 105
Selecting elements............................................................ 80
Session data.............................66, 71, 84, 97, 108, 109, 110
Session timeout ................................................................ 36
Settings tab................................................................. 97, 99
Skipping call flow ............................................................ 84
Substitution button ................................................. 100, 109
Standard elements ...................................................... 54, 57
Start of Call ...................................................................... 74
Static audio..................................................................... 104
Store this in log .............................................................. 108
Subdialog ......................................................................... 36
Subdialog elements .......................................................... 77
Substitution .................................................................... 109
Suspended audio URI....................................................... 38
T
Trial period....................................................................... 18
TTS ................................................................................ 104
U
UID .......................................................................... 99, 111
Undo................................................................................. 89
Unified CVP VoiceXML Server ...................................... 20
Use default audio path.................................................... 104
User Management .................................................... 36, 111
User ID..................................................................... 99, 111
Page Connectors ...............................................................71
Page Entries ......................................................................71
Pages subfolder.................................................................49
Paste..................................................................................88
Phone Number (in substitution) ......................................111
Plug-ins.............................................................................16
Prompt listing ...................................................................43
Preferences........................................................................19
Project properties ..............................................................34
Projects .......................................................................20, 21
Prompt Manager ...............................................53, 112, 113
Property ........................................ See VoiceXML Property
Validating applications................................................... 113
Variable.........................................See VoiceXML Variable
Version control integration......................................... 49, 52
Voice elements ................................................................. 56
VoiceXML gateway ......................................................... 36
VoiceXML Insert elements .............................................. 65
VoiceXML property......................................................... 41
VoiceXML server........................................................... 117
VoiceXML variable.......................................................... 42
R
W
Redo..................................................................................89
Remote deploy ................................................................117
Renaming..........................................................................29
Repositioning elements.....................................................80
Resizing elements .............................................................80
Rich Text Format..............................................................43
Root document settings.....................................................41
Repeatable settings ...........................................................99
Required settings ..............................................................99
Workspace........................................................................ 53
V
X
XML Decision.................................................................. 60
121
INDEX
VOICEXML STUDIO USER GUIDE
FOR CISCO UNIFIED CUSTOMER VOICE PORTAL
Z
Zoom in ............................................................................89
Zoom out ..........................................................................89
122
