VoiceXML Events

By Rob Marchand

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.

VoiceXML Events

This month, we're going to have a closer look at events in VoiceXML. Over these many months, we've seen something about how events work, and how you can use them. In this column, we're going to gather all that information together, and fill in the gaps. In the next article, we'll provide some details examples of how you can use events in your application.

All About Events

Events are a powerful and important part of VoiceXML, and understanding how they work, and how to use them wisely will improve your VoiceXML development.

In many regards, VoiceXML events are similar to events or exceptions in other languages. They provide a way to generate and handle behavior related to normal or exceptional application execution.

VoiceXML events allow your application to deal with many different conditions, for example:

• Dealing with missing or unintelligible user input;
• Handling platform or system problems;
• Recovering from application or web server problems;
• Processing both normal and exceptional conditions that occur as part of application processing;

VoiceXML supports several different types of events:

• Predefined events;
• Application events;
• Platform-specific events.

Events have associated counters. Each time an event is thrown, the event counters for that event, and for any 'parent' events, are incremented. For example, if error.badfetch is thrown, the counters for both error.badfetch and error are incremented. Each form, menu, and form item maintains counters for each event within their scope.

Events are named, using a string made up of components separated by periods. The structure is used for selection of event handlers. Events also have associated messages. When processing an event, you can access the name and message using the ECMAScript variables '_event' and '_message'. The next section has some discussion about the use of these variables.

Generating An Event

Events are generated either implicitly by the VoiceXML platform, or explicitly by the application. In either case, they are effectively thrown when the Form Interpretation Algorithm reaches the 'process' phase of the FIA.

There are many events that can be thrown by the platform. These include those related to collection of user input (<noinput>, etc.) and those generated in response to some kind of error. For example error.semantic will be generated if an illegal condition if found while processing a page.

When processing normal VoiceXML elements (such as <transfer>), it is possible for events such as 'connection.transfer.disconnect' to be generated. These will indicate conditions or errors encountered while processing the element.

The application can also generate events if necessary. For example, you can use the <throw> element to generate an application event. The <throw> element accepts the following attributes:

• event - the event to be thrown;
• eventexpr - an ECMAScript expression returning the event to be thrown;
• message - the message to pass as part of the event object;
•  messagexpr - an ECMAScript expression returning the message to pass as part of the event object;

Note that only one of event or eventexpr can be specified, and only one of message or messagexpr can be specified; otherwise an error.badfetch will be thrown.

 Catching An Event

 A <catch> element defines some VoiceXML executable content to be processed when a matching event is found. The <catch> element accepts the following attributes:

• event - the event or event family to be caught;
• count - the minimum event counter to which this catch will apply;
• cond - a guard condition for this event handler.

While processing within the event handler, you can access information about the event using the ECMAScript variables _message and _event. These are useful for controlling processing or logging information.

Event handlers are inherited through the various VoiceXML scopes as if by copy. This means that they will run as if you cut and paste them into the scope where the event was thrown. So, for example, you can define <catch> blocks in your application root document, and have them do sensible things based upon where they are invoked.

The event handlers are selected as candidates based on their name, either by an exact match, a prefix match (based on the event name components, not arbitrary substrings), or with the 'catch-all' handler (which specifies an empty event name, or just '.').

Once an event has been 'thrown' the VoiceXML Interpreter will search for a suitable catch handler. The 'best qualified' handler is selected as follows:

1. A list of <catch> handlers (including those named with shorthand, such as <noinput>) is constructed. This list is ordered by scope, from the innermost (where the event has been thrown), to the outermost (the application root document); those within the same scope are added to the list in document order;
2. Any which don't match the event, or which have a condition attribute which evaluates to false, are discarded;
3. The list is searched for those with the highest count attribute which doesn't exceed the current count value for this event; others are discarded;
4. The first element of this list is selected to handle the event;

The first event to be selected at a given level will be executed; no others from the list will be executed for this event.

VoiceXML provides some shorthand elements for commonly used event handlers:

• <cancel>
• <error>
• <help>
• <noinput>
• <nomatch>

These behave in exactly the same way as would, for example, <catch event="help">, etc.

Once the event handler has completed, processing will continue in the current dialog as dictated by the FIA, unless the event handler has initiated a transfer to another document or dialog.

Predefined Events

VoiceXML predefines many events. The table below shows some of these.

We'll talk more about these next month.

The VoiceXML Specification does not specify what the audio should be for those events that generate audio, so this will likely be different between platforms. In any case, most applications will override these handlers such that they meet their application or platform requirements. Similarly, the default action will likely be overridden as well.

Application Defined Events

You can define and use your own events to make your application development and execution more effective. It is a good idea to think about the naming convention that you will use, to allow effective use of event handlers.

Application defined events behave in exactly the same way as other events discussed in this article.

Things to Worry About

Well, these aren't really things to worry about, but things to keep in mind when you make use of events in your applications.

• You can throw system defined events if you want to;
• You can't 'rethrow' events. If you throw the same event you've just caught, you will generate either a semantic error or worse, an infinite loop;
• Your platform may provide further information about standard VoiceXML or platform-specific events as part of the _message variable (available in the anonymous scope of the <catch> element);
• Expressions and URIs within <catch> handlers, or <link> elements which specify an event, are evaluated within the scope where the event was generated. Beware, however, as this behaviour is still being specified by the Voice Browser Working Group.
• <catch> blocks are searched in document order. VoiceXML does not specify that the 'best match' will be selected (e.g., error.http over error, when they are both at in the same scope), so you should order handlers from most specific to least specific within the same scope;
• It is okay to define your own events as 'subevents' of system-defined events if it is appropriate, but make sure that they make use of the full prefix of the system event, so that handlers catching the pre-defined events will also catch your new ones;
• How your application deals with exceptional occurrences and events is an important part of your application. Think about how you will do this early in your design process.

Summary

Events are an integral part of VoiceXML, and provide a useful mechanism to handle exceptional conditions as well as application events. However, there are some fundamentals that you should understand to make the most effective use of the capabilities they provide. Once you do, you'll find them a useful addition to your toolbox for VoiceXML application development.

What's Next?

Well, we've covered events in some detail, but to finish this off, next month we'll provide some well-annotated practical examples for you to try.

back to the top

Copyright © 2001-2002 VoiceXML Forum. All rights reserved.
The VoiceXML Forum is a program of the
IEEE Industry Standards and Technology Organization (IEEE-ISTO).