Variable

Overview

The Variable object provides the concept of a non-typed variable as in other standard programming or scripting languages to control the dialog context as well as the business logic of an application.

The Variable object can be used within almost any other object to control certain object properties or processing conditions dynamically at call time. It is also used to present to the caller dynamic application content as part of an Output object. Therefore the Variable object provides the capability to define an output format using either text-to-speech (TTS) processing (e.g. to say the value as a phone number) or alternatively text-to-audio (TTA) processing (e.g. to read back the phone number digit by digit via prerecorded audio resources).

The scope of a Variable object is global to the dialog context of each individual call. A Variable object will be initialized according to its initial value declaration the first time it is used in the dialog flow. By default the initial value is empty (empty string) which is equivalent to NULL. A Variable object containing an empty string can be tested with the Expression function ISNULL ( ), which will return true, or ISNOTNULL ( ), which will return false, respectively. In a Boolean context the Variable object evaluates to true unless its value is an empty string, 0 (zero), or FALSE (in any combination of upper and lower case letters).

A Variable object can also be initialized via the initial URL of the media platform which starts a dialog for the corresponding service. This can be achieved by adding a variable parameter to the URL string with an ampersand sign (&). This parameter is constructed with the prefix var followed by the reference ID of the Variable object. Finally the value is added with an equal sign (=).

...&varVariableID=value

The following example shows a complete URL initializing the caller status variable with the reference ID Status to the value gold:

http://MyServer/VoiceObjects/DialogMapping?VSN=MyService&varStatus=gold

It is possible to initialize multiple variables at the same time as outlined below:

http://MyServer/VoiceObjects/DialogMapping?VSN=MyService&varStatus=gold&
varName=Jeff

The Object Definition below covers the configuration of the Variable object with VoiceObjects Desktop. For information on how to define this object type using VoiceObjectsXML refer to the VoiceObjectsXML Definition paragraph.

The Variable object belongs to the object category Logic.

Dialog Flow Scenario

The following short dialog flow example as part of a flight information service demonstrates an Output object containing some text and two Variable objects with the terminal and gate information. The variables are played back with text-to-speech (TTS) processing.

Object		Dialog Flow
	Text	Your flight will leave on time at terminal:
		C
	Text	gate:
		73

The next dialog flow demonstrates the same scenario as above but using prerecorded audio resources. The Variable objects are played back with text-to-audio (TTA) processing.

Object		Dialog Flow
		Your flight will leave on time at terminal:
		[ c.wav ] C
		gate:
		[ 73.wav ] seventy three

Object Definition

The Definition of the Variable object provides the following sections:

· Declaration
To declare the initial value and reference ID.

· Formatting
To define formatting instructions for playback within an Output.

For information regarding the Properties section, refer to Properties in this Object Reference.

Declaration

The Declaration section provides the Initial Value and the Reference ID field (which is also available in Properties).

The Initial Value can be provided as a constant or can be dynamically initialized at call time from the value of other Variable objects, Expression, Layer, or Script objects. The initial value of the Variable object is evaluated when the Variable object is first used within the dialog flow at call time.

You can use the system functions INIT() and REFRESH() to initialize a variable to the initial value again at a later point in the dialog. REFRESH() re-evaluates the initial value in the current dialog context, whereas INIT() resets the variable to the value it got when it was first initialized. For static initial values, both functions have the same effect.

8 Caution: Make sure that the Variable object itself is not part of its own initial value definition (e.g. by being part of the parameter set passed to the Script object that computes the initial value), as this will lead to infinite loops.

The Reference ID can be used to identify and reference a Variable object outside of the VoiceObjects Server framework, e.g. when using the Variable object in conjunction with a Java connector or a VoiceXML plug-in. In these cases, the automatically generated reference ID should be replaced by a more readable name.

Note that the reference ID may not contain blanks or other special characters except hyphens and underscores. It is not case sensitive and limited to 40 characters. No two objects within one project may have the same reference ID.

In addition to the actual value a Variable object can hold a pronunciation value, which can be set by a grammar during speech recognition in the voice or video channel. This value can be retrieved during call time using the PRONUNCIATION function through the Expression object. For more information on associating pronunciation patterns with a Variable object, refer to Input in this Object Reference.

Formatting

The Formatting section defines how the content of the Variable object is presented to the caller when it is used within an Output object.

Two different categories of formatting types are offered, which are only relevant for the voice and video channel:

· Text-To-Audio (TTA)
The object content is played back to the caller via the concatenation of prerecorded audio files.

· Text-To-Speech (TTS)
The object content is played back to the caller via text-to-speech synthesis provided by the media platform.

The formatting instructions can be defined as an embedded definition as part of the Variable object, or can be linked to an autonomous Format object.

To define formatting types for the text and Web channel, use the Formatting bus as described in Appendix B – How to Use the Formatting Bus in the Administration Guide.

For further details on formatting capabilities refer to the Format object in this Object Reference.

VoiceObjectsXML Definition

The Variable object is represented by the VoiceObjectsXML element <variable>. It has one attribute and two children.

In addition, the element has the standard attributes described in the XDK Guide.

8 Caution: The name attribute is required for Variable objects.

The <variable> element uses the embedded <value> element.

Variable

Attributes

· initial
Reference to an Expression, Script, or Variable object defining the initial value of the variable.

Children

· <value>
Optionally defines the constant initial value of the Variable object.

· <format>
Defines the output formatting for the Variable object.

Example

Value

Children

· CDATA
Embedded value.

Example

Object Interoperability

The Variable object is compatible with any other object type and can be used to dynamically control certain properties or preconditions. The following objects reference Variable objects most frequently:

Icon	Object Name	Use Case Example
	Input	A Variable object can be used to store a recognition result.
	Output	A Variable object can be used for the playback of the variable value to the caller.
	List	A Variable object can be used to store the list selection result.
	Grammar	A Variable object can be used to assign a dynamically generated grammar definition to a Grammar object.
	Connector	A Variable object can be used within the parameter set of a Connector object when connecting to an external resource.
	Database	A Variable object can be used in the SQL statement definition of a Database object.
	Script	A Variable object can be used within the parameter set when processing any business logic using a Script object.
	Plug-In	A Variable object can be used within the parameter set when processing a resource of a Plug-In object.
	Log	A Variable object can be used within the log statement definition of a Log object.
	Expression	An Expression object can be used to assign a new value to a Variable object or to use a variable as an argument.
	Goto	A Variable object can specify the reference ID of the destination object within the Goto object.
	OSDM	A Variable object can be linked within the parameter set of any OSDM object
Any object with a layer or precondition		A Variable object can be used anywhere as a layer or precondition.

Object Naming Conventions

In order to leverage the capabilities of the integrated documentation of VoiceObjects it is important to provide intuitive and self-explanatory object names and descriptions.

The name of a Variable object should be as short as possible and at the same time precise enough that other users will know immediately what the variable is used for. The short description of a Variable object should provide additional information about the format of the content (e.g. number, text, date, time or Boolean values), the expected or valid value domain and finally something about the initial value (if available). If multiple variables are used regarding the same context they should start with the same prefix (e.g. Customer ID, Customer Name, Customer ZIP, etc.).

The table below lists a few examples as a general guideline:

Name	Description
Phone Number	Ten-digit telephone number.
Customer ID	Alphanumerical 40 character ID of the customer. The initial value is set to N/A.
Customer Name	Title, first and last name of the customer (e.g. Mr. George Hill).
Caller Status	Status of the caller which is defined as silver, gold or platinum; otherwise unknown.
Frequent Flyer	Contains the value true if the caller is a frequent flyer otherwise false which is the default value.
Arrival Date	Flight arrival date in the format YYYYMMDD.
Reservation Time	Time designation in the format HH:MM (hours:minutes). Valid values for HH are: 18 to 22. The only valid value for MM is 30.
Shopping Cart Balance	Actual balance of the shopping cart as decimal currency amount with a leading $ symbol. The initial value is set to $0.00.