A tutorial on Call Control XML and voice browser call control

by Peter V. Mikhalenko | Apr 04, 2006 7:31:00 PM

Tags: TELECOMMUNICATIONS, Telecom & Utilities, Call Control XML, Peter V. Mikhalenko, CCXML 1.0, VoiceXML, telephony

2 comment(s)

Takeaway: In this document, we will look at some of VoiceXML's capabilities and limitations, as well as details on how VoiceXML and CCXML can be integrated within an application.

In the last article about SCXML we talked about state machine notations and noted that many concepts were taken from Call Control XML (CCXML) language. The first draft of CCXML specification appeared in the early 2002, and still remains in a working draft status. However, lack of final recommendation is not an obstacle for telecom industry, and there already exist several CCXML implementations in products like OpenCall Media Platform from Hewlett Packard or the open-source Asterisk platform.

Call Control XML is designed to provide telephony call control support for dialog systems, such as VoiceXML It also can be used as a third-party call control manager in any telephony system. The CCXML 1.0 specification defines both a state machine and event handing syntax and a standardized set of call control elements.

In this document, we will look at some of VoiceXML's capabilities and limitations, as well as details on how VoiceXML and CCXML can be integrated within an application. Telephone applications need to receive and process large numbers of events in real-time. These events arrive from outside the program itself—either the underlying telephony platform, or from other sources of events. A CCXML program includes event handlers which are executed when certain events arrive. CCXML also provides a powerful and flexible method of creating multi-party calls.

Note: The downloadable version of this article contains all of the code examples in easy to use text files.

Main concepts and terms

CCXML can be used as a third-party call control manager in any telephony system. Originally there was an intention to add new tags to VoiceXML to support the new features. However, specification designers repeatedly encountered conflicts between the design goals for VoiceXML, and the requirements for CCXML. CCXML and VoiceXML implementations are not mutually dependent. A CCXML implementation may or may not support voice dialogs, or may support dialog languages other than VoiceXML.

The following requirements were addressed by CCXML:

Ability to give each active "call leg" (a real-world phone connection) its own dedicated VoiceXML interpreter. Currently, the second leg of a transferred call lacks a VoiceXML interpreter of its own, limiting the scope of possible applications.
Support for multi-party conferencing, with advanced conference and audio control. A conferencing application involves multiple participants, and is dependent upon call control to establish relationships between those participants.
Sophisticated multiple-call handling and control, including the ability to place outgoing calls.
Handling for a richer class of asynchronous events. Advanced telephony operations involve substantial amounts of signals, status events, and message-passing. VoiceXML 2.0 does not integrate asynchronous "external" events into its event-processing model.
The ability to receive events and messages from external computational entities. Interacting with an outside call queue, or placing calls on behalf of a document server, means that VoiceXML must have additional external interfaces.

A CCXML application itself is a collection of CCXML documents that together create a complete application/program. A single instance of a CCXML application is called a CCXML Session. One session can span multiple documents and phone calls. A CCXML connection can be a "call leg" or a system resource to facilitate interaction with a Voice Dialog.

Media streams between Connections, or between Connections and Conference objects, need to be tracked by the CCXML interpreter and will take real system resources. A Voice Dialog, when active, is associated with a specific Connection by which the Voice Dialog may interact with one-way or two-way media streams from other Connections or a Conference Object. A Conference Object models a resource for mixing media streams.

CCXML programs manipulate these entities through elements defined in the CCXML language. They can also send and/or receive asynchronous events associated with these entities. CCXML programs directly manipulate Connection Objects and Conference Objects with various elements in the language which will be described below. CCXML may also receive events from Connection and Conference Objects, in the case of line signaling, line-status informational messages, or error and failure scenarios. CCXML programs can start and kill Voice Dialogs using language elements as well. Any other interaction takes place through the event mechanism. CCXML Sessions can both send and receive events between one another.

An event in CCXML is an action or occurrence to which an application can respond. Examples of events are incoming phone calls, dialog actions or user defined events. Events in CCXML are modeled as ECMAScript objects and can contain complex values.

Call Control structure in real examples

Now let's have a look at some real examples and try to understand what is done there. The first example (Example1.txt) is a simple "hello world" CCXML application that is started due to an incoming call where the application simply assigns a value to a variable, prints a message to the platform log and exits.

Example 1

<?xml version="1.0" encoding="us-ascii"?>
<scxml version="1.0" xmlns="http://www.w3.org/2005/07/scxml" initialstate="S1">
<state id="S1">
    <transition event="Event1" target="S2"/>
</state>

<state id="S2">
    <transition event="Event2" cond="X>0" target="S1"/>
    <transition event="Event2" cond ="X<0" target next="S3"/>
</state>

<state id="S3">
</state>

</scxml>

The <ccxml> is the parent element of a CCXML document and encloses the entire CCXML script in a document. When a <ccxml> is executed, its child elements are collected logically together at the beginning of the document and executed in document order before the target <eventprocessor>. This is called document initialization. The <eventprocessor> acts as a container for <transition> elements. A valid CCXML document MUST only have a single <eventprocessor> element, and in chain it can contain only <transition> elements.

The content of a <transition> specifies the actions to be taken when it is selected. Its "event" attribute is a pattern that indicates a matching event type. Event types are dot-separated strings of arbitrary length. Variables are declared using the <var> element and are initialized with the results of evaluating the optional "expr" attribute as an ECMAScript expression. The values of variables may be subsequently changed with <assign>element. <log> allows an application to generate a logging or debug message which a developer can use to help in application development or post-execution analysis of application performance. The manner in which the message is displayed or logged is platform-dependent. <exit> ends execution of the CCXML session. All pending events are discarded, and there is no way to restart CCXML execution.

Event Handling

Event Handling is one of the most powerful features of CCXML. CCXML events can be delivered at any time and from a variety of sources. This flexible event-handling mechanism is essential for many telephony applications.

Each running CCXML interpreter has a queue, into which it places incoming events, and sorts them by arrival time. A CCXML programmer can only gain access to these queued events by using the <eventprocessor> element with associated <transition> elements. The CCXML session event queue generally operates in a First In, First Out (FIFO) manner with events to be processed being removed from the head and new events being placed at the tail. There are two exceptions to this behavior: events where a time delay has been specified, and certain special events that are always placed at the head of the queue.

An event can be delivered to a CCXML session using a <send> element in which case an optional delay may be specified. When a delay is specified the event is delivered to the target CCXML session but it is not placed on to the event queue until the delay time has elapsed. When the delay has elapsed the event is placed at the tail of the queue.

An <eventprocessor> is interpreted by an implicit Event Handler Interpretation Algorithm (EHIA). The EHIA's main loop removes the first event from the CCXML session's event queue, and then selects from the set of <transition>s contained in the <eventprocessor>. A <transition> always indicates a set of accepted event types, and MAY indicate a further ECMAScript conditional expression to be evaluated. The <transition> that accepts the type for the just-removed event, has a satisfied conditional expression, and appears first in the <eventprocessor> in document order, is the selected <transition>.

If an event is not selected by any <transition> within the <eventprocessor>, the CCXML platform SHOULD log the event using the "missed" label. The CCXML platform can configure the "missed" label for any desired disposition. This should be (however, not a must) equivalent to the transition presented in Default-transition.txt.

Default Transition

Session Life-Cycle

A CCXML session life-cycle requires more clarification now. A CCXML session can be started for the following reasons:

A new incoming phone call coming into the platform.
A CCXML application executing a <createccxml>.
An external session launch request coming into the platform.

When a session is started due to an incoming call, it has ownership of the event endpoint associated with the new Connection. The new CCXML session will be responsible for processing the Connection state events and performing the Connection actions.

Every CCXML session has a set of standard ECMAScript variables that are available to the program during execution called session variables. The session variables are defined by the CCXML implementation when the CCXML session is created and are read-only to the running script and cannot be modified by the CCXML program. Such variables include session information such as a session identifier, the reason for what the session was started, list of all Connection objects, and so on. A CCXML application can determine the reason its session was started by evaluating the contents of the session.startupmode session variable.

A CCXML session begins with the execution of a CCXML document. The flow of the execution can be changed with the help of <if>, <elseif>, <else>, <fetch>, and <goto>. Most of a CCXML session's execution will take place within an <eventprocessor>, which processes a stream of incoming events. A CCXML session may launch a new CCXML session using <createccxml>. The new CCXML session executes in an independent context and variable space from the original CCXML session, completely independent of the lifetime of the original session. Sessions can communicate by sending messages via <send>.

A CCXML session can end in one of the following ways:

The CCXML application executes an <exit>.
An unhandled "error.*" event.
An unhandled "ccxml.kill" event.
A "ccxml.kill.unconditional" event.

When a CCXML session ends, all active connections, conferences and dialogs that are owned by that session are automatically terminated by the platform.

A connection is typically shorter than a session. A session does not end when a connection terminates. A CCXML session does not necessarily need to have any connections associated with it. After starting, a session may acquire connections as a result of <createcall> or <move> requests. Figure A and Figure B illustrate the session life-cycle of several different scenarios.

Figure A

Session Life Cycle

Figure B

Session Life Cycle, a different scenario

In our "hello world" example (Example1.txt) when a session ends, any resources, including connections owned by that session, are terminated—as illustrated in Figure C. These are not only life-cycle scenarios; sessions can also have multiple sequential connections, or even have multiple concurrent connections. A connection can be moved from one CCXML session to another session.

Figure C

Termination

If at anytime the platform wishes to terminate a CCXML session it must raise a ccxml.kill event to inform the CCXML application. The normal response to this event is for the CCXML application to perform a clear up and termination of current active connections, conferences or dialogs, and then execute an <exit> element.

Let's look at a more complex example of running a simple VoiceXML dialog from CCXML. The application answers an incoming phone call and then connects it to a VoiceXML dialog that returns a value that is then logged to the platform (Example2.txt and Example2.vxml.txt). This is the first point of connection between CCXML and VoiceXML.

Example 2

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml">

<var name="state0" expr="'init'"/>

<eventprocessorstatevariable="state0">
    
    <transition state="init" event="connection.alerting">
      <accept/>
    </transition>
    
    <transition state="init" event="connection.connected" name="evt">
      <log expr="'Houston, we have liftoff.'"/>
      <dialogstartsrc="'example2-dialog.vxml'"/>
      <assign name="state0" expr="'dialogActive'" />

    </transition>
    
    <transition state="dialogActive" event="dialog.exit" name="evt">
      <log expr="'Houston, the dialog returned [' + evt.values.input + ']'" />
      <exit />
    </transition>
    
    <transition event="connection.disconnected" name="evt">
      <exit/>
    </transition>
    
    <transition event="error.*" name="evt">
      <log expr="'Houston, we have a problem: (' + evt.reason + ')'"/>
      <exit/>
    </transition>
</eventprocessor>
</ccxml>

Example 2 - VXML

<?xml version="1.0"?>
<vxmlxmlns="http://www.w3.org/2001/vxml" version="2.0">
<form id="Form">
    <field name="input" type="digits">
      <prompt>
        Please say some numbers ...
      </prompt>
      <filled>
        <exit namelist="input"/>
      </filled>
    </field>
</form>
</vxml>

When a CCXML document receives a connection.alerting event within an <eventprocessor>, like in Example 2, the execution of an <accept> within the <transition> block will cause the underlying platform to signal the telephony system to connect the call. The CCXML document MAY then initiate interactive dialog sessions with the incoming caller, or perform other telephony operations (e.g., place outgoing calls, join calls, etc).

Dialog handling

CCXML does not provide any mechanism for interacting with callers but relies on separate dialog environments such as VoiceXML. Whenever interaction with a caller is required a CCXML session can initiate a separate dialog provided by a VoiceXML capability or some other technology. After the dialog interaction is complete, an asynchronous event is sent to the CCXML session which can use any results returned by the dialog environment to decide what should happen next. All CCXML elements that manipulate dialogs are asynchronous with control returning immediately to the CCXML session after the operation is initiated. The CCXML session is notified when the dialog operation successfully completes, or fails, by an asynchronous event.

A CCXML program initiates a dialog using the <dialogstart> element (See Example 2). Execution of this element connects a dialog environment to a connection and instructs it to start interacting with the caller. For some dialog environments it may take some time to initialize the dialog environment and thus the use of the <dialogstart> element alone may cause the caller to hear silence, or "dead air". To avoid this situation CCXML provides an ability to ready a dialog environment prior to connecting and starting it, this is done using the <dialogprepare> element. Any dialog that has been either started with <dialogstart>, or prepared with <dialogprepare> can be terminated using the <dialogterminate> element. CCXML implementations must support the <dialogprepare>, <dialogstart>, and <dialogterminate> elements though the exact behavior may vary depending on the dialog environments supported.

If the dialog cannot be started for any reason, an error.dialog.notstarted event is posted to the event queue of the CCXML session that processed the <dialogstart> request. When the dialog completes, a dialog.exit event is posted to the event queue of the CCXML session that started it. In our example we process the dialog data in transition element <transition state="dialogActive" event="dialog.exit" name="evt">.

VoiceXML integration

CCXML and VoiceXML 2.0 need to be able to exchange events between the browsers. The method of the message passing is up to the platform but it is assumed that there is some basic capacity in place. Each running CCXML session has an event queue used to process CCXML events, independently of VoiceXML event processing by the dialogs created by that CCXML session. The execution of certain CCXML elements, such as <dialogterminate> and <send> may cause events to be sent to the VoiceXML browser; similarly, certain VoiceXML elements such as <transfer> will result in the generation of dialog events delivered to the CCXML session that owns the dialog in question.

VoiceXML 2.0 provides limited capabilities for handling asynchronous or unexpected events. Since CCXML is designed around a robust event processing mechanism, and since the CCXML session manages connections to the underlying network, processing of asynchronous events—which may be delivered through externally accessible event I/O processors—typically occurs primarily within the CCXML application, which can then control the VoiceXML session as appropriate. The VoiceXML dialog can therefore focus exclusively on interaction with the user.

When a VoiceXML dialog is bridged to a connection with an associated call leg, the standard VoiceXML session variables obtain their values from the call leg. Otherwise, these variables are undefined. VoiceXML Session variables are updated whenever there is an update to the associated connection or conference. When a CCXML application processes a <dialogstart> element it starts up a VoiceXML application on the connection with the URI that is passed in on the <dialogstart> element or to the dialog that was prepared using <dialogprepare> and specified using the prepareddialogid attribute.

Call control

The primary goal of CCXML is to provide call control throughout the duration of a call. Call control includes handling incoming calls, placing outgoing calls, bridging (or conferencing) multiple call legs, and ultimately disconnecting calls. The goals of the CCXML call model are to focus on relatively simple types of call control and to be sufficiently abstract so that the call model can be implemented using all major telephony definitions such as JAIN Call Control (JCC), CSTA, and S.100.

It seems that CCXML has a bright future in telecom industry, partially because there is a strong demand for a unified application interface. There exist several similar processing languages, among which are CPL, CallXML, ECMA-CSTA, TXML and others. You can find them in Appendix A of the CCXML specification.

2 comment(s)