23/06/2011

Building VoiceXML applications

Building VoiceXML applications

A voice application is a collection of one or more VoiceXML documents. A VoiceXML document is composed of one or more dialogs. A single VoiceXML document serves as the application entrypoint. This is the VoiceXML document that the Tellme VoiceXML interpreter fetches when a customer dials the telephone number associated with your voice application. Upon execution of that document, the interpreter fetches dependencies including grammars, scripts, recorded audio, XML data, and additional VoiceXML documents as required by your application. The documents in a voice application share a common application root document. An application root document is a VoiceXML document that can contain variable declarations, scripts, links, grammars, event handlers, and properties that are available throughout the application. Note. Subdialogs are a notable exception, and they are described in detail in Modularizing code with subdialogs. The remainder of this document provides some simple examples of a voice application and provides details about the application root document 1. Understanding voice applications 2. Defining an application root document 3. Referencing an application root document

1. Understanding voice applications

The following diagram depicts a simple voice application. The application consists of a main document, "doc1" that serves as the application entrypoint, an application root document, "app_root", that provides shared application resources, and two additional VoiceXML documents, "doc2" and "doc3".

"doc1" references the external grammar located in the file "gram1". "doc2" refers to the external grammars located in the files "gram2" and "gram3". "doc3" refers to the external grammar located in the file "gram4". The application flows from "doc1" to "doc2" and from "doc2" to "doc3". The following diagram depicts a more complex voice application:

tellme.com//applications-p.html

1/5

23/06/2011

Building VoiceXML applications

"app root" represents the application root document. It references the external grammar file "gram1" and the external script files "script1" and "script2". "doc1" represents the application entrypoint. In this application, "doc1" references the external grammar file "gram2". During execution, "doc1" calls the subdialog contained in the VoiceXML document "sub1". The subdialog "sub1" references the external grammar file "gram3". "doc2", "doc3", and "doc4" represents other VoiceXML documents in the application. All three documents reference the application root document "app root" and have access to the variables, scripts, links, grammars, and event handlers contained within "app root" as well as the grammars and scripts that "app root" references externally. The navigation between these VoiceXML documents is not shown. "doc3" references the external grammar file "gram5". During execution it calls a subdialog located in the VoiceXML document "sub2". "doc4" references the external grammar file "gram5" as well as the external script file script3. During execution, "doc4" calls the subdialogs contained in the VoiceXML documents "sub2" and "sub3". The subdialog contained in "sub3" calls a subdialog contained in the VoiceXML document "sub4". The VoiceXML document "sub4" references the external grammar contained in the file "gram4" as well as the external script contained in the file "script4". The application flows from "doc1" flows to "doc2", back and forth between "doc2" and "doc3" and finally from "doc3" to "doc4".

2. Defining an application root document

When building a voice application, it is useful to define resources such as variables, scripts, grammars, links, and event handlers that can be shared across the application. Variable declared in the application root document have application scope allowing you to share state across the documents that make up your voice application. Declaring scripts in the application root document allows functions and script variables to be loaded once for the lifetime of your application. Grammars declared in the application root document are active throughout the application as are links, and event handlers. The document can contain variable declarations, scripts, links, and event handlers. By placing these elements in the application root, they are available for use by the documents that make up your voice application. The following is an example of an application root document. The document contains the following resources: One variable indicates if the user is logged in; another stores the user's student ID; another stores the URL of the next dialog in the application. A link element that defines a grammar indicating that when the user says "start over" the application
tellme.com//applications-p.html 2/5

23/06/2011

Building VoiceXML applications

should jump to the welcome dialog in the document tellmeu.vxml. A script element defines two functions. The first returns whether or not the user is logged in. The second initializes the previously described variables. An event handler catches a user-defined event, "event.onlistmyclasses". When this event is thrown, the handler assigns a URL to the application scoped variable gsNextDialog and then navigates to the VoiceXML document login.vxml. A property element sets the timeout value to one second for all fields throughout the application with the exception of those that have an explicit timeout value specified. An error element catches all errors that may occur in the application at run-time. In the final catch element, the event attribute doesn't specify any event name or prefix, This guarantees that the application will handle all catcheable events in addition to catcheable errors. If the VoiceXML interpreter executes this handler, you have an error in your voice application code. You should modify your voice application to handle the event explicitly. <!-- tellmeu_root.vxml --> <vxml version="2.1"> <var name="gbLoggedIn" expr="false"/> <var name="giStudentID" /> <var name="gsNextDialog" /> <link next="tellmeu.vxml#welcome"> <grammar mode="voice" root="root_rule" tag-format="semantics/1.0" version="1.0" xml:lang="en-US" xmlns="http://www.w3.org/2001/06/grammar"> <rule id="root_rule" scope="public"> <one-of> <item> start over </item> </one-of> </rule> </link> <script> function IsLoggedIn() { return application.gbLoggedIn; } function InitGlobals() { application.gbLoggedIn = false; application.giStudentID = null; application.gsNextDialog = null; } </script> <property name="timeout" value="1.0"/> <catch event="event.onlistmyclasses"> <assign name="application.gsNextDialog" expr="'my_classes.asp'"/> <goto next="login.vxml"/> </catch> <!-- handle all error events --> <error> <log>APP ERROR!!! <value expr="_event"/> Sorry, there was a problem processing your request.
tellme.com//applications-p.html 3/5

23/06/2011

Building VoiceXML applications

Please try again later. <disconnect/> </error> <!-- handle unhandled non-error events --> <catch event=""> <log>UNHANDLED EVENT!!! <value expr="_event"/> Sorry, there was a problem processing your request. Please try again later. <disconnect/> </catch> </vxml>

3. Referencing an application root document

You reference the application root document by setting the application attribute of the VoiceXML documents that make up your voice application with the exception of subdialogs. <!-- tellmeu.vxml --> <vxml version="2.1" application="tellmeu_root.vxml"> <!-dialogs and document-scoped variables, scripts, event handlers, and links go here --> </vxml>

When you reference an application root document, the VoiceXML interpreter creates an application scope that exists so long as the VoiceXML documents in the application, with the exception of subdialogs, reference the same application root document. If your voice application transitions to a document that reference a different application root or no application root at all, the previous application scope is destroyed. This behavior can be demonstrated with the following example. The application entrypoint is doc1.vxml. When the dialog form1 executes, it increments the applicationscoped variable gVar by 10 and navigates to the dialog form3 in doc2.vxml. Since doc2.vxml doesn't reference the same application root as doc1.vxml, the previous application scope is destroyed, and a new one is created for doc2.vxml. When the dialog form3 in doc2.vxml navigates to the dialog form2 in doc1.vxml, the application scope for doc1.vxml is reinitialized, and the value of gVar is 1. <!-- app_root.vxml --> <vxml version="2.1"> <var name="gVar" expr="1" /> </vxml> <!-- doc1.vxml --> <vxml version="2.0" application="app_root.vxml"> <form id="form1"> <block> <assign name="gVar" expr="gVar+10" /> <goto next="doc2.vxml#form3" /> </block> </form> <form id="form2"> <block> <!-- expect 1 -->
tellme.com//applications-p.html 4/5

23/06/2011

Building VoiceXML applications

<log>In form2, gVar is <value expr="gVar" /> </log> </block> </form> </vxml> <!-- doc2.vxml --> <vxml version="2.0"> <form id="form3"> <block> <goto next="doc1.vxml#form2" /> </block> </form> </vxml> Tellme Networks, Inc. Terms of Service Privacy Policy General Disclaimers

tellme.com//applications-p.html

5/5