Copyright ©2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document describes CCXML, or the Call Control eXtensible Markup Language. CCXML is designed to provide telephony call control support for dialog systems, such as VoiceXML [VOICEXML]. While CCXML can be used with any dialog systems capable of handling media, 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 or a 3GPP Media Resource Function (MRF), and VoiceXML or other dialog systems could be integrated with other call control systems.
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 is the Last Call Working Draft of CCXML 1.0. The Last Call period is set to last 3 weeks. Therefore comments on the documents are welcome until 7 February 2007.
There are no changes since the previous Working Draft, except that this is a Last Call WD.
This document is also available as a non-normative HTML page showing the changes since previous revisions. For a detailed list please see Appendix F - Changes.
An Implementation Report Plan is currently being 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 was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
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 CCXML implementations.
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 a dialog system such as VoiceXML [VOICEXML].
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 four 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.
Figure 1
CCXML is designed to complement dialog systems such as 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.
A CCXML application consists of a collection of CCXML documents that control and manage the objects listed below:
<move>.<createconference> and <destroyconference> for further
information.CCXML programs manipulate these entities through elements defined in the CCXML language. They can also send and/or receive asynchronous events associated with these entities.
CCXML programs directly manipulate Connection Objects and Conference
Objects with various elements in the language, 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.
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.
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.
CCXML provides a powerful and flexible method of creating multi-party calls based on the following concepts:
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.
The following terms, which are used throughout this specification, are defined as:
ECMAScript left-hand-side expression - defined in ECMA-262 [ECMASCRIPT] 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;
Several examples of left-hand-side expressions are as follows (left-hand-side expression in red):
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <script> var simpleVar; var aaVar = Object(); simpleVar = 'Simple Expr'; aaVar[0] = 'Simple Expr'; aaVar['arrayKey'] = 'Simple Expr'; aaVar = {callingDevice: 'notSpecified', callCharacteristics: 'voiceUnitCall'}; </script> </ccxml>
ECMAScript expression - defined in ECMA-262 [ECMASCRIPT] 11.1; this is an expression which produces a value; an expression which is valid on the right hand side of an assignment operator;
Several examples of ECMAScript expressions are as follows (ECMAScript expression in red):
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <script> var simpleVar; var aaVar = Object(); simpleVar = 'hello world'; // simple string expression simpleVar = 'hello world'.length; // Calling a method that returns a // number on the simple string object simpleVar = 5; // Simple number expression simpleVar = aaVar[0]; // Associative Array position expression simpleVar = aaVar['key']; // Associative Array named value expression simpleVar = myCoolFunction(); // Function return expression </script> </ccxml>
ECMAScript variable name - defined in ECMA-262 [ECMASCRIPT] 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;
Several examples of ECMAScript variable names are as follows (ECMAScript variable name in red):
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <script> var simpleVar; var arrayVar = Object(); simpleVar = 'Simple Expr'; arrayVar[0] = 'Simple Expr'; arrayVar['arrayKey'] = 'Simple Expr'; arrayVar = {callingDevice: 'notSpecified', callCharacteristics: 'voiceUnitCall'}; </script> </ccxml>
new Object() ECMAScript expression; an
object with no properties.<var> element or defined within ECMAScript code using the var keyword.<ccxml> and
<transition> are CCXML scope elements. Variables which are defined within a scope element are not visible
to variables defined in other scope elements.'MyConnection = new
Connection()'. Reserved ECMAscript property 'prototype.constructor' MUST
reference the class constructor object, so in the example above, 'MyConnection.prototype.constructor ==
Connection'. The Connection class MUST initiate connection objects, the Dialog class
MUST initiate dialog objects and the Conference class MUST initiate
conference objects.A CCXML session can be started for the following reasons:
<createccxml>.To create a CCXML session, the URI for the initial CCXML document must be known, along with any
fetching parameters affecting how that CCXML document is retrieved. For incoming calls, the selection of the initial URI and
fetching parameters is platform-dependent, and MAY be based on information from the incoming call.
Sessions created via <createccxml> and the session creation event I/O processor determine the initial URI
and fetching parameters as stated in this specification.
When a session is started due to an incoming call it has ownership of the new Connection that caused it to be created.
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.
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.
A CCXML session can end in one of the following ways:
<exit>."error.*" event."ccxml.kill" event."ccxml.kill.unconditional" event.When a CCXML session ends, all active connections, conferences and dialogs that are owned by that session are automatically terminated by the platform.
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.
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.
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.
When a session ends, any resources, including connections owned by that session are terminated.
A session can have multiple sequential connections
In addition to having multiple sequential connections, a session can have multiple concurrent connections.
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.
A connection can be moved from one CCXML session to another session, such as a "master" session.
Implementations MAY, as a platform-specific optimization, choose to deliver more than one inbound
call to a single "master" session. This can be viewed as equivalent to sessions handling incoming calls
performing a <move>, as described in 3.5.3.7, of the new Connection (including the connection.alerting
event) to the single "master" CCXML session.
The default inbound call handling behavior for CCXML implementations is to create a new CCXML session and deliver the
connection.alerting event to it. If a platform supports delivery of multiple inbound calls to a single session,
the way this is configured is implementation specific.
ccxml.kill.unconditional event raisedIf at anytime a ccxml.kill.unconditional event is raised by the underlying implementation, the CCXML session is
immediately terminated and all active connections, conferences and dialogs that are owned by that session are automatically
terminated by the platform.
If at anytime the platform wishes to terminate a CCXML session it MUST raise a
ccxml.kill event to inform the CCXML application. The normal response to this event is for the CCXML application
to perform any clean up and termination of current active connections, conferences or dialogs and then execute an
<exit> element.
If the CCXML application does not respond to the ccml.kill event in a timely manner the platform MAY then raise a ccxml.kill.unconditional event to immediately terminate the CCXML session and all
active connections, conferences, and dialogs that are owned by the session.
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" xmlns="http://www.w3.org/2002/09/ccxml">
<eventprocessor>
<transition event="connection.alerting">
<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.'"/>
<exit/>
</transition>
</eventprocessor>
</ccxml>
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" xmlns="http://www.w3.org/2002/09/ccxml">
<eventprocessor>
<transition event="connection.alerting">
<log expr="'The number called is' + event$.connection.remote + '.'"/>
<if cond="event$.connection.remote == 'tel:+18315551234'">
<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,Time to disconnect it.'"/>
<disconnect/>
</transition>
<transition event="connection.disconnected">
<log expr="'Call has been disconnected. Ending CCXML Session.'"/>
<exit/>
</transition>
</eventprocessor>
</ccxml>
This is an example of running a simple VoiceXML dialog from CCXML. The application answers an incoming phone call and then connects it to a VoiceXML dialog that returns a value that is then logged to the platform:
<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml">
<!-- Lets declare our state var -->
<var name="state0" expr="'init'"/>
<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">
<log expr="'Houston, we have liftoff.'"/>
<dialogstart src="'dialog.vxml'"/>
<assign name="state0" expr="'dialogActive'" />
</transition>
<!-- Process the incoming call -->
<transition state="dialogActive" event="dialog.exit">
<log expr="'Houston, the dialog returned [' + event$.values.input + ']'" />
<exit />
</transition>
<!-- Caller hung up. Lets just go on and end the session -->
<transition event="connection.disconnected">
<exit/>
</transition>
<!-- Something went wrong. Lets go on and log some info and end the call -->
<transition event="error.*" >
<log expr="'Houston, we have a problem: (' + event$.reason + ')'"/>
<exit/>
</transition>
</eventprocessor>
</ccxml>
<?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>
| <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 |
| <dialogprepare> | Prepare a dialog for execution |
| <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 |
| <merge> | Merge two connections at the network level |
| <meta> | Override HTTP headers and provide document metadata |
| <metadata> | Provide document metadata |
| <move> | Move an event source 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 |
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.*). A CCXML session can 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 CCXML media type application/ccxml+xml is defined in [RFC4267]
This media type should be used for a XML document containing CCXML content.
This section details the CCXML elements for control flow and execution.
<ccxml>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".
<ccxml> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| version | true | string | none | 1.0 | The version of this CCXML document. The initial version number must be 1.0. | |
| xml:base | false | valid URL | none | A valid URL | 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. |
<meta>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
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.
<meta> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| name | false | This attribute must not be specified in conjunction with the http-equiv attribute | NMTOKEN | none | seeAlso | The NAME of the metadata property. The seeAlso property must be used to specify a resource that might provide additional metadata information about the content. Either the name or the http-equiv attribute has to be specified. If neither of them is specified, or if both are specified, an error.fetch event must be thrown. |
| http-equiv | false | This attribute must not be specified in conjunction with the name attribute | NMTOKEN | none | A valid HTTP header | The NAME of an HTTP response header. This attribute has special significance when documents are retrieved via HTTP. 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. Either the name or the http-equiv attribute has to be specified. If neither of them is specified, or if both are specified, an error.fetch event must be thrown. |
| content | true | string | none | The value of the metadata property. |
<metadata><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 .
<metadata> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| none | none | none |
<if><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 MUST 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>, CCXML provides familiar if/elseif/else
semantics, but conforms to the rules of valid XML [XML] documents.
<if> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| cond | true | ECMAScript Expression | none | A valid ECMAScript expression | An ECMAScript expression which can be evaluated to true or false. |
<elseif>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>.
<elseif> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| cond | true | ECMAScript Expression | none | A valid ECMAScript expression | An ECMAScript expression which can be evaluated to true or false. |
<else><else> is a synonym for <elseif cond="true"/>.
<else> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| none | none | else is a synonym for elseif cond="true". |
<fetch><fetch> is used to asynchronously fetch content identified by the attributes of the
<fetch>. The fetched content may either be a CCXML document, or script content. Content that has been
acquired using <fetch> is accessible through other elements defined by CCXML. Execution returns from the
element immediately, and the CCXML application can continue on while the platform works to fetch the identified resource. When
the fetch request has been completed, an event is generated against the session that initiated the fetch. The event is one of
fetch.done, which indicates that the identified content was fetched successfully, or error.fetch,
indicative of a failure to fetch the requested content. Note that even if content is successfully fetched, errors in processing
fetched content (for instance, a CCXML document with a syntax error) may result in an error.fetch being
thrown.
The fetch request is local to the session that initiated the <fetch>, and is referenced through a unique
identifier generated by the CCXML platform. The application may obtain the unique identifier for a fetch request by providing
an ECMAScript left-hand-side expression in the fetchid attribute when the fetch is performed. The fetch identifier
can also be obtained as a property of the fetch.done event. The application uses the fetch identifier in any CCXML
elements that reference fetched content, currently <goto> and <script>.
Fetched content has a lifetime that is limited to that of the document in which it is fetched. Therefore, following a
transition to a new CCXML document using <goto>, content fetched in the scope of the current document is no
longer accessible. Note that this should not be taken to preclude platform-level optimizations or caching of resources that are
fetched multiple times.
The use of <fetch> to obtain content does not compel the application to make use of that content.
However, it is wasteful of system resources to fetch resources that are not used. Platforms are responsible for clearing out
unused fetch resources, and may impose limits on the resources that can be fetched by a single session.
The "http" URI scheme MUST be supported by CCXML platforms, the "https" protocol should be supported and other URI protocols may be supported.
<fetch> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| next | true | ECMAScript Expression | none | must evaluate to a valid URL | An ECMAScript expression which returns the URI of the resource to be fetched. | |
| type | false | ECMAScript Expression | application/ccxml+xml | application/ccxml+xml text/ecmascript text/javascript |
An ECMAScript expression which returns a character string that specifies the MIME type of the fetched content. Values
defined by the specification are:
|
|
| namelist | false | Var List | none | List of ECMAScript Variable names | A list of zero or more whitespace separated CCXML variable names. These variables must be
submitted to the web server, with the same qualification as used in the namelist.
When an ECMAscript variable is submitted to the web server, its value must be first
converted into a string before being submitted. If the variable is an ECMAScript Object, the mechanism by which it must be submitted is not currently defined. Instead of submitting ECMAScript Objects directly, the application developer may explicitly submit the properties of an Object. e.g. "date.month date.year". |
|
| method | false | ECMAScript Expression | get | get post |
An ECMAScript expression which returns a character string that indicates the HTTP method to use. Values defined by the
specification are:
|
|
| fetchid | false | ECMAScript Left Hand Side Expression | none | ECMAScript Variable | An ECMAScript left hand side expression evaluating to a previously defined variable. The
value of the attribute must receive 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 identifier can be acquired from the fetch completion event. Every fetch request must receive a unique fetch identifier, even if the request is for the same URL. |
|
| timeout | false | ECMAScript Expression | none | An ECMAScript expression which returns a character string in CSS2 [CSS2] format | The character string returned must be interpreted as a time interval. This interval begins when the fetch is executed. The fetch must fail if not completed at the end of this interval. A failed fetch must return the error.fetch event. | |
| maxage | false | ECMAScript Expression | none | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned must be interpreted as a time interval. This indicates that the document is willing to use content whose age must be no greater than the specified time in seconds (cf. 'max-age' in HTTP 1.1 [RFC2616]). The document is not willing to use stale content, unless maxstale is also provided. | |
| maxstale | false | ECMAScript Expression | none | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned must be interpreted as a time interval. This indicates that the document is willing to use content that has exceeded its expiration time (cf. 'max-age' in HTTP 1.1 [RFC2616]). If maxstale is assigned a value, then the document is willing to accept content that has exceeded its expiration time by no more than the specified number of seconds. | |
| enctype | false | Valid only when the value of the method is "post" | ECMAScript Expression | application/x-www-form-urlencoded | valid media encoding type |
An ECMAScript expression which returns a character string that indicates the media encoding type of the submitted
document (when the value of the method is "post"). Values defined by the specification are:
|
<goto><fetch>, in conjunction with <goto>, is used to transfer execution to a different
CCXML document in a multi-document CCXML application. The <fetch> tells the platform to find, load, and
parse a given CCXML document. After the fetch completes, the CCXML application can then issue a <goto> to
execute 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.example.com/control.ccxml'"/> <--control continues here-> <assign name="state_var" expr="'fetch_wait'"/> </transition> <!-- ……… --> <transition state="fetch_wait" event="fetch.done"/> <goto fetchid="event$.fetchid"/> </transition>
A <goto> transfers control to the document obtained through a fetch request, using the platform-generated
unique identifier associated with that fetch request. The fetch completion event MUST have arrived
before the <goto> is executed, otherwise, an error.semantic event is generated. If the fetched
content referenced by the fetch identifier is not a CCXML document, or the fetch identifier is invalid and does not correspond
to any fetch request, this also results in an error.semantic event.
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.
<goto> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| fetchid | true | ECMAScript Expression | none | A valid fetch id | An ECMAScript expression which returns the fetch identifier of a completed fetch request
acquired either in a fetch with the fetchid attribute, or from the fetchid attribute of a fetch.done event. If the attribute value is invalid, an error.semantic event must be thrown. |
<fetch> and <goto> ExampleThe following code shows the use of the <fetch> and <goto> elements along with the
fetchid attribute to handle more complex fetching situations:
<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml">
<!-- var to hold the value of the fetch
identifier that we care about -->
<var name="myGoodFetchID"/>
<eventprocessor>
<transition event="ccxml.loaded">
<!-- stick the value of the fetch
identifier in the myGoodFetchID var -->
<fetch fetchid="myGoodFetchID"
next="'http://www.example.com/goodfetch.ccxml'"/>
<!-- do not bother saving the fetch id's for these,
we would just ignore them anyway -->
<fetch next="'http://www.example.com/fakefetch1.ccxml'"/>
<fetch next="'http://www.example.com/fakefetch2.ccxml'"/>
</transition>
<transition event="fetch.done">
<if cond="myGoodFetchID == event$.fetchid">
<!-- only matched if we have fetched
http://www.example.com/goodfetch.ccxml -->
<goto fetchid="event$.fetchid"/>
</if>
</transition>
<transition event="error.fetch">
<!-- Ignore bad fetches in this example -->
</transition>
</eventprocessor>
</ccxml>
<createccxml><createccxml> is used to create another CCXML session, which begins execution with the document
identified by this element. 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.
<createccxml> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| next | true | ECMAScript Expression | none | a valid URL | An ECMAScript expression which returns the URI of the resource to be fetched. | |
| namelist | false | Var List | none | List of ECMAScript Variable names | A list of zero or more whitespace separated CCXML variable names. These variables must be
submitted to the web server, with the same qualification as used in the namelist.
When an ECMAscript variable is submitted to the web server, its value must be first
converted into a string before being submitted. If the variable is an ECMAScript Object, the mechanism by which it must be submitted is not currently defined. Instead of submitting ECMAScript Objects directly, the application developer may explicitly submit the properties of an Object. e.g. "date.month date.year". |
|
| fetchparam | false | ECMAScript expression | 'none' | 'none', 'session-id', 'session' |
Specifies parameters, in addition to those specified via 'namelist' (if present), that
will be passed to the web server when fetching the CCXML document for the new session. Three values are legal for this
attribute:
|
|
| parameters | false | Var List | none | List of ECMAScript Variable names | A list of zero or more whitespace separated CCXML variable names. Each named variable will be created as a property of 'session.values' in the newly created session. For instance, passing a variable named 'foo' with value '123' will result in the 'session.values.foo' property evaluating to '123'; similarly, passing a variable named 'foo.bar' would result in a 'session.values.foo.bar' property. Variable values are passed in string form; the passing of ECMAScript objects is not currently defined. | |
| method | false | ECMAScript Expression | get | get post |
An ECMAScript expression which returns a character string that indicates the HTTP method to use. Values defined by the
specification are:
|
|
| sessionid | false | ECMAScript Left Hand Side Expression | none | ECMAScript Variable | An ECMAScript left hand side expression evaluating to a previously defined variable. The value of the attribute must receive an internally generated unique string identifier which identifies the newly created session. | |
| timeout | false | ECMAScript Expression | none | An ECMAScript expression which returns a character string in CSS2 [CSS2] format | The character string returned must be interpreted as a time interval. This time interval must be interpreted by the new CCXML session as the maximum time it may wait for the 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. | |
| maxage | false | ECMAScript Expression | none | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned must be interpreted as a time interval. This indicates that the document is willing to use content whose age must be no greater than the specified time in seconds (cf. 'max-age' in HTTP 1.1 [RFC2616]). The document is not willing to use stale content, unless maxstale is also provided. | |
| maxstale | false | ECMAScript Expression | none | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned must be interpreted as a time interval. This indicates that the document is willing to use content that has exceeded its expiration time (cf. 'max-age' in HTTP 1.1 [RFC2616]). If maxstale is assigned a value, then the document is willing to accept content that has exceeded its expiration time by no more than the specified number of seconds. | |
| enctype | false | Valid only when the value of the method is "post" | ECMAScript Expression | application/x-www-form-urlencoded | valid media encoding type |
An ECMAScript expression which returns a character string that indicates the media encoding type of the submitted
document (when the value of the method is "post"). Values defined by the specification are:
|
<exit><exit> ends execution of the CCXML session. All pending events are discarded, and there is no way to
restart CCXML execution.
<exit> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| expr | false | ECMAScript Expression | undefined | A return ECMAScript expression (e.g. 0 or 'oops!'). If this attribute is omitted, the return value must be ECMAScript undefined. This value must be stored as a property of the exit event. | ||
| namelist | false | Var List | none | List of ECMAScript Variable names | A list of one or more whitespace separated CCXML unqualified variable names to be returned. These variable names and their associated values must 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.
<log><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.
<log> Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| label | false | ECMAScript Expression | none | An ECMAScript expression which returns a character string which must be used, for example, to indicate the purpose of the log. | ||
| expr | true | ECMAScript Expression | none | An ECMAScript expression evaluating to a string to be logged. |
CCXML allows operations such as document fetching, startup and shutdown to execute independently. CCXML events that describe these operations are defined below:
fetch.done - Fetch Completion EventThis event is generated when a fetch request completes successfully. It is delivered to the document which issued the request.
The fields of this event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| name | true | string | fetch.done |
| fetchid | true | string | The internally generated unique fetch identifier |
| uri | true | string | The URI of the resource that was fetched. If the fetch resulted in one or more HTTP redirects (e.g. 302), the value of this property is set to the final target URI. |
| eventid | true | string | The unique identifier for the event. This must match the sendid attribute of send, if the event was generated by a CCXML document. |
| eventsource | true | string | The unique identifier of the event source. This identifies the CCXML Event I/O Processor that sent this event. |
| eventsourcetype | true | string | The name of the Event I/O Processor that sent this event. This must be set to ccxml as this is an event generated by the CCXML Session Event processor. |
error.fetch - Fetch Error EventThis 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:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| name | true | string | error.fetch |
| fetchid | true | string | The internally generated unique fetch identifier |
| reason | true | string | A string description of the fetch error. Content of this field is platform-specific. |
| statuscode | true | int | The numeric HTTP status code (eg 404,500 etc) of the failed HTTP request. |
| uri | true | string |