Cisco Unity Express JSP, Servlet, and VoiceXML Web Application Development Guide First Published: July 13, 2007, 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. Contents Overview, 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 Americas Headquarters: Cisco Systems, Inc., 170 West Tasman Drive, San Jose, CA 95134-1706 USA 2007 Cisco Systems, Inc. All rights reserved.
Overview 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 Overview Your 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 Application The 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 Framework Download 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 2
Developing the Web Application 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 00README.txt build.bat build.sh build.xml webapp.aef doc etc jsp lib src tutorial/banking vxml Webserver Description Description of the content of this archive. Build script to be used on a PC. Build script to be used on a UNIX or Linux platform. Ant file used by the build script to build the web application. The workflow script used to access the VoiceBrowser. Javadoc of the various Java APIs and JSPs included in the tar file. Contains the web.xml file that maps the various JSPs to their respective class files. Contains a collection of JSPs that can be used as is or modified to provide additional functionality. Contains compiled Java APIs that can be used to perform various IVR functions. Placeholder for your customized Java servlets. 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. 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. Contains library files used for execution of the web application. 3
Developing the Web Application JSP, Servlet, and VoiceXML Creation Java APIs When 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 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. 4
Developing the Web Application 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. 5
Developing the Web Application 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. 6
Developing the Web Application 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 Use these methods to verify the fields populated by the constructor. Normal use of these classes does not require accessing these 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. 7
Developing the Web Application Methods Use these methods to verify the fields populated by the constructor. Normal use of these classes does not require accessing these 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. 8
Developing the Web Application com.cisco.cuce.ivrjsp.utils 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. 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. 9
Developing the Web Application 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 10
Developing the Web Application 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. 11
Developing the Web Application 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 12
Developing the Web Application 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 DatabaseGetResults.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. 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: task_id: (Required) Identifier obtained from session.telephone.taskid. 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. 13
Developing the Web Application 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: task_id: (Required) Identifier obtained from session.telephone.taskid. 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: task_id: (Required) Identifier obtained from session.telephone.taskid. 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: task_id: (Required) Identifier obtained from session.telephone.taskid. 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. 14
Developing the Web Application 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. This JSP returns a Boolean called success after execution, set to true if no errors occurred during execution, otherwise it is set to false. 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: task_id: (Required) Identifier obtained from session.telephone.taskid. 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. 15
Developing the Web Application 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. This JSP returns a Boolean called success after execution, set to true if no errors occurred during execution, otherwise it is set to false. 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 > 16
Developing the Web Application 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 ); 17
Developing the Web Application } } 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: <!-- Compiled JSP servlet definitions --> <servlet> <servlet-name>clientservlet</servlet-name> <servlet-class>clientservlet</servlet-class> </servlet> <!-- Compiled JSP servlet-mapping definitions --> <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 18
Developing the Web Application 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 Step 2 Step 3 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 > Create an application-level variable to store the parameter in the VoiceXML root document. Program the JSP to emit VoiceXML code that assigns the result of the result.getparameter() call to the declared application-level variable. Tutorial VoiceXML Application 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. 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. 19
Developing the Web Application Deployment Prerequisites Procedure Before you execute the sample IVR application, perform these steps: Step 1 Step 2 Step 3 Step 4 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. 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. Use the web application to test the e-mail and fax response functions. 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 Step 2 Do not modify the files in the tutorial/banking/vxml directory. They must be left as a reference. 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 20