CCXML Voxeo 1.0 Development Guide

| TOC

This documentation is for CCXML 1.0-Voxeo, which has been superceded by CCXML 1.0-W3C. The CCXML-Voxeo platform is not being updated any longer. The CCXML 1.0-W3C version, however, has many new features and is actively being enhanced. If you're writing a new CCXML application, you should use CCXML 1.0-W3C. Click here for the CCXML 1.0-W3C documentation.

Tutorial: Error Handling

This Lesson will explore Voxeo's implementation of error handling, which is not adequately described by the W3C specification for CCXML; nevertheless, this tutorial builds on knowledge learned from tutorials one, two, and three. If you have not gone through those tutorials, now would be an outstanding time.

In this Lesson, we will:

Learn how to write CCXML code that tosses errors
Learn how to safely trap those errors

Step 1: creating our initial CCXML structure

From our previous episodes, we now recognize the following structure as a normal starting point:


<?xml version="1.0" encoding="UTF-8"?>
<!-- NOTE THAT WE *MUST* DECLARE THE xmlns ATTRIBUTE --> 
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml"> 
</ccxml>

Step 2: wicked, wicked errors

First of all, let's answer the phone, shall we?


  <eventhandler>
    <transition event="connection.CONNECTION_ALERTING">
      <accept/>      
    </transition>
  </eventhandler>

Everything looks in order so far. But what happens if we issue another <accept> command?


  <eventhandler>
    <transition event="connection.CONNECTION_ALERTING">
      <accept/>      
    </transition>

    <transition event="connection.CONNECTION_CONNECTED">
      <accept/>      
      <log expr="'second answer invoked, awaiting error event ...'"/>
    </transition>
  </eventhandler>

So what happens? This kind of haphazard tomfoolery leads to a new event type. Voxeo has defined all error events with the object prefix "error.". In this case the event "error.statemismatch" will be posted as a result of trying to invoke an action on a call which cannot be executed at that time. As always, this error is not immediately recognized -- it will be fired asynchronously.

Step 3: making matters worse

Tossing only one asynchronous error is exciting in the same way mountain biking Kansas quickens the pulse. The bold would try something more challenging -- let's toss two asynchronous errors (just like that, we are biking Missouri).


  <eventhandler>
    <transition event="call.CALL_ACTIVE">
      <log expr="'making a document mistake now ...'"/>
      <log expr="'and the temperature is ' + below.zero"/>
    </transition>	
  </eventhandler>

Writing bad code is easy! Our second <log> tag is referencing a non-existant object ("below.zero"), thus tossing a second error. The astute cyclist may notice that we are using the "CALL_ACTIVE" event in this transition -- this event actually fires in parallel with the "connection.CONNECTION_CONNECTED" event. Which ones fires first? It doesn't matter, because our asynchronous state machine handles it all.

Step 4: two error handlers

We don't have an error. We have freaking errors. Plural.


  <eventhandler>
    <transition event="call.CALL_INVALID">
      <exit/>
    </transition>
  </eventhandler>

This is our classic safety net, properly cleaning up the application if the call is ever lost. It is included here for completeness, but is not technically an "error handler."


  <eventhandler>
    <transition event="error.statemismatch" name="evt">
      <log expr="'state mismatch detected (' + evt.error + ')'"/>
    </transition>	
  </eventhandler>

Our first error handler is seriously cool. Normally, an application suffering this style error would be forced to take evasive action (or even an outright bail) -- after all, a mismatch in the call state is a serious problem. But for now, we just fire off a simple debug line.

Of special note is that Voxeo's implementation of CCXML will not allow any errors to be tossed in an error handling <transition> block. Such a scenario could easily cause infinite loops to occur. Instead, an error generated inside an error handler will force the session to be terminated automatically.


  <eventhandler>
    <transition event="error.*" name="evt">
      <log expr="'an error has occured (' + evt.error + ')'"/>
    </transition>	
  </eventhandler>

Our second error handler is gonzo. Using the wildcard feature of CCXML, we have a generic, universal transition to catch all error events (of course, because it occurs after the more specific "error.statemismatch" handler, this transition will not inadvertently catch our first error). The message delivered to the logger would be for the event "error.document", which we provoked above.

Step 5: the complete script

One good bunny-hop and our trail is complete.


<?xml version="1.0" encoding="UTF-8"?>
<!-- NOTE THAT WE *MUST* DECLARE THE xmlns ATTRIBUTE -->
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml">
  <eventhandler>
    <transition event="connection.CONNECTION_ALERTING">
      <accept/>
    </transition>

    <transition event="connection.CONNECTION_CONNECTED">
      <accept/>
      <log expr="'second answer invoked, awaiting error event ...'"/>
    </transition>

    <transition event="call.CALL_ACTIVE">
      <log expr="'making a document mistake now ...'"/>
      <log expr="'and the temperature is ' + below.zero"/>
    </transition>

    <transition event="call.CALL_INVALID">
        <voxeo:sendemail to="'yourEmail@there.com'"
                        from="'myApp@here.com'"
                        type="'debug'"
                        body=" ' call.CALL_INVALID detected!' "/>
      <exit/>
    </transition>

    <transition event="error.statemismatch" name="evt">
      <log expr="'state mismatch detected (' + evt.error + ')'"/>
            <voxeo:sendemail to="'yourEmail@there.com'"
                        from="'myApp@here.com'"
                        type="'debug'"
                        body=" ' error.statemismatch detected !' "/>
    </transition>

    <transition event="error.*" name="evt">
      <log expr="'an error has occured (' + evt.error + ')'"/>
            <voxeo:sendemail to="'yourEmail@there.com'"
                        from="'myApp@here.com'"
                        type="'debug'"
                        body=" ' generic error detected !' "/>
    </transition>
  </eventhandler>
</ccxml>

Download the CCXML source code!

What we covered:

Successfully trapped CCXML errors

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

Intro to Error Handling

| TOC

| Intro to Dialogs and CCXML