Please refer to the errata for this document, which may include some normative corrections.
See also translations.
Copyright ©2011 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 is the 05 July 2011 Recommendation of "Call Control eXtensible Markup Language (CCXML) Version 1.0". There were no changes since the Proposed Recommendation document.
The W3C Membership and other interested parties are invited to review the document and send comments to the Working Group's public mailing list<EMAIL_ADDRESS>(archive). See W3C mailing list and archive usage guidelines.
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 Voice Browser Activity. The authors of this document are participants in the Voice Browser Working Group. For more information see the Voice Browser FAQ.
During the Candidate Recommendation phase, four independently developed implementations were evaluated. The entrance criteria for the Proposed Recommendation phase requires a minimum of two independently developed interoperable implementations for each required feature, two or more implementations of optional features that would impact interoperability, and a minimum of one implementation for each optional feature that has no impact on interoperability. These requirements were met. For further details and complete results please see section 7 of the CCXML Implementation Report. Comments received during the Candidate Recommendation period can be found in the Disposition of Comments.
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
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 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.
CCXML implementations MAY provide different
levels of optimization in their ECMAScript interpreters and are expected to be deployed in performance critical environments. One such level of
optimization could be a decision to execute all the executable items
in a <transition>
as if they were a single script instead of processing them
line by line as is the normal mode of execution. An example of this is the
following bit of CCXML Code:
<assign name="x" expr="3"/> <var name="x"/>
In the case where the platform executes CCXML line by line the <assign>
statement
will fail with an error.semantic
event due to trying to assign to
an undefined
variable. However on a platform where the actions are optimized into a single
ECMAScript execution block something like the following code would actually be executed instead:
x=3; var x;
Due to how ECMAScript var
statements work, declarations are applied before
assignments no matter where they are placed in the code. This script
is actually allowed and the assignment to x
will be completed without error.
Due to this difference in behavior between line by line vs batch execution application developers SHOULD NOT depend on the ability to declare variables out of document order and SHOULD write code such that its behavior is the same whether executed line by line or in a batch.
A more complex situation can arise if you use the <var>
element to declare
transition scoped variables by the same name as session
or application
scoped variables inside of an <if>
statement. An example of this would be:
<if cond="id==session.id"> <var name="id" expr="'2'"/> </if>
If executed line by line this would end up executing every line in the script and declaring a transition scoped variable named id
with a value of 2.
The <if>
statement would evaluate to true
due to auto scope searching when resolving the id
reference into a session scoped variable
and the next line would assign a new transition scoped variable by the name id
.
However, if the CCXML implementation were to optimize this into a single
ecmascript chunk you may get something like the following scriptlet:
if(id==session.id) { var id = '2'; }
Due to the way ECMAScript treats var
declarations the initial ID will evaluate as undefined
as ECMAScript adds
a implicit var
declaration to the top of the script and changes the var
to an assignment leaving you with something that is executed as if it was written like this:
var id; if(id==session.id) { id = '2'; }
This causes a different flow of execution and could cause unexpected program behavior as id
in the if
statement
will now be undefined
instead of being equal to session.id
.
Application developers SHOULD consider this bad programing practice and avoid creating scenarios where
applications create and depend on ambiguously scoped variables that use assignments inside conditional blocks with variable names
that are already in use by parent scopes.
Based on years of implementation experience the CCXML working group believes that CCXML application code that would be affected by these scenarios is very rare. Any such code likely relies on unusual ordering of variable declarations and assignment statements or the use of confusing variable names and scopes; such code is discouraged due to its potential for producing unintended results.
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()'.
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 <IP_ADDRESS>, 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.  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>
.
This media type should be used for a XML document containing CCXML content, see Appendix M.
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 URI | none | A valid URI | 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 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 | The NAME of the metadata property. | |
| 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. |
| 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 be a CCXML document, script content or other document types supported by
the CCXML platform. Content that has been acquired using <fetch>
is accessible through other elements
defined by CCXML and via the content attribute of the fetch.done
event. 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. If the requested content
was fetched successfully, and in the case of CCXML content, was successfully parsed and validated, a fetch.done
MUST be generated. If the requested content failed to be fetched, an error.fetch
MUST be generated. 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 that could be referenced via a fetchid
(eg, a CCXML or ECMAScript Document) that was fetched in
processed
mode 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.
All other content is only accessible via the content attribute of the fetch.done
event. If the application
needs access to the content outside of the fetch.done
event transition it is the responsibility of the application
to save a reference in an appropriately scoped variable.
Content referenced via fetchid
(for example via <script>
or <goto>
)
MUST be fetched using processed
mode.
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.
If the platform does not support the content type returned from a <fetch>
request but the fetch does
successfully complete (for example HTTP 2xx response code) the platform MUST still throw a
fetch.done
event for the fetchid
.
If the platform implements a security model (such as Access Control for Cross-site Requests [ACCESS-CONTROL]) and the request is denied due to the security model an error.notallowed
event
MUST be thrown.
INFORMATIVE NOTE: It is expected in future versions of CCXML additional forms of processed fetch modes will be added. Examples of these could be dom or e4x mappings of raw XML content.
<fetch>
Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| next | true | ECMAScript Expression | none | must evaluate to a valid URI | An ECMAScript expression which returns the URI of the resource to be fetched. | |
| type | false | ECMAScript Expression | In processed mode "application/ccxml+xml". In raw mode "*/*". | MIME Types formatted as per HTTP Accept header [RFC2616] | An ECMAScript expression which returns a character string setting the value of the HTTP Accept header to tell the application server what content type the application wishes to have returned. | |
| 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 URI |
|
| 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", otherwise ignored. | 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:
|
| mode | false | ECMAScript Expression | processed | processed, raw | Controls what the CCXML platform should do with fetched content. If set to
processed (the default) the CCXML platform MUST attempt to parse and validate the
returned content. If set to raw the platform MUST NOT attempt to process the data and
MUST leave processing of the content to the application who can do what it wishes with the content
via the content attribute of the fetch.done event |
<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 URI | 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", otherwise ignored. | 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 zero 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 |
|---|---|---|---|
| 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. |
| statuscode | true | int | The numeric HTTP status code (eg 200, 202 etc) of the HTTP request. |
| content | true | string | An ECMAScript representation of the fetched content. If the CCXML browser can not represent the content in ECMAScript (for example some content that was fetched in processed mode) this may be ECMAScript undefined. In raw mode it is expected that this attribute will contain a string representation of the fetched content. |
| contenttype | true | string | The returned content type from the web server. |
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 |
|---|---|---|---|
| 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 | 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. |
| content | true | string | An ECMAScript representation of the fetched content. If the CCXML browser can not represent the content in ECMAScript (for example some content that was fetched in processed mode) this may be ECMAScript undefined. In raw mode it is expected that this attribute will contain a string representation of the fetched content. |
| contenttype | true | string | The returned content type from the web server. |
ccxml.exit
- CCXML Document Exit EventThis event is generated when a CCXML session is terminated for any reason, if the terminated session has a parent session. This event is sent to the parent session and not the session that was terminated.
The fields of this event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| sessionid | true | string | The identifier of the exiting session. This must be the same value that was returned to the sessionid attribute of the createccxml which created this session. |
| expr | true | string | The value of the exit expr attribute. If this attribute is omitted in the exit, the value must be ECMAScript undefined. |
| values.* | false | ECMAScript Object | Return values from the ccxml session. This would be the values of each of the objects listed in the CCXML exit element's namelist. |
| reason | true | string | Reason that the session ended. Possible values are: "exit" - Session ended due to a <exit> element "error" - Session ended due to an unhandled error event "kill" - Session ended due to ccxml.kill* event |
ccxml.loaded
- CCXML Document Loaded EventThis event is thrown once the document is parsed and ready for execution (document initialization occurs between the fetched
and loaded events). The CCXML platform MUST 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>
and before events such as connection.alerting which may have triggered creation of the session.
The fields of this event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| sessionid | true | string | The identifier of the session on which this document is executing. |
| parent | true | string | The identifier of the session which issued the createccxml to start this document. If this document was started directly by the CCXML platform the value is ECMAScript undefined. |
ccxml.kill
- CCXML kill EventThe 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. If the
event is caught the session will not be terminated unless an <exit>
element is processed. If the event is
not caught the session will be terminated and all active connections, conferences and dialogs that are owned by that session
will be automatically terminated by the platform.
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 and all active connections, conferences and dialogs that are owned
by that session will be automatically terminated by the platform.
Note that while the normal cause of a ccxml.kill
or ccxml.kill.unconditional
event being queued to
a session is that the platform wishes to terminate the session, it is legal for any event I/O processor to generate a
ccxml.kill
or ccxml.kill.unconditional
event. For instance, it is legal for one CCXML session to
unconditionally kill another session by sending a ccxml.kill.unconditional
event using <send>
.
Note, however, that platforms may impose rules that prevent one session from arbitrarily killing another (to prevent malicious
applications, for instance).
The fields of this event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| sessionid | false | string | The identifier of the session who has sent the event. |
| reason | true | string | A string describing the reason the platform sent the kill event. Content of this field is platform-specific, and is only for informative purposes. |
ccxml.created
- CCXML Session Create Completion EventThis 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, parsed
and has begun execution of it by sending the ccxml.loaded
event to the new session.
The fields of this event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| sessionid | true | string | The identifier of the newly created CCXML session. This must be the same identifier as was returned on the sessionid attribute of the createccxml request that created the session. |
error.createccxml
- CCXML Session Create Failed EventThis 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:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| sessionid | true | string | 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 | true | string | A string description of the error encountered. Content of this field is platform-specific. |
error.unsupported
- CCXML Unsupported OperationThis event is generated when an operation that is not supported by the platform is executed.
The fields of this event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| reason | true | string | A string description of the error encountered. Content of this field is platform-specific. |
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 create a separate dialog to perform that interaction. After the dialog interaction is complete, an asynchronous event is sent to the CCXML session which can use any results returned by the dialog environment to decide what should happen next.
Dialogs initiated by CCXML sessions are not tied to any single dialog language or technology. Any dialog system which fulfils CCXML's requirements MAY be used for interaction with the caller. Examples of dialog systems include VoiceXML, SALT, traditional IVR, 3GPP MRF as well as simple media handling systems for fax, media playback and recording, DTMF detection, answer-machine detectors, etc. 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. Execution of a <dialogprepare>
or <dialogstart>
without preparation
creates a Dialog Object immediately, allowing the Dialog Object to be accessed following the
<dialogprepare>/<dialogstart>
, within the same transition. However, existence of the Dialog Object
does not guarantee anything about the success of the <dialogprepare>/<dialogstart>
request.
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 behavior 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"> <dialogprepare dialogid="preparedId" src="..." connectionid="event$.connectionid"/> </transition> <transition event="dialog.prepared"> <accept connectionid="event$.connectionid"/> </transition> <transition event="connection.connected" > <dialogstart prepareddialogid="preparedId" connectionid="event$.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"> <accept connectionid="event$.connectionid"/> </transition> <transition event="connection.connected"> <dialogstart src="..." connectionid="event$.connectionid"/> </transition> (optionally) <transition event="???"> <dialogterminate dialogid="..." /> </transition>
This next example shows the preparation of a dialog for an outbound call:
<transition event="..."> <dialogprepare src="..." dialogid="preparedId"> <!-- no connectionid --> </transition> <transition event="dialog.prepared" > <createcall dest="..." joinid="event$.dialogid"> <!-- use joinid --> </transition> <transition event="connection.connected"> <dialogstart prepareddialogid="preparedId" connectionid="event$.connectionid"/> </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"> <dialogprepare dialogid="preparedId" src="..." connectionid="event$.connectionid"/> </transition> <transition event="connection.disconnected" > <dialogterminate dialogid="preparedId" /> </transition>
It is possible for Dialogs to exist that are not joined to a Connection or a Conference. For example, this could be due to a
Connection disconnecting, or due to the application performing an <unjoin/>
operation.
<dialogprepare>
<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 the new dialog may be associated with a connection by specifying the connectionid
attribute, or with
a conference by specifying the conferenceid
attribute.
When preparation of the dialog completes successfully a dialog.prepared
event MUST be
posted to the event queue of the CCXML session. If however the dialog cannot be prepared for any reason, an
error.dialog.notprepared
event MUST be posted. However should the dialog be terminated
using <dialogterminate>
while it is being prepared the platform MUST only post a
dialog.exit
event.
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 in the
<dialogprepare>
attributes, create a Dialog object, and return a new unique value to the location defined by
the dialogid
attribute and throw a dialog.prepared
event.
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 MUST 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.
<dialogprepare>
Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| src | true | ECMAScript Expression | none | a Dialog URI | An ECMAScript expression which returns a character string identifying the URI of the dialog document that the dialog interpreter must prepare. | |
| type | false | ECMAScript Expression | application/voicexml+xml | a Valid MIME Type |
An ECMAScript expression which returns a character string that specifies the MIME type of the document, and as a result
determines which dialog manager environment must actually be used. 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 is 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". |
|
| parameters | false | Var List | none | List of ECMAScript Variable names | A list of one or more whitespace separated CCXML variable names. These variables are sent to the dialog environment as a list of name/value pairs. Names are sent exactly as they are specified; values are formed by converting the referenced ECMAScript variable to string form (which is undefined for objects). The dialog environment determines how passed parameters will be handled | |
| dialogid | 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 a dialog identifier value for the launched dialog interpreter instance. If the
attribute value is invalid, an error.semantic event MUST be thrown |
|
| connectionid | false | Must not be used with conferenceid | ECMAScript Expression | none | Connection IDs | An Optional ECMAScript expression which returns the identifier of a connection. If
specified, the dialog being prepared MUST be joined to the referenced connection as specified by
the mediadirection attribute. Note that if the referenced connection is already bridged to another media
endpoint, those existing bridges may be affected according to the rules specified in section 10.4 even prior to
<dialogstart> being performed If the attribute value is invalid an error.semantic event
must be thrown. |
| conferenceid | false | Must not be used with connectionid | ECMAScript Expression | none | Conference IDs | An Optional ECMAScript expression which returns the identifier of a conference bridge. If
specified, the dialog being prepared MUST be joined to the referenced conference as specified by
the mediadirection attribute. If the attribute value is invalid an error.semantic event
must be thrown. |
| mediadirection | false | ECMAScript Expression | both | both dialogtransmit dialogreceive |
An ECMAScript expression that defines the direction of the media flow between the Dialog and the Connection or
Conference. The following values must be used:
<dialogstart> is executed, but this attribute
may be provided as guidance to the dialog environment for preparation. If no value is specified, the dialog environment
must make no assumptions as to the bridging type. For more information about connections and bridges, refer to Section 10 .
|
|
| maxage | false | ECMAScript Expression | none | 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 is 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 | 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-stale' 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", otherwise ignored. | 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:
|
| 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:
|
|
| hints | false | ECMAScript Expression | none | An ECMAScript expression that returns an ECMAScript object | The ECMAScript object returned contains information which may be used by the implementing platform for implementing the dialog operation. Note: The meaning of these hints is specific to the implementing platform and protocol. Platforms that do not support hints MAY ignore this attribute. See Section 9.5.6 for additional requirements when hints are supported by the implementing platform. |
<dialogstart>
<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 MUST include 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 MUST
be posted to the event queue of the CCXML session that processed the <dialogstart>
request, otherwise a
dialog.started
event MUST be posted to indicate that the dialog has started successfully.
When the dialog completes, a dialog.exit
event MUST be posted.
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 MUST be
propagated from the specified connection to the dialog application.
If the prepareddialogid
attribute is specified and any attribute values conflict with the values specified in
the <dialogprepare>
element this MUST result in the throwing of an
error.dialog.notstarted
event.
Dialogs MAY only be started on connections while they are in the ALERTING or CONNECTED states. For connections in the ALERTING state media MAY not be sent or received by the connection making the bridge effectively full-duplex, half-duplex or silent depending on the underlying telephony environment and the restrictions imposed by it.
It is not possible to start a dialog that is not joined to a connection or a conference. For dialogs prepared using
<dialogprepare>
with neither connectionid
nor conferenceid
specified and dialogs
being started directly without preparation, if neither connectionid
nor conferenceid
are specified
then execution of the dialogstart
MUST fail, with an error.dialog.notstarted
event generated.
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 MUST 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.
<dialogstart>
Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| src | false | This attribute must not be specified in conjunction with the
prepareddialogid attribute. |
ECMAScript Expression | none | a valid Dialog URI | An ECMAScript expression which returns a character string identifying the URI of the dialog document that the dialog interpreter must load and begin execution upon startup. |
| prepareddialogid | false | This attribute must not be specified in conjunction with the src ,
type , parameters, maxage, maxstale, enctype, method or namelist attributes. |
ECMAScript Expression | none | a valid dialogid | An ECMAScript expression which returns a dialog identifier of a dialog previously
prepared by the execution of a <dialogprepare> element. |
| type | false | This attribute must not be specified in conjunction with the
prepareddialogid attribute. |
ECMAScript Expression | application/voicexml+xml | a Valid MIME Type |
An ECMAScript expression which returns a character string that specifies the MIME type of the document, and as a result
determines which dialog manager environment must actually be used. Values defined by the specification are:
|
| namelist | false | This attribute must not be specified in conjunction with the
prepareddialogid attribute. |
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 is 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 ". |
| parameters | false | This attribute must not be specified in conjunction with the
prepareddialogid attribute. |
Var List | none | List of ECMAScript Variable names | A list of one or more whitespace separated CCXML variable names. These variables are sent to the dialog environment as a list of name/value pairs. Names are sent exactly as they are specified; values are formed by converting the referenced ECMAScript variable to string form (which is undefined for objects). The dialog environment determines how passed parameters will be handled |
| dialogid | 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 a dialog identifier value for the launched dialog interpreter instance. This identifier
may be used on future invocations of <dialogterminate> . If the attribute value is invalid, an
error.semantic event MUST be thrown |
|
| connectionid | false | Must not be used with conferenceid . |
ECMAScript Expression | none | Connection IDs | An Optional ECMAScript expression which returns the identifier of a connection. If
specified, the dialog being started MUST be joined to the referenced connection as specified by the
mediadirection attribute.If the dialog was previously prepared using a <dialogprepare> element with a connectionid
or conferenceid specified, and this attribute is also specified, execution of the
<dialogstart> MUST fail with an error.dialog.notstarted event.
Note that if the referenced connection is already bridged to another media endpoint, those existing bridges may be affected
according to the rules specified in section 10.4 even prior to <dialogstart> being performed If the
attribute value is invalid an error.semantic event must be thrown. |
| conferenceid | false | Must not be used with connectionid. | ECMAScript Expression | none | Conference IDs | An Optional ECMAScript expression which returns the identifier of a conference bridge. If
specified, the dialog being started MUST be joined to the referenced conference as specified by the
mediadirection attribute.If the dialog was previously prepared using a <dialogprepare> element with a connectionid
or conferenceid specified, and this attribute is also specified, execution of the
<dialogstart> MUST fail with an error.dialog.notstarted event. If
the attribute value is invalid an error.semantic event must be thrown. |
| mediadirection | false | If used in conjunction with prepareddialogid , the bridge type must
match that used on the previous <dialogprepare> element. |
ECMAScript Expression | both | both dialogtransmit dialogreceive |
An ECMAScript expression that defines the direction of the media flow between the Dialog and the Connection or
Conference. The following values must be used:
prepareddialogid are specified and the bridge type specified
by the mediadirection attribute does not match that used on the previous <dialogprepare>
element, an error.dialog.notstarted event must be raised. If no value for the mediadirection attribute was
specified on the previous <dialogprepare> element, any mediadirection type option may be
specified.
|
| maxage | false | Must not be used with prepareddialogid. | ECMAScript Expression | none | 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 is 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 | Must not be used with prepareddialogid. | ECMAScript Expression | none | 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-stale' 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", otherwise ignored. Must not be used with prepareddialogid. | 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:
|
| method | false | Must not be used with prepareddialogid . |
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:
|
| hints | false | ECMAScript Expression | none | An ECMAScript expression that returns an ECMAScript object | The ECMAScript object returned contains information which may be used by the implementing platform for implementing the dialog operation. Note: The meaning of these hints is specific to the implementing platform and protocol. Platforms that do not support hints MAY ignore this attribute. See Section 9.5.6 for additional requirements when hints are supported by the implementing platform. |
<dialogterminate>
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 MUST
send 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 MUST NOT return data
to the CCXML application and the CCXML interpreter MUST post a dialog.exit
event
immediately.
The platform MUST tear down any existing bridges to the dialog and send a
conference.unjoined
to the CCXML document once the media paths have been freed.
<dialogterminate>
Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| dialogid | true | ECMAScript Expression | none | valid dialog ID | An ECMAScript expression which returns a character string identifying the dialog. This
dialogid was returned in the variable identified by the dialogid attribute of previous
<dialogstart> or <dialogprepare> request or the value in a dialog.started or
dialog.prepared event. If the attribute value is invalid, an error.semantic event MUST be thrown |
|
| immediate | false | ECMAScript Boolean Expression | false | true false |
An ECMAScript Boolean expression which returns a character string, that identifies the termination style of the dialog. Valid
values are:
|
|
| hints | false | ECMAScript Expression | none | An ECMAScript expression that returns an ECMAScript object | The ECMAScript object returned contains information which may be used by the implementing platform for implementing the dialog operation. Note: The meaning of these hints is specific to the implementing platform and protocol. Platforms that do not support hints MAY ignore this attribute. See Section 9.5.6 for additional requirements when hints are supported by the implementing platform. |
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 MAY 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>
or a
<dialogprepare>
.
The following are the CCXML events related to dialogs:
dialog.started
The dialog.started
event MUST be thrown when a dialog is successfully started. The
fields available in the event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| connectionid | false | string | The identifier of the connection to which the dialog connection is bridged (usually the
connectionid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a conference the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection is bridged (usually the
conferenceid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a connection the value must be undefined. |
dialog.exit
The dialog.exit
event MUST be thrown when a dialog terminates either normally or
following a <dialogterminate>
request. Termination of a dialog always results in a single
dialog.exit
event; if normal dialog termination and a <dialogterminate>
occur simultaneously,
the dialog.exit
event will reflect the condition that the platform processes first. For example, if a
dialog.exit
event is thrown based on normal termination, and the platform subsequently processes a
<dialogterminate>
request made by the application, it will discard the <dialogterminate>
and will not generate a second dialog.exit
event. The fields available in the event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| connectionid | false | string | The identifier of the connection to which the dialog connection is bridged (usually the
connectionid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a conference the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection is bridged (usually the
conferenceid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a connection the value must be undefined. |
| values.* | false | ECMAScript Object | Return values from the dialog. In VoiceXML this would be the values of each of the objects listed in the exit element's namelist. |
dialog.disconnect
The dialog.disconnect
event represents a request by a dialog to disconnect the Connection or Conference with
which it is presently associated. The actual handling of this event is determined entirely by the running CCXML application,
which may disconnect the associated Connection, detach the dialog from the Connection/Conference, or elect to ignore the
dialog.disconnect
event altogether. The fields available in the event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| connectionid | false | string | The identifier of the connection to which the dialog connection is bridged (usually the
connectionid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a conference the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection is bridged (usually the
conferenceid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a connection the value must be undefined. |
| values.* | false | ECMAScript Object | Return values from the dialog. In VoiceXML this would be the values of each of the objects listed in the dialog element's namelist. |
dialog.transfer
The dialog.transfer
event represents a request by a dialog to transfer the Connection or Conference with which
it is presently associated to a new destination. The actual handling of this event is determined entirely by the running CCXML
application, which may perform a <redirect>
on the associated Connection, use
<createcall>
and <join>
to establish a bridged transfer, handle the transfer request in
some other way, or elect to ignore the dialog.transfer
event altogether. The properties of the
dialog.transfer
event reflect the information dialog environments are most likely to supply when requesting a
transfer, but are up to the running CCXML application to interpret. The fields available in the event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| connectionid | false | string | The identifier of the connection to which the dialog connection is bridged (usually the
connectionid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a conference the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection is bridged (usually the
conferenceid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a connection the value must be undefined. |
| type | true | string | A string value specifying the transfer type. |
| uri | true | a valid URI | A URI describing the destination to which this call must be transferred. The format of this information is protocol and platform specific but might consist of a telephone URI RFC3966 or a SIP URI RFC3261 . |
| values.* | false | ECMAScript Object | Properties returned from the dialog processor relating to the dialogs transfer request. |
| maxtime | true | string | A string in CSS2 format that specifies the maximum amount of time the transfer may stay connected. If the amount of time is unlimited the value must be 0s. |
| connecttimeout | true | string | A string in CSS2 format that specifies the maximum amount of time to spend while attempting to connect the call. |
| aai | false | string | A string of application-to-application information to be passed to the destination party when establishing the transfer. |
dialog.terminatetransfer
The dialog.terminatetransfer
event represents a request by a dialog to terminate an ongoing transfer for
example due to a "hotword" recognition. The actual handling of this event is determined entirely by the running CCXML
application, which may terminate the outgoing call leg and return the media stream of the original call to the dialog using the
<join>
element, handle the terminate transfer request in some other way, or elect to ignore the
dialog.terminatetransfer
event altogether. The properties of the dialog.terminatetransfer
event
reflect the information dialog environments are most likely to supply when terminating a transfer, but are up to the running
CCXML application to interpret. The fields available in the event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| connectionid | false | string | The identifier of the connection to which the dialog connection is bridged (usually the
connectionid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a conference the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection is bridged (usually the
conferenceid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a connection the value must be undefined. |
| reason | false | string | A description of the reason the dialog wants the transfer to be terminated. Content of this field is platform-specific. |
error.dialog
The error.dialog
event MUST be thrown when there was an unspecified error with the
dialog (for example the dialog server crashed).
The platform MUST implicitly tear down any existing bridges to the dialog and send a
conference.unjoined
to the CCXML document once the media paths have been freed. The fields available in the event
are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| connectionid | false | string | The identifier of the connection to which the dialog was connected to (usually the
connectionid that was specified in the dialogstart or dialogprepare). If the dialog was being connected to a conference the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog was connected to (usually the
conferenceid that was specified in the dialogstart or dialogprepare). If the dialog was being connected to a connection the value must be undefined. |
| reason | true | string | A description of the reason the dialog had an error. Content of this field is platform-specific. |
error.dialog.notstarted
The error.dialog.notstarted
event MUST be 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:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| connectionid | false | string | The identifier of the connection to which the dialog connection could not be started (usually
the connectionid that was specified in the dialogstart or dialogprepare). If the dialog was being connected to a conference the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection could not be started (usually
the conferenceid that was specified in the dialogstart or dialogprepare). If the dialog was being connected to a connection the value must be undefined. |
| reason | true | string | A description of the reason the dialog could not be started. Content of this field is platform-specific. |
This section is intentionally left blank.
dialog.user.*
The dialog.user.*
(where * is the name of the user defined event) MUST be thrown when
a dialog sends a user/application-defined event. The fields available in the event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | false | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. NOTE that dialog property in this event is optional because there is not a standard way to raise this event from a dialog system such as [VOICEXML] while a basichttp implementation is allowed. |
| connectionid | false | string | The identifier of the connection to which the dialog connection is bridged (usually the
connectionid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a conference the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection is bridged (usually the
conferenceid that was specified in the dialogstart or dialogprepare). If the dialog is bridged to a connection the value must be undefined. |
| values.* | false | ECMAScript Object | Return values from the dialog for the user event. |
dialog.prepared
The dialog.prepared
event MUST be thrown when a dialog has been successfully prepared
following the execution of a <dialogprepare>
element. The fields available in the event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| connectionid | false | string | The identifier of the connection to which the dialog connection is prepared (usually the
connectionid that was specified in the dialogprepare). If the dialog was prepared without a connection, the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection is prepared (usually the
conferenceid that was specified in the dialogprepare). If the dialog was prepared without a conference , the value must be undefined. |
error.dialog.notprepared
The error.dialog.notprepared
event MUST be thrown when the processing of a
<dialogprepare>
element fails. The fields available in the event are:
| Attribute Name | Required | Type | Details |
|---|---|---|---|
| dialogid | true | string | The ID of the dialog. |
| dialog | true | ECMAScript Object | An ECMAScript object reference to the dialog object identified by the dialogid property of this event. |
| reason | true | string | A description of the reason the dialog could not be prepared. Content of this field is platform-specific. |
| connectionid | false | string | The identifier of the connection to which the dialog connection was attempting to be prepared
(usually the connectionid that was specified in the dialogprepare). If the dialog was prepared without a connection, the value must be undefined. |
| conferenceid | false | string | The identifier of the conference to which the dialog connection was attempting to be prepared
(usually the conferenceid that was specified in the dialogprepare). If the dialog was prepared without a conference, the value must be undefined. |
An instance of the Dialog object is associated with each dialog created by <dialogstart>
or
<dialogprepare>
and referenced in the session.dialogs
associative array.
The Dialog Object is an extension of the Media Endpoint Object as defined in section 10.4.3.
| Dialog Properties | Required | Definitions |
|---|---|---|
| dialogid | true | This property is the ECMAScript string value of the Dialog Identifier, which uniquely identifies each instance of the Dialog class. |
| type | true | An ECMAScript string value that specifies the MIME type of the document that loaded the dialog |
| src | true | An ECMAScript string value identifying the initial URI of the dialog document. |
| input | true | As defined by the Media Endpoint Object in 10.4.3. |
| outputs | true | As defined by the Media Endpoint Object in 10.4.3. |
| objecttype | true | This property states the type of this object which must be 'dialog'. |
All dialog objects MUST be initiated via the Dialog class. The Dialog class currently has no defined properties.
CCXML expressions are valid ECMAScript [ ECMASCRIPT ] expressions, assignable to variables with valid ECMAScript names. For further details please see section 3.4.
Many CCXML elements have multiple attributes that are ECMAScript expressions. The CCXML language does not guarantee a
specific order of evaluation of these expressions. Also, some elements such as <transition>
may or may not
evaluate all attributes. Hence, attributes containing expressions with side-effects can lead to implementation specific
behavior. It is RECOMMENDED that applications do not use ECMAScript expressions with side-effects in
attributes.
If the implementation is unable to evaluate an ECMAScript expression it MUST throw an
error.semantic
event.
<assign>
and <var>
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 ECMAScript 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'" />
Variables declared without an explicit initial value MUST be initialized to the ECMAScript value
undefined
by the implementation.
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.
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 ) 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 four scopes - session
, application
,
ccxml
and transition
. The relationship between these scopes is shown below.
Variable Scoping
A description of the scopes is provided in the table below.
| Scope Name | Details |
|---|---|
session |
This scope is opened by CCXML implementation before interpretation of a new session starts and exists until the session exits. Variables within this scope are provided by CCXML implementation and are read-only. Any attempt to modify the session object or it's properties by the application MUST result in an error.semantic event to be thrown by the platform. |
application |
This scope is opened by CCXML implementation before interpretation of a new session starts and exists until the session exits. Variables within this scope cannot be explicitly declared using <var> element or var statement within a <script>. They can be created only by assigning a value to a property of the application object (application.varname = value;). Unlike in the session scope, variables in this scope can be modified by CCXML programs. They are visible to documents within the CCXML application. |
ccxml |
This scope is opened by CCXML implementation for each CCXML document when it is loaded and exists while the document is loaded. 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. Variables in this scope can be also created without an explicit declaration by assigning a value to a property of the ccxml object (ccxml.varname = value;). |
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. Variables in this scope can be also created without an explicit declaration by assigning a value to a property of the transition object (transition.varname = value;). |
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, the application
scope and then the
session
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'" />
The implementation MUST evaluate the ECMAScript expression contained in the expr
attribute of <assign>
, and assign the results to the variable referenced in the name
attribute.
The variable naming convention is as in ECMAScript, but names beginning with the underscore character ("_") and names ending
with a dollar sign ("$") are reserved for internal use. CCXML variables MUST NOT contain ECMAScript
reserved words. They MUST also follow ECMAScript rules for referential correctness. For example,
variable names must be unique and their declaration MUST NOT include a dot - "var x.y
" is
an illegal declaration in ECMAScript. Variable names which violate naming conventions or ECMAScript rules MUST cause an 'error.semantic
' event to be thrown.
<var>
Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| name | true | String | none | Valid ECMAScript Variable name | Indicates the name of the variable. It must be a valid ECMAScript variable name. However, it must not contain a scope prefix. The scope in which the variable is defined must be determined from the position in the document at which the variable is defined. | |
| expr | false | ECMAScript Expression | undefined | Valid ECMAScript Expression | Indicates the new value of the variable. This will be the initial value. It must be a valid ECMAScript expression. |
<assign>
Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| name | true | 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 the result of the expr attribute. | |
| expr | true | ECMAScript Expression | none | Valid ECMAScript Expression | Indicates the new value of the variable. It must be a valid ECMAScript expression. |
<script>
<script>
encloses computations written in the ECMAScript Compact Profile [ECMA327] scripting language. The ECMAScript Compact Profile is a strict subset of the third edition of
ECMA-262 [ECMASCRIPT]. It has been designed to meet the needs of
resource-constrained environments. Special attention has been paid to constraining ECMAScript features that require
proportionately large amounts of system memory, and continuous or proportionately large amounts of processing power. In
particular, it is designed to facilitate prior compilation for execution in a lightweight environment. For specific details on
what ECMAScript functions are not supported please take a look at ECMA-327 specification [ECMA327].
An implementation MUST support the ECMAScript Compact Profile and MAY support the full ECMA-262 ECMAScript specification.
The example <script>
below defines a function that computes the greatest common factor of two
integers:
<script> <![CDATA[ function gcd(a, b) { var t; if (a < 1 || b < 1) return -1; do { t = a % b; a = b; b = t; } while (b > 1); return (b == 0) ? a : b; } ]]> </script>
An implementation MUST support <script>
within the <ccxml>
element and in executable content. <transition>
and <if>
contain executable content. The
implementation MUST evaluate <script>
in a <ccxml>
immediately
after the document is loaded, along with any <var>
and <assign>
elements, in document
order. When used as a child of the <ccxml>
element, <script>
cannot be used to execute
dynamically fetched content obtained using <fetch>
. The implementation MUST
evaluate <script>
in executable content as it is processed.
The ECMAScript contained within the <script>
can declare variables with the ECMAScript var
statement. Variables declared in this manner are declared in the scope of the closest containing scope CCXML element. They are
known from the point of declaration to the end of the containing scope. The implementation MUST allow
reference to these variables from CCXML and from ECMAScript, using either the fully-qualified variable name, or the declared
name.
If the implementation is unable to run the script referenced it MUST throw an
error.semantic
event.
INFORMATIVE NOTE: The <script>
element's resource loading model is a bit different than the rest of
CCXML for a number of reasons. Because CCXML and ECMAScript applications can be CPU intensive to compile we define
<script>
's src attribute (defining the URI of the document to load) to be a static string instead of a
dynamically valued ECMAScript result. This allows implementations to load ECMAScript content at CCXML document load time and
perform compiling and/or caching of the resulting ECMAScript code. We do however recognize that there are cases where a CCXML
application needs to load a dynamic ECMAScript resource, for this reason applications can use the the
<fetch>
element to asynchronously load a resource and then execute it by referencing it's
fetchid
in the the <script>
element.
<script>
Attribute Details| Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
|---|---|---|---|---|---|---|
| src | false | This attribute must not be specified in conjunction with the fetchid attribute. | Valid URI | none | a valid URI | A URI which references a resource which is the script content, and which must be resolved
when the CCXML document is compiled. Note that the value of the src attribute must not be an ECMAScript expression in order to allow it to be resolved at compile-time. If the ECMAScript script referenced can not be loaded at the CCXML document loading and parsing phase it should be considered a Fetching & compilation error as defined in section 9.5.1. |
| fetchid | false | This attribute must not be specified in conjunction with the src attribute, otherwise ignored. | ECMAScript Expression | none | 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 fetch identifier is invalid, has not completed, or the fetched content is not valid ECMAScript, an error.semantic event must be thrown. |
| timeout | false | This attribute is only valid in conjunction with the src attribute, otherwise ignored. | Character string | none | Character string in CSS2 [CSS2] format | The character string must be interpreted as a time interval. This interval must begin when the script is requested; If the script has not been fetched at the end of this interval, an error.fetch or error.createccxml event must be thrown. |
| maxage | false | This attribute is only valid in conjunction with the src attribute, otherwise ignored. | Character string | none | A valid time value for the HTTP 1.1 request [RFC2616] | The character string 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 | This attribute is only valid in conjunction with the src attribute, otherwise ignored. | Character string | none | A valid time value for the HTTP 1.1 request [RFC2616] | The character string 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-stale' 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. |
| charset | false | Character string | UTF-8 | valid character encoding type | A character string that indicates the character encoding type of the script. UTF-8 and UTF-16 encodings of ISO/IEC 10646 must be supported (as in [XML] ) and other encodings, as defined in the [IANA] , may be supported. |
Every CCXML session has a set of standard ECMAScript variables that are available to the program during execution called session variables. The session variables are defined by the CCXML implementation when the CCXML session is created and are read-only to the running script and cannot be modified by the CCXML program. New session variables cannot be declared by CCXML programs.
Session variable values visible to a CCXML application reflect the state of the executing CCXML session, current as of the
occurrence of the event being processed. For example, when an application processes a Connection event such as
connection.alerting
, the value of the state property of the corresponding Connection object will be updated by the
CCXML implementation so that if the CCXML program's event handler evaluates the state variable, it will evaluate to
ALERTING
, since connection.alerting
always results in a transition to the ALERTING
state. This is true even if the underlying connection is actually DISCONNECTED
, in which case a
connection.disconnected
event would be queued. It is the responsibility of the CCXML implementation to control and
update the session changes as they occur in the CCXML session. It is assumed that session changes are visible to the CCXML
program as they occur. However, it is permissible for a CCXML implementation to optimize session changes by
"lazy-binding" values as they are accessed or evaluated by a CCXML program, so as to minimize processing time. For example, an
implementation might only update the current Connection states when a CCXML program evaluates the variable during execution
time versus continually updating the Connection states inside ECMAScript scope as state changes. Regardless of when session
variables are updated to reflect changes, the CCXML implementation is REQUIRED to provide the correct
values when accessed by a CCXML program.
Variables defined in the session scope are subject to the parent scope chain delegation model but do not have a parent scope defined.
The following are the list of standard session variables:
session.startupmode
| Value |
Details |
|---|---|
newcall |
Session was started due to a new incoming call. |
external |
Session was started due to a external session launch request. |
createccxml |
Session was started due to a <createccxml> request. |
session.id
session.uri
session.uri
includes the query string used when fetching the document, if one is present.session.parentid
session.connections
session.connections["1234"]
would return the Connection object for connection ID 1234. The following example
demonstrates the use of the session.connections
variable:
<transition state="in_vxml_session" event="connection.disconnected"> <if cond="session.connections['1234'].connectionid==event$.connid"> <-- if the disconnect is on the first connection, do something --> <else/> <exit/> </if> </transition>
session.conferences
<createconference>
For example, session.conferences["1234"]
would return the Conference
object for conference id 1234.session.dialogs
session.dialogs["1234"]
would return the Dialog object for dialog id 1234.session.ioprocessors
session.ioprocessors["basichttp"]
would return the access URI (e.g.
http://www.example.com/ccxml/basichttp
) for the "basichttp" type event I/O processor.session.values
<createccxml>
, session.values
contains variables passed using the 'parameters
'
attribute of <createccxml>
. Other session creation mechanisms, such as the HTTP-based session creation I/O
processor defined in Appendix L, define other mechanisms for populating this variable.CCXML provides application variables which, like session variables, persists across the CCXML application. Application variables differ from session variables in that they can be modified by CCXML programs.
The application object is initialized by the CCXML implementation. Application variables that are properties of the application object are not explicitly declared. By default, application variables have the value ECMAScript undefined. Variables in the application scope are subject to the parent scope chain delegation model and have session as their parent scope. For example:
<assign name="application.userid" expr="'user001'"/> <assign name="application.obj" expr="new Object()"/> <assign name="application.obj.prop1" expr="'value of prop1'"/> <assign name="application.obj.prop2" expr="'value of prop2'"/>
Application variables are visible within documents which form the CCXML
application. For example, a document in a CCXML application could assign an application variable a value using
<assign name="application.userid" expr="'user001'"/>
, and a later document in the CCXML application could
reference application.userid
to retrieve the value 'user001'.
Application developers should be careful in their use of application variables since they are visible to all CCXML documents within a CCXML application.
This section contains information on <eventprocessor>
, <send>
,
<cancel>
, <transition>
and <move>
.
Event Handling is one of the most powerful features of CCXML. CCXML events can be delivered at any time and from a variety of sources. This flexible event-handling mechanism is essential for many telephony applications.
Every CCXML session can send and receive events. These might be in response to a previous action by the CCXML session (e.g.,
an outbound-call request, which generates an event to indicate when the call goes off-hook), or on the initiative of some
external source (e.g., an incoming call to be answered). Events can be generated by the telephony system (as in the two
previous examples), other CCXML sessions (which emit events via <send>
), Dialogs, or external sources. CCXML
sessions can also send events to themselves.
There is a core set of telephony-related events (derived from the JCC event model for connection objects; see the JAIN Call
Control API (JCC) [JSR021] for more information) that a browser MUST support. Implementers MAY define and support any platform-specific events they
like. In addition, users/programmers may use <send>
to send arbitrary events to internal or external
destinations, or may send arbitrary events to CCXML documents from internal or external sources and may specify transition
handlers to handle these events.
The transmission and reception of events both external and internal is controlled by a logical component in the platform
called the "Event I/O Processor". A platform MAY support more than one type of Event I/O Processor and
each of them may support a different format of external events (For example: SOAP, JMS, SIP, Simple HTTP or any other event
transmission approaches). For incoming events the Event I/O Processor is responsible for accepting the incoming event and
transforming it into an ECMAScript event object that can be accessed by CCXML. For outgoing events the Event I/O Processor is
responsible for deciding the serialization and transport formats. The operation and behavior of Event I/O Processors is
platform dependent; however, this specification defines a Basic HTTP Event I/O Processor (Appendix K) that defines event
transmission over HTTP. External Event I/O processors and new events created using <send>
will typically
generate application-specific events with different names than those of the standard events in this specification; however, it
is legal for external sources and for events created using <send>
to generate standard events. For instance,
it is useful to be able to generate a ccxml.kill
event to attempt graceful termination of a session from an
external context, or from another CCXML session. Platforms SHOULD reject any standard events that do
not contain all of the mandatory properties defined in this specification, and SHOULD notify the
sender of the rejection (for instance with an error.send
event).
Each running CCXML interpreter has a queue, into which it places incoming events. Events are generally queued on a first-in,
first-out (FIFO) basis; however, certain classes of events are queued differently, as described in the paragraphs below. A
CCXML programmer can only gain access to these queued events by using the <eventprocessor>
element with
associated <transition>
elements.
An event can be delivered to a CCXML session using a <send>
element in which case an optional delay may
be specified. If a delay is specified, the event is not delivered to the target CCXML session until the delay time has elapsed.
When the delay has elapsed, the event is queued as if it had just occurred, using standard queueing rules.
There are three types of events that, when delivered to a CCXML session, are handled differently. All
ccxml.kill
and ccxml.kill.*
events are placed at the head of the event queue rather than the tail so
that they are processed in preference to all other events. All error.*
events are placed at the head of the queue
but behind any error.*
, ccxml.kill
, or ccxml.kill.*
events that are already on the
queue. ccxml.loaded
events are always placed at the head of the queue.
An <eventprocessor>
is interpreted by an implicit Event Handler Interpretation Algorithm (EHIA). The
EHIA's main loop removes the first event from the CCXML session's event queue, and then selects from the set of
<transition>
s contained in the <eventprocessor>
. A <transition>
always
indicates a set of patterns to match event names, MAY indicate a required current value of the
ECMAScript state variable specified in the <eventprocessor>
, and MAY indicate a
further ECMAScript conditional expression to be evaluated. The <transition>
that accepts the type for the
just-removed event, is in the specified state, has a satisfied conditional expression, and appears first in the
<eventprocessor>
in document order, is the selected <transition>
.
Once selected, an object representing the event being processed is created at transition scope, and the elements inside the
<transition>
are executed in document order. If an ECMAScript evaluation error occurs during the execution
of an element within a <transition>
, error.semantic
MUST be raised for
that element, and successive elements within that <transition>
MUST NOT be
executed; Note that while an element that references an invalid connection, dialog, or conference identifier also causes the
platform to raise error.semantic
, these scenarios MUST NOT terminate execution of the
<transition>
in which that element is contained.
At most one <transition>
will be chosen. If no <transition>
meets all the criteria,
none are selected and the event is simply dropped; the EHIA loop then starts over again, removing the event at the head of the
queue. The only exception to this rule is when ccxml.kill
, ccxml.kill.*
and error.*
events are received; in this case, the CCXML interpreter will end the session if there are no <transition>
s
that match the ccxml.kill
, ccxml.kill.*
and error.*
events explicitly.
Any events that arrive while an event is already being processed are just placed on the queue for later. If the event queue is empty, and the EHIA wants to process an event, execution pauses until an event arrives.
During the processing of an event by the EHIA, the state of any ECMAScript objects exposed by a platform, such as the
Connection object, must reflect the state of the CCXML session immediately following the occurrence of
the event. For instance, if a 'connection.alerting
' event is being processed against a connection with ID 1234,
then session.connections['1234'].state
would have a value of Connection.ALERTING
. This is true even
if the actual connection has already been terminated, with a 'connection.disconnected
' event queued (but not yet
processed) against the session. It is required that the ECMAScript context for the session is updated
prior to the selection of a matching <transition>
, since the <transition>
might contain
an ECMAScript conditional expression, the value of which depends on the state changes caused by the event.
Elements inside an <transition>
SHOULD run "quickly", without blocking
execution. This will allow events to be rapidly processed. CCXML applications should be aware of this and should keep
calculations such as large ECMAScript functions within a transition to a minimum.
The only way for CCXML execution to leave an <eventprocessor>
is via an explicit
<goto>
or <exit>
inside a <transition>
or an unhandled error or
ccxml.kill
event .
An <eventprocessor>
MAY also declare a state variable attribute. An
<eventprocessor>
's state variable must be declared in the ccxml scope using a <var>
or a
<script>
. The <eventprocessor>
can be considered, and programmed as, a
finite-state-automaton, with the state variable indicating the automaton's current state or node, and the
<transition>