• About This Project
• VTP Home
• Project Plan
• VTP Team
• Downloads
• Documentation
• User's Guide
• FAQ
• Community
• Mailing List
• NewsGroups

User's Guide

This guide provides an extremely high-level overview of openVXML, and how it fits into the context of a voice platform; it then introduces the openVXML Designer and describes the components used in voice application design. After that, it provides a detailed walk through of the steps involved in creating and deploying an application.

• Big Picture
• Installation
  • Installing the OpenVXML Designer
  • Running OpenVXML for the first time
• Voices
  • Creating a Voice Project
  • Adding Audio Files to a Voice
  • Creating a Grammar File
  • Presenting Dynamic Values
  • Creating Shared Content
• Applications
  • Creating a Voice Application Project
• The Editor
  • Adding and Connecting a Module
  • Formatting the Diagram
• Canvases
  • Adding Additional Canvases
  • Deleting a Canvas
  • Renaming a Canvas
• Modules
  • PlayPrompt Module
  • Question Module
  • OptionSet Module
  • Record Module
  • Script Module
  • Subdialog Module
  • Transfer Module
  • Variable Assignment Module
  • Decision Module
  • Portal Exit Module
  • Portal Entry Module
  • End Call Module
• Data Access - Databases and Webservices
  • Creating a New Database Object
  • Defining a Database Table
  • Defining a Business Object
  • Adding a Database Query Module
• Deploying OpenVXML Web Applications

The Big Picture (Greatly Simplified)

This diagram illustrates the basic components of an IVR as it is configured when using the open source version of openVXML. The application is first created with the openVXML Designer; it is then exported and uploaded (as a Web ARchvie, or WAR file) to an Apache Tomcat installation (although it could be any valid Java servlet container). The voice browsers are typically configured to request VXML from the webserver when a caller dials into the system. The VXML instructs the voice browser to play the configured audio files and TTS prompts for the caller, what to expect from the caller as input, and subsequent actions to take based on the caller's response.

Within the openVXML Designer there are two main components, the Voice and the Application. The idea is to keep the logic separate from the presentation. The Application handles the logic – decisions to be made, any sort of database or webservice queries, transfers, the attachment of data, and more generally the basic layout of a callflow. The Voice contains all interface elements – all audio and grammar files. The Voice is also responsible for playing dynamic data (like an account balance or a date) back to the caller. A Voice is language-specific; an application can be made multilingual by adding a second Voice for the new language.

Installation

Installing the OpenVXML Designer

Installing the openVXML Designer requires two steps. First, install the JRE if it's not already. Check to see if you already have the current version of the JRE installed by looking in your Programs menu or folder first. You can also find out if you have java installed and what version it is by running the following at the command prompt:

java -version

If the JRE needs to be installed, download it from Sun here. On this web page, look for the Java Runtime Environment (JRE) section. Follow the link, and then download and install the JRE for your platform (Windows, Linux, SPARC or Solaris).

Second, run the openVXML installer. A dialog box will prompt you to choose the location of the installation. This step takes a few minutes when run for the first time. The progress bar will indicate the status of installation.

Running OpenVXML for the first time

The first time openVXML Designer is run, a dialog will appear asking which workspace is to be used. The workspace in Eclipse is the location where all of the voice application data used to develop your voice application will be stored – the callflows, audio files, grammar files, etc. It can be anywhere that makes sense for you. Whichever location you chose, Eclipse will remember this the next time you run the openVXML Designer and suggest it as the workspace to use. If you don't plan on using more than one workspace, you can check the Use this as the default and do not ask again option to skip this screen from now on.

Once Eclipse has started, you may see the Welcome screen. If so, click the 'Go to the Workbench' image on the right.

After clicking the 'Go to the Workbench' icon, your screen may look like this:

If so, it means you're in the default Java perspective. To change this, click Window -> Open Perspective -> Other'

Select the OpenVXML Perspective and then click OK.

You'll know you're ready to go when you see something that looks a lot like this:

Voices

A Voice project contains all of the audio and grammar files necessary for an application. The Voice also manages the combination of prerecorded audio files to playback dynamic data, such as dates, account balances, phone numbers, etc. A Voice is created for a particular language; this is because the ways in which the audio files are combined to represent things like dates and dollar amounts are different for different languages.

Creating a Voice Project

The first step in developing an application with the openVXML Designer is to create a Voice for the language to be used in the application. Of course, an application can have more than one language, but we'll only be choosing one here for purposes of demonstration. There are two ways to create a project in Eclipse:

• Using the main menu
• Using the context menu of the Projects View

We'll use the context menu as many other features of the Designer can be accessed in this way.

1. Right-click with your mouse in an open (white) area of the Projects view to open the Projects View Context Menu.

   

2. Select Create Voice from this context menu to launch the New Voice Wizard.

   

3. Enter the name for your new Voice. It's helpful if the name indicates in some way the language the Voice is to represent.
4. Choose the language this Voice is to speak in the Formatter field. Remember, the Voice arranges the bits of audio to play back dynamic information – in other words, it formats the audio for a language. To support another language, simply write or acquire a formatter for that language.

   Note: The Voice name can be any combination of letters, numbers, <space>, or '_'. The name you choose must also be unique compared to the other (both Voice and application) projects in your workspace.

   

   An error message will be displayed if the name does not satisfy these requirements.

5. Select the language pack information in the Language combo box.
6. Click Finish to save the information. The Voice should be saved unless there are errors.
7. To cancel the changes, select the Cancel button.

Adding Audio Files to a Voice

A Voice can contain any number of pre-recorded audio files. These files are placed into the Media Files folder of the Voice project. Subfolders can also be created under the Media Files folder to help organize the audio files. Subfolders are also a key requirement of Magic Filenames – the ability of openVXML to automatically understand and use prerecorded audio snippets when playing back dynamic data, such as dates and numeric amounts.

A new subfolder can be created by Right-clicking on the Media Files folder under your recently created Voice folder.

1. Right-clicking on the Media Files folder in the Voice project.
2. Select Create Media Folder from the context menu. This will open the New Folder dialog.

   

3. To create the folder, enter a name into the input box
4. Click the button labeled Finish.

Note: The folder name can only contain letters, numbers, and _. The name must also be unique amongst the other folders and files in its parent folder. An error will be displayed if any of these requirements are not satisfied.

Files can be added by dragging the files or folders you want to add into the destination folder.

The type of audio files required depends on the voice browser you're using, not OpenVXML Designer. Consult your voice browser's documentation. Generally speaking, Dialogic's Vox format (u-law, 8KHz, 64 kbps, mono) tends to work. There are many programs available for converting and editing audio files; one we're fond of is the GoldWave Digital Audio Editor (www.goldwave.com).

Creating a Grammar File

Grammar files tell the speech recognition engine what to be listening for. They are generally either written to listen for DTMF tones or speech. There are several different grammar file formats available; consult the documentation for your speech recognition engine (which may be bundled with your voice browser) for details. A common format is GRXML, which is easy to create in the OpenVXML Designer:

1. Right-click on the Media Files folder under the Voice you created earlier in the left-hand pane.
2. Select "Create Grammar File" from the drop-down menu
3. Enter a file name for your grammar
4. Select Voice or DTMF Grammar
5. Click Finish
6. Double click on the file that you just created in the left-hand pane.
7. Edit the grxml file displayed to reflect your grammar's choices. This is usually done by replacing

   <!--Insert your grammar structure here-->
   

   between the <rule> tags with something like this, for example:

   <one-of>
        <item> general information </item>
        <item> information </item>
        <item> general info </item>
        <item> hear information </item>
   </one-of>
   

For more information on writing GRXML files, see http://www.vxml.org/grxmlbasics.htm

Presenting Dynamic Values

One of the most useful aspects of OpenVXML is its ability to render dynamic values using TTS or audio files, such as an account balance. In English, the value $123.50 might be represented as "one hundred twenty-three dollars and fifty cents". The rendering of dynamic values is performed by the VoiceFormatter associated with the voice project.

The most VoiceFormatters will use audio files if available in preference to TTS. The formatter locates the audio files it needs by searching the files available in the voice project for specific file names. The directory structure and exact file names used by the VoiceFormatter can differ from one formatter to another. To illustrate how this might be set up, the following is the general structure used by the SimpleEnglishFormatter distributed with OpenVXML:

Months

(for january.vox, february.vox, etc.)

Digits

(for 1.wav, 2.wav, 10.wav, 11.wav, 20.wav, 100.wav, etc.)

Letters

(for a.au, b.au, c.au, etc.)

Ordinals

(for 1st.vox, 2nd.vox, etc.)

Common

(for hundred.wav, hundredth.au, thousand.vox, negative.au, and.wav, cent.vox, dollars.wav, etc.)

Creating Shared Content

Shared content is effectively a predefined prompt which can be invoked at any point in the application. It's handy for standardized prompts (like a greeting or some sort of obligatory legalese); when the time comes to change the prompts, they can be modified in one place and instantly update throughout the system.

Shared content exists in the Voice Project, in the Voice.xml file. Double-click this to see the Voice Project Editor, which is the interface for adding, editing or deleting shared content. To add shared content,

1. Click the Add Shared Content button at the bottom of the Voice Project Editor.
2. Provide a name for the shared content.
3. Click the Add Entry button to add some TTS, or a prerecorded file, or another piece of shared content.
4. Repeat this until you've got the prompt you want.
5. Click OK to save.
6. Save the Voice.xml file before switching to another page.

To use shared content within a prompt in the application, select a content type of Reference, and then pick the shared content from the static value list.

Applications

An application project organizes the call flow and configuration information into a simple structure. The call flow is stored in the CallDesign.xml document. The Databases, Business Objects, and Web Services folders contain information used for data access using the built-in components. The Dependencies folder contains external libraries that extend the application's functionality. An application must be configured to use a Voice for each language it supports. Branding can also be applied, providing a simple mechanism for caller experience differentiation within the application.

Note: Creating an Application requires the creation of a Voice first; if you haven't already done this, go back and create a Voice project now.

Creating a Voice Application Project

There are three ways to create a project in Eclipse:

• Using the main menu bar ("File -> New -> Project", then under the Eclipse VTP Wizards select Eclipse Voice Tools Application Project)
• Using the new icon in the tool bar (In the dialog that appears, under Eclipse VTP Wizards select Eclipse Voice Tools Application Project)
• Using the context menu of the Projects View (select Create Application).

For this example, we'll use the context menu.

1. Right-click with your mouse in an open (white) area of the view to bring up the Projects View context menu.
2. Select Create Application from this context menu to launch the New Application Wizard.
3. Enter the name for your new application in the text field.

   

   Note: The application name can be any combination of letters, numbers, <space>, or _. The name you choose must also be unique compared to the other (both persona and voice application) projects in your workspace. An error message will be displayed if the name does not satisfy these requirements.

4. Click the Next > button. The screen to configure Languages and Brands will appear.

   

5. Click the Add Language button to add the Voice (language) created earlier. A small dialog will appear; select the Voice project to add and give it a name.

   Note: Some may argue that it doesn't make much sense to provide another name for the Voice project, and they'd be right. This step is provided as groundwork for future functionality which will give the designer an enormous amount of control over how the Voices and brands interact, but which isn't completely implemented in this version.

6. Optionally, a new brand can be added here (though this is not required, the default brand will do just fine).
7. Click the Finish button and a new project will be created in your workspace.

Note: If you want to add or remove support for a language to an existing application, you can do this by right-clicking on the application and selecting Properties and navigating to the Build Path properties panel.

The Editor

The application editor is made up of two primary elements:

• The Design Area
• The Canvas Tabs

Additionally, there are two other views that will come in handy:

1. The Canvas Browser
2. The Voice Pallet

The Canvas Browser (on the left) is a handy graphical representation used for navigation between the canvases that make up the application.

The Design Area (in the middle) shows the call flow of the currently selected canvas. Below that is another way to both indicate the current canvas and to select another canvas to view: the Canvas Tabs.

Note: Incidentally, in the Projects sidebar on left: little green "D" stands for dialog and little purple "P" stands for profile. – I don't think this is still true.

The Voice Pallet (on the right) displays the available building blocks for the application. This includes the primitive objects (prompts, decision blocks, database queries, etc.) as well as the more complex structures (dialogs, application fragments, and custom integrations).

Adding and Connecting a Module

There are two ways to add a new module to the selected canvas: dragging from the Voice Pallet or right-clicking the Design Area and selecting Add. For this example, we'll use the Voice Pallet to add a PlayPrompt.

Select the PlayPrompt module from the Voice Pallet; drag this onto the canvas and then drop it. The new PlayPrompt module should appear on the canvas. To connect it to the Begin block, click the arrow in the bottom right corner of the Begin block and then drag the arrow over to the new Greeting block and drop it. The Connector dialog will appear.

This dialog will display the exit points of the source module that have not been assigned to a connector yet. In this case, the Begin block only has a single exit point – Continue. Select Continue from the list and then click OK.

Note: The newly added module would display an icon on the top right hand corner indicating that it needs to be configured. This icon would later change or disappear based on the state of the module.

Formatting the Diagram

The application design canvas offers several options for formatting the call flow for readability. First, using the pointer tool select the module(s) you wish to move or format. Multiple modules can be selected by either holding down the <shift> key and clicking on the modules independently, or by clicking in an open (white) area of the canvas and drawing a box around the items you want to select.

You can move the selected module(s) by clicking on them and dragging them to the desired location. Right-clicking on one of the selected modules to open a context menu with additional formatting options when multiple modules are selected. The formatting options are:

Align Edges

Places all the edges of the selected modules in line with the module you right-clicked on to access the context menu.

Align Centers

Moves all the modules selected so that their centers are aligned with the center of the module you right-clicked on to access the context menu.

Canvases

Adding Additional Canvases

Very often, you as the designer would like to end the clutter of one canvas and, finding a natural break in the flow, would like to skip to another canvas both to separate the type of work being done on each as well as to reduce the sheer number of modules and connectors on each canvas. To do this, you need to create a new canvas and to use both the Portal Entry Module and the Portal Exit Modules, covered in the next few steps.

The Canvas Browser

The Canvas Browser displays an iconic version of all the design canvases of the application. You can navigate to other design canvases by clicking on its iconic representation. The currently selected canvas will have a blue border around its iconic representation. The Canvas Browser is also used to create new canvases and clear, delete, or rename an existing canvas.

To create a new design canvas in the application,

1. Right-click in the Canvas Browser and select Add Canvas from the context menu. This will open the New Design Canvas wizard.

   

2. Enter a name for the new design canvas in the input box. Note: This name must be unique amongst the existing design canvases in the application. An error message will be displayed if the name already exists.
3. To finalize the creation of the new design canvas, click the Finish button. The canvas will be added to the application and will automatically be selected.

Deleting a Canvas

You can delete an existing design canvas and all of its contents from an application by right-clicking on the canvas you wish to delete and selecting Delete Design Canvas. You will be asked to confirm the action as it cannot be undone. You cannot delete the initial canvas that contains the Begin module.

Renaming a Canvas

To rename an existing canvas, simply click its name in the Canvas Browser. The text will become editable. When the new name has been entered, press Enter.

Note: As with new design canvases, the new design canvas name cannot be the same as another canvas.

Modules

The Voice Pallet contains a collection of modules used to create the voice application. Some describe interactions with caller; others perform backend data operations, such as querying a database or interacting with a web service. One of the modules will run your custom javascript code, doing pretty much whatever you tell it to.

PlayPrompt Module

The PlayPrompt is the most basic unit of the IVR – it simply cues up audio to be played by the voice browser. This can be TTS, pre-recorded audio, or dynamic combinations of prerecorded audio snippets to play dynamic data.

1. Select the PlayPrompt module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. Configure the message to be played. In the Media section, double-click the Not Configured label – this opens the prompt's Contents window.
5. Click Add Entry to show the Prompt Entry window.
6. Select the content type; this can be text (TTS), shared content, audio files, or dynamic data to be read back using dynamically arranged audio snippets. For the example, select Text.
7. Make sure Use a static value is selected, and then enter some text to be read to the caller in to box. (If you wanted to read the contents of a variable, you'd select Use a value from a variable and then choose it from the list – to do this, you'd need to have wired the new PlayPrompt module into a pre-existing callflow before any variables would appear in the drop-down box.)
8. Click OK. The entry will appear in the Contents window.
9. Repeat steps 5 – 8 as needed to build up the desired prompt.
10. When the prompt is complete, click OK on the Contents window.
11. The Barge-In Enabled selection indicates whether the caller can skip through the prompt by pressing or saying something. Any entry will be applied to the next available Question Module, Option Set, or Dialog. Make a selection.
12. Click OK to finalize the changes for the PlayPrompt module.

Question Module

A Question module is used when you would like to ask something simple of the user, not present them with several options that all require their own prompts and grammars. This could be a yes or no, a phone number, desired pizza toppings, etc.

1. Select the Question module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. One prompt and grammar will apply for the entire question, as opposed to the Option Set module, where multiple of both are required. Configure the Prompt and Grammar as stated above in the PlayPrompt and Grammar sections.
5. Enter a variable name for the user input. This will be a new variable, created and initialized in this block, that will be visible from this point on in the callflow to any subsequent modules.
6. In the Settings section at the bottom is where you choose whether you want a voice only, DTMF only or Hybrid interaction for your Caller. The settings differ slightly based on which style you choose. Choose your style, decide whether you would like to allow Barge-in and set your timeouts, confidence and levels according to your wishes. Some defaults have been set for you. You can set all of this individually per module.
7. Click OK to finalize the Question module.

Option Set Module

There are two out-of-the-box ways to add a menu-like offering to your project: Option Set and Menu Dialog. The Option Set is the simpler of the two, but is also more limited in its built-in capabilities, such as error handling. It simply provides the menu of options to the caller (along with the associated prompts and grammars for each option), and results in a branch, with one path for each option and then two more paths to handle caller errors. All error handling and retry functionality must be provided by the callflow author. For a more standardized, pre-packaged approach which includes the error handling and retry functionality, try the Menu Dialog.

To add an Option Set,

1. Select the Option Set module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. In the Settings section at the bottom is where you choose whether you want a voice only, DTMF only or Hybrid interaction for your Caller. The settings differ slightly based on which style you choose. Choose your style, decide whether you would like to allow Barge-in and set your timeouts, confidence and levels according to your wishes. Some defaults have been set for you. You can set all of this individually per option.
5. Click the 'Add Option' button for each option you would like to add to your menu.
6. Give the option a meaningful name and a new section of the Option Set dialog will appear with the following options to set:

   Prompt

   The message to be played for this option

   DTMF Value (for DTMF or Hybrid input styles)

   The DTMF value the caller will use to select this option.

   Grammar (for Voice or Hybrid input styles)

   The grammar file which indicates valid speech recognition matches to select this option.

   Option Is Silent

   Disables the prompt, but not the ability to select the option.

7. Options can be deleted, moved up or down or a guard condition can be set in the buttons that appear on the right-hand side of properties listed for each Option you create. A guard condition is a condition you can set that needs to evaluate to TRUE before that Option can be presented to the user, allow menu options to be dynamically available. An option with a guard condition which evaluates to FALSE cannot be selected by the caller. Setting guard conditions is optional.
8. Double-click on 'Not Configured' to set the Prompt and Grammar for each option. The prompts for each valid option will be concatenated together to become the entire menu prompt from the caller's perspective when your project is actually run. This means you'll need to include connective words such as 'and' and 'or' where appropriate. Configure the Prompt and Grammar as stated above in the PlayPrompt and Grammar sections.
9. Then click OK.

Record Module

When you wish to record a Caller's input verbatim instead of using speech recognition or checking for a DTMF value, you need a Record Module. This records the caller's speech into an audio file that can be archived, transcribed, emailed, etc.

1. Select the Record module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. Configure the Prompt as stated above in the PlayPrompt section.
5. Enter the name of the new variable that will store the recording.
6. In the Settings section at the bottom is where you decide whether you would like to allow Barge-in and set your timeouts, recording time and whether or not a beep precedes the recording or if a DTMF value will come after it, according to your wishes. Some defaults have been set for you.

Script Module

When you would like to enter some custom scripting of your own to the flow:

1. Select the Script module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. Click on the Script tab and enter your javascript.

Note: Callflow variables can be referenced in the script modules by preceding them with 'Variables'. For example, if the callflow variable 'TotalFailures' were being used to track the number of user errors happening at a menu, the line

Variables.TotalFailures++;

would increment this count by one.

For examples of the script module in action, take a look at the pre-built Menu and Field dialogs.

Using Java in a Script Module

Any Java object that's available to the JVM can be invoked from within a script block; it just needs to be done explicitly. For example, here's how to use the Java date object:

     var d = new java.util.Date();
     Log.info('date: ' + d);

Note that Java classes which are automatically imported in a normal Java environment aren't in this case. For example, the String object can still be used, it just needs an explicit declaration:

     var str = new java.lang.String(Variables.myOldString);
     Log.info('substring: ' + str.substring(2,3));

Accessing and Manipulating Business Objects from the Script Module

For the sake of this section, let's assume that a business object has been created called 'widget' that has these fields:

• name (String)
• dateMade (DateTime)
• numAvailable (Number)
• price (Decimal)
• exists (Boolean)
• attributes (Array of Strings)

If this business object had already been created in the callflow with the variable myWidget, it could be accessed in a Script Module with this:

     Variables.myWidget

So a log statement might look like this:

     Log.info('got the widget: ' + Variables.myWidget.name + ' at $' + Variables.myWidget.price);

For the sake of bevity, a local variable can be created to access the callflow variable. With this in mind, the previous line could be rewritten like this:

     var wdgt = Variables.myWidget;
     Log.info('got the widget: ' + wdgt.name + ' at $' + wdgt.price);

This technique also works to simply accessing elements of an Array of Business Objects. For example, if you had an array of Business Objects called 'accounts', you could extract a single reference to the array like this:

     var acct = Variables.accounts[0];
     Log.info('got this account: ' + acct.name);

which of course works exactly the same as

     Log.info('got this account: ' + Variables.accounts[0].name);

You might have need to create your own Business Object in a script block. To do this, you'd use the helper function 'create' of the Variables object. The code example below assumes that a Business Object variable for the widget Business Object exists, but is uninitialized (i.e., the Business Object variable is empty and doesn't actually point to a Business Object). The business object is created, a local variable is made for easier access, and then all of the properties are filled out.

     Variables.myNewWidget = Variables.create('widget');
     Variables.myNewWidget.name = 'test widget';

     var wdgt = Variables.myNewWidget;
     Log.info('name: ' + wdgt.name);

     wdgt.dateMade = '1/2/2010';
     wdgt.numAvailable = 200;
     wdgt.price = 12.50;
     wdgt.exists = false;
     wdgt.attributes = Variables.create('Array');
     wdgt.attributes[0] = 'very big';

Note the exception for the 'attributes' field. This is an array, and so it's initialization begins by creating a new Array object; once this is done, the first element of the array is assigned. (the Array object handles its resizing transparently, so you can add elements as needed. Remember, array indicies start at 0).

Setting the Brand from a Script Module

There are two built-in javascript constructs that are required for this, namely

• SelectedBrand
• Brands

SelectedBrand is an object that has the property 'value'. Brands' is an object that exposes all existing brands as properties. In an application that had a Gold brand, the brand could be changed from whatever it is to Gold with

     SelectedBrand.value = Brands.Gold;

Subdialog Module

The Subdialog module is used to invoke a VXML subdialog. This allows an openVXML application to seamless integrate certain kinds of existing VXML constructions into an application. For example, you could use the Subdialog module to utilize a Nuance OSDM.

1. Select the Subdialog module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. Enter the exact URL for the subdialog.
5. You'll need to know the signature of the subdialog; in other words, the parameters it's expecting to receive when invoked and the results it will return. Use the Add Input and Add Output buttons to configure the Inputs and Outputs tables to match your subdialog.
6. Click OK to finalize the Subdialog module.

Transfer Module

The Transfer module transfers the caller to the specified

1. Select the Transfer module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. TODO: Enter a destination. Format? Types?

Variable Assignment Module

The Variable Assignment module assigns static values to variables. It also lists all variables available at that point in the callflow and can be used to create variables (for more information about variable propagation, see Appendix B). Any change made to a variable listed (either the creation of a new variable or the assignment of a value to an existing variable) is indicated by a * in the leftmost column. A listing of 'N/A' in the Value column means that variable will not be altered. To use a Variable Assignment module:

1. Select the Variable Assignment module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. Click Add and create a Variable name and type.
5. Click on the Value field if you want to enter a static value.
6. To rename or change any variables or types, you have to delete and then recreate them.

Decision Module

A Decision module chooses one of two paths based on a comparison. This comparison involves any combination of two variables, javascript expressions, or static values.

There are 6 types of comparisons:

• Equals (=)

• Less Than (<)

• Less Than or Equal (<=)

• Greater Than (>)

• Greater Than or Equal (>=)

• Not Equal (!=)

Any expressions used in the comparison needs to be surrounded with single quotes. To use a Decision module:

1. Select the Decision module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name. This can be anything; it's only used to help you keep track of the module on the canvas.
4. Click on the Comparison tab on the left to enter the comparison for your decision module. Enter the left and right-hand variables or expressions and choose a Comparison type for them.

Portal Exit Module

The Portal Exit module is half of the link between two canvases; specifically, it is used on the destination canvas where it marks the exit of the portal. A Portal exit must be created before their corresponding module, the Portal Entry, can be configured. A Portal Exit can have more than one Portal Entry, but a Portal Entry can only have one Portal Exit. To use a Portal Exit:

1. Go to the destination canvas and select the Portal Exit module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Enter a meaningful name; this is the name that will be used when linking the Portal Entry to this exit.

Portal Entry Module

The Portal Entry module is half of the link between two canvases; specifically, it I used on the originating canvas where it marks the entrance of the portal. A Portal Exit must have already been created to use a Portal Entry. To use a Portal Entry:

1. Make sure a Portal Exit on the destination canvas has been created; know the name of this Exit.
2. Go to the originating canvas; select the Portal Entry module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
3. Double-click the new module to see the properties page.
4. Select the desired Portal Exit from the drop-down list. This will be the name of the Portal Exit noted in step 1.

End Call Module

The End Call module provides a graceful way to end the caller's session. This module has no properties and no exit paths.

1. Select the End Call module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. There are no properties for this module, because it simply ends the call with no processing. Just drag a connector to it and call it a day.

Data Access - Databases and Webservices

Creating a New Database Object

The openVXML platform has built in support for simple JNDI and JDBC database queries. There are several steps that must be performed before this capability can be leveraged in the voice application.

The first step is to create a database object to represent the database that will house the desired information. To create a database object:

1. Right click on the Databases Folder of the application in the Projects view.
2. Select New Database from the context menu. This will open the New Database wizard.

   

3. Type the name of the database object into the input field.
4. Click the Finish button.

Note: The name given here does not need to be the same as the actual database the application will connect to.

Defining a Database Table

The second step in this process is to define the structure of the database table which stores the needed information. To create a new database table object:

1. Right-click on the database object, which contains the new table object.
2. Select New Database Table from the context menu. This will open the New Database Table wizard.

   

3. Type the name of the database table object into the Table Name Input Box.
4. Click the Finish button.

   Note: Unlike the database object, the name of the table object must exactly match the name of the actual database table that stores the required information. This can usually be obtained from your IT administrators.

After creating the table object, you will have to specify the columns of the database table. These can also be obtained from your IT administrator.



5. To edit the table, Double click the table name in the Projects view. This will open the table structure editor. The table will not initially contain any columns.
6. To add a new column to the table, right-click in the editor.
7. Select Add Column from the context menu. The column will be added to the editor.
8. Give the column a name and select the type of data that is contained in the database table column.

Note: To remove a column, right-click the column name and select Remove Column from the context menu. The list of columns does not have to contain all the columns of the real database table, but all columns listed must be in the table. The column names must match the database table's column names exactly. We will finalize the database tie-in in the deployment section of this document. Databases, Tables and Database Objects and Fields cannot be renamed. Be sure of the name the first time, or delete them and recreate them to give them different names.

Defining a Business Object

The final task in setting up support for built in database queries is to define a business object that will be used to hold the data retrieved from the database query. To create a new Business Object:

1. Right-click on the Business Objects folder of the application in the Projects view.
2. Select New Business Object from the context menu. This will open the New Business Object wizard.

   

3. Type the name of the business object into the input box.
4. Click the Finish button. The new business object will be created and added to the Business Objects folder. To open the business object editor, double-click the name of the business object you wish to edit.

   

5. The business object will not initially contain any fields. To add a field to the business object, right-click in the editor and select Add Field from the context menu.
6. A new row will be added to the editor for the field.
7. Specify the field name.
8. Select the type of data the field will contain.

A business object will usually have the same field names as the columns from the database table it will hold the data for. To remove a field, right-click on the field name and select Remove Field from the context menu.

Adding a Database Query Module

You need to add a Database Query Module if you intend to hit a database with your application. A Database Object will already need to be created to be referenced in this Module. Adding the Module is covered in these steps. Creating the necessary Database and Business Objects is covered in the sections above.

1. Select the Database Query module from the Voice Pallet; drag this on to the canvas and then drop it. The new module should appear on the canvas.
2. Double-click the new module to see the properties page.
3. Set a Target Variable by selecting an existing variable in the drop-down or click New Variable and create a name and type.
4. Select the Source Database tab and choose a previously created database and table from the drop-downs.
5. Select the Fields tab and select a value for your business object by clicking on the value field and then on the '...' button.
6. Define your Search Criteria by clicking on the Comparison and Matching Value fields for the Column Name you've selected to use for your comparison.

Deploying OpenVXML Web Applications

Applications developed in the OpenVXML Development Environment may be exported as web applications and deployed in any Java Servlet 2.3 compatible server. The exported application can be run by accessing the URL:

http://[server_address]:[server_port]/[warfile_name_without extension]/[Eclipse_project_name]

1. To deploy a web application from the Development Environment, right-click on the application project. Select 'Save' and then select 'Export'.
2. Under 'Other', select "Web Application" from the export destination list and click "Next."
3. On the following screen, enter the location of the file to export to. This exported file should end in ".war" and will be a ZIP file of the web application's contents.
4. Select your application in the next screen.
5. After the file has been selected, "Finish" may be clicked at any subsequent point in the wizard to use the default configuration for the remaining elements.
6. Click "Next" to provide a custom configuration for the application specifics covered in Steps 6, 7 and 8.
7. If the exported application declares any databases, the next screen will allow the database connection information to be configured. Database connections can be acquired from the Java Naming and Directory Interface (JNDI) or from the Java Database Connectivity (JDBC) Driver Manager. By default, database connections will be obtained from JNDI under the name of the database and connections will be made using container-based authentication. To configure a database connection strategy, select the desired database from the list on the left and select either "JNDI Lookup" or "JDBC Driver" from the drop-down box.
   • For JNDI configurations, enter the name of the JNDI resource relative to the "java:comp/env/" base path in the "JNDI URI" field (see the JNDI specification for more information). To use container-based authentication, leave the "User Name" and "Password" fields blank, or fill in the appropriate values if application-based authentication is desired (see the Java Servlet Specification or your application server vendor documentation for more information on JNDI data sources).
   • For straight JDBC configurations, enter the name of the JDBC driver class in the "JDBC URL" field, the driver-specific database URL in the "JDBC URL" field, and fill out the "User Name" and "Password" fields with the appropriate values (See the JDBC specification or your database vendor documentation for more information on database connectivity).

8. If the exported application declares any web services the next screen will allow the connection information to be configured. To configure a web service connection, select the desired web service from the list on the left and enter the endpoint address to connect to (See the web service's documentation for connection specifics). By default connections will be made to the address specified in the web service description.
9. The final screen allows you to customize the JAR files that will be included in the web application. These JAR files will consist of:
   • The openVXML Runtime Environment libraries
   • The language packs the application is using
   • The custom module libraries used in the application
   • Any custom dependencies declared in the application

   Note: All of the listed libraries are required for the web application to work, so only exclude libraries that are already deployed to your servlet container in a shared area (see your application server vendor documentation on how this is done). By default, all libraries will be included in the application archive.

10. After clicking "Finish" a web application archive file (WAR) will be created that can be deployed into your web server of choice (see your application server vendor documentation for more information on deploying web applications).