VoiceXML Review - Columns

Volume 3, Issue 3 - May/June 2003

VoiceXML Events

By Rob Marchand

Welcome to "First Words" - the VoiceXML Review's column to teach you about VoiceXML and how you can use it. We hope you enjoy the lesson.

Don't forget to have a look at the VoiceXML Candidate Recommendation, published earlier this year:

http://www.w3.org/TR/voicexml20/

Be sure to have a look at it, as this provides the benchmark for implementation of a VoiceXML Interpreter, and is your reference for developing portable applications in VoiceXML. Changes between now and the time that VoiceXML 2.0 is published as a full Recommendation should will be minor.

And now, back to the task at hand….

Event Propagation

Overview

This issue, we're going to talk a little bit about how events are propagated in a VoiceXML application. It is important to understand how this works so that you can include error handling at the appropriate places in your VoiceXML pages.

We have talked about events in some detail in two previous columns:

http://www.voicexmlreview.org/Aug2002/columns/Aug2002_first_words.html
http://www.voicexmlreview.org/Oct2002/columns/Oct2002_first_words.html

You may recall that events can be thrown by the platform in response to a number of conditions. These might indicate an error condition (for example, a document is not available), or indicate some problem in the interaction with the caller (they have not spoken at all, or we have not been successful in recognizing what they've said).

Events are caught by catch elements placed at strategic places within your application. Where you place these will depend on how you structure your application - but it is critical that your application be prepared to deal with unexpected events, and to deal with them in a reasonable way.

Selection of <catch> Elements

Catch elements (<catch>) can be placed at appropriate places within the application. Understanding how these are selected is the subject of this particular column.

The first thing to understand is that <catch> elements are scoped according to the standard VoiceXML hierarchy rules. So event handlers can be declared (in increasingly narrow scope):

Interpreter defaults;

In the application root document;

At the document level;

At the dialog level;

Within input items;

More general handlers can be declared at the higher scopes, and those that are more specific can be tied to the particular dialog or input items to which they are most applicable. The 'most-specific' handler will be selected (see the algorithm below), and executed in response to an event.

It is important to recall that catch elements are inherited "as if by copy". What exactly does this mean? Primarily, it defines how the various components of the catch handler are 'resolved'. From the VoiceXML specification:

The "as if by copy" semantics for inheriting catch elements implies that when a catch element is executed, variables are resolved and thrown events are handled relative to the scope where the original event originated, not relative to the scope that contains the catch element. For example, consider a catch element that is defined at document scope handling an event that originated in a within the document. In such a catch element variable references are resolved relative to the 's scope, and if an event is thrown by the catch element it is handled relative to the . Similarly, relative URI references in a catch element are resolved against the active document and not relative to the document in which they were declared. Finally, properties are resolved relative to the element where the event originated. For example, a prompt element defined as part of a document level catch would use the innermost property value of the active form item to resolve its timeout attribute if no value is explicitly specified.

Or, basically, the behavior is as if you had physically copied the right event handler into the scope where the event was thrown.

Selection of the right handler is very explicitly defined in the VoiceXML specification:

Form an ordered list of catches consisting of all catches in the current scope and all enclosing scopes (form item, form, document, application root document, interpreter context), ordered first by scope (starting with the current scope), and then within each scope by document order.

Remove from this list all catches whose event name does not match the event being thrown or whose cond evaluates to false after conversion to boolean.

Find the "correct count": the highest count among the catch elements still on the list less than or equal to the current count value.

Select the first element in the list with the "correct count".

This algorithm describes how to select events using VoiceXML scoping rules, including dealing with multiple handlers in the same scope, using event counts to select particular handlers, and so on. There are, however, some other things to be aware in terms of how events are propagated within an application.

Things to Watch Out For

Make sure you understand the catch element description algorithm above, in particular how names are selected, and how event counts work, if you are using them. - This will avoid surprises in your application error handling;
Remember - Semantic errors in a page that is being fetched will be thrown in the context of the document doing the fetching. So if a target page has a 'compile-time' error that can be detected, it will show up the page that is trying to fetch it. These errors include HTTP fetch errors, poorly formed XML documents, and so on.
Events thrown in a subdialog won't be passed to the calling document unless you explicitly 'return' an event in the subdialog <return> tag using the 'event' attribute. This is often a surprise to new developers.
Errors that occur after entering the Form Initialization Algorithm (FIA) initialization phase (i.e. the target document is executing), such as semantic errors, are raised in the new document, and will be handled by event handlers as selected in that scope;
Errors that occur after loading and before entering the initialization phase of FIA are handled in a platform-specific manner;
The handling of errors encountered during the loading of the first document in a session is platform-specific.

For the last two, you should consult your platform provider to determine the behavior of event propagation in these circumstances.

Summary

This time around, we've discussed how events are propagated in VoiceXML applications. Next column, we'll look at some specific examples to support this information. If there is a VoiceXML topic you'd like me to cover in a feature topic in the First Words column, drop us a line at editor@voicexmlreview.org.

back to the top