Cisco Unity Express JSP, Servlet, and VoiceXML Web ... · PDF fileCisco Unity Express JSP,...

Americas Headquarters:Cisco Systems, Inc., 170 West Tasman Drive, San Jose, CA 95134-1706 USA

© 2007 Cisco Systems, Inc. All rights reserved.

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide

First Published: July 13, 2007, OL-14106-01

With the addition of Interactive Voice Response (IVR) features, Cisco Unity Express 3.0 allows deployment of your customized JavaServer Pages (JSP), servlet, and VoiceXML applications. Your applications must use the built-in VoiceBrowser to render the deployed applications.

Note In this document, the term web application refers to your customized application that can be deployed on Cisco Unity Express. The JSP or servlet objects may be referred to as Dynamic Objects when the reference can include either one.

ContentsOverview, page 2

Developing the Web Application, page 2

Development Framework, page 2

JSP, Servlet, and VoiceXML Creation, page 4

Java APIs, page 4

Dynamic Objects, page 12

VoiceXML Documents, page 18

Building and Deploying the Web Application, page 21

Downloading the Development Framework, page 21

Customizing the VoiceXML and JSP, page 22

Installing Development Environments, page 22

Modifying Build Scripts, page 22

Executing Build Scripts, page 23

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide Overview

2Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide

OL-14106-01

Deploying the Web Application, page 23

Executing the Web Application, page 24

Debugging the Web Applications, page 25

Cisco DTMF Grammar, page 25

VoiceXML VoiceBrowser Known Limitations, page 27

Supported VoiceXML Session Variables and Field Properties, page 28

Additional References, page 29

Obtaining Documentation, page 29

OverviewYour customized VoiceXML application using the Cisco Unity Express built-in VoiceBrowser can access most of the resources that are available to a script written using the Cisco Unity Express Script Editor, including the prompts. Your customized application also has access to a logging utility that provides tracing similar to Cisco tracing.

Your customized VoiceXML application must use the Cisco Dual Tone Multifrequency (DTMF) grammar otherwise known as Cisco regular expression (regex) grammar when defining the DTMF patterns that the application accepts. See the “Cisco DTMF Grammar” section on page 25 for a description of this grammar. Other grammars such as Grammar Specification Language (GSL), Nuance, Speech Recognition Grammar Specification (SRGS), and Speech Synthesis Markup Language (SSML) are not supported.

The JSP technology enables you to create and deploy dynamic web applications. The JSP technology allows Java code and certain other predefined actions to be embedded into the static content, like VoiceXML, to provide the dynamic content. Cisco Unity Express only supports Java based languages in creating dynamic content, so other languages, such as ASP, Perl, and PHP are not supported.

You can also use the Java servlet APIs to create servlet objects that can also generate dynamic web content. The servlet object can process requests and generate responses to interact with VoiceXML.

Developing the Web ApplicationThe web application development process is:

1. Download the tar file that contains the framework in terms of library files, sample JSP and VoiceXML files and build scripts.

2. After this tar file is downloaded and expanded, you can write new JSP, servlet, and VoiceXML files to implement the desired functionality.

3. Use the build script to compile and build the deployable web archive (WAR) file.

Development FrameworkDownload the ivrjsp.<version>.tar file from Cisco.com. Obtain this file from the Voice Software download section under Cisco Unity Express software version 3.0.0. The main Voice Software download page is located at http://www.cisco.com/kobayashi/sw-center/sw-voice.shtml. Extract the archive to

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide Developing the Web Application


OL-14106-01

create the files and directories shown in Table 1. This archive can be extracted in either a Linux or a PC environment. The “Building and Deploying the Web Application” section on page 21 has more information on how to use these files.

Table 1 Tar File Contents

Filename or Directory Name Description

00README.txt Description of the content of this archive.

build.bat Build script to be used on a PC.

build.sh Build script to be used on a UNIX or Linux platform.

build.xml Ant file used by the build script to build the web application.

webapp.aef The workflow script used to access the VoiceBrowser.

doc Javadoc of the various Java APIs and JSPs included in the tar file.

etc Contains the web.xml file that maps the various JSPs to their respective class files.

jsp Contains a collection of JSPs that can be used as is or modified to provide additional functionality.

lib Contains compiled Java APIs that can be used to perform various IVR functions.

src Placeholder for your customized Java servlets.

tutorial/banking Contains a complete sample VoiceXML application that can be deployed on Cisco Unity Express to simulate a banking environment. Three subdirectories hold the VoiceXML scripts, custom prompts needed to execute the scripts, and a database schema file to set up an external database.

vxml Contains a VoiceXML.DTD document type definition (DTD) file and an example VoiceXML file. The VoiceXML files included in the banking tutorial are also copied into this directory. If you are not building the tutorial banking web application, all the VoiceXML files related to the tutorial may be deleted, although their deletion is not required. To make changes to the tutorial web application's VoiceXML files, make them in this directory.

Do not modify the files in the tutorial/banking/vxml directory so you can use them as a reference. Another reason for not modifying the files is that the build scripts provided do not include any VoiceXML files that are in the tutorial/banking/vxml directory. Only the VoiceXML files in this directory are included. Place additional VoiceXML files in this directory.

Webserver Contains library files used for execution of the web application.



OL-14106-01

JSP, Servlet, and VoiceXML CreationWhen you invoke a deployed web application, you invoke one of the VoiceXML files in the package as the initial entry point. This script usually calls one or more Dynamics Objects or other VoiceXML files. These Dynamics Objects usually invoke one or more Java application program interface (API) calls into the Cisco Unity Express workflow. The following sections describe the development process which includes:

• Java APIs, page 4

• Dynamic Objects, page 12

• VoiceXML Documents, page 18

Java APIs

The Java APIs are divided into three packages which are described in the following sections:

• com.cisco.cuce.ivrjsp.helpers, page 5

• com.cisco.cuce.log, page 8

• com.cisco.cuce.ivrjsp.utils, page 9

Figure 1 shows the package hierarchy that you see while viewing the included Javadoc file in Tree view mode.



OL-14106-01

Figure 1 Package Hierarchy

com.cisco.cuce.ivrjsp.helpers

This package contains the following helper classes you use to create the body and attachments of e-mails and faxes and an exception class specific to this package.

• Class CiscoDocument, page 5

• Class Body, page 6

• Class Attachment, page 7

• Exception vxmlHelperException, page 8

Class CiscoDocument

The CiscoDocument class is used as a wrapper for files that were uploaded to Cisco Unity Express using the Document Management command line interface (CLI). This class provides access to those uploaded documents. When the documents are uploaded, they must be assigned to a specific type: GENERIC, TEMPLATE or TIFF.



OL-14106-01

Fields

• GENERIC: Generic file such as Microsoft Word, Microsoft Excel, or Joint Photographic Experts Group (JPEG).

• TEMPLATE: Text substitution template file.

• TIFF: Tagged Image File Format (TIFF) Profile-F conformant image.

• EDBS (Enterprise Database Subsystem): The document is a database stored binary file. This field is reserved for use by the voice-mail system and is not for your use.

Constructors

• CiscoDocument(java.lang.String fileName, int documentType, java.util.HashMap values) throws vxmlHelperException

– fileName: Name of the uploaded file.

– documentType: Type of the document, one of GENERIC, TEMPLATE or TIFF.

– values: If the document type is TEMPLATE, the values can contain the HashMap used for text substitution.

• CiscoDocument(java.lang.String fileName, int documentType, java.util.HashMap values, java.util.Locale documentLocale) throws vxmlHelperException

– fileName: Name of the uploaded file.

– documentType: Type of document, one of GENERIC, TEMPLATE or TIFF.

– values: If the document type is TEMPLATE, the values can contain the HashMap used for text substitution.

– documentLocale: Use this field to change the locale to which the document was uploaded. If you use the constructor without the documentLocale, then the default locale configured in Cisco Unity Express is used.

Methods

Use these methods to verify the fields populated by the constructor. Normal use of these classes does not require accessing these methods.

• java.util.Locale getDocumentLocale(): Returns the locale of the document.

• int getDocumentType(): Returns the type of document.

• java.lang.String getFileName(): Returns the filename of the CiscoDocument.

• java.util.HashMap getHashMap(): If the document type is TEMPLATE, this API returns the HashMap associated with this document.

• java.io.FileInputStream getInputStream(): Returns the FileInputStream for this document.

Class Body

Use the Body class to encapsulate data types into a common interface that can act as the body of an e-mail or fax.

Fields

These values represent the data type of the Body, and they are set automatically based on the constructor used.

• CISCODOC: com.cisco.cuce.ivrjsp.helpers.CiscoDocument.

• TEXT: Plain text.

• URL: Specified by a URL.



OL-14106-01

• URLWITHHASH: Specified by a URL, and a HashMap is included to perform text substitution.

Constructors

• Body(CiscoDocument doc) throws vxmlHelperException: Use a CiscoDocument to create the body.

• Body(java.lang.String body) throws vxmlHelperException: Use the provided string as the body.

• Body(java.net.URL, java.util.HashMap values) throws vxmlHelperException: If the HashMap is null, then the body is pointed to by the URL. If HashMap is provided and is not null, then assume the URL is a template and use the HashMap for text substitution.

Methods


• int getBodyType(): Returns the type of the Body.

• CiscoDocument getCiscoDocumentBody(): If the type is CISCODOC, this API returns the content of the Body.

• java.lang.String getStringBody(): If the type is TEXT, this API returns the String content of the Body.

• java.net.URL getUrlBody(): If the type is URL or URLWITHHASH, this API returns the URL of the file.

• java.util.HashMap getUrlHashMap(): If the type is URLWITHHASH, this API returns the HashMap associated with the Body.

Class Attachment

Use this class, similar to the Body class, to encapsulate various data types into a common interface that you can use as an attachment to an e-mail or fax.

Fields

These values represent the data type of the Body, and they are set automatically based on the constructor used.

• CISCODOC: CiscoDocument.

• TEXT: Plain text.

• URL: Specified by a URL.

• URLWITHHASH: Specified by a URL, and a HashMap is included to perform text substitution.

• AESOP_DB_DOC: Specified by a database URL. This is for internal use only. Your customized applications cannot store documents in the database or access them using this API.

Constructors

• Attachment(CiscoDocument doc) throws vxmlHelperException: Use a CiscoDocument object to create the Attachment.

• Attachment(java.lang.String attach) throws vxmlHelperException: Use a String parameter to create the Attachment object.

• Attachment(java.net.URL fileUrl, java.util.HashMap values, java.lang.String friendlyName) throws vxmlHelperException: If the HashMap is null, the attachment is specified by the URL. Because an attachment must be a file, you can use the friendly name to specify a name for this file. If this is not provided, the last part of the URL is used as the name of the attachment. If a HashMap is provided, the content of the URL acts as a template and values in the HashMap are used to perform the text substitution.



OL-14106-01

Methods


• java.lang.String getAesopDatabaseAttachment(): If the attachment type is AESOP_DB_DOC, this API returns the URL associated with the attachment. This is for internal use only. Your customized application cannot store documents in the database, so this method is not useful.

• int getAttachmentType(): Returns the Attachment type.

• CiscoDocument getCiscoDocumentAttachment(): If the attachment type is CISCODOC, this API returns the content of the Attachment.

• java.lang.String getFriendlyName(): If the attachment type is URL or URLWITHHASH, this API returns the friendlyName to use for the attachment.

• java.lang.String getStringAttachment(): If the attachment type is TEXT, this API returns the String content of the Attachment.

• java.net.URL getUrlAttachment(): If the attachment type is URL or URLWITHHASH, this API returns the URL of the file.

• java.util.HashMap getUrlHashMap(): If the attachment type is URLWITHHASH, this API returns the HashMap associated with the attachment.

Exception vxmlHelperException

This is an exception defined to handle situations that might arise when using the vxmlHelpers objects. It can be thrown by any of the classes in this package. This exception is thrown when:

• Any of the mandatory parameters are null when creating Body or Attachment objects. This exception is thrown with an appropriate message.

• The URL is malformed.

com.cisco.cuce.log

This package provides the necessary APIs to enable logging debug messages to the atrace logging system of Cisco Unity Express. You can enable these traces by using the trace webapp userapp all command in Cisco Unity Express. See the Cisco Unity Express 2.3 Command Reference.

Constructor

• Log(): Create a new Log entity.

Methods

• void debug(java.lang.String str): Logs the input string into the trace buffer when the debug trace activity is on.

• void debug(java.lang.String str, java.lang.Throwable t): Logs the input string and the stack trace into the trace buffer when the debug trace activity is on.

• void error(java.lang.String str): Logs the input string into the trace buffer when the error trace activity is on.

• void error(java.lang.String str, java.lang.Throwable t): Logs the input string and the stack trace into the trace buffer when the error trace activity is on.

• void info(java.lang.String str): Logs the input string into the trace buffer when the info trace activity is on.

• void info(java.lang.String str, java.lang.Throwable t): Logs the input string and the stack trace into the trace buffer when the info trace activity is on.

http://www.cisco.com/en/US/docs/voice_ip_comm/unity_exp/rel2_3/cmdref/cmdref.html



OL-14106-01

• void warn(java.lang.String str): Logs the input string into the trace buffer when the warning trace activity is on.

• void warn(java.lang.String str, java.lang.Throwable t): Logs the input string and the stack trace into the trace buffer when the warning trace activity is on.

• void xdebug(java.lang.String str): Logs the input string into the trace buffer when the xdebug trace activity is on.

• void xdebug(java.lang.String str, java.lang.Throwable t): Logs the input string and the stack trace into the trace buffer when the xdebug trace activity is on.

com.cisco.cuce.ivrjsp.utils

This package contains most of the APIs that you use to perform IVR operations such as sending of e-mails and faxes, accessing an external database, and accessing the system user information database. The APIs in this package invoke the Remote Method Invocation (RMI) methods in the back end to perform the desired operation. All the methods contained within this package are declared as static, so they can be invoked directly, without having to instantiate an object of that class.

• Class DatabaseAccess, page 9

• Class Email, page 10

• Class Fax, page 11

• Class User, page 12

• Exception vxmlUtilsException, page 12

Class DatabaseAccess

Methods

• static int executeDBQuery(long taskid, java.lang.String dbResourceName, java.lang.String dbProfileName, java.lang.String sqlQuery, int queryTimeout) throws vxmlUtilsException: Causes the EDBS Subsystem to do a database QUERY to the specified Data Source Name (DSN).

– taskid: ID of the active task. This can be obtained by the VoiceXML script that invoked this call.

– dbResourceName: A unique string that can be used to get the results from this query. Using different values for the resource name, you can execute multiple queries at the same time, and the results remain accessible.

– dbProfileName: Database profile defined on Cisco Unity Express to use to execute this query.

– sqlQuery: Structured Query Language (SQL) query string.

– queryTimeout: Timeout in seconds to wait for a result.

This method returns a zero if no errors are reported. Otherwise, a vxmlUtils exception is thrown to indicate the error.

• static int executeDBUpdate(long taskid, java.lang.String dbResourceName, java.lang.String dbProfileName, java.lang.String sqlUpdate) throws vxmlUtilsException: Causes the EDBS Subsystem to do a database UPDATE to the specified DSN.

– taskid: ID of the active task.

– dbResourceName: Resource name string used to execute the query.

– dbProfileName: Database profile configured in Cisco Unity Express used to execute this update.

– sqlUpdate: SQL string to execute the update.



OL-14106-01

This method returns a zero if no errors are reported. Otherwise, a vxmlUtils exception is thrown to indicate the error.

• static java.util.List getDBQueryResults(long taskid, java.lang.String dbResourceName, java.util.List fieldsToReturn, int count) throws vxmlUtilsException: Causes the EDBS Subsytem to return the results of the query from executeDBQuery execution.

– taskid: ID of the active task.

– dbResourceName: Resource name string used to execute the query.

– fieldsToReturn: java.util.List containing the list of fields to return from the database. Leaving this parameter null returns all fields.

– count: Maximum table entries to return.

This method returns the requested data as a list collection of HashMaps. The list contains as many elements as the number of rows that were requested. Each element is a HashMap, which contains a key-value pair representing the field name and value.

• static int releaseDBResource(long taskid, java.lang.String dbResourceName) throws vxmlUtilsException: Causes the EDBS Subsytem to release all the resources allocated for database access to the specified DSN.

– Taskid: ID of the active task.

– dbResourceName: Resource name string used to execute the query. Only the resources associated with this unique string identifier are released.

This method returns zero (0) if no errors occur. Otherwise, a vxmlUtils exception is thrown to indicate the error.

Class Email

Methods

• public static boolean sendEmail(java.lang.String taskID, java.lang.String fromAddress, java.lang.String toAddress, java.lang.String subject, Body body, boolean sync) throws vxmlUtilsException: Use this method to send an e-mail without attachments. Before invoking this method, the calling method must create a new Body object to include as the body of the Email. The Body can be created with any of the four data types: TEXT, URL, URLWITHHASH, and CISCODOC.

– taskID: ID of the active task. This can be obtained by the VoiceXML script that invoked this call.

– fromAddress: From address of the e-mail. If set to null, it is replaced by the default from address configured in Cisco Unity Express.

– toAddress: To address of the e-mail. Multiple comma-separated addresses may be included. Specify at least one address.

– subject: Subject of the e-mail. May be set to null.

– body: Body of the e-mail. May be set to null if body is not used.

– sync: Setting sync to true sends the e-mail synchronously to the processing. Setting it to false queues the e-mail to be sent asynchronously. Use asynchronous mode for large e-mails.

This method returns a boolean true if all processing was successful, and there were no exceptions reported. Otherwise, the vxmlUtilsException is used to catch and rethrow any exceptions reported by the Email subsystem.

• public static boolean sendEmail(java.lang.String taskID, java.lang.String fromAddress, java.lang.String toAddress, java.lang.String subject, Body body, java.util.List attachments boolean sync) throws vxmlUtilsException: Use this method when the e-mail is going to contain one or more



OL-14106-01

attachments. Befrore invoking this API, all attachments must be encapsulated into the Attachment object and added to a java.util.List. The Attachment object for an e-mail supports URL, URLWITHHASH, and CISCODOC data types only. If the Attachment is created with a String, it results in an exception.

– taskID: ID of the active task. Obtain by the VoiceXML script that invoked this call.

– fromAddress: From address of the e-mail. If set to null, it is replaced by the default from address configured in Cisco Unity Express.

– toAddress: To address of the e-mail. Multiple comma-separated addresses may be included. At least one address must be specified.

– subject: Subject of the e-mail. May be set to null.

– body: Body of the e-mail. May be set to null if body is not used.

– Attachments: List of Attachment objects.

– sync: Setting sync to true sends the e-mail synchronously to the processing. Setting it to false queues the e-mail to be sent anynchronously. Use asynchronous mode for large e-mails.

This method returns a Boolean true if all processing was successful. Otherwise, the vxmlUtilsException is used to catch and rethrow any exception returned by the Email subsystem.

Class Fax

Methods

• public static boolean sendFax(java.lang.String taskID, java.lang.String fromAddress, java.lang.String faxNumber, java.lang.String subject, Body body, boolean sendDSN) throws vxmlUtilsException: Use this method to generate a fax message without an Attachment. As with the Email class, you must create the Body object before invoking this API. Only a plain text Body is allowed for Fax, so you must create the Body using either TEXT, URLWITHHASH, or CISCODOC with document type TEMPLATE. Any other Body type results in an exception.

– taskID: ID of the active task. Obtain by the VoiceXML script that invoked this call.

– fromAddress: From address of the fax. If set to null, it is replaced by the default from address configured in Cisco Unity Express.

– faxNumber: Phone number of the destination fax machine. This must be present to send the fax.

– subject: Subject of the fax. May be set to null.

– body: Body of the fax message. May be set to null if body is not used. However, if the body is needed, then this must be an object of com.cisco.cuce.ivrjsp.helpers.Body object.

– sendDSN: Setting this field to true results in an e-mail being sent to the fromAddress if the fax is delivered successfully.

This method returns a Boolean true if all processing was successful and no exceptions were seen from the Fax subsystem. Otherwise, the vxmlUtilsException is used to catch and rethrow any exception returned by the Fax subsystem.

• public static boolean sendFax(java.lang.String taskID, java.lang.String fromAddress, java.lang.String faxNumber, java.lang.String subject, Body body, Attachment attachment, boolean sendDSN) throws vxmlUtilsException: Use this to generate a fax message with an attachment. The attachment to the fax message can be created with any data type: TEXT, URL, URLWITHHASH, or CISCODOC (GENERIC, TEMPLATE or TIFF). The main difference between Email and Fax is that the Fax API only supports a single Attachment object, not a List. Since Fax only supports plain text format and TIFF, any attachments must be in plain-text format or TIFF.

– taskID: ID of the active task. Obtain by the VMXL script that invoked this call.



OL-14106-01

– fromAddress: From address of the fax. If set to null, it is replaced by the default from address configured in Cisco Unity Express.

– faxNumber: Phone number of the destination fax machine. This must be present to send the fax

– subject: Subject of the fax. May be set to null.

– body: Body of the fax message. May be set to null if body is not used. However, if the body is needed, then this must be an object of com.cisco.cuce.ivrjsp.helpers.Body.

– attachment: Use this field to specify a single document that can be attached to the fax message. This may be set to null if no attachment is needed. If used, this must be a com.cisco.cuce.ivrjsp.helpers.Attachment object.

– sendDSN: Setting this field to true results in an e-mail being sent to the fromAddress if the fax is successfully delivered.

This method returns a Boolean true if all processing was successful and no exceptions were seen from the Fax subsystem. Otherwise, the vxmlUtilsException is used to catch and rethrow any exception returned by the Fax subsystem.

Class User

Methods

• static User getUser(java.lang.String userid): Use this method to get the User object with the given userid. The User object contains get methods to retrieve information about the user.

• userid: Userid as configured in Cisco Unity Express.

• java.lang.String getDisplayName(): Returns the user display name.

• java.lang.String getE164Number(): Returns the user E.164 extension.

• java.lang.String getExtension(): Returns the user extension.

• java.lang.String getFirstName(): Returns the user first name.

• java.lang.String getLastName(): Returns the user last name.

• java.lang.String getPreferredLanguage(): Returns the user preferred language locale.

• java.lang.String getSpokenNameURL(): Returns the user spoken name URL. This URL can be passed to VoiceXML to play out the spoken name of the user.

Exception vxmlUtilsException

This exception handles situations that might arise when using the vxmlUtils objects. It can be thrown by any of the classes in this package. All the classes in this package need to access the subsystems through the RMI. If any of these RMI connections fail, the RMI exception is rethrown as a vxmlUtilsException.

If the subsystem encounters any errors while trying to execute the RMI request, that exception is thrown through the RMI exception method. This exception is caught and rethrown as a vxmlUtilsException.

Dynamic Objects

To facilitate creation and deployment of IVR applications, JSP files are included in the development package. You can use these JSPs as provided, alter them to fit a custom application, or use them as a template for a completely new version.

You can use the JSPs included in the package to access all the functionality in the vxmlUtils package. This includes sending an e-mail, sending a fax, using all four database operations, and getting user information. The interface between VoiceXML and JSP is text-based, so passing parameters back and forth must be done a single parameter at a time. If an array is to be passed in, a parameter representing



OL-14106-01

the size of the array and each element of the array must be passed in with unique names. The following sections describe the various input and output parameters associated with each JSP. The input parameters are processed into a format that can be passed into the methods of the vxmlUtils classes. The result of these methods is converted into string parameters that can be passed back to VoiceXML. The parameter names that accompany each JSP file must match the parameters in the invoking VoiceXML file. The JSP files get these parameters from the context by requesting these parameter names. The order that these parameters are included in the invocation of the JSP is not important, however, the JSP is not able to retrieve the parameter's value if the parameter name is not one of the input parameters described in the following sections.

No sample servlets are provided in the Development Environment. See the “Writing Servlets” section on page 17 for guidelines on writing the servlets.

DatabaseQuery.jsp

Use this JSP file to query an external database. This file executes the query, which causes the results to be stored in the EDBS subsystem. The list of input parameters follows:

• task_id: (Required) Identifier obtained from session.telephone.taskid.

• dbResourceName: (Required) Unique string identifier attached to this query. Use this identifier to get the query results and execute updates. You must use this identifier to release this database resource.

• dbProfileName: (Required) Configured in Cisco Unity Express. This must match at least one of the dbprofiles configured in Cisco Unity Express.

• queryString: (Required) SQL search string to execute.

• queryTimeout: Timeout value in seconds. If this value is not specified, it is set to zero, indicating that the query does not time out.

This JSP returns a Boolean called success after execution. It is set to true if there were no errors seen during the execution, otherwise it is set to false.

DatabaseGetResults.jsp

Use this JSP file to get the results from the execution of the query command. This JSP can retrieve up to 20 fields from each row of the result set. This JSP is configured to get only one line of results per call. Invoke this JSP multiple times to get the subsequent rows of data. The list of input parameters follows:


• dbResourceName: (Required) This string identifier must match the one that was used when executing the query. The EDBS subsystem uses this name to look up the result set from which to return the data.

• listOfFieldsCount: (Optional) If only certain fields from each row of data are needed, use this parameter to reduce the list of fields that are needed. This parameter specifies how many fields are specified, up to a maximum of 20. If this parameter is not included or is set to zero, all the fields, up to a maximum of 20, are returned. If a value greater than 20 is specified, the JSP imposes a limit of 20 automatically.

• Field0: (Required based on listOfFieldsCount setting) If the listOfFieldsCount is specified and is greater than 0, this parameter specifies the field name. Include additional field names as Field1, Field2, etc. If listOfFieldsCount is set to N, then Field0 to Field<N-1> parameters must be included.

This JSP returns items which vary based on the number of fields of data that were requested.

• success: Boolean used to return the status of the JSP execution.



OL-14106-01

• returnCount: Parameter specifies how many key-value pairs of data are included.

• key0 and val0: These two fields return the data that was obtained from the database. The key is the name of the field and the val is value of that field. Up to 19 additional key-val pairs can be returned from the JSP as key1-val1 to key19-val19. Only objects that can be represented as simple strings can be returned using this method. There is no implied order in the key-val pairs. Key0 does not necessarily represent the first data field in the database result set. When these fields are returned from the JSP, the VoiceXML code invoking the JSP verifies the key of the field before using the corresponding value. See the “Tutorial VoiceXML Application” section on page 19 for an example.

DatabaseUpdate.jsp

Use this JSP to update the database with a given SQL string. The list of input parameters follows:


• dbResourceName: (Required) Unique string to identify this resource. Use this string to release the database resource when the update is complete.

• dbProfileName: (Required) The dbprofile configured in Cisco Unity Express.

• updateString: SQL string to update the database. This parameter can contain UPDATE, DELETE, or other SQL commands.

This JSP returns a Boolean called success after execution, set to true if there were no errors seen during the execution, otherwise it is set to false.

DatabaseRelease.jsp

Use this JSP to release the database resource allocated by the DatabaseQuery or DatabaseUpdate JSPs. The list of input parameters follows:


• dbResourceName: Unique resource name provided when running the DatabaseQuery or DatabaseUpdate.

This JSP returns a Boolean called success after execution, set to true if no errors occurred during execution, otherwise it is set to false.

sendEmail.jsp

Use this JSP to create and send an e-mail. The Java API invoked to send the Email supports more complex messages, however, this JSP is designed to handle typical messages, that is, e-mail in which the Body of the Email is the only place where text substituted documents may be used. Also, typical messages include a maximum of three attachments. These restrictions were created to ensure that the interface between VoiceXML and JSP does not become overly complex. The list of input parameters follows:


• to: (Required) Destination Email address. This parameter can include comma-separated values to accommodate multiple addresses.

The remaining parameters are optional:

• from: From address of the Email. If left null, the default from address configured in Cisco Unity Express is used.

• subject: Subject of the Email

• bodyType: Type of the Body. Must be one of URL, URLWITHHASH, TEXT, or CISCODOC.



OL-14106-01

• bodyString: String of the Body. The content of this parameter depends on the bodyType specified.

• bodyCiscoDocType: If the bodyType is CISCODOC, this is a required parameter. This parameter can have a value of TIFF, TEMPLATE, or GENERIC. If this parameter is not specified, the Body is not created.

• bodyLanguage: If the bodyType is CISCODOC, this parameter can identify a specific language that was used to upload the document. This is an optional parameter which has a default value configured in Cisco Unity Express if not specified. An example for language string is en_US.

• bodyHashCount: If the bodyType is URLWITHHASH or CISCODOC with documentType TEMPLATE, use this parameter to specify the number of text substitution values. The maximum is five.

• bodyHashKey0: Hash key for index 0. Use bodyHashKey1 to 4 for subsequent values.

• bodyHashVal0: Hash value for index 0. Use bodyHashVal1 to 4 for subsequent values. Specify the keys and values in pairs, otherwise errors can occur when the text substitution is performed.

• attachmentCount: Number of attachments to be included. The maximum is three.

• attachmentType0: Attachment type for index 0. Use attachmentType1 and attachmentType2 for subsequent attachments. Allowed values are URL and CISCODOC. If CISCODOC is used, it is assumed to be GENERIC and cannot be modified.

• attachmentString0: String of the body which is either the URL of the file, or the name of the GENERIC CISCODOC document. Use attachmentString1 and attachmentString2 for subsequent attachments.

• attachmentFriendlyName0: When using attachmentType URL, this name is used as the filename of the attached file when the Email is sent.

• attachmentLanguage: If any attachmentType is set to CISCODOC, use this parameter to specify the override language. This parameter can apply to all three attachments if needed.


sendFax.jsp

Use this JSP to create and send a fax message. Like the sendEmail JSP, this JSP also allows you to create a simple fax message that does not take advantage of all the options made available by the sendFax Java API described above. The list of input parameters follows:


• faxNumber: (Required) Destination fax machine phone number. Only one phone number can be included. Specified as numeric characters only.

The remaining parameters are optional:

• from: From address for the fax. If none is specified, the default from address configured in Cisco Unity Express is used.

• subject: Subject string to use for the fax.

• bodyType: Type of Body to use. Only TEXT and URLWITHHASH are permitted. This restriction allows the JSP to ensure that only text is used as the Body of the fax.

• bodyString: Text of the Body or the URL of the template depending on the bodyType.

• bodyHashCount: If the bodyType is URLWITHHASH, use this parameter to specify the number of text substitution values. The maximum is five.

• bodyHashKey0: Hash key for index 0. Use bodyHashKey1 to bodyHashKey4 for subsequent values.



OL-14106-01

• bodyHashVal0: Hash value for index 0. Use bodyHashVal1 to bodyHashVal4 for subsequent values. Specify the keys and values in pairs, otherwise errors can occur when the text substitution is performed.

• attachmentType: Specifies the type of attachment to include with the fax. Only one attachment is allowed for a fax message, so there is no numerical designation for the attachmentType. This parameter can have a value of URL or CISCODOC. If CISCODOC is used, it is assumed to be TIFF and cannot be changed.

• attachmentString: Either the URL of the attachment file or the name of the CISCODOC TIFF file.

• attachmentLanguage: If the attachmentType is CISCODOC, use this parameter to override the default language.


userInfo.jsp

Use this JSP to retrieve all available information about a particular user. The only input parameter is:

• userId: ID of the user being queried.

The following output parameters contain the user information:

• success: Boolean indicating if the information was successfully queried.

• displayName: Displayed name of the user.

• firstName: Configured first name of the user.

• lastName: Configured last name of the user.

• extension: Extension of the user.

• e164Number: E.164 number of the user if configured.

• preferredLanguage: Preferred language of the user, if configured.

• spokenNameUrl: Recorded name URL of the user, if it is recorded. The returning URL can be played out by VoiceXML as <audio expr=“userinfo.spokenNameUrl”/>. The subdialog name invoking this JSP is assumed to be userinfo in the preceding VoiceXML code.

Writing New JSPs

Using the JSP files described in the previous sections as examples, you can write new custom JSPs. The JSPs do not have to be separated by function. They can be combined in a single JSP to perform more complex operations. For example, multiple database operations can be performed by a JSP followed by generating an e-mail or fax as confirmation. This series of events can be driven by the VoiceXML script using individual JSPs, or as a single JSP. If the same operation is to be performed many times, combine the operations into a single JSP file.

When writing new JSPs the following guidelines make it easier to develop, deploy, and debug the new JSP applications.

• Make sure that the header of the JSP file matches the one used in the provided JSPs:

<?xml version=“1.0”?>

<!DOCTYPE vxml SYSTEM “voicexml.dtd”>

<vxml version=“2.0” xmlns=“http://www.w3.org/2001/vxml”>



OL-14106-01

• Use the logging mechanism provided. Logging helps tremendously in the debugging process. The logging messages included in the JSPs can be enabled using the trace webapp userapp all command in Cisco Unity Express. These logging messages are added into the atrace log using the module id “wapp” and entity “uapp.”

• Perform as much parameter validation in the JSP as possible before invoking the Java APIs. Ensure that at least the required list of parameters are provided before calling the Java API.

• Any new JSPs that are added must be updated in the etc/web.xml file. This file is provided in the web application development directory and is for mapping the JSP name to a particular class name. All the provided JSPs are already included, so only the newly added ones need to be updated.

Writing Servlets

A servlet can perform most of the same functions as a JSP, however, it tends to be simpler to write and test. A JSP can contain a mixture of VoiceXML, JavaScript, Java, and various JSP directives. This mixture can make writing a JSP a daunting task, which is where a servlet can help. A servlet is a Java class that implements the javax.servlet.Servlet interface. It is easier for someone familiar with Java to develop a servlet, than a JSP.

When you are developing servlets for use within the Cisco Unity Express application, consider the following:

• The response output from the servlet must be VoiceXML, not HTML.

• To allow socket connections, use the allow-network-connect flag with the deploy command when you deploy the application. This applies to both inbound and outbound socket connections. See the “Deploying the Web Application” section on page 23 for more details.

• The following example is a basic shell of a servlet. It returns a VoiceXML response with a success flag as a parameter.

import java.io.*;import java.net.*;import javax.servlet.*;import javax.servlet.http.*;

public class ClientServlet extends HttpServlet {

public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

PrintWriter out = response.getWriter(); response.setContentType(“text/xml”);

/* * Add Java code here to perform a task */

// Create a VoiceXML response out.println(“<?xml version=\”1.0\”?>\n”+ “<!DOCTYPE vxml SYSTEM \”voicexml.dtd\”>\n”+ “<vxml version=\”2.0\” xmlns=\”http://www.w3.org/2001/vxml\”>\n”); out.println(“<form id=\”sample\”>”); out.println(“<var name=\”success\” expr=\”'true'\”/>\n”); out.println(“<block>\n”+ “<return namelist=\”success\”/>\n”+ “</block>\n”+ “</form>\n”+ “</vxml>\n”);

OL-14106-01

} public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doPost(request, response); }}

• When you add a new Java servlet to the web application, you must update the etc/web.xml file to map the servlet class to a URL that may be invoked by the VoiceBrowser. For example, if you added the previously shown example servlet to the webapp, you must make the following changes to the etc/web.xml file:

<servlet> <servlet-name>ClientServlet</servlet-name> <servlet-class>ClientServlet</servlet-class></servlet>

<servlet-mapping> <servlet-name>ClientServlet</servlet-name> <url-pattern>/vxml/ClientServlet.java</url-pattern></servlet-mapping>

VoiceXML Documents

VoiceXML is the standard XML format for specifying interactive voice dialogs between a person and a computer. VoiceXML documents are developed and deployed similarly to HTML documents. Just as a web browser is used to interpret HTML content, a voice browser is used to interpret the VoiceXML documents. The VoiceBrowser on Cisco Unity Express does not implement all possible VoiceXML tags. See the “VoiceXML VoiceBrowser Known Limitations” section on page 27 for more information.

VoiceXML documents can use the provided JSPs or your customized JSPs to interface with a database, send e-mails and faxes, and obtain user information. VoiceXML can also handle call transfers. Several VoiceXML documents are included in the development framework. The example.vxml file is a standalone script which shows the usage and parameters of each of the provided JSPs described previously. Do not use this script as an entry point for the VoiceXML application; it is provided for reference only. The tutorial/banking/ directory provides a tutorial web application that implements a banking IVR application. The IVR application serves as an example of using VoiceXML scripting to create an IVR, creating a multidocument VoiceXML application, using the provided JSPs, transferring phone calls, and using Cisco style logging.

Passing Parameters from Cisco Unity Express Script Editor Scripts

VoiceXML applications can be interfaced with Cisco Unity Express Script Editor scripts. Parameters can be passed to the VoiceXML application from the Script Editor script and from the VoiceXML application back to the Script Editor script. When moving control from a Script Editor script to a VoiceXML script, the Voice Browser step in the Script Editor is used to invoke the voice browser. This step allows you to choose the Request Parameters tab or the Return Parameters tab. If you choose the Request Parameters



OL-14106-01

tab, you can use a customized JSP to retrieve the parameters passed to the invoked VoiceXML application. The JSP uses request.getParameter(“<parameter name>”) to retrieve the parameter value. In order to use the parameter in a larger VoiceXML application, perform the following steps:

Step 1 Program the JSP to emit VoiceXML code that declares it as a leaf document to the application root document. For example:

<vxml version=”2.0” xmlns=”http://www.w3.org/2001/vxml” application=”root document name”>

Step 2 Create an application-level variable to store the parameter in the VoiceXML root document.

Step 3 Program the JSP to emit VoiceXML code that assigns the result of the result.getParameter() call to the declared application-level variable.

These steps allow you to use the parameter throughout the VoiceXML application. You can find an example of this usage in the CUE-IVR-jsp example script available on Cisco.com.

In order to pass parameters from a VoiceXML application to a Script Editor script when the invoked VoiceXML script exits, use an <exit expr=”<parameter name>”> tag, or an <exit namelist> tag for multiple parameters. These tags are passed back to the Script Editor script, where you can retrieve them by using the Return Parameters tab of the Voice Browser step. You can find an example of this usage in the CUE-IVR-vbrowser example script available on Cisco.com.

Tutorial VoiceXML Application

The IVR application consists of a main menu with four menu options which accepts DTMF inputs as responses. Throughout the web application, most of the provided JSPs are used. When the web application is deployed, these scripts are loaded into the WAR file. The web application consists of seven VoiceXML scripts found in the tutorial/banking/vxml/ directory:

• banking_ampleIVR.vxml—Root document for the application. Contains the global parameters and welcome prompt. When the application is configured in Cisco Unity Express, load this script as the startPage. See the “Executing the Web Application” section on page 24 for more information.

• banking_main.vxml—Loaded from banking_sampleIVR.vxml. Contains the main menu of the bank IVR application, and prompts to log in to the system. It can load any of the other scripts in the web application.

• banking_account_preferences.vxml—Loaded from banking_main.vxml. Contains a menu giving the user options to edit account preferences and return to the main menu.

• banking_account_balance.vxml—Loaded from banking_main.vxml. Contains a menu giving the user options to hear account balances stored in a local database and return to the main menu.

• banking_transfer_balance.vxml - Loaded from banking_main.vxml. Contains a menu giving the user options to transfer money between accounts. Transactions executed by this script send a confirmation e-mail to a stored user e-mail address, and also send a fax confirmation of the transaction, if the user's account is configured to do so.

• banking_connect_to_local.vxml—Loaded from banking_main.vxml. Contains a prompt to get the zip code of the bank to which the user wants to connect. The script then dials the extension of the specified bank, transferring the call to another line.

• banking_goodbye.vxml—Handles the closing of the script, if a hang up does not occur.



OL-14106-01

Deployment Prerequisites Procedure

Before you execute the sample IVR application, perform these steps:

Step 1 Configure user prompts.

All user prompts are in the tutorial/banking/prompts/ directory. Copy each of these prompts into Cisco Unity Express using the ccn copy url command. See the Cisco Unity Express 2.3 Command Reference. These prompts are already correctly named to work in the web application.

Step 2 Configure the e-mail address and fax preference to valid entries in a local database.

A database schema, in the form of a Microsoft Excel spreadsheet is in the tutorial/banking/database/ directory. The database required for the web application consists of two tables: account_info and bank_info. While the actual data stored in the database can be changed for the tutorial, the schema must remain the same so the scripts function properly. The account_info table contains mock user information pertaining to a bank account including: account number, e-mail address, fax preference, fax number, checking balance, and savings balance.

Step 3 Use the web application to test the e-mail and fax response functions.

Step 4 Configure Cisco Unity Express to run the tutorial. The tutorial was tested using a Microsoft SQL Server Desktop Engine (MSDE) database.

a. Configure two phones. The IVR application requires one phone to call the system and another phone to simulate transferring a call to a local bank.

b. Configure an outbound fax. Fax confirmations are used in the Transfer Balances menu.

c. Configure an SMTP server to use the e-mail confirmation feature.

d. Configure the database storing the user and bank information using the ccn subsystem edbs dbprofile command.

Deploying the Tutorial

To deploy the banking tutorial, perform these steps:

Step 1 Build and deploy the web application.

In order to use the bank tutorial web application, you must first build the WAR file. See the “Executing Build Scripts” section on page 23. When the tar file is unarchived, the VoiceXML scripts that are included in the /tutorial/banking/vxml directory are also copied into the top-level vxml directory. If any changes must be made to the VoiceXML script, modify the ones in the top-level vxml directory.

Note Do not modify the files in the tutorial/banking/vxml directory. They must be left as a reference.

Step 2 Execute the web application.

See the “Deploying the Web Application” section on page 23. The show webapp command displays the following:

Webapp Status #Sessions<webapp name> running 0




OL-14106-01

Step 3 To configure the application, set the startPage parameter to vxml/sampleIVR.vxml and set appName to the name of your deployed web application. See the “Executing the Web Application” section on page 24. To configure the trigger, set the application parameter to the name of your deployed web application.

Step 4 Use the show running-config command to verify your configuration. The configuration should contain the following:

ccn application <webapp name> ivr description "ivr" enabled script "webapp.aef" parameter "startPage" "vxml/banking_sampleIVR.vxml" parameter "appName" "<deployed Webapp name>" end application

ccn trigger sip phonenumber <number> application "<webapp name>" enabled end trigger

Step 5 Use a configured phone to dial the trigger number. The trigger loads the deployed web application and begins the IVR system prompts.

Building and Deploying the Web ApplicationCreation and use of a custom web application consists of the steps that follow. These steps are described in the following sections.

Step 1 Download the development framework from Cisco.com.

Step 2 Modify and/or add the VoiceXML or JSP files.

Step 3 Install Java and Apache Ant development environments.

Step 4 Modify the build scripts if necessary.

Step 5 Execute the build script.

Step 6 Deploy the resulting WAR file onto Cisco Unity Express.

Step 7 Configure Cisco Unity Express to execute the deployed web application.

Step 8 Debug the deployed web application using the provided tracing facility.

Downloading the Development Framework

The development framework is available as a tar file that is located under the Cisco Unity Express heading on the Voice Software download page on Cisco.com, http://cisco.com/public/sw-center/sw-voice.shtml. Use the WinZip or tar utility in Linux to extract the tar file. If you are extracxting on Microsoft Windows, note the directory where the tar file is extracted because you need to update it in the build file.

The default build script for Microsoft Windows assumes that the tar file is extracted into the c:\webapp directory. In this document, the directory to which the files are extracted is referred to as build_base.

http://cisco.com/public/sw-center/sw-voice.shtml

OL-14106-01

Customizing the VoiceXML and JSP

After the tar file is extracted, the provided JSP files and the VoiceXML files can be modified as needed. The JSPs are located in build_base/jsp. The VoiceXML files are located in build_base/vxml.

Note If new JSP files are added, you must update the web.xml file in the build_base/etc directory.

For example, if a new JSP called testFile.jsp is added, the following two sections must be added to the web.xml file:

Under the 

<servlet> <servlet-name>testFile</servlet-name> <servlet-class>testFile</servlet-class> </servlet>

Under the 

<servlet-mapping> <servlet-name>testFile</servlet-name> <url-pattern>/vxml/testFile.jsp</url-pattern> </servlet-mapping>

You can add new VoiceXML documents to the build_base/vxml directory without updating anything else.

Installing Development Environments

To build the deployable web application, you must install a Java development environment and Apache Ant on the host. The development framework has been tested with Java version 1.4.2 and Apache Ant version 1.5. Because Cisco Unity Express uses JVM version 1.4.2, the Java version used to build the web application must also be 1.4.2.

Modifying Build Scripts

The build process is a combination of the build.sh (for Linux) or build.bat (for Windows) and build.xml. In all three of these files, there are parameters you can modify to customize the location of Java, Ant, and the destination of the resulting WAR file.

If you are building in a Linux environment, the build.sh script expects that the ANT_HOME and JAVA_HOME environment parameters are defined.

If you are building in a Windows environment, the build.bat assumes that Ant is installed in c:\ant, the Java JDK is installed in c:\j2sdk1.4.2_12, and the development framework is extracted into c:\webapp. You can modify all three of these parameters to match their actual locations.

The build.xml file builds the web application called vxml.war and copies it into the /tftpboot directory on Linux and the c:\webapp directory in Windows. You can change the “vxml” in the web application name by changing the app.name property in the build.xml file. You can change the location of the final web application by changing the tftp.home property.



OL-14106-01

Executing Build Scripts

For Windows

Step 1 Open a command window.

Step 2 Navigate to the build_base directory.

Step 3 Execute the build.bat script to build the web application.

For Linux

Step 1 Navigate to the directory to which the archive was extracted.

Step 2 Execute the build.sh script to build the web application, or you can also execute the build scripts using the keyword clean with the build command to remove all the compiled files from the build_base directory.

The three build process steps are:

Step 1 Prepare: Creates the necessary directories and copies the necessary files to the deploy directories.

Step 2 Compile: Converts the JSPs to Java files, then compiles the Java files into class files.

Step 3 Dist: Cleans up intermediate files and builds the WAR file that can be deployed. The WAR file, vxml.war or whatever it was renamed in the build.xml file, is copied to the location specified by the tftp.home property in build.xml.

Deploying the Web Application

The WAR file must be located in a directory that can be accessed by FTP, TFTP or Secure File Transfer Protocol (SFTP). You can specify the location of the WAR file by modifying the tftp.home property in the build.xml file, or you can copy the WAR file to the final destination manually.

There are six commands related to deploying and using the web application in Cisco Unity Express. They are executed at the Cisco Unity Express EXEC mode.

• Deploy: Use this command to upload the WAR file to Cisco Unity Express and make it available for execution. Include the allow-network-connect flag if the web application needs to listen for and accept incoming network connections. Outbound network connections are allowed by default.

se-10-0-0-0> webapp deploy url <url of the war file> webappname <local name of the webapp> [username <username to access the URL if needed> password <password to access the URL if needed>] [allow-network-connect]

You may see the following errors on execution of this command:

– Webapp appname already exists.

– Web archive war-url does not exist.

– Webapp appname produced exception.



OL-14106-01

– Webapp appname is too large.

– Too many webapps already deployed.

• Start: Use this command to start a previously deployed web application that was stopped.

se-10-0-0-0> webapp start webappname <local name>


– Webapp appname is already started.

– Webapp appname does not exist.


• Stop: Use this command to stop an active web application without uninstalling it.

se-10-0-0-0> webapp stop webappname <local name>


– Webapp appname is already stopped.



• Reload: Use this command to stop and start a script using a single command.

se-10-0-0-0> webapp reload webappname <local name>




• Delete: Use this command to delete a web application that the system no longer needs.

se-10-0-0-0> webapp delete webappname <local name>


– Webapp appname is not stopped.



• Show: Use this command to display the web applications loaded on the system and their status.

se-10-0-0-0> show webappWebapp Status #SessionsWebapp1 running 2Webapp2 stopped 0

Executing the Web Application

In order to execute an uploaded web application, you must configure a new application which uses the webapp.aef script in Cisco Unity Express. This script is automatically installed in Cisco Unity Express, if Cisco Unity Express is using an IVR-capable license. Otherwise, it is also available in the Development Framework archive. There are two parameters associated with the script which are used to specify the URL to the VoiceBrowser.

• appName—Configure this parameter to match the local name of the web application that was specified when it was deployed.

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide Cisco DTMF Grammar


OL-14106-01

• startPage—Set this parameter to one of the VoiceXML files included in the web application. If multiple VoiceXML files are invoked from within each other, set this parameter to the VoiceXML file that can serve as an entry point. If the entry point is a VoiceXML document, set the startPage parameters to vxml/startPage.vxml. If the “vxml” is left out of the path, a 404 error results when the application is executed.

After you create the application, you must set up a trigger in Cisco Unity Express to point to that application. At this point, any call coming into this trigger number executes the webapp.aef script, which invokes the VoiceBrowser with the URL http://localhost/<appName>/<startPage>.

Debugging the Web Applications

The errors in VoiceXML are detected and logged by the VoiceBrowser. To enable the tracing of this output, use the trace ccn vBrowserCore all command to turn on traces. Use of this command generates many traces that show the entire VoiceBrowser process. We recommend that you turn off all other traces using the no trace all command, then enable VoiceBrowser traces using the trace ccn vBrowserCore all command. Use the show trace buffer tail command to display the tail of the trace buffer as debugs are added.

After the VoiceBrowser traces show that there are no syntax errors in the VoiceXML code, you can add traces into the VoiceXML code to print values of parameters and mark progress through the scripts. The syntax for using the log statements in VoiceXML is as follows:

<log expr=”’uapp: some string'”/>

The addition of the uapp: tag is explained below.

In addition to the VoiceXML debugs, you can use the Log class methods to add traces into the JSPs. The provided JSP methods already have many traces added in strategic places. You can add traces at will in the existing or new JSPs. To enable the display of these traces, use the trace webapp userapp all command. When these traces are displayed using the show trace buffer tail command, the traces printed include uapp as the trace entity name. If the VoiceXML log message above uses this same tag in the log messages, you can filter it out of the VoiceBrowser traces easily. If the VoiceBrowser and userapp traces are enabled, you can use the show trace buffer tail | include “uapp” command to print the VoiceXML traces with the uapp keyword and all of the traces in the JSPs. Printing these traces makes it easier to debug the VoiceXML/JSP interface. Numerous examples of using these traces are in the JSPs and in the sample VoiceXML applications.

After the web application is deployed, you may have to debug it as it executes. Follow this process:

Step 1 Debug the VoiceXML document to ensure that there are no syntax errors.

Step 2 Debug the JSPs.

Step 3 Debug the VoiceXML and JSP interaction.

Cisco DTMF Grammar

Note See the Cisco VoiceXML Programmer's Guide.

http://www.cisco.com/en/US/docs/ios/voice/vxml/developer/guide/refgde1.html

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide Cisco DTMF Grammar


OL-14106-01

The Cisco dual-tone multiple frequency (DTMF) grammar supported is a regular expression grammar. The media type of the grammar is application/grammar+regex. Cisco DTMF grammar has the following limitations:

• It supports inline grammar only.

• It cannot be used as a form grammar.

• It cannot be given a document scope when used as a menu grammar.

Cisco DTMF grammar supports the metacharacters in Table 2 only. If an unsupported metacharacter is used, no error is triggered. However, input recognition produces unexpected results.

In addition to matching the original pattern, the Cisco DTMF grammar matches the original pattern followed by extra digits. Matching of extra digits occurs only if the repetition operators are at the end of a pattern.

Regular expression for Cisco DTMF grammar allows you to use only empty spaces instead of the operator | to join characters.

For example, to join \* and .+ use an empty space instead of the operator |, as in the following example:

<grammar type=”application/grammar+regex”>\* .+</grammar>

The <field> builtin types digits and number accept any nondigit input. A nomatch event is not generated.

Table 2 Cisco DTMF Grammar Supported Metacharacters

Metacharacter Description

. Matches any single character.

For example, Cisco DTMF grammar with a regular expression <grammar type=”application/grammar+regex”>1408.......</grammar> matches a seven digit phone number with the leading area code 1408.

\ Quoting character. It removes any special meaning from the following character and treats it as an ordinary character.

For example, <grammar type=”application/grammar+regex”>\*</grammar> matches a literal asterisk (star) key, not the asterisk repetition operator.

Repetition Operators

? Matches zero or one occurrence of the character or regular expression immediately preceding.

For example, <grammar type=”application/grammar+regex”>408?</grammar> matches 40, 4088, 40888, 408123, 4083456. The match occurs for 408, 4088, 40888 and also for 408 followed by other extra digits that occur after 408.

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide VoiceXML VoiceBrowser Known Limitations


OL-14106-01

VoiceXML VoiceBrowser Known LimitationsThe Cisco Unity Express VoiceBrowser is based on VoiceXML 2.0. These are the known limitations of the VoiceBrowser:

• Automatic Speech Recognition (ASR) and Text to Speech (TTS) are not supported.

• Your customized VoiceXML application must use the Cisco DTMF grammar, otherwise known as Cisco regex grammar, when defining the DTMF patterns that the application accepts. See the “Cisco DTMF Grammar” section on page 25 for a description of this grammar. Other grammars such as Grammar Specification Language (GSL), Nuance, Speech Recognition Grammar Specification (SRGS), and Speech Synthesis Markup Language (SSML) are not be supported.

• The <record> element is not supported.

• Catching and fetching attributes are not supported.

• External regex grammars are not supported.

• Explicit grammars with platform-specific builtins are not supported.

• Universal tags HELP, CANCEL, and EXIT are not supported. You can define document or application scope grammars explicitly.

• Nested elements inside the <grammar> element are not supported.

• VoiceXML 1.0 compatibility is not supported.

• The obsolete elements <emp>, <div>, <pros>, <says>, and <dtmf> are not supported.

• The <dtmf> element has been replaced by the <grammar> element with mode=dtmf.

• For the <value> element, the class, mode, and recsrc attributes are not supported.

• The <object> element is not supported.

• The finalsilence attribute is not supported.

+ Matches one or more occurrences of the character or regular expression immediately preceding.

For example, <grammar type=application/grammar+regex>408+</grammar> matches 408, 4088, 40888, 408123, 408883456. The match occurs not only for 408, 4088, 40888 but also for 408 followed by other extra digits that occur after 408.

* Matches zero or more occurrences of the character immediately preceding.

For example, <grammar type=application/grammar+regex>408*</grammar> matches 40, 4088, 40888, 408123, 4083456. The match occurs not only for 408, 4088, 40888 but also for 408 followed by other extra digits that occur after 408.

Table 2 Cisco DTMF Grammar Supported Metacharacters (continued)

Metacharacter Description

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide Supported VoiceXML Session Variables and Field Properties


OL-14106-01

• Platform-specific audio is not supported.

Supported VoiceXML Session Variables and Field PropertiesTable 3 lists the supported session variables.

Table 4 lists the supported Cisco field properties.

Table 3 Session Variables

Session Variable Description

SESSION.CONNECTION.LOCAL Object

SESSION.CONNECTION.REMOTE Object

SESSION.CONNECTION.ORIGIN Object

SESSION.CONNECTION.LOCAL.URI Local VoIP URI

SESSION.CONNECTION.REMOTE.URI Remote VoIP URI

SESSION.CONNECTION.PROTO Object

SESSION.CONNECTION.PROTO.NAME Call Protocol Name

SESSION.CONNECTION.PROTO.VER Call Protocol Version

SESSION.TELEPHONE.ANI Local VoIP URI

SESSION.TELEPHONE.DNIS Remote VoIP URI

SESSION.TELEPHONE.SESSIONID Session ID

SESSION.TELEPHONE.TASKID Task ID

Table 4 Supported Cisco Field Properties

Property Description

com.cisco.dtmf.termlength Used in menus as a <property> to interpret DTMF input “termlength” digits at a time. Please see the banking tutorial for usage.

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide Additional References


OL-14106-01

Additional ReferencesThe following sections provide references related to the Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development feature.

Related Documents

Technical Assistance

Obtaining DocumentationCisco documentation and additional literature are available on Cisco.com. This section explains the product documentation resources that Cisco offers.

Cisco.comYou 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.cisco.com/public/countries_languages.shtml

Related Topic Document Title

Cisco Unity Express CLI Cisco Unity Express 2.3 Command Reference

Cisco Unity Express Cisco Unity Express Documentation, By Version

Description Link

The Cisco Support website provides extensive online resources, including documentation and tools for troubleshooting and resolving technical issues with Cisco products and technologies.

To receive security and technical information about your products, you can subscribe to various services, such as the Product Alert Tool (accessed from Field Notices), the Cisco Technical Services Newsletter, and Really Simple Syndication (RSS) Feeds.

Access to most tools on the Cisco Support website requires a Cisco.com user ID and password.


http://www.cisco.com/public/support/tac/home.shtml

http://www.cisco.com/en/US/docs/voice_ip_comm/unity_exp/roadmap/cuedocs.html



http://www.cisco.com

http://www.cisco.com/public/countries_languages.shtml

Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide Obtaining Documentation


OL-14106-01

Product Documentation DVDThe Product Documentation DVD is a library of technical product documentation on a portable medium. The DVD enables you to access installation, configuration, and command guides for Cisco hardware and software products. With the DVD, you have access to the HTML documentation and some of the PDF files found on the Cisco website at this URL:

http://www.cisco.com/cisco/web/support/index.html

DVDs are available singly or by subscription. Registered Cisco.com users can order a Product Documentation DVD (product number DOC-DOCDVD= or DOC-DOCDVD=SUB) from Cisco Marketplace at the Product Documentation Store at this URL:

http://www.cisco.com/go/marketplace/docstore

Ordering DocumentationYou must be a registered Cisco.com user to access Cisco Marketplace. Registered users may order Cisco documentation at the Product Documentation Store at this URL:


If you do not have a user ID or password, you can register at this URL:

http://tools.cisco.com/RPF/register/register.do

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, HomeLink, Internet Quotient, IOS, iPhone, IP/TV, iQ Expertise, the iQ logo, iQ Net Readiness Scorecard, iQuick Study, LightStream, Linksys, MeetingPlace, MGX, Networking Academy, Network Registrar, Packet, PIX, ProConnect, ScriptShare, 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. (0705R)

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.

© 2007 Cisco Systems, Inc. All rights reserved.

http://www.cisco.com/cisco/web/support/index.html



http://tools.cisco.com/RPF/register/register.do

Cisco Unity Express JSP, Servlet, and VoiceXML Web ... · PDF fileCisco Unity Express JSP,...

Documents

Transcript of Cisco Unity Express JSP, Servlet, and VoiceXML Web ... · PDF fileCisco Unity Express JSP,...