VoiceXML Programming 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 .
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.
TABLE OF CONTENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) PREFACE ...................................................................................................................................................................V PURPOSE ................................................................................................................................................................... V AUDIENCE ......................................................
TABLE OF CONTENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) USING THE JAVA API...............................................................................................................................................34 USING THE XML API ..............................................................................................................................................34 CHAPTER 8: STANDARD DECISION ELEMENTS..............................................
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Preface Purpose This document describes how to use the programming APIs provided by Cisco Unified CVP VoiceXML. Topics covered include building custom elements and the Cisco Unified CVP VoiceXML Java and XML APIs. Audience This document is intended for system and voice applications and component developers using Cisco Unified CVP VoiceXML.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter Description Chapter 9: Configurable Elements Describes how to create custom voice, action, and decision elements and integrate them into both Cisco Unified CVP VoiceXML Studio and the Cisco Unified CVP VoiceXML Server. Chapter 10: Application Start Classes Describes how to create application start classes to run code when an application starts.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) 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.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Conventions This manual uses the following conventions: Convention boldface font Description Boldface font is used to indicate commands, such as user entries, keys, buttons, and folder and submenu names. For example: Choose Edit > Find. Click Finish. italic font 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.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Obtaining Documentation Cisco documentation and additional literature are available on Cisco.com. This section explains the product documentation resources that Cisco offers. Cisco.com You can access the most current Cisco documentation at this URL: http://www.cisco.com/techsupport You can access the Cisco website at this URL: http://www.cisco.com You can access international Cisco websites at this URL: http://www.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) 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.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) To register as a Cisco.com user, go to this URL: http://tools.cisco.com/RPF/register/register.do Obtaining Technical Assistance Cisco Technical Support provides 24-hour-a-day award-winning technical assistance. The Cisco Support website on Cisco.com features extensive online support resources.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) 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.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Developers using VoiceXML Studio scripts, ASR, and the like may be interested in joining the Cisco Developer Services Program. This fee-based subscription program was created to provide you with a consistent level of Services that you can depend on while leveraging Cisco interfaces in your development projects.
PREFACE VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) category to direct you quickly to the documentation for your products. You can view the latest release of “What’s New in Cisco Documentation” at this URL: http://www.cisco.com/univercd/cc/td/doc/abtunicd/136957.htm World-class networking training is available from Cisco. You can view current offerings at this URL: http://www.cisco.com/en/US/learning/index.
CHAPTER 1: INTRODUCTION VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 1: Introduction Cisco Unified Customer Voice Portal VoiceXML Server software has been designed to be easy to use but highly extendable. While the software provides enough to produce high quality voice applications out of the box, many users will want to extend the functionality of the software by building custom components that perform very specific tasks.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 2: Cisco Unified CVP API Introduction Cisco Unified CVP’s API design has three goals: to be simple to use, to provide all the information a developer may need, and to allow the use of as many programming languages as possible. The API is used for simple tasks such as getting the ANI of the call or complex tasks such as creating a custom voice element.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The classes used to obtain and change environment information are referred to as the Session API. All components receive an instance of one of the classes to act as the conduit between the component and Unified CVP VoiceXML Server.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) An application is loaded into memory when the VoiceXML Server first starts up or the application is updated. During this process, a single instance of each element (both standard and configurable) is created and cached for the application to use. Whenever a call to that application encounters an element, the VoiceXML Server will call the execution method of that single instance.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Unified CVP VoiceXML Studio Deployment Unified CVP VoiceXML Studio provides a location to place components that are to be shared across all applications: VoiceXML Studio/eclipse/plugins/com.audiumcorp.studio.library.common_5.1.0. Individual classes are placed in the classes subdirectory and JAR file archives are placed in the lib subdirectory.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) As a result, it is the developer’s responsibility that the contents of the common folder in VoiceXML Studio also appear in the VoiceXML Server common folder. Note that when the VoiceXML Server initializes, it first loads the classes in common and then loads each application’s classes.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Apache Jakarta Tomcat application server, a library for connecting to a mainframe system can be placed in TOMCAT_HOME/common/lib rather than any Unified CVP directory. XML API The philosophy behind the XML API is to provide as much of the functionality found in the Java API as possible in a way that can be accessed by non-Java developers.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) While the XML API provides the same functionality as the Java API, there are some small deficiencies. Firstly, there is additional overhead involved in the XML API since it involves the creation and parsing of XML as well as the overhead inherent in HTTP communications.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Figure 2-1 shows a sample DTD diagram that contains most of what can be found in an XML DTD. A DTD diagram is a graphical representation of a DTD that explains how an XML document is formatted. Due to the nature of XML, syntax is very important and DTD diagrams describe the syntax of an XML document.
CHAPTER 2: CISCO UNIFIED CVP API INTRODUCTIONVOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Notes: child1 is allowed to appear multiple times because it has a * next to it. One child1 tag does not have an attribute because it is optional. Additionally, since these tags do not encompass any additional content, the tag is closed with a “/>” so there is no need for a closing tag. child2 contains its two child tags.
CHAPTER 3: SESSION API VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 3: Session API As described in the previous chapter, Cisco Unified CVP provides a mechanism for the developer to access and change information having to do with the phone call or the session. Through this API one can get environment information such as the phone number of the caller (ANI), the time the call began, and application settings such as the default audio path.
CHAPTER 3: SESSION API VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Creating session data. This class does not allow the creation of element data because only elements can do so (the start of call class cannot, for example). Triggering custom logging events and warning events that are picked up by loggers. Setting the maintainer, default audio path, application language and encoding, as well as the call’s session timeout.
CHAPTER 3: SESSION API VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) XML Document Sent in “inputs” Figure 3-1 shows the DTD diagram for the XML document sent to all components in the “inputs” argument. Its DTD is defined in the file ElementRequest.dtd in the VoiceXML Server dtds folder.
CHAPTER 3: SESSION API VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) telephony – This tag holds information about the call itself such as the ANI. It also contains the area code and exchange of the ANI. All values are “NA” if not sent by the voice browser (area code and exchange won’t appear at all in the case that the ANI is not sent). call – This tag holds call information. The session ID is used by Unified CVP VoiceXML Server to identify the call.
CHAPTER 3: SESSION API VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) XML Document Sent in “settings” Figure 3-2 shows the DTD diagram for the XML document sent to all components in the “settings” argument. Its DTD is defined in the file Settings.dtd in the VoiceXML Server dtds folder. Note that this document shares the same DTD as the static application settings file settings.
CHAPTER 3: SESSION API VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The tags in this XML document are: application – The root tag. The key and serial attributes are used by VoiceXML Studio and the VoiceXML Server and can be safely ignored here. The version attribute holds the version of the file. The above diagram represents version 1.2 of the DTD. The subdialog attribute holds a true if the application is accessed as a subdialog, false if not.
CHAPTER 3: SESSION API VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) o on_start_call. The Java class or URI to call when a call to the application starts. The class attribute lists the full class name of the Java class. The src attribute contains the URI to call. The two attributes are mutually exclusive.
CHAPTER 3: SESSION API VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Again, these two documents are sent as HTTP POST arguments to any URL using the XML API. The documents mirror all the functionality provided in the Java API to obtain session information. Changing session information, such as setting session data, is done in the response XML document. Since each component has a separate response document, they are described in each component’s individual chapter.
CHAPTER 4: CALL START ACTION VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 4: Call Start Action Unified CVP VoiceXML Server can be configured to run code when a call has been received before the call flow is visited. The call start action can be implemented with either the Java API or the XML API. The call start action is a good way to create session data to be used by the rest of the application.
CHAPTER 4: CALL START ACTION VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Using the Java API The call start action is built in Java by implementing the Unified CVP class StartCallInterface found in the com.audium.server.proxy package. It contains a single method named onStartCall that is the execution method for the call start class. This method receives a single argument, an instance of CallStartAPI.
CHAPTER 4: CALL START ACTION VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The tags in these XML documents are: new_data – This tag holds the session data to be created. Any number of tags can appear, one for each session data variable to be created. Note that element data cannot be created because the call start action is not an element. set_uid – This tag is used to associate the call to a UID in the user management system.
CHAPTER 5: CALL END ACTION VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 5: Call End Action Unified CVP VoiceXML Server can be configured to run code once a call has ended. Unlike the call start action, the call end action can occur at any time in the call and there are several different situations that would trigger the call end action. The following lists those situations: The caller hangs up normally. The application hangs up on the caller.
CHAPTER 5: CALL END ACTION VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) A unique feature of the call end action is to optionally send back a final VoiceXML page to the voice browser. Some voice browsers will actually interpret a VoiceXML page sent back in response to a request triggered by a disconnect or hang-up event.
CHAPTER 5: CALL END ACTION VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The tags in these XML documents are: new_data – This tag holds the session data to be created. Any number of tags can appear, one for each session data variable to be created. Note that element data cannot be created because the call end action is not an element. set_uid – This tag is used to associate the call to a UID in the user management system.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 6: Dynamic Element Configurations Configurable voice, action, and decision elements used in an application must have configurations. Usually, the configuration will be fixed, i.e., it acts the same every time a caller visits it. In this case, the configuration itself exists as an XML file stored on the system.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The method must return an instance of the configuration object (VoiceElementConfig, ActionElementConfig or DecisionElementConfig). This can be a modified version of the object passed as input to the method or one built from scratch. It is expected that should an unrecoverable error occur, the dynamic configuration class should throw an AudiumException.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The response must contain the final configuration to use, which follows the same DTD as the base configuration XML document. Incidentally, this DTD is the same one used for the fixed element configuration XML files created by Unified CVP VoiceXML Studio.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) error – This tag reports to Unified CVP VoiceXML Server that an error occurred while executing the dynamic configuration. The VoiceXML Server will then throw an exception whose message is contained in the tag. This allows the XML API to throw exceptions just as the Java API does.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) invalidate_session – This tag, if included in the XML, will prompt Unified CVP VoiceXML Server to invalidate the call session it retains in memory, call the end of call class or URI (if defined), and free up the VoiceXML Server port utilized by the call. The session is invalidated only after the execution method of the dynamic configuration is completed.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The tags in this XML document are: configuration – The root tag. The class attribute refers to the Java class defining the configurable voice element whose configuration is being dynamically produced. Refer to the VoiceXML Element Specifications for Cisco Unified Customer Voice Portal document for the full Java class names of all Unified CVP elements.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) new_data – This tag holds the element and session data this dynamic element configuration is to create. Any number of and tags can appear, one for each element and session data variable to be created. The log attribute of sets whether the value of the variable is stored in the activity log.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Since the DTDs of the documents returned by the XML API are the same as those for static element configurations produced by Unified CVP VoiceXML Studio, dynamic configurations may also utilize substitution.
CHAPTER 6: DYNAMIC ELEMENT CONFIGURATIONS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) historical_data – Represents past actions taken by the user associated with this call (available only when the user management system is turned on and the call is associated with a particular UID). These tags are identical to tags of the same name used within the Unified CVP XML decision format.
CHAPTER 7: STANDARD ACTION ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 7: Standard Action Elements Action elements are responsible for performing some action and returning an indication whether the action was a success. A pre-built, configurable action element has already defined the actions to take and only requires a configuration to modify its behaviors.
CHAPTER 7: STANDARD ACTION ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Figure 7-1 The elements in this XML document are: status – Since the XML API accesses a process that exists in context separate from Unified CVP VoiceXML Server, there is no automatic way for an error that occurs during the creation of a response to be caught and handled properly by the VoiceXML Server.
CHAPTER 7: STANDARD ACTION ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) new_data – This tag holds the element and session data this standard action element is to create. Any number of and tags can appear, one for each element and session data variable to be created. The log attribute of sets whether the value of the variable is stored in the activity log.
CHAPTER 8: STANDARD DECISION ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 8: Standard Decision Elements Decision elements apply business logic to decide which exit state to return. A pre-built, configurable decision element has already defined the business logic and only requires a configuration to modify its behavior.
CHAPTER 8: STANDARD DECISION ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Figure 8-1 The elements in this XML document are: exit_state – This tag contains the string value representing the exit state in the exact format specified in Unified CVP VoiceXML Studio when the standard decision element was first defined. error – This tag reports to Unified CVP VoiceXML Server that an error occurred while executing the standard decision element.
CHAPTER 8: STANDARD DECISION ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) set_flag – This tag is used to make the decision element act like a flag when visited. If it appears, a flag with the same name as the decision element will be considered triggered and that fact will be noted in the activity log. log – This tag is used to store information in log files for this application when this standard decision element is executed.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 9: Configurable Elements The large array of Unified CVP Elements bundled with Cisco Unified CVP software encapsulate a lot of functionality a typical voice application requires. There are, however, situations where more customized, proprietary, or robust elements are desired.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) com.audium.server.voiceElement package. These three base classes all extend a common base class for configurable elements, ElementBase.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Common Methods The methods listed below are defined in ElementBase and are common to all configurable elements no matter what type. All custom Unified CVP classes used by these methods are defined in the com.audium.server.voiceElement package. Refer to the Javadocs for more in depth explanations of these methods and the classes they utilize.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) At this juncture, neither VoiceXML Studio nor the VoiceXML Server use the information returned from this method. One of the reasons is that for some elements, what element data is created may not be known until runtime. In future versions, VoiceXML Studio may utilize the results of this method to aid the application designer in choosing element data when using substitution.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) configured to allow substitution or prevent it, for example if that setting’s behavior would be too unpredictable if its value were set dynamically. See the VoiceXML Server User Guide for Cisco Unified Customer Voice Portal for more on substitution. The setting default value.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) creating and editing a configuration object, a custom element uses these classes basically to read their information. There is little reason to edit the configuration classes within a custom element as the configuration object applies only to that particular use of the element (revisiting the element will provide it with a new configuration).
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The execution method, doDecision(), receives an instance of the API class DecisionElementData. This class belongs to the Session API and is used to access session information (See Chapter 3: Session API for more on this API).
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Having a single voice element class produce multiple VoiceXML pages poses a problem. With multiple calls simultaneously accessing the element in various stages of a call, how is the voice element to know where a particular caller is within the element at any one moment in time? Unified CVP helps by providing “scratch space” for custom voice elements to store any data it wishes.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The diagram shows a typical exchange between the voice browser, Unified CVP VoiceXML Server, and several voice elements. In step 1, the voice browser makes an HTTP request for a VoiceXML page to the VoiceXML Server. According to its record of the application call flow, the VoiceXML Server in step 2 accesses the voice element Foo. The voice element Foo is shown on the right.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The voice element cannot use a or to link to a VoiceXML page external to the VoiceXML Server. When it is time to return to the voice element in a VoiceXML page, a URL pointing back to the VoiceXML Server must be used. This is required by the design using the VoiceXML Server as the abstraction layer between the voice browser and the voice element.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) A voice element can add any Java object to scratch space via the setScratchData() method in VoiceElementData. Scratch data is used for voice element internal uses only since the scratch space is cleared when the voice element ends, even if it is revisited in the same call. Additionally, the data in the scratch space is stored in the session managed by the VoiceXML Server.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) should be visited again when the voice browser sends its next request to the VoiceXML Server. Only when the method returns a proper exit state will the VoiceXML Server follow the application call flow and proceed to the next element.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) that instance. This executes a sub-element within the super-element using the same context. The sub-element executes normally, it reads from a configuration object and creates VFC classes. The difference is that the super-element can take what the sub-element produced and modify it or add to it.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The element data namespace is shared across the super-element and all sub-elements. Again, the VoiceXML Server uses a separate namespace for each element it is aware of, which means the super-element. The super-element must ensure that element data created by one sub-element does not overwrite the element data created by another sub-element.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The audio groups are arranged in sets by storing them in a HashMap Java collection. The keys of the HashMap are the names of the audio group sets and the values of the HashMap are arrays of AudioGroup instances that belong to their set. The array represents the audio groups to display within that set. The order specified in the array is the order they appear in VoiceXML Studio.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) must be explicitly added to the argument list in order to log correctly. Another advantage of using the getSubmitVAction() methods are that they already add this variable to the submit. The convention used to for interaction logging appends the action name, description, and timestamp using the following format: “|||ACTION$$$VALUE^^^ELAPSED” where: ACTION is the name of the action.
CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Note that the expr attribute of is used because the value is actually an expression that concatenates various strings together. First, the audium_vxmlLog variable must be listed because we are appending new data to it.
CHAPTER 10: APPLICATION START CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 10: Application Start Classes Application start classes are unlike most components in that they are not related to a call session. Application start classes are instead associated with a particular application and are executed when the application itself is initialized or updated. Currently, only the Java API can construct code to run when an application starts.
CHAPTER 10: APPLICATION START CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The main purpose for an application start class would be to prepare information that would then be used by call-specific components, especially if the setup process takes a long time to run. For example, if an application has elements that are written to access a backend database or mainframe system, they could initiate connections to that system each time they need to.
CHAPTER 11: APPLICATION END CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 11: Application End Classes Application end classes are unlike most components in that they are not related to a call session. Application end classes are instead associated with a particular application and are executed when the application itself is taken down or updated. Currently, only the Java API can construct code to run when an application starts.
CHAPTER 11: APPLICATION END CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) classes have the ability to create application or global data, though the concept of creating data right before the application is released would seem pointless. The one situation where this would be useful would be to set data that a subsequent application end class could use.
CHAPTER 12: SAY IT SMART PLUGINS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 12: Say It Smart Plugins Similar to the ability for a developer to create custom elements, a developer can create their own Say It Smart plugins. A developer can produce plugins that handle brand new Say It Smart types as well as plugins that extend the functionality of existing Say it Smart plugins.
CHAPTER 12: SAY IT SMART PLUGINS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) output formats, so when the output format changes, the list of filesets available changes accordingly. The plugin defines these dependencies using a configuration method. Note that a fileset deals with audio files so does not apply when the Say It Smart value is rendered in TTS only.
CHAPTER 12: SAY IT SMART PLUGINS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) transcript (by making it null) would mean that if the audio file could not be found, the application would prematurely end with an error. The developer can throw a SayItSmartException in this method indicating the data passed to the plugin could not be converted using the specified configuration.
CHAPTER 12: SAY IT SMART PLUGINS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) getDisplayInformation() is abstract, meaning every Say It Smart plugin must implement this method. SayItSmartDependency getFormatDependencies() As described in the design section, a plugin’s output formats are dependent on the input formats. This method defines those relationships.
CHAPTER 12: SAY IT SMART PLUGINS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Utility Methods These utility methods are provided to aid Say It Smart plugin developers. Their use is optional. void validateArguments(Object data, String inputFormat, String outputFormat, String fileset) This method validates each argument and throws a SayItSmartException if there is an error with one of them.
CHAPTER 13: LOGGERS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 13: Loggers The mechanism used by Cisco Unified CVP VoiceXML Server to record information about activities taken by callers to deployed applications or administrators is by using loggers.
CHAPTER 13: LOGGERS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) single instance. Note that an instance variable in the logger class will allow it to maintain information that spans calls. A logger is expected to “register” the events it wishes to act on. This is done on logger initialization. When Unified CVP VoiceXML Server loads, it initializes all the loggers referenced for an application the records which events each will act on.
CHAPTER 13: LOGGERS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) would be handled in the same order they occurred within the call. To remedy this situation while keeping the design unfettered, it is possible to specify that Unified CVP VoiceXML Server pass a logger instance events in the same order they occurred in a call. With this option on, the logger developer can be assured that the events for a call would not be handled out of order.
CHAPTER 13: LOGGERS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) This method is called by Unified CVP VoiceXML Server when a new logger instance is created. This occurs in four different situations: the application server starts up, the VoiceXML Server web application is restarted, the application the logger instance belongs to is deployed after the application server had started up, and the application is updated.
CHAPTER 13: LOGGERS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) This method is the execution method for the logger and is called by Unified CVP VoiceXML Server when a new event has occurred that the logger must handle. This method is called only if the VoiceXML Server has found the event’s ID in the eventsToListenFor HashSet. Only one object is passed to this method, an ApplicationEvent.
CHAPTER 13: LOGGERS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Generally speaking, there are two types of application events; call-level, and applicationlevel. o Call-level events extend from ActivityEvent and are associated with a particular call. As such, these events provide information about the call environment through the method getLoggerAPI().
CHAPTER 13: LOGGERS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Utility Methods These utility methods provide important information to the logger. String getLogFileDirectory() This method returns the full path of the directory Unified CVP VoiceXML Server has provided this logger to store its logs, if necessary. On startup, the VoiceXML Server creates a folder for each logger instance whose name is the logger instance name within the logs folder of the application.
CHAPTER 14: HOTEVENTS VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 14: Hotevents Hotevents can only be produced through the Java API because they involve the use of the Unified CVP Voice Foundation Classes (VFCs), which are Java-only (see 0 The Voice Foundation Classes for more on the VFCs). When a new hotevent is added to the workspace in Unified CVP VoiceXML Studio, the full name of a Java class must be entered in the hotevent dialog box.
CHAPTER 15: ON ERROR NOTIFICATION VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) Chapter 15: On Error Notification The error notification process can only be implemented using Java because when an error occurs, one desires the most reliable method for reporting that error. There is no guarantee an HTTP request to a URI could even be generated, a response received and the XML parsed without incurring another error.
0 THE VOICE FOUNDATION CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) The Voice Foundation Classes The Unified CVP Voice Foundation Classes are a Java API for generating VoiceXML. Any custom component wishing to produce VoiceXML must use the VFCs because their main purpose is to act as an abstraction layer between VoiceXML and the component.
0 THE VOICE FOUNDATION CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) and version 2.0, and the similarities are encapsulated in a common base class. Figure 15-1 shows this graphically with the VForm class. The main VForm class extends the VRoot class and is itself extended by VFormV1 and VFormV2, representing VoiceXML 1.0 and 2.0 compliance.
0 THE VOICE FOUNDATION CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) VPreference pref = ved.getPreference(); VForm form = VForm.getNew(pref, "start"); Here, the VPreference object is obtained from the VoiceElementData object passed as input to a voice element. It is used to create a VForm object.
0 THE VOICE FOUNDATION CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) com.audium.core.vfc.list.VList. This class is used to encapsulate a list of items that can be deployed as either a traverse list or a streaming list. A traverse list presents a menu after an item is presented that allows the caller to move forwards and backwards through the list. A streaming list is one where all the items are played one after the other.
0 THE VOICE FOUNDATION CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) o com.audium.core.vfc.form.VFormItemRoot. This class is the base class for all form items. It defines the ability to include audio, which every form item shares. com.audium.core.vfc.form.VInitial. This class is used when performing mixed initiative data capture.
0 THE VOICE FOUNDATION CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) o com.audium.core.vfc.form.VMenuField. This class is used when a menu is desired in the VoiceXML document. The class produces tags with
0 THE VOICE FOUNDATION CLASSES VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) o com.audium.core.vfc.util.VoiceInput. This class is used to encapsulate how input is to be expected from the caller. It can encapsulate voice only input, DTMF only input, or both. It is also used to specify what data to look for, which can be a single or multiple keywords or keypresses. This class is typically used with menus and forms. o com.audium.core.vfc.util.IfCondition.
0 THE VOICE FOUNDATION CLASSES A Accessing the Global API.................................................12 Action Elements................................................................45 ActionAPI.........................................................................25 ActionConfigInterface ......................................................25 ActionElementBase ..............................................34, 40, 45 ActionElementConfig ...........................................
INDEX VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) G P Gateway Adapters.............................................................75 Global API........................................................................11 GlobalErrorInterface.........................................................74 Perl ................................................................................. 2, 7 PHP ..........................................................................
INDEX VOICEXML PROGRAMMING GUIDE FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1) V VEvent..............................................................................73 VFC Classes .....................................................................77 VFC Design ......................................................................75 VFCsSee Voice Foundation Classes, See Voice Foundation Classes Voice browser...................................................................
