Welcome to First Words, VoiceXML Review's column that teaches you about VoiceXML and how you can use it. We hope you enjoy the lesson.
This month, we're going to take a wider ranging look at shadow variables and their role in VoiceXML. Over the past year, we've touched on them in various places, but we'll talk about them in a bit more detail in this column.
VoiceXML Voice User Interfaces (VUIs) consist of a set of form items declared within a VoiceXML document. Processing of these form items is driven by execution of the Form Interpretation Algorithm. When a form input item is visited and processed, we are usually primarily interested in the value that the input item receives. However, along with the assignment of a value to the input item, VoiceXML may create an associated shadow variable, which will typically have a number of associated properties.
Shadow variables are created as conventional ECMAScript variables within the VoiceXML context, and have the same scope and behavior as their less shadowy counterparts. You may occasionally hear or see a shadow variable property (such as name$.confidence) referred to as a separate shadow variable, but it is really an ECMAScript property of the name$ shadow variable.
A shadow variable is referenced as name$.shadowvar, where name is the value of the input item's name attribute, and shadowvar is the name of a specific shadow variable.
Any input item can have an associated shadow variable. Shadow variables provide a way to retrieve further information regarding the value of an input item. They are created and set as the result of an attempt to collect input. Shadow variables are usually set as a result of a successful input collection. However, there are some exceptions to this, which are useful when you want to design a more effective VUI.
You can write perfectly useful VoiceXML applications without making use of shadow variables. However, they can provide useful additional functionality, and also the support information you need to provide a better user experience, or to improve the user experience over time.
Now we'll take a look at each of the input items that provide shadow variables. We'll also provide some suggestions as to where you might find them useful. The following VoiceXML form input items currently make use of shadow variables:
Field
Record
Transfer
The following VoiceXML form input items currently not make use of shadow variables:
Subdialog
Object
We will discuss only those shadow variables that are part of VoiceXML 2.0 at the time of this writing (the April 23rd, Working Draft). However, your VoiceXML platform may provide additional shadow variables that provide access to interesting bits of information. Be aware that use of these may render your application non-portable. If you have a shadow variable that you think you can’t live without, then you should consider submitting a change request to the Voice Browser Working Group of the W3C.
Each form input item collection will update the values of the shadow variables, so keep this in mind in your application. Note that for a field called (for example) "credit_card", the related shadow variables will be "credit_card$.confidence", "credit_card$.utterance", and so on. In the tables below, we use 'name' as the generic form input item name.
Field
When the caller successfully fills a field input item, the following shadow variable properties will be assigned.
Shadow Variable
Contents
Typical Uses
name$.confidence
Recognition confidence, between 0 and 1.0
Useful for deciding whether a confirmation is necessary.
name$.utterance
The 'raw' result that was matched in the grammar (the phrase spoken by the caller).
Useful for logging and testing grammars, as well as tuning.
name$.inputmode
How the field was filled: 'dtmf' or ‘speech’.
If the caller used DTMF, and took several tries, it may indicated a noisy environment, and that they should continue to be hear prompts regarding DTMF.
name$.interpretation
The 'interpreted' results; that is, after semantic processing by the ASR and/or interpreter. (the meaning of the caller input)
By mapping many similar commands to a common interpretation, the VUI and post-processing is greatly eased.
In the case where you are using
Record
The record form input item will provide a number of interesting shadow variable properties, primarily useful for determining the result of the recording attempt.
Shadow Variable
Contents
Typical Uses
name$.duration
Duration of the recording in milliseconds
Logging the length of the recording; perhaps generating other application information.
name$.size
Size of the recording in bytes
Logging the length of the recording, perhaps checking for sufficient server-side storage space.
name$.termchar
If the 'dtmfterm' property is true for this recording, and the user has terminated the recording with a DTMF keypress, then this will contain the DTMF key entered. Otherwise undefined.
Taking action on the user-entered call termination. Perhaps a shortcut for future action.
name$.maxtime
'true' if the recording was terminated because the record tag 'maxtime' attribute was exceeded. Otherwise 'false'.
Determining whether the recording was successful, or whether the caller has exceeded a preset maximum. Can be used to select the next prompt to play.
name$.utterance
If the platform supports within , and the user input triggered the grammar, this will contain the raw phrase spoken by the caller that matched the grammar. Otherwise undefined.
Used to select the next phase of the user interaction; perhaps to indicate that the recording should be stored, or discarded.
name$.confidence
If the platform supports within , and the user triggered the grammar, this will contain the confidence score (0.0-1.0) from the recognition. Otherwise undefined.
As with other speech inputs, used to determine whether confirmation is required, etc.
