Voxeo Developer’s Corner

When people come to CCXML from other languages, one concept that is sometimes difficult to understand is the whole notion of a “state machine”. Once you are comfortable with that idea, CCXML becomes rather easy to work with. While the Wikipedia page on state machines gets quite complex, let’s reduce the concept to some basics.

First, some vocabulary. In a “state machine”, there are a series of “states“, such as being “on” or “off”. There are then “events” that cause there to be a “transition” between states.

Now to illustrate this, let’s take the typical action hero film (such as any one of the James Bond movies) and describe it as a series of “states”:

1. Hero is relaxing on a beach with a drink in some exotic locale.

2. Hero is preparing for mission (getting briefing, gadgets, etc.)

3. Hero is hunting for evil villain.

4. Hero is fighting evil villain and his minions.

5. Hero is relaxing on a beach in some other exotic locale in the company of rescued beautiful woman.

There are obviously other “states” that occur in an action movie, many of which involve beds, but in an effort to: a) keep this blog “safe for work”; and b) keep our example simple, we’ll reduce it to this list. Graphically, we could depict this as something like:

The hero can remain in any one of these “states” indefinitely (and in some films it seems like the hero does!) until there is some event that triggers a “transition” between the states. Let’s look at our list again and add in some events:

1. Hero is relaxing on a beach with a drink in some exotic locale.

   • Receives visit from courier who says his assistance is needed immediately. (Alternatively and more exciting for a movie, a team of assassins attempts to kill him.)

2. Hero is preparing for mission (getting briefing, gadgets, etc.)

   • Receives final briefing, heads to airport, etc.

3. Hero is hunting for evil villain.

   • Finds evil villain (or is found by evil villain).

4. Hero is fighting evil villain and his minions.

   • Blows up villain and his lair, saves world, rescues beautiful woman.

5. Hero is relaxing on a beach in some other exotic locale in the company of rescued beautiful woman.

At a 10,000 foot level, you can describe most action movies in this pattern. A series of states where events trigger transitions between those states.

So what does this have to do with CCXML, eh?

Well, you could take the basic successful inbound call to a CCXML application and describe it in the following states and events:

1. CCXML application is waiting for connections.

   • Call is received.

2. Application enters “Alerting” state to decide what to do with the call.

   • Application accepts call.

3. Application is connected to incoming call and performs actions such as playing dialogs, accepting input, etc..

   • Application finishes - or caller hangs up.

4. Application is disconnected from call and performs any final actions.

   • Application finishes post-call activity and exits.

5. Application returns to waiting for connections.

Graphically, we could illustrate it like this:

Conceptually, this is what it looks like. I would, though, note, that the “waiting” state I’ve shown here is not typically a part of the actual CCXML application but rather is part of the application platform on which your CCXML application is housed. For instance, the “platform” could be our Evolution hosted platform or a copy of our Prophecy premise platform running on your network. When a call is received by either Evolution or Prophecy, your CCXML application is loaded and (in this example) the “connection.alerting” event is sent which triggers the transition into the “Alerting” state.

You can think of this in a similar fashion to a web server. Your Apache (or other) web server is sitting there waiting for connections. When it receives a connection, it loads the appropriate page which may contain an application which is then executed. CCXML works in a similar fashion (and yes, there are exceptions… remember, I’m trying to keep this tutorial simple!).

In any event, let’s see what this looks like in CCXML code:

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
  <eventprocessor>
    <transition event=”connection.alerting”>
    <log expr=”‘*** Incoming call from Caller ID: ‘ + event$.connection.remote”/>
    <accept/>
    </transition>
    <transition event=”connection.connected”>
      <log expr=”‘*** Call was accepted ***’”/>
      <disconnect/>
    </transition>
    <transition event=”connection.disconnected”>
      <log expr=”‘*** Call was disconnected ***’”/>
      <exit/>
    </transition>
  </eventprocessor>
</ccxml>

That’s it. The <transition> tag indicates what actions should be taken when the event included in the “event” attribute occurs. Conceptually this is a transition between states. So when the event “connection.alerting” is received by this application the code in the first <transition> is executed. At the end of that block you can see the <accept/> command which is the action that causes a new event (”connection.connected“) to occur. Likewise, <disconnect/> and <exit/> in later states signal that a new event has occurred and a transition needs to occur.

Your task, then, is to write the actions that occur in each state since this code above does really nothing except accept and then hangup a call (and generate log entries). During the “alerting” state, for instance, maybe there are some phone numbers from which you do not want to accept calls. You may have some conditional logic there that rejects calls from some numbers and then accepts calls from all others. In the “connected” state, obviously, is where the meat of your application goes. What are you going to do with the caller?

With this framework in mind, you can now dive into the “Learning CCXML” section of our CCXML documentation and see the examples there that flesh out the very simple outline I’ve given here.

I should note, of course, that my simple example doesn’t even closely illustrate all the “states” in CCXML. What happens if a call fails in some way other than just a disconnect? What if there are errors in your application? How about outbound calls where the “alerting” concept doesn’t make sense? We go into the different states in our documentation and the actual CCXML specification from the W3C also has this nice diagram (click on the image to see it larger):

(Hint: For an outbound call, the initial state equivalent to “alerting” is “progressing“.) This, too, does not show all the states, but does provide a richer view of the flow of a typical CCXML application. As you’ll see in the documentation, there’s a lot more you can do with states in CCXML. You can create your own events that you us the <send> command to trigger a transition to a new state. There are a range of pre-defined states as well, that both our documentation and the W3C CCXML specification describe in more detail.

Again, it is all about the CCXML application describing a series of “states” and what actions occur during that state. Events trigger transitions between states.

Got it? Ready to start actually building applications? If so just head over to www.voxeo.com/free and sign up for either a free developer account on our Evolution hosted platform or download our free Prophecy premise platform to run on your own server. Figure out your states and away you go…

P.S. If you are really intrigued by all the theory around state machines, you might want to check out the “Semantics” section of another W3C draft language called SCXML (”State Chart XML”) which dives into the theory around Harel State Tables and much more. The aim of the (draft) SCXML effort is to create a more generic state machine language which is not tied to telephony as CCXML is. If all you want to do is write voice applications, feel free to skip these links entirely!

Technorati Tags: applications, state machines, ccxml, scxml, w3c, voxeo, programming, xml, voip, voice, voice mashups, phone mashups

Tags: CCXML

You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.