W3C

Voice Browser Call Control: CCXML Version 1.0

W3C Working Draft 30 April 2004

This version:
http://www.w3.org/TR/2004/WD-ccxml-20040430/
Latest version:
http://www.w3.org/TR/ccxml/
Previous version:
http://www.w3.org/TR/2003/WD-ccxml-20030612/
Editor:
RJ Auburn, Voxeo <rj@voxeo.com>

Copyright © 2004 W3C ® ( MIT , ERCIM, Keio ), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.

Abstract

This document describes CCXML, or the Call Control eXtensible Markup Language. CCXML is designed to provide telephony call control support for VoiceXML [VOICEXML] or other dialog systems. CCXML has been designed to complement and integrate with a VoiceXML interpreter. Because of this there are many references to VoiceXML's capabilities and limitations. There are also 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 Interactive Voice Response (IVR) system and VoiceXML or other dialog systems could be integrated with some other call control systems.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

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 version of the specification has a large number of editorial changes to clarify sections that were ambiguous or incomplete. A number of sections have been completely rewritten. Major changes include:

For a detailed list please see Changes in Last Call Working Draft.

This is a W3C Last Call Working Draft for review by W3C Members and other interested parties. Last Call means that the Working Group believes that this specification is technically sound and therefore wishes this to be the Last Call for comments. If the feedback is positive, the Working Group plans to submit it for consideration as a W3C Candidate Recommendation. Comments can be sent until 28 May 2004.

Although an Implementation Report Plan has not yet been developed for this specification, the Working Group currently expects to require at least two independently developed interoperable implementations of each required feature, and at least one implementation of each feature, in order to exit the next phase of this document, the Candidate Recommendation phase. To help the Voice Browser Working Group build such a report, reviewers are encouraged to implement this specification and to indicate to W3C which features have been implemented, and any problems that arose.

This document is for public review. 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 on-line.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document has been produced under the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.

Conventions of this Document

In this document, the key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" are to be interpreted as described in [RFC2119] and indicate requirement levels for compliant VoiceXML implementations.

Table of Contents

1: Introduction

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

CCXML can provide a complete telephony service application, comprised of Web server CGI compliant application logic, one or more CCXML documents to declare and perform call control actions, and to control one or more dialog applications that perform user media interactions

Since platforms implementing CCXML MAY choose to use one of many telephony call control definitions ( JAIN Call Control [ JSR021 ], ECMA CSTA [ CSTA ], S.100 [ S.100 ], etc.), the call control model in CCXML has been designed to be sufficiently abstract so that it can accommodate all major definitions. For relatively simple types of call control, this abstraction is straightforward. The philosophy in this regard has been to "make simple things simple to do." Outdial, transfer (redirect), two-party bridging, and many forms of multi-party conferences fall within this classification.

Figure 1 shows the architecture of a telephony implementation consisting of three primary components:

The Telephony Web Application may or may not be integrated with the Voice Web Application.

The Telephony Control and Dialog Control Interfaces may be implemented as an API or protocol.

The components as shown in the figure below represent logical functions, and are not meant to imply any particular architecture.

CCXML architecture overview
Figure 1

2: Motivation (Informative)

CCXML is designed to complement VoiceXML by providing advanced telephony functions. It also can be used as a third-party call control manager in any telephony system. This document contains references to VoiceXML's capabilities and limitations, as well as details on how VoiceXML and CCXML can be integrated.

The CCXML specification originated from the desire to handle call control requirements that were beyond the scope of the VoiceXML specification. The following requirements are addressed by this specification:

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.

3: Concepts and Architecture

A CCXML application consists of a collection of CCXML documents that control and manage the objects listed below:

CCXML programs manipulate these entities through elements defined in the CCXML language. They can also send and/or receive asynchronous events (mentioned above) associated with these entities.

CCXML programs directly manipulate Connection Objects and Conference Objects with various elements in the language, such as <accept>, <createconference>, and <join>. 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. Connections and Conference Objects do not accept events; CCXML must use the builtin elements to direct them.

CCXML programs 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.

CCXML programs can create other CCXML sessions using <createccxml>. This is the only guaranteed control mechanism a CCXML Session ever wields over another. Any other interaction takes place through the event mechanism. CCXML Sessions can both send and receive events between one another.

3.1: Event Processing

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. There are mechanisms for passing information back and forth between Voice Dialogs (such as VoiceXML) and CCXML, but the important points are that CCXML:

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

3.1.1: CCXML / VoiceXML event relationship

All asynchronous event processing is handled in a CCXML Session. Every executing VoiceXML Dialog 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 processing the event at the head of the event queue. Meanwhile, the VoiceXML Dialog can interact with the user, undisturbed by the incoming flow. Most VoiceXML implementations never need to consider event processing at all.

3.2: Conferencing

CCXML provides a powerful and flexible method of creating multi-party calls based on on the following concepts:

3.4: Scripting

The computational semantics of CCXML language is based on the ECMAScript Compact Profile (ES-CP, also known as ECMA-327) [ECMA327]. ES-CP is a strict subset of the third edition of ECMA-262 [ECMASCRIPT]. Execution efficiency is a primary goal of CCXML implementations, and ES-CP was chosen to ensure that CCXML implementations can operate in a variety of execution environments and without excessive execution overhead.

The ES-CP document specification 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.'

While CCXML implementations are not necessarily intended for battery powered embedded devices, it is intended to be used in 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. For example, a CCXML implementation, for optimization purposes, could translate and compile frequently used CCXML documents 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 same document.

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

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

A CCXML implementation MUST support the ECMAScript Compact Profile.

3.5 Definitions

The following terms, which are used throughout this specification, are defined as:

3.6: Session Life-Cycle

3.6.1: Startup

A CCXML session can be started for the following reasons:

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. If the session was started because of a <createccxml>, it will start without ownership of any event endpoints unless an event was forwarded using the start attribute of <createccxml>, in which case the associated event endpoint would then be owned by the new CCXML session. In the case of an external session launch the session will not own any event endpoints.

A CCXML application can determine the reason its session was started by evaluating the contents of the session.startupmode session variable that is defined in the Session Variables section.

3.6.2: Shutdown

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

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

3.6.3: Session Life-Cycle Diagrams

The following diagrams illustrate the session life-cycle of several different scenarios. These diagrams do not show all possible scenarios but rather show some of the most common ones that CCXML applications may encounter.

3.6.3.1: session can live before and after active connections (or no connections at all)

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.

Session lifecycle diagram
3.6.3.2: connection life shorter than session

In this example, the session is started due to an incoming call. A connection is typically shorter than a session. A session does not end when a connection terminates.

Session lifecycle diagram
3.6.3.3: session ends, kills all active connections

When a session ends, any resources, including connections owned by that session are terminated.

Session lifecycle diagram
3.6.3.4: session can have multiple sequential connections

A session can have multiple sequential connections

Session lifecycle diagram
3.6.3.5: session can have multiple sequential connections and multiple concurrent connections

In addition to having multiple sequential connections, a session can have multiple concurrent connections.

Session lifecycle diagram
3.6.3.6: move a connection to a newly created session

A connection can be moved from one CCXML session to another session. In the figure below, CCXML session (1) creates a new CCXML session (2) via <createccxml>. Then, the connection is moved from the original CCXML session to the new session.

Session lifecycle diagram
3.6.3.7: move a connection to a "master" session

A connection can be moved from one CCXML session to another session, such as a "master" session.

Session lifecycle diagram

4: Simple Examples

4.1: Hello World

This simple CCXML document shows an example of a "hello world" 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:

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
  <eventprocessor>  
    <transition event="connection.alerting" name="evt">
      <var name="MyVariable" expr="'This is a CCXML Variable'"/>
      <log expr="'Hello World. I just made a variable: ' + MyVariable"/>
      <log expr="'Lets hang up on this incoming call as this is an example.'"/>
      <exit/>
    </transition>    
  </eventhandler>
</ccxml>

4.2: Accept or Reject a Call

This CCXML document shows an example of how to process a incoming call event and answer or reject the call based on the phone number of the calling party:

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
  <eventprocessor>
  
    <transition event="connection.alerting" name="evt">
      <log expr="'The phone number the user called is' + evt.connection.remote + '.'"/>
      <if cond="evt.connection.remote == '8315551234'">
        <log expr="'Go away! we do not want to answer the phone.'"/>
        <reject/>
      <else/>
        <log expr="'We like you! We are going to answer the call.'"/>
        <accept/>
      </if>
    </transition>
    <transition event="connection.connected">
      <log expr="'Call was answered, we are now going to disconnect it.'"/>
      <disconnect/>
    </transition>
    <transition event="connection.disconnected">
      <log expr="'Call has been disconnected. We should now end the CCXML session.'"/>
      <exit/>
    </transition>
    
  </eventhandler>
</ccxml>

4.3: Simple Dialog

This is an example of running a simple VoiceXML dialog from CCXML. The application answers a incoming phone call and then connects it to a VoiceXML dialog that returns a value that is then logged to the platform:

dialog.ccxml:

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0">
  <!-- Lets declare our state var -->
  <var name="state0" expr="'init'"/>
  
  <eventprocessor statevariable="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.'"/>
      <dialogstart src="'gimme.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>
  </eventhandler>    
</ccxml>

dialog.vxml:

<?xml version="1.0"?>
<vxml xmlns="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>

5: CCXML Elements Listing

<accept> Accept an incoming phone call
<assign> Assign a variable a value
<cancel> Cancel a CCXML event timer
<ccxml> CCXML container element
<createcall> Make an outbound call
<createccxml> Create a new CCXML session
<createconference> Create a multi-party audio conference
<destroyconference> Destroy a multi-party audio conference
<dialogstart> Start a dialog session's execution
<dialogterminate> Stop a dialog session's execution
<disconnect> Terminate a phone connection
<else> Used in <if> statements
<elseif> Used in <if> statements
<eventprocessor> Block of event-processing statements
<exit> Ends execution of the CCXML session
<fetch> Preload a CCXML file
<goto> Move execution to a new location
<if> Conditional logic
<join> Connect two audio sources
<log> Log to the platform debug log
<move> Move a event to another ccxml session
<redirect> Redirect an incoming call to a new endpoint
<reject> Reject an incoming phone call
<script> Run ECMA Script
<send> Generate an event
<transition> A single event-processor block
<unjoin> Disconnect two audio sources
<var> Declare a variable

6: Document Control Flow and Execution

6.1: Overview

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 can consist of multiple CCXML documents, traversed by use of <goto> and <fetch>.

A new CCXML session has a new session object (session.*), where initially the length of the connection array is 0. A CCXML session contain multiple active connections.

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>.

The media type application/ccxml+xml will be registered for CCXML documents.

The proposed definition of the media type is at J The CCXML Media Type

This media type should be used for a XML document containing a CCXML document.

6.2: Elements

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

6.2.1: <ccxml>

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> 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 <ccxml> can designate the CCXML namespace. This can be achieved by declaring an xmlns attribute or an attribute with an " xmlns " prefix. See [XMLNS] for details. Note that when the xmlns attribute is used alone, it sets the default namespace for the element on which it appears and for any child elements. The namespace URI for CCXML is "http://www.w3.org/2002/09/ccxml".

6.2.1.2: <ccxml> Attribute Details
Attribute Name Details
version The version of this CCXML document (REQUIRED). The initial version number is 1.0.
xml:base The base URI for this document as defined in [XML-BASE]. As in [HTML], a URI which all relative references within the document take as their base. (OPTIONAL)

6.2.2: <meta>

6.2.2.1: Overview

The <metadata> and <meta> are containers in which information about the document can be placed. The <metadata> provides more general and powerful treatment of metadata information than <meta> by using a metadata schema.

A <meta> declaration associates a string to a declared meta property or declares " http-equiv " content. Either a name or http-equiv attribute is REQUIRED. It is an error to provide both name and http-equiv attributes. A content attribute is REQUIRED. The seeAlso property is the only defined <meta> property name. It is used to specify a resource that might provide additional metadata information about the content. This property is modelled on the rdfs:seeAlso property of Resource Description Framework (RDF) Schema Specification 1.0 [RDF-SCHEMA §2.3.4]. The http-equiv attribute has a special significance when documents are retrieved via HTTP. Although the preferred method of providing HTTP header information is by using HTTP header fields, the " http-equiv " content MAY be used in situations where the CCXML document author is unable to configure HTTP header fields associated with their document on the origin server, for example, cache control information. Note that, as with <meta> in HTML documents [HTML], HTTP servers and caches are not REQUIRED to introspect the contents of <meta> in CCXML documents and thereby override the header values they would send otherwise.

Informative: This is an example of how <meta> can be included in a CCXML document to specify a resource that provides additional metadata information and also indicate that the document MUST NOT be cached.

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0"
       xmlns="http://www.w3.org/2002/09/ccxml">
       <meta name="seeAlso"
content="http://example.com/my-ccxml-metadata.xml"/>
       <meta http-equiv="Cache-Control" content="no-cache"/>
</ccxml>

<meta> is an empty element.

6.2.2.2: <meta> Attribute Details
Attribute Name Details
name The name of the metadata property.
content The value of the metadata property.
http-equiv The name of an HTTP response header.

6.2.3: <metadata>

6.2.3.1: Overview

<metadata> is a container in which information about the document can be placed using a metadata language. Although any metadata language can be used within <metadata>, it is recommended that the Resource Description Format [RDF] be used in conjunction with the general metadata properties defined by the Dublin Core Metadata Initiative [DC].

RDF [RDF-SYNTAX] is a declarative language and provides a standard way for using XML to represent metadata in the form of statements about properties and relationships of items on the Web. A recommended set of generally applicable metadata properties (e.g., " title ", " creator ", " subject ", " description ", " copyrights ", etc.) is the Dublin Core Metadata Element Set [DC], used in the example below.

Document properties declared with <metadata> can use any metadata schema.

Informative: This is an example of how <metadata> can be included in a CCXML document using the Dublin Core version 1.0 RDF schema [DC] describing general document information such as title, description, date, and so on:

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0"
       xmlns="http://www.w3.org/2002/09/ccxml">
  <metadata>
   <rdf:RDF
       xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:dc = "http://purl.org/dc/elements/1.1/">
   <!-- Metadata about CCXML document -->
   <rdf:Description rdf:about="http://www.example.com/meta.ccxml"
       dc:title="Hamlet-like Soliloquy"
       dc:description="Aldine's Soliloquy in the style of Hamlet"
       dc:publisher="W3C"
       dc:language="en"
       dc:date="2002-11-29"
       dc:rights="Copyright 2002 Aldine Turnbet"
       dc:format="application/ccxml+xml" >
       <dc:creator>William Shakespeare</dc:creator>
       <dc:creator>Aldine Turnbet</dc:creator>
   </rdf:Description>
  </rdf:RDF>
 </metadata>
</ccxml>

The following CCXML elements can occur within the content of <metadata> : none .

6.2.3.2: <metadata> Attribute Details
Attribute Name Details
none none

6.2.2: <if>

6.2.2.1: Overview

<if> is a container for conditionally executed elements. <else> and <elseif> can optionally appear within an <if> as immediate children, and serve to partition the elements within an <if>. <else> and <elseif> have no content. <else/> is a synonym for <elseif cond="true"/>.

Each partition within an <if> is preceded by an element having a cond attribute. The initial partition is preceded by the <if> and subsequent partitions by <elseif> 's (or <else> 's). The first partition in document order with a cond that evaluates to true is selected. <else> always evaluate to true. A partition MAY be empty.

If an <if> has no immediate <elseif> or <else> children, the full contents of the <if> will be selected when the cond attribute is true.

<else> was chosen to match similar concepts in other languages, and supports examples such as

<if cond="...">
  <!-- selected when <if cond> is true -->
  <else>
    <!-- selected when <if cond> is false -->
  </if>.

However, <else> is a synonym for <elseif cond="true"/>, so an example such as

<if cond="...">
  <!-- selected when <if cond> is true -->
<else/>
  <!-- selected when <if cond> is false -->
<else/>
  <!-- never selected -->
</if>
is also possible and SHOULD be interpreted as 
<if cond="...">
  <!-- selected when <if cond> is true -->
<elseif cond="true"/>
  <!-- selected when <if cond> is false -->
<elseif cond="true"/>
  <!-- never selected -->
</if>.
With this definition for <else>, a valid XML [XML] document is also a valid CCXML document.
6.2.2.2: <if> Attribute Details
Attribute Name Details
cond An ECMAScript expression which can be evaluated to true or false.

6.2.3: <elseif>

6.2.3.1: Overview

An <elseif> partitions the content of an <if>, and provides a condition that determines the selection of the partition it begins. <elseif> can appear optionally as an immediate child of an <if>.

6.2.3.2: <elseif> Attribute Details
Attribute Name Details
cond An ECMAScript expression which can be evaluated to true or false.

6.2.4: <else>

6.2.4.1: Overview

<else> is a synonym for <elseif cond="true"/>.

6.2.4.2: <else> Attribute Details
Attribute Name Details
none none

6.2.5: <fetch> and <goto>

6.2.5.1: Overview

<fetch>, together with <goto>, is used to transfer execution to a different CCXML document in a multi-document CCXML application. In CCXML we break the document transition into two parts. The <fetch> tells the platform to find, load, and parse a given CCXML document. Execution returns from the element immediately, and the CCXML application can continue on while the platform works to get the target document ready for execution. When the <fetch> completes, the session which issued the fetch receives a fetch completion event. It can then issue a <goto> to immediately start executing the now-fetched document.

Below is a small snippet of code from the CCXML application'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 platform services the event, and the application performs 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 documents, but it is wasteful to not do so.

Asynchronous execution of a <fetch> 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 session 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> 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.

A <goto> transfers control to the document identified by the fetch ID. The execution of a <goto> 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> 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.

Platforms are responsible for clearing out unused fetch resources. When a session is terminated any associated fetches MAY be released.

6.2.5.2: <fetch> Attribute Details
Attribute Name Details
next an ECMAScript expression which returns the URI of the CCXML document to be fetched.
namelist a list of zero or more whitespace separated CCXML variable names. These variable names and their associated values will be included in the URI sent to the server, with the same qualification used in the namelist.
method an ECMAScript expression which returns a character string that indicates the HTTP method to use. Valid values are " get " and " post ". The default is " get ".
fetchid is an ECMAScript left-hand-side expression which receives an internally generated unique string identifier to be associated with the completion event. This identifier can be tested by the fetch completion event handler to distinguish among several outstanding fetch requests. If this attribute is not specified, the fetch ID can be acquired from the fetch completion event. Every fetch request will receive a unique fetch ID, even requests for the same document.
synch is an ECMAScript left-hand-side expression that is set to the fetch completion event. The specification of this attribute in a <fetch> implies a blocking fetch, which will be executed synchronously. If this attribute is not specified, the fetch is asynchronous.
timeout is an ECMAScript expression returning a string in CSS2 [CSS2] format interpreted as a time interval. The interval begins when the <fetch> is executed. The fetch will fail if not completed at the end of this interval. A failed fetch will return the error.fetch event.
6.2.5.3: <goto> Attribute Details
Attribute Name Details
fetchid an ECMAScript expression which returns the fetch ID of a document referenced in a fetch completion event. The fetch ID can be acquired in a <fetch> with the fetchid attribute. The fetch completion event also provides a property whose value is the fetch ID of the document fetched.

6.2.6: <createccxml>

6.2.6.1: Overview

<createccxml> 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 new CCXML session has no relation to its creator once spawned, and has a wholly separate lifetime and address space.

Execution returns from the <createccxml> element immediately, and the CCXML interpreter can continue on while the new CCXML session is established and loads its initial document. If the new session is successfully established or a failure occurs an event is generated and is delivered to the session that executed the <createccxml> element.

6.2.6.2 <createccxml> Attribute Details
Attribute Name Details
next an ECMAScript expression which returns the URI of the CCXML document that will begin execution in the new session.
namelist a list of zero or more whitespace separated CCXML variable names. These variable names and their associated values will be included in the URI sent to the server, with the same qualification used in the namelist.
method an ECMAScript expression which returns a character string that indicates the HTTP method to be used, by the new session, when fetching the initial document. Valid values are " get " and " post ". The default is " get ".
start an ECMAScript expression which returns an event object which is the initial event for the new session. This event will be the first event sent to the document started by this element. The endpoint which originated this event will be inherited by the new session. This attribute is OPTIONAL.
sessionid an ECMAScript left-hand-side expression that is set to an internally generated unique string identifier which identifies the newly created session. This attribute is OPTIONAL.
timeout is an ECMAScript expression returning a string in CSS2 [ CSS2 ] format interpreted as a time interval. The time interval is interpreted by the new CCXML session as the maximum time it should wait for completion of the fetch for the initial document specified by the next attribute. If the new CCXML session is unable to fetch the initial document within the timeout interval, an error.createccxml event MUST be thrown.

6.2.7: <exit>

6.2.7.1: Overview

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

6.2.7.2 <exit> Attribute Details
Attribute Name Details
expr A return ECMAScript expression (e.g. 0 or 'oops!'). This attribute is OPTIONAL ; if omitted, a value of zero is assumed. This value is stored as a property of the exit event.
namelist a list of zero or more whitespace separated CCXML unqualified variable names to be returned which will be set as properties of the exit event.

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

6.2.8: <log>

6.2.8.1: Overview

<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. The usage of label is platform-dependent. The use of <log> SHOULD have no other side-effects on interpretation. <log>is an empty element.

6.2.8.2 <log> Attribute Details
Attribute Name Details
label an ECMAScript expression which returns a character string which MAY be used, for example, to indicate the purpose of the log
expr An ECMAScript expression evaluating to a string to be logged

6.3: Events

6.3.1: Overview

CCXML allows operations such as document fetching, startup and shutdown to execute independently. CCXML events that describe these operations are defined below:

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:

Field Name Details
name fetch.done
fetchid The internally generated unique fetch identifier
uri The URI of the fetch request.

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:

Field Name Details
name error.fetch
fetchid The internally generated unique fetch identifier
reason A string description of the fetch error.
uri The URI of the fetch request.

6.3.4: ccxml.exit - CCXML Document Exit Event

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

The fields of this event are:

Field Name Details
name ccxml.exit
sessionid the identifier of the exiting session; this is the same value returned to the sessionid attribute of the <createccxml> which created this session;
expr the value of the <exit> expr attribute;
namelist If the namelist attribute was specified in the <exit>, this property is a string valued array of the names in the list. The length of the property is equal to the number of names in the list. The actual values are stored in the " values " sub-object.
values.* Each name in the namelist is a property whose value is the value of the name at the time the <exit> was executed.

6.3.5: ccxml.loaded - CCXML Document Loaded Event

This event is thrown once the document is parsed and ready for execution (document initialization occurs between the fetched and loaded events). 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>. This event would be processed after the platform had executed the document initialization including executing any elements under the <ccxml> .

The fields of this event are:

Field Name Details
name ccxml.loaded
sessionid the identifier of the session on which this document is executing;
parent the identifier of the session which issued the <createccxml> to start this document; if this document was started directly by the CCXML platform, the identifier is 0

6.3.6: ccxml.kill - CCXML kill Event

The kill event can be used by the platform to terminate a session without an explicit <exit>. There are two versions of this event: catchable, and non-catchable. The ccxml.kill event can be caught, typically to perform a clean-up operation at the end of a session. Unlike other events, the ccxml.kill.unconditional event is the only event that cannot be caught by an application; it will unconditionally terminate the session end.

The fields of this event are:

Field Name Details
name ccxml.kill
sessionid the identifier of the session
reason a string describing the reason the platform sent the kill event. Content of this field is platform-specific, and is only for informative purposes.

6.3.7: ccxml.created - CCXML Session Create Completion Event

This event is generated when a <createccxml> request completes successfully. It is delivered to the document which issued the request and indicates that the new session has retrieved the specified initial CCXML document and has begun execution of it.

The fields of this event are:

Field Name Details
name ccxml.created
sessionid The identifier of the newly created CCXML session. This is the same identifier as was returned on the sessionid attribute of the <createccxml> request that created the session.

6.3.8: error.createccxml - CCXML Session Create Failed Event

This event is generated when a <createccxml> request fails to complete. It is delivered to the document which issued the request and indicates that the new session has not been created.

The fields of this event are:

Field Name Details
name error.createccxml
sessionid The identifier of the failing CCXML session. This is the same identifier as was returned on the sessionid attribute of the <createccxml> request that created the session.
reason A string description of the error encountered.

6.3.9: error.unsupported - CCXML Unsupported Operation

This event is generated when an OPTIONAL operation that is not supported by the platform is executed.

The fields of this event are:

Field Name Details
name error.unsupported
reason A string description of the error encountered.

7: Dialogs

7.1: Overview

CCXML does not provide any mechanism for interacting with callers but relies on separate dialog environments such as VoiceXML [ 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. When the interaction is complete, control returns to the CCXML session which can use any results returned by the dialog environment to decide what should happen next.

Dialogs initiated by CCXML sessions are not tied to any single dialog language or technology. The requirements on a dialog environment are very small so that VoiceXML, SALT [ SALT ], and even traditional IVR languages and platforms MAY be used with CCXML. A CCXML platform MAY support interaction with several dialog systems with the selection of the particular technology being based on the MIME type specified when the dialog is initiated.

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. 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 behaviour may vary depending on the dialog environments supported.

The following examples illustrate the valid use patterns for these three elements. Firstly the normal case of preparing a dialog, starting it, then optionally terminating it before normal completion. This example illustrates the use of <dialogprepare> to ready a dialog while the call is left in alerting state. When the alerting notification arrives the script executes a <dialogprepare> to prepare a dialog and associate it with the connection. When the dialog is prepared the script executes an <accept> to connect the call and then when the connection transitions to connected state, a <dialogstart> element is used to execute the previously prepared dialog.

<transition event="connection.alerting" name="evt">
    <dialogprepare src="..." connectionid="evt.connectionid"/>
</transition>
<transition event="dialog.prepared" name="evt">
    <accept connectionid="session.dialogs[evt.dialogid].connectionid"/>
</transition>
    
<transition event="connection.connected" name="evt">
    <dialogstart prepareddialogid="evt.dialogid" connectionid="evt.connectionid"/>
</transition>
    
(optionally)
<transition event="???">
    <dialogterminate dialogid="..." />
</transition>

The next example shows a single step dialog invocation without dialog preparation. In this case a connection in alerting state is accepted and, when the transition to connected state occurs, a <dialogstart> element is used to start the dialog.

<transition event="connection.alerting" name="evt">
    <accept connectionid="evt.connectionid"/>
</transition>
    
<transition event="connection.connected" name="evt">
    <dialogstart src="..." connectionid="evt.connectionid"/>
</transition>
    
(optionally)
<transition event="???">
    <dialogterminate dialogid="..." />
</transition>

The final example shows the case where a dialog which has been previously prepared is cancelled before a <dialogstart> has been issued. A dialog may be terminated when it is in the prepared state or while it is being prepared such as might be the case if the caller hangs up at some arbitrary point. In this case the <dialogterminate> may be executed before or after the dialog.prepared event is processed.

<transition event="connection.connected"> name="evt">
    <dialogprepare src="..." connectionid="evt.connectionid"/>
</transition>
<transition event="connection.disconnected" name="evt">
    <dialogterminate dialogid="evt.connection.dialogid" />
</transition>

7.2: Elements

7.2.1: <dialogprepare>

7.2.1.1: Overview

<dialogprepare> is used to get an appropriate dialog handler ready to process, it is used as the precursor to a <dialogstart> request. The element includes a URI reference to the initial document for the dialog. The new dialog is prepared on a separate logical execution thread (this MAY be a thread, process, or system depending upon platform implementation) and does not block the processing of further events by the CCXML session. The use of the <dialogprepare> element is entirely optional, applications may choose to simply use <dialogstart> without prior preparation.

Optionally then new dialog may be associated with a connection by specifying the connectionid attribute. The association with the connection may be overridden by specifying a connectionid or conferenceid on a subsequent <dialogstart> request.

When preparation of the dialog competes successfully a dialog.prepared event is posted to the event queue of the CCXML session. If however the dialog cannot be prepared for any reason, an error.dialog.notprepared event is posted.

CCXML implementations MUST support dialog preparation though the processing carried out as part of a <dialogprepare> request is dialog manager specific. In the case of a dialog manager that does not support preparation, the CCXML implementation MUST as a minimum, note the values provided via the src, namelist, and connectionid attributes, create a Dialog object, and return a new unique value to the location defined by the dialogid attribute.

The CCXML session selects what it believes to be the appropriate dialog manager based on the MIME type specified by the type attribute without retrieving the resource specified by the src URI. If, when the dialog manager retrieves the content, it finds the MIME type, as specified by the HTTP headers, differs from that specifed by the type attribute, it SHOULD raise an error.dialog.notprepared event with a reason indicating the type mismatch. The dialog manager MUST NOT ignore the type mismatch or render the resource as a different type based on the HTTP headers or on inspection of the document data. Refer to the W3C guidelines for client handling of MIME types [MIME-TAG] for further information.

7.2.1.2: <dialogprepare> Attribute Details
Attribute Name Details
src Is an ECMAScript expression which returns a character string identifying the URI of the dialog document that the dialog interpreter should prepare.
type An OPTIONAL ECMAScript expression which returns a character string that specifies the MIME type of the document, and as a result, determines which dialog manager environment is actually used. A MIME type of "application/xml+vxml" requests a VoiceXML interpreter instance. A MIME type of "audio/wav" requests a dialog manager that merely plays wave files. If omitted, the type attribute defaults to "application/xml+vxml".
namelist An OPTIONAL list of one or more CCXML variable names. These variable names and their associated values will be added to the URI, specified by the src attribute, as a query string. The complete URI, including query string, is sent to the selected dialog manager.
dialogid An OPTIONAL ECMAScript left-hand-side expression that will receive a dialog identifier value for the launched dialog interpreter instance. This identifier may be used on future invocations of <dialogstart> or <dialogterminate>.
connectionid Is an OPTIONAL ECMAScript expression which returns the identifier of a connection. The specified connection will be associated with the dialog being prepared.
conferenceid Is an ECMAScript expression which returns an identifier of a conference bridge. A connection will be allocated for the dialog being prepared.

7.2.2: <dialogstart>

7.2.2.1: Overview

<dialogstart> is used to start a dialog and associate the dialog with a connection or conference. (See Section 10 for a discussion of connections and bridges). The element includes either a URI reference to the initial document for the dialog or the identity of a previously prepared dialog. The dialog executes on a separate logical execution thread (this MAY be a thread, process, or system depending upon platform implementation) and does not block the processing of further events by the CCXML session.

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.

If the connectionid attribute of <dialogstart> is specified, 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.

The connectionid or conferenceid attribute may be specified on the <dialogstart> element even if a connectionid attribute has been specified on a previous <dialogprepare> element for this dialog. In this case the new value will override the value specified on the <dialogprepare> element and the dialog will be associated with the newly specified connectionid or conferenceid.

The CCXML session selects the appropriate dialog manager based on the MIME type specified by the type attribute without retrieving the resource specified by the src URI. If, when the dialog manager retrieves the content, it finds the MIME type, as specified by the HTTP headers, differs from that specifed by the type attribute, it SHOULD raise an error.dialog.notstarted event with a reason indicating the type mismatch. The dialog manager MUST NOT ignore the type mismatch or render the resource as a different type based on the HTTP headers or on inspection of the document data. Refer to the W3C guidelines for client handling of MIME types [MIME-TAG] for further information.

7.2.2.2: <dialogstart> Attribute Details
Attribute Name Details
connectionid Is an ECMAScript expression which returns an identifier of a connection. A connection will be allocated for the dialog being started, and this connection will be bridged to the connection specified by connectionid. The connectionid attribute is OPTIONAL ; if omitted, the interpreter will use the id indicated in the current event being processed. For more information about connections and bridges, refer to Section 10. Only one of connectionid or conferenceid can be specified. If both are specified an error.semantic event will be thrown.
conferenceid Is an ECMAScript expression which returns an identifier of a conference bridge. A connection will be allocated for the dialog being started, and this connection will be bridged to the conference specified by conferenceid. The conferenceid attribute is OPTIONAL ; if omitted, the interpreter will use the id indicated in the current event being processed. For more information about connections and bridges, refer to Section 10 . Only one of connectionid or conferenceid can be specified. If both are specified an error.semantic event will be thrown.
prepareddialogid Is an OPTIONAL ECMAScript expression which returns a dialog identifier of a dialog previously prepared by the execution of a <dialogprepare> element. If the specified dialog identifier refers to an unknown dialog or a dialog that has already been executed, by way of another <dialogstart> element, an error.dialogwrongstate event is thrown.

This attribute may not be specified in conjunction with the src, type, or namelist attributes.
src Is an OPTIONAL ECMAScript expression which returns a character string identifying the URI of the dialog document that the dialog interpreter SHOULD load and begin executing upon startup.

This attribute may not be specified in conjunction with the prepareddialogid attributes.
type An OPTIONAL ECMAScript expression which returns a character string that specifies the MIME type of the document, and as a result, determines which dialog manager environment is actually used. A MIME type of "application/xml+vxml" requests a VoiceXML interpreter instance. A MIME type of "audio/wav" requests a dialog manager that merely plays wave files. If omitted, the type attribute defaults to "application/xml+vxml".

This attribute may not be specified in conjunction with the prepareddialogid attributes.
namelist An OPTIONAL list of one or more CCXML variable names. These variable names and their associated values will be added to the URI, specified by the src attribute, as a query string. The complete URI, including query string, is sent to the selected dialog manager.

This attribute may not be specified in conjunction with the prepareddialogid attributes.
dialogid An OPTIONAL ECMAScript left-hand-side expression that will receive a dialog identifier value for the launched dialog interpreter instance. This identifier may be used on future invocations of <dialogterminate>.
duplex An OPTIONAL bridging mode specification for the dialog connection. Valid values are half or full, default is full. This determines the type of bridge between the connection associated with the dialog and the connection or conference specified by the connectionid or conferenceid attribute. For more information about connections and bridges, refer to Section 10.

7.2.3: <dialogterminate>

7.2.3.1: Overview

A CCXML document may decide that it wants to terminate a currently executing dialog, to throw away a previously prepared dialog, or to terminate the preparation of a dialog. This is accomplished using the <dialogterminate> element. When the CCXML interpreter encounters a <dialogterminate> element, it sends a terminate request to the specified dialog.

A dialog terminated due to the processing of a <dialogterminate> element MAY still return data to the CCXML application using a dialog.exit event if the value of the immediate attribute is false or unspecified. The details of the data returned are dialog environment specific.

If the immediate attribute is set to true the dialog does not return data to the CCXML application and the CCXML interpreter SHALL post a dialog.exit event immediately.

7.2.3.2: <dialogterminate> Attribute Details
Attribute Name Details
dialogid An ECMAScript expression which returns a character string identifying the dialog. This dialogid was returned in the variable identified by the dialogid attribute of a previous <dialogstart> or <dialogprepare> request or as the value of dialogid in a dialog.started or dialog.prepared event.
immediate An OPTIONAL termination style specification. Specifies whether the dialog SHOULD be terminated immediately. Valid values are true, for immediate termination, or false. The default is false.

7.3: Events

7.3.1: Overview

The majority of communication between CCXML interpreter sessions and dialogs is by way of events. Dialog environments post events to the CCXML interpreter event queue and a CCXML application can send an event to a dialog. How this is handled on the dialog side is dialog manager and CCXML interpreter dependent. On the CCXML side it is done by using <send> and passing in the dialogid that was received as a result of processing a <dialogstart>.

The following are the CCXML events related to dialogs:

7.3.2: dialog.started

The dialog.started event is thrown when a dialog is successfully started. The fields available in the event are:

Field Name Details
name 'dialog.started'
dialogid The ID of the dialog.
connectionid The identifier of the connection to which the dialog connection is bridged (usually the connectionid that was specified in the <dialogstart> ). If the dialog is bridged to a conference the value will be null.
conferenceid The identifier of the conference to which the dialog connection is bridged (usually the conferenceid that was specified in the <dialogstart> ). If the dialog is bridged to a connection the value will be null.

7.3.3: dialog.exit

The dialog.exit event is thrown when a dialog terminates either normally or following a <dialogterminate> request. The fields available in the event are:

Field Name Details
name 'dialog.exit'
dialogid The ID of the dialog.
connectionid The identifier of the connection to which the dialog connection is bridged (usually the connectionid that was specified in the <dialogstart> ). If the dialog is bridged to a conference the value will be null.
conferenceid The identifier of the conference to which the dialog connection is bridged (usually the conferenceid that was specified in the <dialogstart> ). If the dialog is bridged to a connection the value will be null.
namelist List of items that are stored on the values sub-object.
values.* Values returned from the dialog.

7.3.4: dialog.disconnect

The dialog.disconnect event is thrown when a dialog requests it be disconnected from its current call. The dialog is not terminated, but simply requests the CCXML application end the call. The fields available in the event are:

Field Name Details
name 'dialog.disconnect'
dialogid The ID of the dialog.
connectionid The identifier of the connection to which the dialog connection is bridged (usually the connectionid that was specified in the <dialogstart> ). If the dialog is bridged to a conference the value will be null.
conferenceid The identifier of the conference to which the dialog connection is bridged (usually the conferenceid that was specified in the <dialogstart> ). If the dialog is bridged to a connection the value will be null.
namelist List of items that are stored on the values sub-object.
values.* Values returned from the dialog.

7.3.5: dialog.transfer

The dialog.transfer event is thrown when a dialog requests a transfer of its current call. The fields available in the event are:

Field Name Details
name 'dialog.transfer'
dialogid The ID of the dialog.
connectionid The identifier of the connection to which the dialog connection is bridged (usually the connectionid that was specified in the <dialogstart> ). If the dialog is bridged to a conference the value will be null.
conferenceid The identifier of the conference to which the dialog connection is bridged (usually the conferenceid that was specified in the <dialogstart> ). If the dialog is bridged to a connection the value will be null.
type A string value specifying the transfer type.
URI A URI describing the destination to which this call should be transfered. The format of this information is protocol and platform specific but might consist of a telephone URI [ RFC2806 ] or a SIP URI [ RFC2543 ].
namelist List of items that are stored on the values sub-object.
values.* Dialog transfer parameters. This is where a dialog language can specify more information about the transfer request. For example with VoiceXML this could contain all the attributes of the <transfer>.
maxtime A string in CSS2 format that specifies the maximum amount of time the transfer should stay connected. If the amount of time is unlimited the value will be 0s.
connecttimeout A string in CSS2 format that specifies the maximum amount of time to spend while attempting to connect the call.
aai A string of application-to-application information to be passed to the destination party when establishing the transfer.

7.3.6: dialog.terminatetransfer

The dialog.terminatetransfer event is thrown when a ongoing transfer must be terminated, for example due to a "hotword" recognition. As part of handling of the dialog.terminatetransfer event, the CCXML Application should terminate the outgoing call leg and return the media stream of the original call to the dialog using the <join> tag. The fields available in the event are:

Field Name Details
name 'dialog.terminatetransfer'
dialogid The ID of the dialog.
connectionid The identifier of the connection to which the dialog connection is bridged (usually the connectionid that was specified in the <dialogstart> ). If the dialog is bridged to a conference the value will be null.
conferenceid The identifier of the conference to which the dialog connection is bridged (usually the conferenceid that was specified in the <dialogstart> ). If the dialog is bridged to a connection the value will be null.
reason A string value specifying the reason the transfer needs to be returned.

7.3.7: error.dialog.notstarted

The error.dialog.notstarted event is thrown when the processing of a <dialogstart> element fails because the dialog cannot be started for some reason. The fields available in the event are:

Field Name Details
name 'error.dialog.notstarted'
dialogid The ID of the dialog.
conid The identifier of the connection or conference to which the dialog connection was to have been bridged (the conid that was specified in the <dialogstart> )
reason A description of the reason the dialog could not be started.

7.3.8: error.dialog.wrongstate

The error.dialog.wrongstate event is thrown when a dialog request such as <dialogterminate> has been received by the dialog environment but it cannot be completed because the dialog is not in a suitable state. The fields available in the event are:

Field Name Details
name 'error.dialog.wrongstate'
dialogid The ID of the dialog.
connectionid The identifier of the connection to which the dialog connection is bridged (usually the connectionid that was specified in the <dialogstart> ). If the dialog is bridged to a conference the value will be null.
conferenceid The identifier of the conference to which the dialog connection is bridged (usually the conferenceid that was specified in the <dialogstart> ). If the dialog is bridged to a connection the value will be null.
reason A description of the reason the dialog is in the wrong state.

7.3.9: dialog.user.*

The dialog.user.* event is thrown when a dialog sends a user event to the CCXML session that initiated it. The fields available in the event are:

Field Name Details
name 'dialog.user.*'
dialogid The ID of the dialog.
connectionid The identifier of the connection to which the dialog connection is bridged (usually the connectionid that was specified in the <dialogstart> ). If the dialog is bridged to a conference the value will be null.
conferenceid The identifier of the conference to which the dialog connection is bridged (usually the conferenceid that was specified in the <dialogstart> ). If the dialog is bridged to a connection the value will be null.
namelist List of items that are stored on the values sub-object.
values.* Values associated with the event.

7.3.10: dialog.prepared

The dialog.prepared event is thrown when a dialog has been successfully prepared following the execution of a <dialogprepare> element. The fields available in the event are:

Field Name Details
name 'dialog.prepared'
dialogid The ID of the dialog.

7.3.11: error.dialog.notprepared

The error.dialog.notprepared event is thrown when the processing of a <dialogprepare> element fails. The fields available in the event are:

Field Name Details
name 'error.dialog.notprepared'
dialogid The ID of the dialog.
reason A description of the reason the dialog could not be prepared.

7.4: Dialog Class Properties

An instance of the Dialog class is associated with each dialog created by <dialogstart> and referenced in the session.dialogs array.

Dialog Properties Definitions
id this property is the ECMAScript string value of the Dialog identifier, which uniquely identifies each instance of the Dialog class
connectionid The identifier of the connection to which the dialog connection is bridged (usually the connectionid that was specified in the <dialogstart> ). If the dialog is bridged to a conference the value will be null.
conferenceid The identifier of the conference to which the dialog connection is bridged (usually the conferenceid that was specified in the <dialogstart> ). If the dialog is bridged to a connection the value will be null.
type an ECMAScript expression which returns a character string that specifies the MIME type of the document that loaded the dialog.
src Is an ECMAScript expression which returns a character string identifying the URI of the dialog document.
duplex Equal to "half" or "full". The type of bridge between the connection associated with the dialog and the connection or conference the dialog is connected to.

8: Variables and Expressions

8.1: Overview

CCXML expressions are valid ECMAScript [ ECMASCRIPT ] expressions, assignable to variables with valid ECMAScript names. For further details please see section 3.4.

8.2: Elements

8.2.1: <assign> and <var>

8.2.1.1: Overview

Variables are declared using the <var> element and are initialized with the results of evaluating the OPTIONAL expr attribute as an ECMAScript expression. If the expr attribute is not present in the <var> declaration, the variable is initialized to EMCAScript undefined. The values of variables MAY be subsequently changed with <assign>.

Variables are declared explicitly by <var> :

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

It is illegal to make an assignment to a variable that has not been explicitly declared using <var> or a var statement within a <script>. Attempting to assign to an undeclared variable causes an error.semantic event to be thrown. Please see Section 9.5 for a detailed description of error events.

Variables declared without an explicit initial value MUST be initialized to the ECMAScript value undefined by the implementation.

Note that when an ECMAScript object, e.g. "obj", has been properly initialized then its properties, for instance "obj.prop1", can be assigned without explicit declaration. An attempt to declare ECMAScript object properties such as "obj.prop1" results in an error.semantic event being thrown.

CCXML uses an ECMAScript scope chain (please see section 3.4.2) to allow variables to be declared at different levels of hierarchy in an application. For instance, a variable declared at ccxml (document) scope can be referenced anywhere within that document, whereas a local variable declared in a <transition> is only available within that element.

The implementation MUST define two scopes - ccxml and transition. The relationship between these two scopes is shown below.

Variable Scoping
Figure x: Variable Scoping

A description of the two scopes is provided in the table below.

Scope Name Details
ccxml Variables within this scope are declared with <var> and <script> elements that are children of <ccxml>. They are initialized in document order when the document is loaded. They exist while the document is loaded. They are visible only within that document.
transition Each <transition> element has a scope that exists while the implementation is processing the executable content within that <transition>, and which is visible to the elements of that <transition>. Variables with transition scope are declared by <var> and <script> child elements of <transition>. The child <var> and <script> elements of <transition> are initialized in document order when the executable content is executed.

The implementation MUST instantiate a variable within 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. The implementation MUST allow reference to variables by their fully qualified names. The implementation MUST allow reference to variables without requiring use of their fully qualified names. In the case of like-named variables declared in different scopes, the implementation MUST reference the variable in the closest containing scope, unless the fully-qualified variable name is used.

The implementation MUST resolve variables by searching the enclosing transition scope first (if applicable) followed by the ccxml scope, unless the variable reference is qualified with a scope prefix.

If the variable includes a scope prefix, the implementation MUST resolve the variable by searching the named scope.

If a variable is declared more than once, the implementation MUST evaluate the expr attribute of each subsequent declaration, and assign the result to the variable declared by the first <var>.

Variables can be assigned new values using <assign> :

        <assign name="currentstate" expr="'cleanup'" />
</