Developer's Guide

CHAPTER 9: CONFIGURABLE ELEMENTS VOICEXML PROGRAMMING GUIDE

FOR CISCO UNIFIED CUSTOMER VOICE PORTAL RELEASE 4.0(1)

A voice element can add any Java object to scratch space via the

setScratchData() method

in VoiceElementData. Scratch data is used for voice element internal uses only since the

scratch space is cleared when the voice element ends, even if it is revisited in the same call.

Additionally, the data in the scratch space is stored in the session managed by the VoiceXML

Server. To minimize performance issues, placing large Java objects in the scratch space is not

suggested.

VoiceElementBase Methods

A voice element extends the abstract Java class VoiceElementBase found in the

com.audium.server.voiceElement package. Like other elements, it shares methods obtained

from the base class ElementBase described in the previous sections. VoiceElementBase,

however, adds many additional methods that apply to voice elements only. Its execution method

is also more complex.

Execution Method

String addXmlBody(VMain vxml, Hashtable params,

VoiceElementData data) throws VException, ElementException

This is the execution method for voice elements. The arguments to the method are:

vxml. The VMain object is the container VFC object in which all VoiceXML content is added

(by adding other VFC objects to it). The desired VoiceXML page to produce must be

assembled using the VFCs and added to this object. If no VFCs are added, an incomplete

VoiceXML page will be produced, causing the voice browser to encounter an error. Simply

add all VForm objects to this object. Unified CVP VoiceXML Server will take care of the

rest. Note that the form you wish to be visited first must be named start. This is very

important!

params. The params object is a Hashtable that contains all HTTP arguments passed by the

voice browser through the VoiceXML Server. For example, if the voice element produces a

VoiceXML page with a variable named dataToCollect that is then included in a submit

argument list, the params Hashtable will contain an entry with the key “dataToCollect” and

the value as a

String. To access it, the developer would write:

String data = (String) params.get("dataToCollect");

data. The VoiceElementData object belongs to the Session API and is used to access session

information (See Chapter 3: Session API for more on this API). Aside from the standard

functionality,

VoiceElementData provides all data required by the voice element such as

ways to access the scratch space, obtain the

VPreference object used to instantiate the

VFCs, and obtain the voice element’s configuration object, VoiceElementConfig.

The

String return value of the method must refer to the real name of the voice element’s exit

state. The real name of the exit state must match one of the names given in the

getExitStates() configuration method. Since voice elements can span multiple VoiceXML

pages, returning null indicates that the voice element is not done and the execution method