Voice Browser Call Control: CCXML Version 1.0

Abstract

This document describes CCXML, or the Call Control eXtensible Markup Language. CCXML is designed to provide telephony call control support for VoiceXML or other dialog systems. CCXML has been designed to complement and integrate with a VoiceXML system. Because of this you will find many references to VoiceXML's capabilities and limitations. You will also find details on how VoiceXML and CCXML can be integrated. However it should be noted that the two languages are separate and are not required in an implementation of either language. For example CCXML could be integrated with a more traditional IVR system and VoiceXML or other dialog systems could be integrated with some other call control systems.

Status of this Document

This specification describes the Call Control XML (CCXML) markup language that is designed to provide telephony call control support for VoiceXML or other dialog systems. This document has been produced as part of the W3C Voice Browser Activity, following the procedures set out for the W3C Process. The authors of this document are members of the Voice Browser Working Group ( W3C Members only ). This is a Royalty Free Working Group, as described in W3C's Current Patent Practice note. Working Group participants are required to provide patent disclosures.

This release of the CCXML specification includes major revisions to the call control and media models to better specify the behavior and includes full details on all call control objects and events. A number of attribute names were updated to make the specification more consistent. There were also a large number of smaller changes that are listed in detail in Appendix G.

This document is for public review, and comments and discussion are welcomed on the public mailing list <www-voice@w3.org>. To subscribe, send an email to <www-voice-request@w3. org> with the word subscribe in the subject line (include the word unsubscribe if you want to unsubscribe). The archive for the list is accessible online.

This is a W3C Working Draft for review by W3C Members and other interested parties. It is a draft document and may be updated, replaced or made obsolete by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress".

This is work in progress and does not imply endorsement by the W3C membership. A list of current W3C Recommendations and other technical documents, including Working Drafts and Notes, can be found at http://www.w3.org/TR/.

Table of Contents

• Section 1: Introduction
• Section 2: Background
• Section 3: Concepts
• • 3.1: Event Processing
  • 3.2: Conferencing
  • 3.3: Call Management
  • 3.4: Scripting
  • • 3.4.1: Introduction
    • 3.4.2: Definitions
• Section 4: Object Model and Programming Contract
• Section 5: CCXML Elements Listing
• Section 6: Document Control Flow and Execution
• • 6.1: Overview
  • 6.2: elements
  • • 6.2.1: <ccxml>
    • 6.2.2: <if>
    • 6.2.3: <elseif>
    • 6.2.4: <else>
    • 6.2.5: <fetch> and <goto>
    • 6.2.6: <createccxml>
    • 6.2.7: <exit>
    • 6.2.8: <log>
  • 6.3: Events
  • • 6.3.1: Overview
    • 6.3.2: fetch.done
    • 6.3.3: error.fetch
    • 6.3.4: ccxml.exit
    • 6.3.5: ccxml.loaded
• Section 7: Dialogs
• • 7.1: Overview
  • 7.2: elements
  • • 7.2.1: <dialogstart>
    • 7.2.2: <dialogterminate>
  • 7.3: Events
  • • 7.3.1: Overview
    • 7.3.2: dialog.started
    • 7.3.3: dialog.exit
    • 7.3.4: dialog.disconnect
    • 7.3.5: dialog.transfer
    • 7.3.6: error.dialog.notstarted
    • 7.3.7: error.dialog.wrongstate
    • 7.3.8: dialog.user.*
• Section 8: Variables and Expressions
• • 8.1: Overview
  • 8.2: elements
  • • 8.2.1: <assign> and <var>
    • 8.2.2: <script>
• Section 9: Event Handling
• • 9.1: Event Concepts
  • 9.2: elements
  • • 9.2.1: <eventhandler>
    • 9.2.2: <transition>
    • 9.2.3: <send>
    • 9.2.4: <move>
  • 9.3: Event Transmission
  • 9.4: Standard Events
  • • 9.4.1: Connection Class
    • 9.4.2: Connection Events
    • 9.4.3: Standard Events
  • 9.5: Error Events
• Section 10: Telephony Operations and Resources
• • 10.1: Incoming Calls
  • • 10.1.1: Overview
    • 10.1.2: <accept>
    • 10.1.3: <redirect>
    • 10.1.4: <reject>
    • 10.1.5: <hold>
  • 10.2: Outgoing Calls
  • • 10.2.1: <createcall>
  • 10.3: Conferencing
  • • 10.3.1: <createconference>
    • 10.3.2: <destroyconference>
    • 10.3.3: <join>
    • 10.3.4: <unjoin>
  • 10.4: Bridging
  • 10.5: Disconnect
  • • 10.6.1: <disconnect>
• Section 11: Security
• • 11.1: Overview
  • 11.2: <authenticate>
• Section 12: Examples
• Appendix A - Future Study and Issues
• Appendix B - Related Work
• Appendix C - CCXML DTD
• Appendix D - CCXML Schema
• Appendix E - VoiceXML Integration
• Appendix F - Recommended Telephony Protocol Names
• Appendix G - Changes
• Appendix H - Acknowledgments

Section 1: Introduction

This document describes CCXML, the Call Control eXtensible Markup Language. CCXML provides declarative markup to describe telephony call control. CCXML is an adjunct language that can be used with VoiceXML or other dialog systems.

CCXML has been designed specifically to complement VoiceXML. Therefore, this document contains references to VoiceXML's capabilities and limitations, and details on how VoiceXML and CCXML can be integrated. However, the two languages are separate and neither is required for an implementation of the other. CCXML can be integrated with a traditional IVR system, and VoiceXML can interface with other call control systems.

CCXML is not complete. This draft provides access to an early version of the language, and illustrates the direction of the working group.

This is a large document and there are improvements still to be made to it. However, the working group believes it is more important to stimulate widespread discussion of CCXML's ideas by releasing a series of CCXML working drafts, than to defer release until the document is refined. There are a number of known issues and improvements, listed in this document in green, which highlight ideas that should be incorporated, but that are not resolved in this draft because of time constraints.

Section 3: Concepts

Properly adding advanced telephony features to VoiceXML entails adding not just a new telephone model, but new call management and event processing, as well. We'll briefly cover these three areas here. Since new event processing has the largest impact on our architecture, let's examine it first.

Section 3.1: Event Processing

Telephone applications need to receive and process large numbers of events. These events arrive from outside the program itself - either the underlying telephony platform, or from other programs. They must be processed quickly, as any delays could be discerned by the user.

Unfortunately, VoiceXML is not designed for the task. Its event model assumes only "synchronous" events - those which occur only when the program occupies certain states. (For example, a nomatch event can only occur within a field.) The language would have to be augmented to properly handle events which can arrive at any time. (It's true that telephone.disconnect can occur at any time, but this is something of a special case.) Further, it would be tough to reconcile the need for immediate processing with VoiceXML's single-threaded model.

Instead, we move all asynchronous handling to a CCXML session. Every executing VoiceXML program has an associated CCXML session. It runs on a session separate from the VoiceXML dialog. When an event is delivered to a user's voice session (now a coupling of an active VoiceXML dialog and its CCXML session), it is appended to the CCXML session's queue of events. The CCXML session spends almost all its time removing the event at the queue's head, processing the event, and then removing the next event. Meanwhile, the VoiceXML dialog can interact with the user, undisturbed by the incoming flow. Most VoiceXML programs never need to consider event processing at all.

Writing a CCXML program, then, mainly involves writing the handlers which are executed when certain events arrive. There are mechanisms for passing information back and forth between VoiceXML and CCXML, but the important points are that CCXML:

• lives on its own thread, and
• carries the burden of rapid asynchronous event handling

Note: References to threads are meant as logical threads and do not imply any specific platform implementation.

Section 3.2: Conferencing

VoiceXML currently has very few options for conferencing. Only the transfer element will establish any kind of connection between two voice callers; calls involving more than two parties, or other advanced applications, are out of reach. VoiceXML is largely a language for voice dialogs, and is silent on many telephony issues.

We would like a far more powerful and flexible method of creating calls. To do so, we introduce a few ideas here:

• Call legs are in some ways just audio sinks and sources. We should be able to join together arbitrary networks of them.
• A modern-day conference is not much more than an audio stream that mixes together all the speakers' audio outputs. Our conference networks will allow for conference objects, which mix together inputs into a single output channel.
• Our conferences could also include splitters, which take a single input channel and emit it over several outputs.
• The conference's architecture may be modified dynamically, thus allowing for moderation, floor control, mute, etc.
• Human speakers are not the only entities that can generate and consume audio. VoiceXML interpreters will be first-class citizens in the conferences we create, allowing, for example, "robot moderators" to operate discussions.
• Finally, we realize that conferencing technology is very dependent on the implementation platform. CCXML browsers may refuse to create certain conferences or networks, and still be in compliance. A large part of a CCXML program's event handlers will be concerned with these conferencing operations. All of these goals match the use-case and architectural documents that the Call Control working group has discussed so far.

Section 3.3: Call Management

VoiceXML also fails to offer sufficient control over the underlying telephone network. Although VoiceXML offers the disconnect directive to hang up an existing phone call, there are a number of desirable features to which the VoiceXML programmer cannot get access. They include:

• Outbound call placement.
• Selective call-answering. Currently, a running VoiceXML interpreter is always tied to an answered line. We may want to perform some computation before deciding if and how to answer the call.
• Some access to phone network signaling and error conditions.

We want to expose the phone network in a provider-neutral way, while still offering enough methods and information to allow sophisticated types of call management. Toward that end, we have defined typical call control actions in a high-level, abstract way so that almost any underlying telephony definition should be able to implement them. This is discussed in more detail in Section 9.

Section 3.4: Scripting

Section 3.4.1: Introduction

The computational semantics of CCXML are based on the ECMAScript Compact Profile (ES-CP, also known as ECMA-327). Execution efficiency is a goal of the designers of CCXML, and ES-CP was chosen in order to avoid excessive execution overhead.

The ES-CP document states,

'ECMAScript Compact Profile is a subset of ECMAScript 3rd Edition tailored to resource-constrained devices such as battery powered embedded devices. Therefore, special attention is paid to constraining ECMAScript features that require proportionately large amounts of system memory (both for storing and executing the ECMAScript language features) and continuous or proportionately large amounts of processing power.'

CCXML is not intended for battery powered embedded devices, but it is intended to be practical for large, real-time telephony platforms managing thousands of lines. The constraints of ES-CP emphasize CCXML's ongoing concern for execution efficiency.

Even though ES-CP tends to be implemented using interpreters, CCXML does not require an interpretive implementation. ES-CP can be compiled to a target language such as C, and thus in turn to machine code, so that CCXML documents which are static can be rendered once in machine code. Even frequently modified CCXML documents can be translated and compiled on their way from the document server to the CCXML execution environment, in order to avoid multiplying interpretive overhead by the number of lines that execute the document.

The emphasis on efficiency in CCXML is also shown by the avoidance of features which can only be implemented either by interpretation or run-time evaluation.

The choice of an implementation strategy is up to the CCXML implementer. CCXML is designed to allow a range of choices in order to accommodate practical implementations on a wide variety of platforms.

Section 3.4.2 Definitions

The following terms, which are used throughout this specification, are defined here.

ECMAScript left-hand-side expression - defined in ECMA-262 11.2; this is an expression which produces a result to which a value can be assigned; an expression which is valid as the left hand operand of an assignment (=) operator;

ECMAScript expression - defined in ECMA-262 11.14; this is an expression which produces a value; an expression which is valid on the right hand side of an assignment operator;

ECMAScript variable name - defined in ECMA-262 7.6; this is any valid sequence of characters, known as an identifier, which can be used as a variable name, a property name, or a function name; this does not include any qualifiers, such as array or property accessors;

Empty ECMAScript object - an object returned by the new Object() expression; an object with no properties.

CCXML variable name - a variable name declared in a CCXML <var> element, with optional dot separated qualification.

Scope element - a CCXML element which defines a variable scope; <ccxml> and <transition> are CCXML scope elements.

Times - CCXML uses the CSS2 time format. Time designations consist of a non-negative real number followed by a time unit identifier. The time unit identifiers are:

• ms: milliseconds

• s: seconds

Examples include: "3s", "850ms", "0.7s", ".5s" and "+1.5s".

Section 4: Object Model and Programming Contract

CCXML can start and kill voice dialogs using language elements. It can receive events from voice dialogs, which may be standardized events such as dialog.exit , or application-specific ones. CCXML can support sending of an event to a voice dialog. We describe below how VoiceXML might be slightly modified to synchronously process arbitrary external events, much as it processes recognition events today. CCXML's only guaranteed control over a dialog is start and kill. Even if VoiceXML will process these external events, anything more than lifetime-management must be specifically supported by the voice dialog.

Finally, CCXML can create other CCXML sessions using a language element. That is the only guaranteed control one CCXML sessions ever wields over another. Any other interaction takes place through the event mechanism. CCXML sessions can both send and receive events between one another.

Section 5: CCXML Elements Listing

Section 6: Document Control Flow and Execution

Section 6.1: Overview

The execution of a CCXML document begins with the <ccxml> element at the top and then proceeds element by element in document order. The flow of the execution can be changed with the help of <if>, <elseif>, <else>, <fetch>, and <goto> elements. Most of a CCXML session's execution will take place within an <eventhandler> , which processes a stream of incoming events. A CCXML application can consist of multiple CCXML documents, traversed by use of <goto> and <fetch> .

Section 6.2: elements

Here are the details of the CCXML elements for control flow and execution.

Section 6.2.1: <ccxml>

Section 6.2.1.1: Overview

This is the parent element of a CCXML document and encloses the entire CCXML script in a document. When a <ccxml> element is executed, its child elements are collected logically together at the beginning of the document and executed in document order before the target <eventhandler>. This is called document initialization.

Section 6.2.1.2: CCXML Attribute Details

Section 6.2.2: <if>

Section 6.2.2.1: Overview

The <if> element is a program-control element. The <else> and <elseif> elements can appear optionally within an <if> element.

Section 6.2.2.2: If Attribute Details

Section 6.2.3: <elseif>

Section 6.2.3.1: Overview

The <elseif> element is a program-control element. The <else> and <elseif> elements can appear optionally within an <if> element.

Section 6.2.3.2: Elseif Attribute Details

Section 6.2.4: <else>

Section 6.2.4.1: Overview

The <else> element is a program-control element. The <else> and <elseif> elements can appear optionally within an <if> element.

Section 6.2.4.2: Else Attribute Details

Section 6.2.5: <fetch> and <goto>

Section 6.2.5.1: Overview

The <fetch> element, together with <goto> , is used to transfer execution to a different CCXML document in a multi-document CCXML application. In VoiceXML this is performed via the <goto> element, which blocks execution until the target page is loaded and ready to execute. CCXML programs, however, can be substantially more timing-sensitive than VoiceXML ones. All event-handling would have to be suspended until a blocking <goto> had found the target page, loaded, and parsed it. The time required could be hundreds of milliseconds or seconds, periods too lengthy for ignoring important incoming events.

Instead, we break the functions of VoiceXML's goto command into two parts. The <fetch> operator tells the interpreter to find, load, and parse a given page of CCXML. Execution returns from the element immediately, and the CCXML interpreter can continue on while the execution context works to get the target document ready for execution. When the <fetch> completes, the document which issued the fetch receives a fetch completion event. It can then issue a <goto> to immediately start executing the now-fetched page.

Below is a small snippet of code from the CCXML program's event handler. We execute a <fetch> operation, and continue on to assign to a state variable, and maybe handle more events. Eventually, the fetch completes, the CCXML interpreter services the event, and we perform the <goto> .

<fetch next="'http://www.web.com/control.ccxml'"/>
<--control continues here->
<assign name="state_var" expr="'fetch_wait'"/>
</transition>

<!-- ……… -->

<transition state="fetch_wait" event="fetch.done" name="evt"/>
<goto fetchid="evt.fetchid"/>
</transition>

There's no requirement to <goto> previously-fetched pages, but it is wasteful to not do so.

Section 6.2.5.2: Fetch Attribute Details

Asynchronous execution of a fetch element initiates a request for the CCXML document identified by its attributes. Execution immediately continues with the element following the fetch. When the asynchronous request has completed, the fetch completion event will be generated. If the fetch fails for any reason, a fetch fail event will be generated instead.

When fetch is executed synchronously, the CCXML document blocks until the fetch completes, and the fetch completion event is stored as identified by the synch attribute. In this case, the element following the fetch element will not be executed until fetch completes. The properties of the fetch completion event can be tested to determine the result of the fetch request, so that error handling alternatives can be provided.

Section 6.2.5.3: Goto Attribute Details

A goto element transfers control to the document identified by the fetch ID. The execution of a goto element does not depend upon whether the target document was fetched synchronously or asynchronously. However, the fetch completion event must have arrived before the <goto> is executed, otherwise, an error event is generated.

When a goto element is executed, the target document replaces the current document in its session. event sources associated with this session are inherited by the target document. Execution of the current document terminates.

Section 6.2.6: <createccxml>

Section 6.2.6.1: Overview

The createccxml element is used to create another CCXML session, which begins execution with the document identified by this element. The term "session" is not meant to imply a particular form of implementation. A CCXML session exists for each concurrently executing CCXML document. A session provides independent execution and a separate variable space for the CCXML documents it executes. A session is associated with one or more event sources and will receive events only from those endpoints. The execution of a CCXML document may add or subtract event sources from a session.

The createccxml element is used to create another CCXML session. The new CCXML session has no relation to its creator once spawned, and has a wholly separate lifetime and address space.

Section 6.2.6.2 Createccxml Attribute Details

Section 6.2.7: <exit>

Section 6.2.7.1: Overview

The exit element ends execution of the CCXML session. All pending events are discarded, and there is no way to restart CCXML execution.

The exit element ends execution of a CCXML document and its session.

Section 6.2.7.2 Exit Attribute Details

A CCXML script executing the <exit> element will generate a ccxml.exit event to the parent session. The exiting document will be identified on the exit event by its session ID.

Section 6.3: Events

Section 6.3.1: Overview

CCXML allows operations such as document fetching, startup and shutdown to execute independently.

The following are the CCXML events that have to do with this:

Section 6.3.2: fetch.done - Fetch Completion Event

This event is generated when a fetch request completes. It is delivered to the document which issued the request.

The fields of this event are:

Section 6.3.3: error.fetch - Fetch Error Event

This event is generated when a fetch request does not successfully complete. It is delivered to the document which issued the request.

The fields of this event are:

Section 6.3.4: ccxml.exit - CCXML Document Exit Event

This event is generated when a CCXML document executes an <exit> element.

The fields of this event are:

Section 6.3.5: ccxml.loaded - CCXML Document Loaded Event

This event is generated for a newly loaded CCXML document to provide an opportunity for initialization. The CCXML platform should generate this event when the CCXML document is first loaded, both at session startup and after transferring control to a new document with the <goto> element. This event would be processed after the platform had executed the document initialization including executing any elements under the <ccxml> element.

The fields of this event are:

Section 7: Dialogs

Section 7.1: Overview

CCXML deals with all user interaction as "dialogs". Any time you want to perform an action where you interact with a caller you start a dialog on their session. Once a dialog has completed it can then return back to the CCXML session and the CCXML session can then make a decision on what to do next depending on what was returned.

Dialogs are not tied to any single dialog language. The requirements on a dialog language are very small and this could be implemented on anything from VoiceXML, SALT and even traditional IVR languages and platforms. Because of this a CCXML platform may support interaction with several dialog systems based on the mime type passed in at dialog startup.

CCXML treats starting a dialog as an asynchronous action meaning that when you start the dialog the control returns immediately back to the CCXML session and the CCXML session is notified of the result by an asynchronous event.

Section 7.2: elements

Section 7.2.1: <dialogstart>

Section 7.2.1.1: Overview

The <dialogstart> element is used to launch a dialog, allocate a connection, associate the launched dialog with the allocated connection, and bridge the associated connection to another connection or to a conference. (See Section 10 for a discussion of connections and bridges.). The element includes a URI reference to a start-document for a dialog manager. The launched dialog executes on a separate thread of execution (may be a thread, process, or system depending upon platform implementation), not on CCXML's thread of execution. Once the dialog is kicked off, the CCXML script can immediately go back to handling incoming events.

The <dialogstart> element does not block execution of the CCXML script until the started dialog completes. The CCXML script regains control immediately. If the dialog cannot be started for any reason, an error.dialog.notstarted error event is thrown.

When the dialog completes, a "dialog.exit" event is posted to the event queue of the CCXML instance that launched it.

If the "conid" attribute in the <dialogstart> specifies a connection rather than a conference, and if the dialog language allows access to telephony variables such as ANI, DNIS and UUI, values of these variables will be propagated from the specified connection to the dialog application.

Section 7.2.1.2: <dialogstart> Attribute Details

Section 7.2.2: <dialogterminate>

Section 7.2.2.1: Overview

A CCXML script may decide that it wants to destroy a current dialog. This is accomplished using the <dialogterminate> element in a CCXML script.

When the CCXML interpreter encounters a <dialogterminate> element, it sends a terminate event to the specified dialog.

Note that a <dialogterminate> request cannot be honored if the launched dialog is not yet in a ready state to receive it and act upon it. If this happens, a "error.dialog.wrongstate" event will be thrown.

When the CCXML application does a <dialogterminate> the dialog will still have a chance to return data to the CCXML application using a dialog.exit event. The details of how this mapping is done is up to the dialog language.

If you set the immediate attribute to true however the dialog does not get a chance to return data to the CCXML application and the CCXML application receives the "dialog.exit" event right away.

Section 7.2.2.2: <dialogterminate> Attribute Details

Section 7.3: Events

Section 7.3.1: Overview

CCXML and Dialogs do most of their communication using events. In the case where CCXML is receiving a event from a dialog it gets input into the CCXML applications event queue.

A CCXML application can also send a event to a dialog. How this is handled on the dialog side is dialog language dependent. On the CCXML side it is done by using the <send> element and passing in the dialogid that was received on the <dialogstart> element.

The following are the CCXML events that have to do with dialogs:

Section 7.3.2: dialog.started

This event is thrown when a dialog is started.

The fields of this event are:

Section 7.3.3: dialog.exit

This event is thrown when a dialog exits.

The fields of this event are:

Section 7.3.4: dialog.disconnect

This event is thrown when a dialog requests the call to be disconnected. It does not terminate the dialog but is only a request into the CCXML application to end the call.

The fields of this event are:

Section 7.3.5: dialog.transfer

This event is thrown when a dialog is requesting the call to be transferred.

The fields of this event are:

Section 7.3.6: error.dialog.notstarted

This event is thrown when a dialog can not be started for some reason.

The fields of this event are:

Section 7.3.7: error.dialog.wrongstate

This event is thrown when a dialog request was received and could not be completed because we are in a improper state.

The fields of this event are:

Section 7.3.8: dialog.user.*

This event is thrown when a dialog sends a user event to the CCXML application.

The fields of this event are:

Section 8: Variables and Expressions

Section 8.1: Overview

CCXML variables and expressions are similar to those in VoiceXML. All expressions must be valid ECMAScript expressions, assignable to variables with valid ECMAScript names. For more details please see section 3.4

Section 8.2: elements

Section 8.2.1: <assign> and <var>

Section 8.2.1.1: Overview

Variables are declared explicitly by the var element:

<var name="sessionid" />
<assign name="currentstate" expr="'initial'"/>

Variables declared without an explicit initial value are initialized to the ECMAScript undefined value. Variables must be declared before being used. However, see the <assign> element for a discussion of implicit declaration.

A variable is declared with the scope of the closest containing scope element. The fully-qualified name of a variable is the name of the variable's scope object prepended with a dot to the name of the variable. Within the attribute values of CCXML elements, variables can be referenced without their full qualification, which is implied. In the case of like-named variables declared in different scopes, the closest containing scope is implied, unless a fully-qualified variable name is used. If a variable is declared more than once, declarations subsequent to the first are considered to be assignments of the expr attribute initializer value to the variable. The default initializer is the ECMAScript value undefined .

Assignment to a variable which is undeclared at the point of the assignment implicitly declares that variable. The variable is declared in the scope of its closest containing scope element, and is known from the point of the assignment to the end of the scope. (See diagram)

Variables are declared using var element and assigned a value either at declaration time, or later through the assign element.

Section 8.2.1.2: Var Attribute Details

Section 8.2.1.3: Assign Attribute Details

Section 8.2.2: <script>

Section 8.2.2.1: Overview

The <script> element encloses computations written in the ECMAScript Compact Profile (ECMA-327) scripting language. For example, this <script> element defines a function that computes the greatest common factor of two integers:

<script>
<![CDATA[
function gcd(a, b)
{
 var t;
 if (a < 1 || b < 1)
   return -1;
 do
  {
   t = a % b;
   a = b;
   b = t;
  }
 while (b > 1);
 return (b == 0) ? a : b;
}
]]> 
</script>

A <script> element may occur in a <ccxml> element and in executable content. <transition> elements and <if> elements contain executable content. Script elements in a <ccxml> element are evaluated just after the document is loaded, along with the <var> and <assign> elements, in document order. Script elements in a <transition> element are evaluated as they are encountered. A <script> element in an <if> element is executed like other executable elements, as it is encountered.

A <script> element can declare variables with the ECMAScript var statement. Variables declared in this manner are in the scope of the closest containing scope element. They are known from the point of declaration to the end of the containing scope. The variables may be referenced with or without the qualification of their scope object. If a variable is declared more than once, declarations subsequent to the first are considered to be assignments of the initializer value to the variable. The default initializer is the ECMAScript value undefined

Section 8.2.2.2: script Attribute Details

Section 9: Event Handling

This section contains information on the <eventhandler>, <send>, <transition> and <move> elements.

Section 9.1: Event Concepts

Event Handling is one of the most powerful features of CCXML, and one way in which it is markedly different from VoiceXML. CCXML events have little to do with VoiceXML's events, such as nomatch or filled. VoiceXML events only occur within well-defined contexts, and are generated by the task at hand; it's impossible to receive a recognition-related event except within a field inside a form. CCXML events, however, can be delivered at any time and from a variety of sources. This flexible event-handling mechanism is essential for many telephony applications.

Every CCXML session can receive events. These might be in response to a previous action by the CCXML session (e.g., an outbound-call request, which generates an event to indicate when the call goes off-hook), or on the initiative of some external source (e.g., an incoming call to be answered). Events can be generated by the telephony system (as in the two previous examples), other CCXML session (which emits events via the send element), or the CCXML recipient-interpreter (by sending an event to itself). There is a core set of telephony-related events (derived from the JCC event model for connection objects. See JSR021 at java.sun.com for more information) that a browser must generate. Implementers are otherwise free to define and generate any platform-specific events they like. In addition, users/programmers may use the send element to send arbitrary events to external destinations, or may send arbitrary events to CCXML scripts from internal or external sources and may specify transition handlers to handle these events.

Each running CCXML interpreter has a queue, into which it places incoming events, and sorts them by arrival time along with any specified delay that has been requested. A CCXML programmer can only gain access to these queued events by using an eventhandler .

eventhandler elements are 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 elements contained in the eventhandler . A transition element always indicates a set of accepted event types, and may indicate a further ECMAScript conditional expression to be evaluated. The transition element that accepts the type for the just-removed event, has a satisfied conditional expression (or none at all), and appears first in the eventhandler by document order, is the selected transition .

Once selected, the elements inside a transition element are executed in document order. At most, one transition will be chosen. If no transition elements meet all the criteria, none are selected and the event is simply dropped; the EHIA loop then starts over again, removing the event at the head of the queue. Any events that arrive while an event is already being processed are just placed on the queue for later. If the event queue is empty, and the EHIA wants to process an event, execution pauses until an event arrives.

Code inside an eventhandler should run "instantaneously", without blocking execution. This will allow events to be rapidly processed.

The only way for CCXML execution to leave an eventhandler is via an explicit goto inside a transition .

An eventhandler may also declare a state variable. An eventhandler 's state variable is used just as any other variable, but with a scope limited to the eventhandler and its elements. The eventhandler can be considered, and programmed as, a finite-state-automaton, with the state variable indicating the automaton's current state or node, and the transition elements, driven by incoming events, moving the machine to a new state and creating side effects along the way. We expect, but CCXML does not require, that each transition will contain an assignment to the state variable to drive the automaton to its next state.

Section 9.2: elements

Section 9.2.1: <eventhandler>

The <eventhandler> element acts a container for the <transition> elements. A valid CCXML document MUST only have a single <eventhandler> element.

Section 9.2.1.1: eventhandler Attribute Details

Eventhandler elements can contain only transition elements.

Section 9.2.2: <transition>

Section 9.2.2.1: transition Attribute Details

Section 9.2.3: <send>

Section 9.2.3.1: Overview

It's now clear how CCXML can receive, process, and respond to external events. But it's not obvious how CCXML can generate those events directly. For that, we need the send element. When the interpreter encounters a send , it will generate and deliver an event of the specified type to an indicated CCXML session. The set of addressable CCXML session is up to the browser implementer, but at least all CCXML session running within the same browser must be able to send events to each other.

Successful execution of the send element implies the event has been delivered to the event queue of the target CCXML session, however, the event will not be processed by the receiving session's eventhandler until any specified delay has elapsed. In the case of an event sent with a delay, the sending CCXML session need not continue executing after processing the send event, it is the responsibility of the receiving session to maintain the event on its queue until the delay has elapsed.

Section 9.2.3.2: send Attribute Details

Section 9.2.4: <move>

Section 9.2.4.1: Overview

The <move> element is used to move an event source (such as a Connection object) to an executing CCXML session. When an event source is moved to a session, events originating from that source will be delivered to that session's currently executing CCXML document. You MUST specify the "event" OR the "source" attribute. If you do not specify one or if you specify both a "error.ccxml" event will be thrown.

Section 9.2.4.2: <move> Attribute Details

Section 9.3: Event Transmission

Many useful applications are only possible when events can be passed to an arbitrary CCXML session, regardless of browser. For example, a user could be notified about a failed remote print job, or transferred to a now-available remote operator. Both scenarios involve events generated from a remote location and delivered over a network to a CCXML session. CCXML browsers must be able to dispatch such events correctly.

The protocol for communicating these events is now undetermined, but will eventually be specified so we can guarantee interoperability between CCXML. (HTTP and SIP are two options for network protocol.) Encoding options include SOAP and Xforms. Whatever we decide, the protocol we choose must allow for the following:

• Arbitrary string passing
• Encrypted and authenticated transmission
• Reliable transport
• Easy network operation

Section 9.4: Standard Events

CCXML can generate arbitrarily-named events. While any event name is possible, there is a small set of well-known events that are generated as a matter of course, and which any telephone application should handle. There are two kinds of these events: telephony events, which abstract interaction with the phone network, and language events.

The first, and larger set, is present so CCXML can keep abreast of what's happening with the telephone network. CCXML is designed to be neutral with respect to the telephony layer, so the event set we choose must be very generic and capable of describing the behavior of a wide variety of systems (e.g., Q931, SS7, VoIP, etc).

We've focused on relatively simple types of call control, and we have tried to make the call control model in CCXML sufficiently abstract so that it can be implemented using all major telephony definitions such as JAIN Call Control (JCC), ECMA CSTA, and S.100.

We've chosen an event model for connections based on JCC (JSR 021). It abstracts away many of the differences between the networks mentioned above. There may be better models than JCC, but it fits the bill for what we need at the moment: a small and easily-understood call model so we can write concrete sample programs.

JCC was designed to be a cross-platform high-level event set to describe as generic a phone model as possible. The JCC call model consists of Addresses, Calls, Connections, and Providers. In the context of CCXML, we felt that the Address, Call, and Provider objects would add more complexity than value, so we omitted them as explicitly visible objects and focused on the behavior of Connections.

The CCXML call model therefore is based on the behavior of Connections. A call is received or initiated under control of a CCXML session through properties of a Connection.

In CCXML, a Connection is an object modeling a resource by which two independent unidirectional media streams, and optionally any associated network signaling traffic, can be controlled by a CCXML session. This corresponds roughly to a "call leg" as the term is used informally. <dialogstart> implicitly creates a Connection and bridges it to the Connection or Conference specified as an attribute of the <dialogstart> element. The behavior of Connections and bridges is discussed in Section 10.

Note that the JCC model is designed for endpoint devices only. Here is a fast description of the events. The descriptions and names are borrowed directly from the JavaSoft documentation.

Section 9.4.1: Connection Class

The state of a Connection object reflects events occurring at the telephony source it represents and actions taken by the CCXML document. The following state diagram shows the major aspects of Connection behavior, but omits some detail in favor of clarity.

The list of valid states that a connection can be in is:

• IDLE
• ALERTING
• PROGRESSING
• CONNECTED
• FAILED
• DISCONNECTED

Connections begin in the IDLE state and return to it when all other actions have been completed. The state diagram shows a DISCONNECTED state with a dotted line transition to IDLE. These states are essentially equivalent, IDLE/DISCONNECTED, and the dotted line transition occurs without the Connection emitting an event. Platforms may choose to implement one or both of these states.

• Transitions from IDLE/DISCONNECTED
  • connection.ALERTING event: the CCXML document is being notified of an incoming call; Connection transitions to ALERTING
  • <createcall> issued by the CCXML document; the Connection will emit a connection.PROGRESSING event and transition to PROGRESSING
• Transitions from ALERTING
  • <accept> issued by the CCXML document will connect the call; the Connection will emit a connection.CONNECTED event and transition to CONNECTED
  • <reject> issued by the CCXML document will reject the call; the Connection will emit a connection.FAILED event and transition to FAILED
  • <redirect> issued by the CCXML document will redirect the incoming call to another destination; the Connection will emit a connection.REDIRECTED event and transition to IDLE DISCONNECTED
    
  • a failure will result in a connection.FAILED event, and the Connection will transition to FAILED; the failure can occur before or after execution of CCXML elements
  • connection.ALERTING event if the network provides call progress indications
• Transitions from PROGRESSING
  • connection.CONNECTED event when the call is answered by the destination
  • connection.FAILED event when the call attempt is abandoned, which may indicate a busy, a no-answer, or other failure situation
  • connection.PROGRESSING event if the network provides call progress indications
• Transitions from CONNECTED
  • connection.DISCONNECTED event when the disconnect originates in the network; this requires not further action by the CCXML document;
  • <redirect> issued by the CCXML document will redirect the call to another destination; the Connection will emit a connection.REDIRECTED event and transition to IDLE/DISCONNECTED
  • <disconnect> issued by the CCXML document; the Connection will emit a connection.DISCONNECTED when the disconnect is completed.
  • connection.SIGNAL is emitted when additional Connection related information is available for processing by the CCXML application. The Connection remains in the CONNECTED state.
• Transitions from FAILED
  • the transition to IDLE DISCONNECTED will occur automatically after a short period of time, with no event emitted by the Connection, once the platform recovers from the failure
• Transitions from DISCONNECTED
  • Once a Connection enters DISCONNECTED, it transitions immediately to IDLE without further events being generated and without needing further action by the CCXML document

If a platform operational error occurs, the Connection will emit a connection.ERROR event, and transition to the ERROR state. A Connection will remain in the ERROR state until the error is corrected, and may then spontaneously transition to IDLE/DISCONNECTED. It will not transition to any other state from ERROR. The PROGRESSING and ALERTING states have reflexive transitions. This is intended to model protocols which have additional states at these points, and which may exchange messages such as PROCEEDING, ALERTING, FACILITY, or NOTIFY. Platforms may choose to implement addtional states which may be reflected in the substate property of the Connection object. Additional messages can be implemented with the CCXML <send> element.

Section 9.4.1.1: Connection Class Properties

An instance of the Connection class is associated with each telephony event source. Each instance is uniquely identified by its connection identifier. All Connection instances have a set of properties in common, shown in the following table. Properties marked with * only appear on an instance of the Connection class if they have a value. Other properties will always be present. Properties marked with + have been equated with those available in VoiceXML 2.0. In some cases, property names are slightly different in order to present the properties at a single level.

Connection Properties	Definitions
id	this property is the ECMAScript string value of the Connection identifier, which uniquely identifies each instance of the Connection class
state	this property identifies the current state of the Connection instance; the value of the state is a symbolic constant that is the name of the state
substate*	this property is a protocol-dependent property which allows further refinement of the state of a Connection, if desired
dialog*	this property is the identifier of an associated dialog, if there is one currently using the connection
local*+	this property is a URI which addresses the interpreter platform; for an incoming call, this is the called URI; for a redirected incoming call, this is also the most recent redirection, and the prior values are contained in the "redirect" property; for an outgoing call, this is the calling URI;
remote*+	this property is a URI which addresses the remote device; for an incoming call, this is the calling URI; for a redirected incoming call, this is the requestor of the most recent redirection, and prior values are contained in the "redirect" property; for an outgoing call, this is the called URI;
protocol*+	this property is a reference to an object defining protocol information for the protocol used on this connection; the referenced object defines information which applies to all connections using this protocol, and it has at least two properties: name - the name of the connection protocol; the name may also be a property on the connection instance referencing protocol specific information; if no further protocol specific information is available, then Connection[Connection.protocol.name] is undefined; (see Appendix F for a suggested set of protocol names) version - the version of the connection protocol For example, the assignment of protocol-dependent user-to-user information to a variable tmp from a Connection instance referenced by the variable cx would be: <assign name="tmp" expr="cx[cx.protocol.name].uui"/>
redirect*+	this property is an array representing the connection redirection paths; the first element, Connection.redirect[0], is the original number, and the last element is the most recent redirected number; each element of the array may define any of the following four properties: uri - this element's path pi - presentation information si - screening information reason - for example, "unknown", "user busy", "no reply", "deflection during alerting", "deflection immediate response", "mobile subscriber not reachable"
aai*+	this property is the application-to-application information passed during connection setup
originator*+	this property is set to either "local" or "remote" and indicates the originator of the connection; for an incoming call, this property is set to "remote"; for an outgoing call, it is set to "local"; For example, the assignment of the originating URI to a variable uri from a Connection instance referenced by the variable cx would be: <assign name="uri" expr="cx[cx.originator]"/>

Platforms may choose to add properties to Connection instances. By convention, the properties should begin with an underscore, "_", to identify them as platform-dependent.

Section 9.4.2: Connection Events

Section 9.4.2.1: connection.* Events

CCXML applications are notified of Connection activities by events, which often reflect Connection state changes. Applications may also take actions which change the state of a Connection and which cause other events to be generated.

All Connection events have a set of properties in common, shown in the following table. Fields marked with an asterisk only appear on the event object if they have a value. Other fields will always be present.

Common Field Names	Definitions
name	this property is set to the ECMAScript string value of the event name
connid	this property is the ECMAScript string value of the ID of the Connection object associated with this event
protocol*	this property is an ECMAScript string which identifies the protocol used by the event source; although this property is optional, it is recommended that platforms provide it in order to allow applications to tailor their behavior (see Appendix F for a suggested set of protocol identifiers)
info*	this property provides a reference to an object which may contain platform or protocol dependent information specific to the event
reason*	this property, although not provided by every event, when present provides a code indicating the status of the operation which triggered this event, or a reason for the occurrence of this event
connection	an ECMAScript object reference to the Connection object identified by the connid property for this event

Platforms may choose to add properties to events. By convention, the properties should begin with an underscore, "_", to identify them as platform-dependent.

Platforms must provide a global method to convert symbolic connection identifiers, connid's, to object references. This method, connidReference(connid), takes a connection identifier as its only parameter and returns the object reference of the Connection object corresponding to the passed identifier, or null if the identifier does not refer to an instance of the Connection class. The connection property in the above table may be considered to be the result of calling this method with the connid property as its argument.

Section 9.4.2.2: connection.ALERTING

This event is emitted when a Connection transitions to the ALERTING state, or is notified of call progress in the ALERTING state.

The fields of this event are:

Field Name	Details
name	"connection.ALERTING"
connid	The ID of the Connection associated with this event
protocol*	The platform protocol ID of the Connection protocol
info*	An object which provides additional platform or protocol dependent information
connection	an ECMAScript object reference to the Connection object identified by the connid property for this event

Information provided by the protocol prior to connection is accumulated and stored with the identified Connection object. This information will be available when the ALERTING event is delivered to the application.

Any further information provided by the protocol prior to connection will be provided in subsequent ALERTING events, and made available in the updated Connection object. Call related information provided after connection will result in connection.SIGNAL events.

Section 9.4.2.3: connection.PROGRESSING

This event is emitted when a Connection transitions to the PROGRESSING state as a result of <createcall>, or is notified of call progress in the PROGRESSING state.

The fields of this event are:

Field Name	Details
name	"connection.PROGRESSING"
connid	The ID of the Connection associated with this event
protocol*	The platform protocol ID of the Connection protocol
info*	An object which provides additional platform or protocol dependent information
connection	an ECMAScript object reference to the Connection object identified by the connid property for this event

Section 9.4.2.4: connection.CONNECTED

This event is emitted when a Connection transitions to the CONNECTED state as a result of <accept>.

The fields of this event are:

Field Name	Details
name	"connection.CONNECTED"
connid	The ID of the Connection associated with this event
protocol*	The platform protocol ID of the Connection protocol
info*	An object which provides additional platform or protocol dependent information
connection	an ECMAScript object reference to the Connection object identified by the connid property for this event

Section 9.4.2.5: connection.DISCONNECTED

This event is emitted when a Connection transitions to the DISCONNECTED state, as a result of either CCXML action or off-platform events.

The fields of this event are:

Field Name	Details
name	"connection.DISCONNECTED"
connid	The ID of the Connection associated with this event
protocol*	The platform protocol ID of the Connection protocol
reason*	A disconnection reason code
info*	An object which provides additional platform or protocol dependent information
connection	an ECMAScript object reference to the Connection object identified by the connid property for this event

Section 9.4.2.6: connection.REDIRECTED

This event is emitted when a Connection transitions to the DISCONNECTED state as a result of <redirect>.

The fields of this event are:

Field Name	Details
name	"connection.REDIRECTED"
connid	The ID of the Connection associated with this event
protocol*	The platform protocol ID of the Connection protocol
reason*	A redirect result code.
info*	An object which provides additional platform or protocol dependent information
connection	an ECMAScript object reference to the Connection object identified by the connid property for this event

Section 9.4.2.7: connection.FAILED

This event is emitted when a Connection transitions to the FAILED state, when an incoming or outgoing call fails to complete its connection.

The fields of this event are:

Field Name	Details
name	"connection.FAILED"
connid	The ID of the Connection associated with this event
protocol*	The platform protocol ID of the Connection protocol
reason*	A failure reason code
info*	An object which provides additional platform or protocol dependent information
connection	an ECMAScript object reference to the Connection object identified by the connid property for this event

Section 9.4.2.8: connection.ERROR

This event is emitted when a Connection transitions to the ERROR state.

The fields of this event are:

Field Name	Details
name	"connection.ERROR"
connid	The ID of the Connection associated with this event
protocol*	The platform protocol ID of the Connection protocol
reason*	An error code if one is available
info*	An object which provides additional platform or protocol dependent information
connection	an ECMAScript object reference to the Connection object identified by the connid property for this event

Section 9.4.2.9: connection.SIGNAL

This event is emitted when a Connection is notified of new data available when in the CONNECTED state. The fields of this event are:

Field Name	Details
name	"connection.SIGNAL"
connid	The ID of the Connection associated with this event
protocol*	The platform protocol ID of the Connection protocol
info*	An object which provides additional platform or protocol dependent information

Examples where connection.SIGNAL could be generated include:

• DTMF received on the media stream after connection, perhaps identifying call setup information such as DNIS;
• Messaging received by the protocol after connection, such as that delivered by SIP INFO or ISDN FACILITY messages;
• Call analysis results indicating the results of answering machine, FAX, or modem detection attempt.

The data provided within the connection.SIGNAL event is protocol dependent. This data may be used to initiate a dialog (for example, if all required information is now available), or to message other platform components.

Signalling delivered on the media stream after a successful <dialogstart> may not be available to the CCXML application. This behavior is platform dependent.

All available call setup information is provided in the Connection object when the first connection.ALERTING event is generated. Any further information provided by the protocol prior to connection will be provided in subsequent ALERTING events, and made available in the updated Connection object. Call related information provided after connection will result in connection.SIGNAL events.

The Connection Object may be updated with new or changed information as the result of a connection.SIGNAL event.

Section 9.4.3: Standard Events

The second, smaller set, is only for language purposes. Of these, there are a) events sent from dialogs, and b) events sent from the CCXML interpreter. The standard events are described here.

• ccxml.loaded indicates that the script has just been completely loaded by the interpreter. This is a convenient time to perform script start-up processing.
• ccxml.fetch.done indicates that a CCXML fetch operation has completed.
• ccxml.joined indicates that a join operation has succeeded.
• ccxml.authenticated indicates that a <authenticate> operation has succeeded.

For dialog related events please see section 7.3 on dialog events.

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

Section 10: Telephony Operations and Resources

This section contains information on the <accept>, <createcall>, <createconference>, <destroyconference>, <disconnect>, <join>, <redirect>, <reject>, and <unjoin> elements.

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.

In CCXML, a Connection is an object modeling a resource by which two independent unidirectional media streams, and optionally any associated network signaling traffic, can be controlled by a CCXML session. This corresponds roughly to a "call leg" as the term is used informally.

The CCXML call model is based on the behavior of Connections. A network call is received or initiated under control of a CCXML session through properties of a Connection.

<dialogstart> implicitly creates a Connection and bridges it to another Connection or to a Conference specified as an attribute of the <dialogstart> element. In other words, to facilitate interaction between a network party and a dialog, two connections are required: one connection is associated with the network call, and the other connection is associated with the dialog.

Each Connection has one input by which it receives a media stream from another Connection or Conference.

Each Connection has one output media stream that can be directed to the inputs of multiple Connections and/or Conferences.

If a network call is active on a Connection, the media stream received from the network is the Connection output, and the Connection input media stream is transmitted to the network.

For a Connection created by <dialogstart>, the Connection input media stream is available to a recognizer under control of the CCXML session, and the Connection output media stream can be sourced from a resource (such as a TTS engine) under control of the CCXML session.

A "bridge" is a relationship between the input and/or output streams of connections or conferences. This is discussed in greater detail in Section 10.4.

Section 10.1: Incoming Calls

Section 10.1.1: Overview

One of the events a CCXML document can receive is a call setup indication. A CCXML session interested in handling incoming calls will have an eventhandler transition block for execution. The transition block will either accept, reject, or redirect the incoming call using the <accept>, <reject> or <redirect> CCXML elements. The underlying platform will signal the telephony system appropriately, depending on the element. Once the call is accepted, the CCXML document may initiate interactive dialog sessions with the incoming caller, or perform other telephony operations (e.g., place outgoing calls, join calls, etc).

Section 10.1.2: <accept>

Section 10.1.2.1: Overview

The <accept> element will accept and connect an incoming phone call.

Section 10.1.2.2: accept Attribute Details

Section 10.1.3: <redirect>

Section 10.1.3.1: Overview

The <redirect> element will redirect an incoming phone call.

Section 10.1.3.2: redirect Attribute Details

Section 10.1.4: <reject>

Section 10.1.4.1: Overview

The <reject> element will reject an incoming phone call.

Section 10.1.4.2: reject Attribute Details