A tutorial on Call Control XML and voice browser call control (2023)

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

<transition event=”*” name=”ev”>
<log label=”‘missed'” expr=”ev.toString()”/>
</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”>
<!– Lets declare our state var –>
<var name=”state0″ expr=”‘init'”/>

<eventprocessorstatevariable=”state0″>
<!– Process the incoming call –>
<transition state=”init” event=”connection.alerting”>
<accept/>
</transition>
<!– Call has been answered –>
<transition state=”init” event=”connection.connected” name=”evt”>
<log expr=”‘Houston, we have liftoff.'”/>
<dialogstartsrc=”‘example2-dialog.vxml'”/>
<assign name=”state0″ expr=”‘dialogActive'” />

</transition>
<!– Process the incoming call –>
<transition state=”dialogActive” event=”dialog.exit” name=”evt”>
<log expr=”‘Houston, the dialog returned [‘ + evt.values.input + ‘]'” />
<exit />
</transition>
<!– Caller hung up. Lets just go on and end the session –>
<transition event=”connection.disconnected” name=”evt”>
<exit/>
</transition>
<!– Something went wrong. Lets go on and log some info and end the call –>
<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.

Daily Tech Insider Newsletter

Stay up to date on the latest in technology with Daily Tech Insider. We bring you news on industry-leading companies, products, and people, as well as highlighted articles, downloads, and top resources. You’ll receive primers on hot tech topics that will help you stay ahead of the game.

(Video) How to Build a Call Center with Python - Full In-Depth Walkthrough

Delivered Weekdays

Sign up today