Variables

A variable is used to record information provided by the caller, another VoiceXML file, or the back-end application.

Variables can be used for operations in scripts, and their values may be re-initialized or altered in the course of the same dialog. Like properties, variables can be declared at different levels of your application. Variable declarations can appear in a document, a form, or executable content.

Variable scope

The scope of a variable determines which parts of your VoiceXML application are able to use it. There are five different levels of scope:

Session scope variables are declared and set by the voice browser service. They are read-only variables that are available during each call.
Application or global scope variables are declared in the root document, using the VoiceXML <var> element in the <vxml> main body element (but outside any form elements). They are accessible throughout the entire application. For example, the pizza.vxml file main body declares several global variables:

<?xml version="1.0"?>

<!DOCTYPE vxml PUBLIC "-//Nuance/DTD VoiceXML 2.0//EN" "http://voicexml.nuance.com/dtd/nuancevoicexml-2-0.dtd">

<vxml version="2.0"> 

... 

  <var name="PromptPath" expr="'../prompts/'"/>

  <var name="PizzaSize" expr="null"/>

  <var name="PizzaToppings" expr="null"/>

  <var name="PhoneNumber" expr="null"/>

  <var name="DeliveryTime" expr="null"/>
Document scope variables are declared in the main body of a VoiceXML document (a <var> element appearing after the opening <vxml> delimiter, but not in a <form> ). They are accessible only within the current document. For example, the GetPizzaSize.vxml file declares an “entry” variable:
```
<!DOCTYPE vxml PUBLIC "-//Nuance/DTD VoiceXML 2.0//EN" "http://voicexml.nuance.com/dtd/nuancevoicexml-2-0.dtd">
```
```
<vxml version="2.0" application="pizza.vxml">
```
```

```
```
<var name="entry" expr="'init'"/>
```
Form or dialog scope variables are declared within a form element. They can only be used by the form in which they appear. If the form contains a field, the field automatically defines a form variable with that name. Form variables are initialized each time the form is entered.

For example, the GetPizzaSize form in GetPizzaSize.vxml includes a size field, which automatically creates a form variable of the same name:
```
<form id="GetPizzaSize">
```
```
  <field name="size">
```
```
  ... 
```
```
    <grammar src="../grammars/pizza.grxml#Pizza_Size"/>
```
```
    <filled>
```
```
      <assign name="PizzaSize" expr="size"/>
```
```
      <goto next="GetPizzaToppings.vxml"/>
```
```
    </filled>
```
```
  </field>
```
```
</form>
```
Since the size variable disappears as soon as the application leaves the form, the form must assign its value to the global PizzaSize variable using the <assign> element in order to use this size in the rest of the application.

Anonymous scope variables are declared in an event handler (<catch>, <error>, <help>, <noinput>, <nomatch>), a <block>, or a <filled> element. They can be used only within the element in which they are declared. The voice browser service initializes the variable when it enters the anonymous block, and erases the variable when it leaves the block. For example:

<catch event="error.badfetch">

 <var name="modifiedmessage" expr="'Please contact technical

   support or call our toll free hotline.'"/>

 <assign name="modifiedmessage" expr="_message + '.'

   + modifiedmessage"/>

 <prompt> Sorry we are having problems. The event is

    <value expr="_event"/>. The error message is <value

    expr="modifiedmessage"/>.

  </prompt>

</catch>

The variables declared in the main body of pizza.vxml all have an application scope, because pizza.vxml is the root document. These variables are available to any subdocument that identifies pizza.vxml as its root document, and many are assigned new values based on the input to subdocument fields.

However, some other VoiceXML files (GetPizzaSize.vxml, GetPizzaToppings.vxml, and so on) each declare an “entry” variable:

<var name="entry" expr="'init'"/>

Since these variables are each declared at the document level, they are only available within each document itself. Once the voice browser service exits the document, the variable is wiped from memory and must be declared and assigned a value again if you want to use it in another document.

Variable declaration

Variables in a VoiceXML application can be declared explicitly using the <var> element. However, variables are also created implicitly by other VoiceXML elements, such as <field>, <initial>, <block>, <record>, <subdialog>, and <transfer>, or built into the system to record session or application data.

The <var> element

A variable can be declared using the <var> element, and may be modified or reset by other elements within the dialog. For example, the pizza.vxml file main body begins with several declarations of variables:

<var name="PromptPath" expr="'../prompts/'"/>

<var name="PizzaSize" expr="null"/>

<var name="PizzaToppings" expr="null"/>

<var name="PhoneNumber" expr="null"/>

<var name="DeliveryTime" expr="null"/>

Since they are declared in the root document of the application, these variables have an application scope: that is, they can be used throughout the application.

Declared variables are often used to carry values forward to another part of the application once a form is exited. For example, the GetPizzaSize.vxml file collects a value for the pizza size in the size field. However, since the size variable is not available outside the form (see Variable scope above), we assign the collected size to the PizzaSize variable so it can be used in other parts of the application:

<form id="GetPizzaSize">

  <field name="size">

    <--! various prompts for different situations -->

    <grammar src="../grammars/pizza.grxml#Pizza_Size"/>

    <filled>

      <assign name="PizzaSize" expr="size"/>

      <goto next="GetPizzaToppings.vxml"/>

    </filled>

  </field>

</form>

Form item variables

A form element may contain several different form items, each or which creates variables by implication whenever they’re used. These variables have a form scope, and have the same name as the form item.

<field>—Creates a variable to store a recognition result
<record>—Creates a variable that stores digitized audio
<subdialog>—Creates a variable to store values returned by the subdialog
<transfer>—Creates a variable to store the outcome of the transfer

Note: The <initial> and <block> form items also create variables, but these do not store input from the caller. They only act as guard variables (see below).

In addition to storing information from the caller, form item variables act as guard variables. This means that elements within the item are not executed if the variable already has a value—the item is skipped.

Guard variables can be useful in a mixed-initiative dialog, where the caller’s initial reply may not supply all required information. In subsequent prompts the application can skip items that have already been filled, and only prompt for the information that is missing. Note that form item variables are automatically reset to undefined whenever the form containing them is entered.

Shadow variables

A shadow variable stores information about or associated with the value of an input item. For example, when NVP recognizes the reply to a field, it fills the field input variable with the value it recognized. However, NVP also assigns a confidence score to the value. This confidence score is stored in a shadow variable of the field input variable.

A shadow variable is referenced as variable$.shadow, where:

variable is the name of the input variable
shadow is the name of the shadow variable

For example, size$.confidence contains the confidence score assigned to a recognition for the size field in the GetPizzaSize form of GetPizzaSize.vxml. You could use this shadow variable to add a condition to the form, setting a minimum confidence score required in order to accept the recognition:

<form id="GetPizzaSize">

  <field name="size">

    <--! various prompts for different situations -->

    <grammar src="../grammars/pizza.grxml#Pizza_Size"/>

    <filled>

    <!-- Here is where we add the minimum condition -->

      <if cond="size$.confidence &lt; 0.5">

        <throw event="nomatch"/>

      </if>

      <else />

      <assign name="PizzaSize" expr="size"/>

      <goto next="GetPizzaToppings.vxml"/>

    </filled>

    </field>

</form>

For a full list of the shadow variables that NVP assigns to a recognition result, see Recognition results.

Variable value assignment

The initial value of a declared variable is usually assigned when it is declared by specifying a value for the expr attribute of the declaring <var> element:

<var name="PizzaSize" expr="null"/>

If no value is specified the variable is initialized to “null”, meaning undefined.

If a <var> element specifies a variable that is already in scope, it does not declare a new variable with the same name, but simply assigns a value to the existing variable. If the <var> element has an expr attribute, the variable is assigned the specified value. Otherwise, the variable is assigned the value undefined.

You can also set a declared variable’s value with the <assign> element. For example, GetPizzaSize.vxml assigns a value to the global PizzaSize variable when the appropriate grammar rule recognizes a response and assigns a size:

<filled>

  <assign name="PizzaSize" expr="size"/>

  <goto next="GetPizzaToppings.vxml"/>

</filled>

A form item variable is assigned a value when the item is filled with appropriate data—a recognition result (<field>), a recording (<record>), and so on.

Clearing variables

Declared variables can be reset to an undefined value using a <clear> element:

<clear namelist="variable1 variable2 variable3" />

This element also clears event and prompt counters for one or more form items. You can also use this element to set a variable that has been declared in ECMAScript to undefined.

Referring to variables

Since applications assign values to variables and pass them between documents, an application developer must refer to variables in a consistent manner. The method for referring to a given variable depends on its scope.

If variable x has a document scope, you may refer to it as either x or document.x (for clarity, or to resolve ambiguity). If the variable is declared in the root document, then you can refer to it as x or application.x.

You can refer to a variable x with dialog scope as either x or dialog.x.

If a variable x has an anonymous scope, you can refer to it as x within the field in which it appears. You cannot refer to it outside that field.

Variables in VoiceXML and ECMAScript

VoiceXML variables are equivalent to ECMAScript variables that appear in a <script> element—they are part of the same namespace.

This means VoiceXML variables can be used in a script, just as variables defined in a <script> element can be used in VoiceXML. Declaring a variable using a <var> element is equivalent to using a var statement in a <script> element.