2.4. VoiceXML variable support
VoiceXML provides the capability of storing values in variables. A var element can declare variables, and an assign element can then be used to assign a value to an already defined variable. In addition several other elements implicitly declare and/or assign values to variables, including field, object, record, initial, subdialog, link, and transfer elements.
VoiceXML variables behave exactly like ECMAScript variables. In fact, the declaration, assignment, and evaluation of VoiceXML variables are typically implemented using an ECMAScript interpreter. The var element type is used to define variables within a form. As part of the FIA's initialization process, any variable that is not initialized will be set to undefined.
2.4.1. Variable types
VoiceXML variables are "weakly typed." This means that there is no restriction on what type of value can be stored in any given variable. For example, some variable x could be assigned an integer value, then on the next line of code the same variable x could be assigned a string value.
In practice, you can think of all VoiceXML variables as being of type String. The interpreter can perform type conversions according to context. For example, after executing the VoiceXML code shown in Example 2-24, the value of d will be 43.14 since both a and b are numbers. The value of e, however, will be Jimmy43.13 since c is not parseable as a number. This would lead the interpreter to handle both c and d as strings in the computation of e.
Example 2-24. VoiceXML document excerpt demonstrating the behavior of "weak types"
<var name="a" expr="3.14"/> <var name="b" expr="40"/> <var name="c" expr="'Jimmy'"/> <var name="d" expr="a+b"/> <var name="e" expr="c+d"/> |
2.4.2. A variable's scope
Defining a variable in VoiceXML implicitly defines the scope over which that variable is "visible," or accessible for assignment and evaluation. In VoiceXML there are five different scopes:
session,
application,
document,
dialog,
anonymous.
Session variables are built-in and read-only variables, declared and set by the interpreter based on a user session. Section 2.4.7, “Built-in variables,” on page 59 covers the built-in session variables as well as built-in application variables.
Application variables are not limited to being built-in, they can be declared at the root document. They are initialized when the application root document is loaded and are visible to the root document and any other loaded application leaf document (see 2.10, “Organizing code into VoiceXML applications,” on page 123).
Document-scoped variables can also be declared with the var element. They are initialized when the document is loaded and are visible only within that document.
Dialog scope refers to variables declared within a form or menu element that exist while the dialog is active. Forms can have variables set with a child var element or var elements declared within a form item or executable content (see Chapter 3, “VoiceXML language reference,” on page 136 for a definition of executable content). The child var elements of a form are initialized when the form is first visited, var elements declared within a form item are initialized when the form item is collected, and var elements within executable content are initialized when the executable content is executed.
Anonymous scope refers to variables defined within block, filled, or catch elements. The catch element type allows a VoiceXML application to catch an asynchronous event (it will be discussed in greater detail in 2.8, “Events,” on page 93). A var inside a block, filled, or catch is initialized when any of these elements are visited.
In Figure 2-2 the relationship between the five scopes is shown. Next to each scope an example of a scoped var definition is given. Notice in the examples how the dot notation "." is used to differentiate scope between variables with the same name.
Figure 2-2. VoiceXML scope hierarchy
The VoiceXML application, shown in Example 2-25, shows variables from several different scopes. This application first defines a global variable retirementBenefitsAge and sets the value of that variable to 65. It then specifies a form containing a single field. This form simply asks the user in what year he or she was born. Once the user answers that question, the interpreter sets the value of the variable named birthYear defined over the scope of form.
Example 2-25. VoiceXML application demonstrating using variables in different scopes
<?xml version="1.0" encoding="iso-8859-1"?>
<vxml version="1.0">
<var name="retirementBenefitsAge" expr="65"/>
<form id="checkAge">
<var name="age"/>
<field name="birthYear" type="date">
<prompt>
Enter your birth year.
</prompt>
</field>
<filled>
<assign name="age" expr="(new Date()).getYear() - birthYear"/>
<if cond="age >= retirementBenefitsAge">
<goto next="retirementBenefits.vxml"/>
<else/>
<goto next="preRetirementInfo.vxml"/>
</if>
</filled>
</form>
</vxml>
|
The filled element then computes the value of the variable age defined over the form element by subtracting the variable birthYear from the the current year as determined using the built-in Date class in ECMAScript. (Note that the user's age may appear to be one year too young depending on the current month and day and the month and day of birth.)
If the user is at least 65 years of age or more, control will pass to the document retirementBenefits.vxml; otherwise, if the user is under 65 years, control will pass to the document preRetirementInfo.vxml.
2.4.3. The var element type: declaring a variable
VoiceXML can declare variables to be used for application logic. Variables are not form items and do not affect the FIA form item logic. Before you can use a variable it must be declared. This can be accomplished with a var element, for example by specifying <var name="account"/>. The account variable will be initialized to the ECMAScript default undefined, or it can be initialized to a value using <var name="account" expr="2091"/>. Where possible, it is a good idea to initialize variables with expr and avoid any ambiguous variable states.
Avoid using variable names that begin with an underscore character (_), end with a dollar sign ($), or use a dot (.). Such names are treated as reserved words in ECMAScript and VoiceXML.
2.4.4. The assign element type: setting variable values
To set a variable, use an assign element with two attributes that work as a name/value pair. The name attribute specifies the name and expr attribute sets the value. In Example 2-25 we saw how to dynamically assign a value to a variable. By writing <assign name="age" expr="thisYear - birthYear"/>, we set the variable age to the difference between two variables, thisYear and birthYear.
One of the most common bugs in VoiceXML applications stems from forgetting to use single quotes around constant strings in the expr attribute. For example, will be interpreted as "assign the contents of the variable named John to the variable named FirstName." What was probably intended here was which assigns the literal string value 'John' to the variable FirstName. Don't let the double-quotes around the attributes fool you!
2.4.5. The clear element type: clearing a variable value
To reset or clear a variable value, use a clear element. This will set the specified variable or variables to undefined.
In Example 2-26, after the user responds to the prompts for city, state, and name, the form-level filled element will test the state variable. If state is not equal to California the clear will set city and state to undefined, forcing the form to reprompt for the city and state. If the namelist attribute were omitted, all variables (city, state, and name) would have been set to undefined.
Example 2-26. A clear element affecting fields visited by the Form Interpretation Algorithm
<?xml version="1.0" encoding="iso-8859-1"?>
<vxml version="1.0">
<form id="directory_information">
<field name="city">
<grammar src="city.grxml"/>
<prompt>What city?</prompt>
</field>
<field name="state">
<grammar src="state.grxml"/>
<prompt>What state?</prompt>
</field>
<field name="name">
<grammar src="name.grxml"/>
<prompt>What name?</prompt>
</field>
<filled>
<if cond="state !='California'">
<prompt>
This is a directory service for California state.
</prompt>
<clear namelist="city state"/>
<else/>
<prompt>One moment please.</prompt>
<submit next="servlet/lookup" namelist="city name"/>
</if>
</filled>
</form>
</vxml>
|
2.4.6. The value element type: getting variable value
A value element allows the value of a variable to be accessed with the expr attribute. In Example 2-27, value is used to insert an ECMAScript expression containing a variable's value into a text-to-speech response.
Example 2-27. Accessing a variable's value
<var name="var1" expr="A"/>
<var name="var2" expr="B"/>
<assign name="var2" expr="var1"/>
<if cond="var1==var2">
<prompt>
The two variables are equal with the value of
<value expr="var1"/>
</prompt>
</if>
|
2.4.7. Built-in variables
VoiceXML provides standard variables for the purpose of accessing status information. With VoiceXML 1.0, only standard session variables were provided. Standard session variables provide session and connectivity related status information accessible by all applications. The VoiceXML 2.0 Specification warns that the many of the session variables may be deprecated and replaced with the session connection, a generic, non-protocol-specific variable space. VoiceXML also adds application variables used to provide meta-information from the voice and DTMF recognition process.
VoiceXML 1.0 and 2.0 session variables are as follows:
session.telephone.ani
Automatic number identification: for an incoming call, gives the caller telephone number.
session.telephone.dnis
Dialed number identification service: for an incoming call, gives the number the caller dialed.
session.telephone.iidigits
Information indicator digits: the type of phone call origin.
session.telephone.uui
User to user information: supplementary call-setup information.
VoiceXML 2.0 session variables are as follows:
session.telephone.rdnis
Redirected dialed number information: origin of a redirected call.
session.telephone.redirect_reason
Redirect reason: a string variable for why the call was redirected.
VoiceXML 2.0 proposed future session variables are as follows:
session.connection.local.uri
The URI of the local interpreter context.
session.connection.remote.uri
The remote URI which is the remote caller device.
session.connection.protocol.name
Name of the connection protocol and its sub-objects.
session.connection.protocol.version
Connection protocol version.
VoiceXML 2.0 standard application variables are as follows:
application.lastresult$
An array of interpretations with associated confidence, utterance, and input mode values for each interpretation.
application.lastresult$[i].confidence
The recognition or interpretation confidence level of thei-th best match, 0.0 minimum and 1.0 maximum.
application.lastresult$[i].utterance
Raw string of words recognized.
application.lastresult$[i].inputmode
The mode of input, either dtmf or voice.
application.lastresult$[i].interpretation
Interpretations sorted in confidence order.