Introduction to CCXML, Part II

Tuesday Nov 5th 2002 by Jonathan Eisenzopf
Share:

In Part II of the Introduction to CCXML, we will become more familiar with the elements of the language and how they work together to create call control applications.

In case you missed it, you can still read the previous section of this article: Introduction to CCXML, Part I.

In Part II of the Introduction to CCXML, we will become more familiar with the elements of the language and how they work together to create call control applications.

CCXML Test Platform

To test my CCXML applications, I have been using the Voxeo Tech Preview platform, which includes CCXML support. Voxeo was the first company to support CCXML and is currently leading CCXML development. It also helps that RJ Auburn from Voxeo is Editor of the CCXML specification. You can sign up for a Voxeo Tech Preview account at http://techpreview.voxeo.com to start working with CCXML platforms. As of this writing, Telera had also developed CCXML support, and it will be available for testing on its developer site in short order according to Srinivas Penumaka, Product Manager for Telera's DeVXchange.

Note: CCXML is still in a draft stage. The specification will change. Also, the CCXML examples that you'll see in this series are tuned for Voxeo and may not work with another provider's implementation even though it conforms to the specification.

Basic CCXML elements

The root element, <ccxml>

Each CCXML application has a <ccxml> root element that encapsulates the rest of the CCXML tags. It has one attribute, version, which is required and whose value should be 1.0:

ex. <ccxml version="1.0">

Exiting a CCXML application with <exit>

By calling the <exit> element, the CCXML application stops executing, discards all pending events and throws a ccxml.exit event. If the CCXML application was started by another CCXML application via the <createccxml> element, then the calling application can catch this exit event, the return value of the expr attribute and the values of the namelist attribute.

ex. <exit expr="0" namelist="state0"/>

Spawing a new CCXML application with <createccxml>

The <createccxml> element contains only one attribute, src, which specifies the URL of the CCXML application to execute. Because CCXML interpreters are non-blocking, both CCXML applications will continue to execute at the same time. The called CCXML application can return values with the <exit> element described above.

ex. <createccxml src="notification.ccxml/>

Queuing a CCXML application with <fetch>

In a multi-document CCXML application where callers may be transitioned from one CCXML document to another, it's a good idea.

ex. <fetch next="conference.ccxml"/>

Once a CCXML document has been loaded, it will throw a ccxml.fetch.done event, which can be caught with a <transition> element. The <fetch> element is usually used in conjunction with the <goto> element, which transitions a user to another CCXML application.

Handling Events

<eventhandler>

When an event is triggered, the CCXML interpreter examines the <transition> handlers to see if there is a matching trigger for the event. The <eventhandler> element contains one or more <transition> elements. The element can contain two optional attributes:

  • id - the name of the eventhandler
  • statevariable - each <eventhandler> can be assigned a state variable that tracks the current state of a call. State variables will be covered later in the CCXML series.
ex. <eventhandler id="default" 
                  statevariable="state0">

It is unclear which events must be handled, so I would recommend creating <transition> handlers for all event triggers listed in Part I.

<transition>

Each <transition> element contains the code that will be executed if the event attribute matches the current event that is being processed. For example, the following transition element will match the connection.CONNECTION_ALERTING event when a caller dials up the CCXML application. From the caller's perspective, this state is when the phone is ringing and waiting to be answered:

ex. <transition 
            event="connection.CONNECTION_ALERTING" 
            name="evt">

The <transition> element contains the following attributes:

  • state - optional; used when you want to control which event handler is triggered based on the current state in addition to the event.
  • event - required; one of the events defined in the list in Part I of the CCXML tutorial.
  • cond - optional; contains an ECMAScript expression that must evaluate as true for the handler to be executed.
  • name - optional; defines a local variable name that can be referred to within the <transition> element to access and set attributes of the call object.

The state, event, and cond attributes all define the criteria that must be matched for the <transition> element to be executed. This provides programmers with the ability to create fine grained handlers based upon state variable, call states and call conditions.

The <transition> elements will contain the majority of the call control code. Below is a list of CCXML elements that can be included within a <transition> element:

  • <accept> - answers a call
  • <createcall> - places an outbound call
  • <join> - conferences two call legs
  • <unjoin> - disconnects a two leg conference
  • <createconference> - joins multiple call legs together
  • <destroyconference> - breaks down a conference call
  • <dialogstart> - executes a VoiceXML dialog
  • <dialogterminate> - terminates the execution of a VoiceXML dialog
  • <send> - triggers a defined event
  • <disconnect> - ends the call
  • <assign> - assigns a specified values to a CCXML variable
  • <var> - defines a new CCXML variable
  • <if> - conditional statement similar to VoiceXML
  • <fetch> - pre-fetches a CCXML application and queues it for execution
  • <goto> - transitions the call to another CCXML application
  • <submit> - submits CCXML variables to another CCXML application
  • <exit> - stops the CCXML application

These elements will be covered in detail later.

Basic Call Control

Accepting calls with <accept>

The <accept> element answers an incoming phone call and is usually called within a <transition> element, which is answering to the connection.CONNECTION_ALERTING event.

ex.
<transition event="connection.CONNECTION_ALERTING"
            name="evt">
  <accept callid="evt.callid"/>
</transition>

The <accept> element contains the callid attribute, which is optional, and specifies the call leg id that will be accepted. If the callid is not specified, it will default to the call leg id of the event that's being processed. Setting the callid attribute manually means that only a call with the specified id will be answered. It is unlikely that you will ever set this attribute manually. In the code snippet above, the callid attribute is set to the callid value of the evt call object, which is the call leg id of the object that is processing the connection.CONNECTION_ALERTING event. This is essentially the same as excluding the callid attribute.

Rejecting calls with <reject>

Of course, we don't always have to <accept> the call, we could have also rejected it based upon the caller's phone number or some other criteria by using the <reject> element. See the <if> element in the Conditional/Control Statements section below for an example.

Terminating a call with <disconnect>

The <disconnect> element does exactly what its name implies--it terminates a call. You can specify the call leg to terminate by specifying the call leg id in the callid attribute. The attribute is optional.

ex. <disconnect callid="evt.callid">

Making an outbound call with <createcall>

The <createcall> element dials the phone number or SIP address specified by the dest attribute. When the call is connected, a connection.CONNECTION_CONNECTED event is sent, which can be caught by a <transition> element. If the call cannot be connected, a connection.CONNECTION_FAILED event is sent.

ex. <createcall dest="'7035551212'"/>

Once an outbound call is connected, it's common to execute a VoiceXML dialog to interact with the caller. The code fragment below is an example of two <transition> elements; the first one places the call with <createcall>, the second one is executed when the call is connected and executes a VoiceXML dialog with the <dialogstart> element:

    <transition state="'init'" event="ccxml.loaded">
      <assign name="state0" expr="'dialing'"/>            
      <createcall dest="'7034769418'"/>
    </transition>

    <transition state="'dialing'" 
           event="connection.CONNECTION_CONNECTED">
      <assign name="state0" expr="'connected'"/>            
      <dialogstart src="'angie.vxml'"/>
    </transition>

Conditional/Control Statements

Controlling executing with <if>, <elseif>, <else>

In fact, you might remember an earlier VoiceXML tutorial where we controlled the dialog based upon the caller's phone number. So in conjunction with the CCXML <accept> and <reject> elements, we could replicate this functionality in CCXML:

<transition event="connection.CONNECTION_ALERTING" 
            name="evt">
  <if cond="evt.calledid == '7035551212'">
    <reject/>
  <else/>
    <accept/>
  </if>
</transition>

The code snippet above is based in part on a tutorial located at:

http://techpreview.voxeo.com

If the ECMAScript code in the event attribute is evaluated to true, then we reject the call; otherwise we accept it and pick up the line.

Transitioning to another CCXML application with <goto>

The <goto> element contains only one attribute, next, which contains the URL of the CCXML application that the caller will be transitioned to.

ex. <goto next="conference.ccxml"/>

Submitting CCXML variables with <submit>

If it's necessary to pass values to the next CCXML application, you'll want to use the <submit> element rather than <goto>. Like <goto>, the next attribute contains the URL of the CCXML application that will be executed. The namelist attribute contains the list of variables contained in the current CCXML application whose values will be passed to the next application. The method attribute corresponds to the HTTP method, which can be GET or POST (the default is GET).

ex. <submit next="conference.asp" 
            namelist="state calledid callerid"/>

Executing VoiceXML Content

Starting a VoiceXML dialog with <dialogstart>

The <dialogstart> element executes a VoiceXML dialog specified by the src attribute. The element contains the following attributes, all of which are optional except for src:

  • callid - same as the callid attribute defined for the <accept> element
  • src - must be a valid URL location of a VoiceXML dialog
  • type - MIME type; default is application/xml+vxml
  • name - same as the <transition> element
ex. <dialogstart src="'example2.vxml'"/>

The CCXML is non-blocking, so it does not stop executing the CCXML application when a VoiceXML dialog starts. 

Stopping a VoiceXML dialog with <dialogstop>

In fact, you may want to pause or stop the VoiceXML dialog with a <dialogstop> while the dialog is still executing. For example, you might execute a VoiceXML dialog that plays on-hold music while you try to conference in another party. When the other party connects, you'd want to stop the music and announce that the other party has joined the conference.

Conclusion

In Part II of the Introduction to CCXML series, we've learned the basic elements that are used to handle events, execute VoiceXML content, and control calls. In Part III, we will apply our knowledge by creating a practical CCXML application.

About Jonathan Eisenzopf

Jonathan is a member of the Ferrum Group, LLC  which specializes in Voice Web consulting and training. He has also written articles for other online and print publications including WebReference.com and WDVL.com. Feel free to send an email to eisen@ferrumgroup.com regarding questions or comments about the VoiceXML Strategy series, or for more information about training and consulting services.

Share:
Home
Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved