OpenVXI

Configuring and Running the OpenVXI

Configuring the OpenVXI

Once you have completed installing OpenVXI, you must configure the OpenVXI before attempting to place calls. The configuration procedures completely depend on the integration, as the reference OpenVXI components never directly access a configuration subsystem. Instead, all configuration parameters are passed to the initialization or resource creation functions for each OpenVXI component.

Start off by using the bundled reference application manager (testVXI) with the reference VXIrec, VXIprompt, and VXItel implementations to test that the installation and configuration was successful. This also allows you to quickly experiment with the OpenVXI. For this reference application manager, modify a configuration file as directed in the sub-section that follows.

Once this is complete, you’ll integrate the OpenVXI components into your own telephony platform (optionally based on testVXI) and write your telephony hardware integration (optionally based on the bundled reference VXIprompt, VXIrec, and VXItel simulator implementations). When doing so, the configuration mechanism is completely determined by you: you may opt to copy code from testVXI to continue using the configuration file described below, or you can extend your existing platform configuration system to specify the relevant OpenVXI parameters.

Configuring the Reference Application Manager

The sample OpenVXI client (testVXI) is configured through a text configuration file specified on the command line. Each line of this file defines a value for a property (parameter) applying to a given OpenVXI component; the possible property names are defined in the interface header files for the various components. The configuration file format is described in detail in a comment block at the top of the sample configuration file, config/OSBclient.cfg in your OpenVXI installation directory.

NOTE: Before configuring, make a backup copy of OSBclient.cfg.

Once you have made a backup copy, review the properties in the configuration file and modify their settings as appropriate. For an explanation of each property, refer to their definition in the corresponding component header files and the Interface Reference.

In most cases you can modify the following properties to get started (listed in priority order):

1. In the Client configuration section, set client.inet.cacheDir to the directory where you want to store cached Internet files from URL fetches.

2. Set the client.inet.cacheTotalSizeMB property to the desired size limit in megabytes for the Internet fetch cache.

Configuring the Web Server

The OpenVXI supports running against static content stored as local files as well as static or dynamic content served by a web server. The OpenVXI is generally used with a web server. Content can be VoiceXML documents, audio files (if supported by your VXIprompt implementation), and grammar files (if supported by your VXIrec implementation). When a web server delivers the content, it also provides the MIME content type for the content and information about the desired caching behavior for the content.

For the MIME content type for VoiceXML documents, a value of application/vxml+xml is recommended, but not mandatory, as the OpenVXI can use information within the XML document to verify it is a VoiceXML document. For VXIprompt and VXIrec implementations the MIME content type is more important, as several common audio formats do not have a header that permits self-identification. Support for the following audio formats is recommended for play and record operations, but not mandatory.

MIME Content Type	Description
audio/basic (from http://ietf.org/rfc/rfc1521.txt)	Raw (headerless) 8kHz 8-bit mono mu-law [PCM] single channel. (G.711)
audio/x-alaw-basic	Raw (headerless) 8kHz 8 bit mono A-law [PCM] single channel. (G.711)
audio/x-wav	WAV (RIFF header) 8kHz 8-bit mono mu-law [PCM] single channel.
audio/x-wav	WAV (RIFF header) 8kHz 8-bit mono A-law [PCM] single channel.

The length of time the OpenVXI caches an item fetched from a web server is controlled by the caching values returned in the HTTP/1.1 header. The reference VXIinet implementation (OSBinet) provided with the OpenVXI currently only supports the “Expires” header, which defines the date and time when the OpenVXI must discard the cached copy and re-fetch from the web server. Some web servers allow defining caching property defaults based on the MIME content type, useful for allowing caching of audio files but not dynamically generated VoiceXML documents, for example.

Sample Applications

The OpenVXI includes a number of sample applications with packaged grammars, VoiceXML files, and audio files. These files are installed in the samples subdirectory of the installation.

The most basic is rec_test.vxml that prompts the caller for the name of a fruit, then plays a confirmation prompt of what was spoken and exits. This works out-of-the-box with the reference simulator VXIrec implementation, OSBrec, which simply returns “berry” for this application. The other examples are set up to work with a real VXIrec implementation, and will thus need minor modifications to generate the proper results as described in the next section of this document, as well as potential changes to use in-line Java Speech Grammar Format (JSGF) grammars instead of W3C grammars.

Controlling the OSBrec Simulator

The reference VXIrec implementation for the OpenVXI, OSBrec, is a simple simulator. When the VoiceXML interpreter requests recognition, it merely looks up the value of the “RecResult” property as set through the VoiceXML property element, then returns this as the recognition result. For example, the following property element will result in recognition returning “123”.

By setting this property within the appropriate VoiceXML application scopes, it is possible to simulate a simple call flow. If you serve your application off a web server, you can also choose to dynamically alter the VoiceXML page to modify this property on the fly for a more dynamic simulation. You can also extend the OSBrec implementation to support additional controls if you choose, as its implementation is quite straightforward.

Running the Reference Application Manager

To run an application, first ensure your VXISDK environment variable is set to the top-level directory of your OpenVXI installation, and that your path environment variables (Path on Microsoft Windows, PATH and LD_LIBRARY_PATH on UNIX) are set appropriately so that you pick up the correct OpenVXI, Apache Xerces, Mozilla SpiderMonkey, and W3C Libwww binaries. See the Build and Install Instructions for details.

You may run applications as static documents directly from your file system, or you may configure your web server so that the application directory is in the web server’s path. When using a web server, check that you can retrieve the application documents from your web server using your HTML based web browser before running testVXI.

You can then run the program testVXI using the following command line:

testVXI -url rec_test.vxml –channels 1 –calls 2 –config OSBclient.cfg

where you substitute the path or URL to your desired VoiceXML document for rec_test.vxml, the number of telephony channels you want to run on for 1, the number of calls to process on each channel for 2 (specify –1 for unlimited calls), and the path to your configuration file for OSBclient.cfg. On Windows, you must also substitute “testVXID” for “testVXI” if you wish to run the debug version.

VoiceXML is a Trademark of the VoiceXML forum.