In addition to the HTML version, this document is also available in these non-normative formats: diff marked HTML version.
Copyright © 2005 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 some other call control systems.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This specification describes the Call Control XML (CCXML) markup language that is designed to provide telephony call control support for VoiceXML or other dialog systems. This document has been produced as part of the W3C Voice Browser Activity, following the procedures set out for the W3C Process. The authors of this document are members of the Voice Browser Working Group ( W3C Members only ).
This second last call working draft addresses many of the comments that came up during the last call review. Feedback was received on the public working group mailing list and via the internal working group reviews. Some of the changes include:
For a detailed list please see Changes in Last Call Working Draft 2.
This is a W3C Last Call Working Draft for review by W3C Members and other interested parties. Last Call means that the Working Group believes that this specification is technically sound and therefore wishes this to be the Last Call for comments. If the feedback is positive, the Working Group plans to submit it for consideration as a W3C Candidate Recommendation. Comments can be sent until 31 January 2005.
A Implementation Report Plan is currently being developed for this specification. The Working Group currently expects to require at least two independently developed interoperable implementations of each required feature, and at least one implementation of each feature, in order to exit the next phase of this document, the Candidate Recommendation phase. To help the Voice Browser Working Group build such a report, reviewers are encouraged to implement this specification and to indicate to W3C which features have been implemented, and any problems that arose.
This document is for public review. Comments and discussion are welcomed on the public mailing list < www-voice@w3.org >. To subscribe, send an email to <www-voice-request@w3. org> with the word subscribe in the subject line (include the word unsubscribe if you want to unsubscribe). The archive for the list is accessible on-line.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document has been produced under the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.
In this document, the key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" are to be interpreted as described in [RFC2119] and indicate requirement levels for compliant VoiceXML implementations.
This document describes CCXML, the Call Control eXtensible Markup Language. CCXML provides declarative markup to describe telephony call control. CCXML is a language that can be used with a dialog system such as VoiceXML [VOICEXML].
CCXML can provide a complete telephony service application, comprised of Web server CGI compliant application logic, one or more CCXML documents to declare and perform call control actions, and to control one or more dialog applications that perform user media interactions
Since platforms implementing CCXML MAY choose to use one of many telephony call control definitions ( JAIN Call Control [ JSR021 ], ECMA CSTA [ CSTA ], S.100 [ S.100 ], etc.), the call control model in CCXML has been designed to be sufficiently abstract so that it can accommodate all major definitions. For relatively simple types of call control, this abstraction is straightforward. The philosophy in this regard has been to "make simple things simple to do." Outdial, transfer (redirect), two-party bridging, and many forms of multi-party conferences fall within this classification.
Figure 1 shows the architecture of a telephony implementation consisting of three primary components:
The Telephony Web Application may or may not be integrated with the Voice Web Application.
The Telephony Control and Dialog Control Interfaces may be implemented as an API or protocol.
The components as shown in the figure below represent logical functions, and are not meant to imply any particular architecture.
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 (mentioned above) associated with these entities.
CCXML programs directly manipulate Connection Objects and
Conference Objects with various elements in the language, such as
<accept>
, <createconference>
, and <join>
. CCXML may also
receive events from Connection and Conference Objects, in
the case of line signaling, line-status informational messages, or error and failure scenarios.
Connections and Conference Objects do not accept events;
CCXML must use the builtin elements to direct them.
CCXML programs can start and kill Voice Dialogs using language elements. It can receive
events from Voice Dialogs, which may be standardized events such as
dialog.exit
, or application-specific ones. CCXML can support sending of an event to a
Voice Dialog.
CCXML programs can create other CCXML sessions using <createccxml>
.
This is the only guaranteed control mechanism a CCXML Session ever wields over another.
Any other interaction takes place through the event mechanism. CCXML Sessions can both
send and receive events between one another.
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 on the following concepts:
The computational semantics of CCXML language is based on the ECMAScript Compact Profile (ES-CP, also known as ECMA-327) [ECMA327]. ES-CP is a strict subset of the third edition of ECMA-262 [ECMASCRIPT]. Execution efficiency is a primary goal of CCXML implementations, and ES-CP was chosen to ensure that CCXML implementations can operate in a variety of execution environments and without excessive execution overhead.
The ES-CP document specification states:
'ECMAScript Compact Profile is a subset of ECMAScript 3rd Edition tailored to resource-constrained devices such as battery powered embedded devices. Therefore, special attention is paid to constraining ECMAScript features that require proportionately large amounts of system memory (both for storing and executing the ECMAScript language features) and continuous or proportionately large amounts of processing power.'
While CCXML implementations are not necessarily intended for battery powered embedded devices, it is intended to be used in large, real-time telephony platforms managing thousands of lines. The constraints of ES-CP emphasize CCXML's ongoing concern for execution efficiency.
Even though ES-CP tends to be implemented using interpreters, CCXML does not require an interpretive implementation. ES-CP can be compiled to a target language such as C, and thus in turn to machine code, so that CCXML documents which are static can be rendered once in machine code. For example, a CCXML implementation, for optimization purposes, could translate and compile frequently used CCXML documents on their way from the document server to the CCXML execution environment in order to avoid multiplying interpretive overhead by the number of lines that execute the same document.
The emphasis on efficiency in CCXML language is also shown by the avoidance of requirements which can only be implemented either by interpretation or by run-time evaluation.
The choice of an implementation strategy is up to the CCXML implementer and CCXML language is aimed to allow a range of design choices in order to accommodate implementations on a wide variety of platforms.
A CCXML implementation MUST support the ECMAScript Compact Profile.
The following terms, which are used throughout this specification, are defined as:
ECMAScript left-hand-side expression - defined in ECMA-262 [ECMASCRIPT] 11.2; this is an expression which produces a result to which a value can be assigned; an expression which is valid as the left hand operand of an assignment (=) operator;
Several examples of left-hand-side expressions are as follows (left-hand-side expression in red):
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <script> simpleVar = 'Simple Expr'; arrayVar[0] = 'Simple Expr'; arrayVar['arrayKey'] = 'Simple Expr'; arrayVar = {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> 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 = array[0]; // Array position expression simpleVar = array['key']; // 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> 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.A CCXML session can be started for the following reasons:
<createccxml>
.When a session is started due to an incoming call it has ownership of the event endpoint associated with the new
Connection. The new CCXML session will be responsible for processing the Connection state events and performing the
Connection actions. If the session was started because of a <createccxml>
, it will start without
ownership of any event endpoints unless an event was forwarded using the start attribute of
<createccxml>
, in which case the associated event endpoint would then be owned by the new CCXML
session. In the case of an external session launch the session will not own any event endpoints.
A CCXML application can determine the reason its session was started by evaluating the contents of the
session.startupmode
session variable that is defined in the Session
Variables section.
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 is can be viewed as equivalent to several
sessions performing a <move>
, as described in 3.5.3.7, of the connection.alerting
event to a single 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 clear 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" name="evt"> <var name="MyVariable" expr="'This is a CCXML Variable'"/> <log expr="'Hello World. I just made a variable: ' + MyVariable"/> <log expr="'Lets hang up on this incoming call.'"/> <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" name="evt"> <log expr="'The number called is' + evt.connection.remote + '.'"/> <if cond="evt.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" name="evt"> <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" name="evt"> <log expr="'Houston, the dialog returned [' + evt.values.input + ']'" /> <exit /> </transition> <!-- Caller hung up. Lets just go on and end the session --> <transition event="connection.disconnected" name="evt"> <exit/> </transition> <!-- Something went wrong. Lets go on and log some info and end the call --> <transition event="error.*" name="evt"> <log expr="'Houston, we have a problem: (' + evt.reason + ')'"/> <exit/> </transition> </eventprocessor> </ccxml>
<?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 |
<meta> | Override HTTP headers and provide document metadata |
<metadata> | Provide document metadata |
<move> | Move a event to another ccxml session |
<redirect> | Redirect an incoming call to a new endpoint |
<reject> | Reject an incoming phone call |
<script> | Run ECMA Script |
<send> | Generate an event |
<transition> | A single event-processor block |
<unjoin> | Disconnect two audio sources |
<var> | Declare a variable |
A CCXML session begins with the execution of a CCXML document. The flow of the execution can be changed with the
help of <if>
, <elseif>
, <else>
, <fetch>
,
and <goto>
. Most of a CCXML session's execution will take place within an
<eventprocessor>
, which processes a stream of incoming events.
A CCXML session can consist of multiple CCXML documents, traversed by use of <goto>
and
<fetch>
.
A new CCXML session has a new session object (session.*), where initially the length of the connection array is 0. A CCXML session can contain multiple active connections.
A CCXML session may launch a new CCXML session using <createccxml>. The new CCXML session executes in an
independent context and variable space from the original CCXML session, completely independent of the lifetime of the
original session. Sessions can communicate by sending messages via <send>
.
The media type application/ccxml+xml
will be registered for CCXML documents.
The proposed definition of the media type is located in Appendix J: The CCXML Media Type.
This media type should be used for a XML document containing CCXML content.
This section details the CCXML elements for control flow and execution.
<ccxml>
This is the parent element of a CCXML document and encloses the entire CCXML script in a document. When a
<ccxml>
is executed, its child elements are collected logically together at the beginning of the
document and executed in document order before the target <eventprocessor>
. This is called
document initialization.
The <ccxml>
can designate the CCXML namespace. This can be achieved by declaring an
xmlns
attribute or an attribute with an " xmlns
" prefix. See [XMLNS] for details. Note that when the xmlns
attribute is used alone, it sets the
default namespace for the element on which it appears and for any child elements. The namespace URI for CCXML is
"http://www.w3.org/2002/09/ccxml".
<ccxml>
Attribute DetailsName | 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 is 1.0. | |
xml:base | false | valid URL | none | A valid URL | The base URI for this document as defined in [XML-BASE]. As in [HTML], a URI which all relative references within the document take as their base. |
<meta>
The <metadata>
and <meta>
are containers in which information about the document can be placed. The
<metadata>
provides more general and powerful treatment
of metadata information than <meta>
by using a metadata
schema.
A <meta>
declaration associates a string to
a declared meta property or declares " http-equiv
" content. Either a
name
or http-equiv
attribute is REQUIRED.
It is an error to provide both name
and http-equiv
attributes. A
content
attribute is REQUIRED. The seeAlso
property is the only defined <meta>
property name. It is
used to specify a resource that might provide additional metadata information about the content. This property is
modelled on the
rdfs:seeAlso
property
of Resource Description Framework (RDF) Schema Specification 1.0 [RDF-SCHEMA
§2.3.4]. The http-equiv
attribute has a special significance when documents are
retrieved via HTTP. Although the preferred method of
providing HTTP header information is by using
HTTP header fields, the " http-equiv
" content MAY be used in situations where the CCXML document author is unable to configure
HTTP header fields associated with their document on the
origin server, for example, cache control information. Note that, as with <meta>
in HTML documents
[HTML], HTTP servers and caches are
not REQUIRED to introspect the contents of <meta>
in CCXML documents and thereby override the header values they would send
otherwise.
Informative: This is an example of how <meta>
can be
included in a CCXML document to specify a resource that provides additional metadata information and also indicate
that the document MUST NOT be cached.
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <meta name="seeAlso" content="http://example.com/my-ccxml-metadata.xml"/> <meta http-equiv="Cache-Control" content="no-cache"/> </ccxml>
<meta>
is an empty element.
<meta>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
name | false | This attribute may not be specified in conjunction with the http-equiv attribute | NMTOKEN | none | seeAlso |
The NAME of the metadata property.
The seeAlso property is used to specify a resource that might provide additional metadata information about the content. Either the name or the http-equiv attribute has to be specified. If neither of them is specified, or if both are specified, an error.fetch event will be thrown. |
http-equiv | false | This attribute may not be specified in conjunction with the name attribute | NMTOKEN | none | A valid HTTP header |
The NAME of an HTTP response header.
This attribute has special significance when documents are retrieved via HTTP. The http-equiv content may be used in situations where the CCXML document author is unable to configure HTTP header fields associated with their document on the origin server. Either the name or the http-equiv attribute has to be specified. If neither of them is specified, or if both are specified, an error.fetch event will be thrown. |
content | true | string | none | The value of the metadata property. |
<metadata>
<metadata>
is a container in which
information about the document can be placed using a metadata language. Although any metadata language can be used
within <metadata>
, it is
recommended that the Resource Description Format [RDF] be used in conjunction with the
general metadata properties defined by the Dublin Core Metadata Initiative [DC].
RDF [RDF-SYNTAX] is a declarative language and provides a standard way for using XML
to represent metadata in the form of statements about properties and relationships of items on the Web. A
recommended set of generally applicable metadata properties (e.g., " title
", "
creator
", " subject
", " description
", " copyrights
", etc.) is
the Dublin Core Metadata Element Set [DC], used in the example below.
Document properties declared with <metadata>
can use
any metadata schema.
Informative: This is an example of how <metadata>
can
be included in a CCXML document using the Dublin Core version 1.0 RDF schema [DC] describing
general document information such as title, description, date, and so on:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <metadata> <rdf:RDF xmlns:rdf = "http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc = "http://purl.org/dc/elements/1.1/"> <!-- Metadata about CCXML document --> <rdf:Description rdf:about="http://www.example.com/meta.ccxml" dc:title="Hamlet-like Soliloquy" dc:description="Aldine's Soliloquy in the style of Hamlet" dc:publisher="W3C" dc:language="en" dc:date="2002-11-29" dc:rights="Copyright 2002 Aldine Turnbet" dc:format="application/ccxml+xml" > <dc:creator>William Shakespeare</dc:creator> <dc:creator>Aldine Turnbet</dc:creator> </rdf:Description> </rdf:RDF> </metadata> </ccxml>
The following CCXML elements can occur within the content of <metadata>
: none .
<metadata>
Attribute DetailsName | 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 SHOULD be interpreted as
<if cond="..."> <!-- selected when <if cond> is true --> <elseif cond="true"/> <!-- selected when <if cond> is false --> <elseif cond="true"/> <!-- never selected --> </if>.With this definition for
<else>
, a valid XML [XML]
document is also a valid CCXML document.
<if>
Attribute DetailsName | 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 DetailsName | 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 DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
none | none | else is a synonym for elseif cond="true". |
<fetch>
<fetch>
is used to asynchronously fetch content identified by the attributes of the
<fetch>
. The fetched content may either be a CCXML document, or script content. Content that has
been acquired using <fetch>
is accessible through other elements defined by CCXML. Execution
returns from the element immediately, and the CCXML application can continue on while the platform works to fetch
the identified resource. When the fetch request has been completed, an event is generated against the session that
initiated the fetch. The event is one of fetch.done
, which indicates that the identified content was
fetched successfully, or error.fetch
, indicative of a failure to fetch the requested content. Note
that even if content is successfully fetched, errors in processing fetched content (for instance, a CCXML document
with a syntax error) may result in an error.fetch
being thrown.
The fetch request is local to the session that initiated the <fetch>
, and is referenced
through a unique identifier generated by the CCXML platform. The application may obtain the unique identifier for a
fetch request by providing an ECMAScript left-hand-side expression in the fetchid
attribute when the
fetch is performed. The fetch identifier can also be obtained as a property of the fetch.done
event.
The application uses the fetch identifier in any CCXML elements that reference fetched content, currently
<goto>
and <script>
.
Fetched content has a lifetime that is limited to that of the document in which it is fetched. Therefore,
following a transition to a new CCXML document using <goto>
, content fetched in the scope of the
current document is no longer accessible. Note that this should not be taken to preclude platform-level
optimizations or caching of resources that are fetched multiple times.
The use of <fetch>
to obtain content does not compel the application to make use of that
content. However, it is wasteful of system resources to fetch resources that are not used. Platforms are
responsible for clearing out unused fetch resources, and may impose limits on the resources that can be fetched by
a single session.
<fetch>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
next | true | ECMAScript Expression | none | must evaluate to a valid URL | An ECMAScript expression which returns the URI of the resource to be fetched. | |
type | false | ECMAScript Expression | application/ccxml+xml |
application/ccxml+xml
text/ecmascript text/javascript |
An ECMAScript expression which returns a character string that specifies
the MIME type of the fetched content.
Values defined by the specification are:
| |
namelist | false | Var List | none | List of ECMAScript Variable names |
A list of zero or more whitespace separated CCXML variable names.
These variables will be submitted to the server, with the same qualification
as used in the namelist.
When an ECMAscript variable is submitted to the server, its value is 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". | |
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 will 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 will receive a unique fetch identifier, even if the request if for the same URL. | |
timeout | false | ECMAScript Expression | none | An ECMAScript expression which returns a character string in CSS2 [CSS2] format | The character string returned is interpreted as a time interval. This interval begins when the fetch is executed. The fetch will fail if not completed at the end of this interval. A failed fetch will return the error.fetch event. | |
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 is 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 | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned is interpreted as a time interval. This indicates that the document is willing to use content that has exceeded its expiration time (cf. 'max-age' in HTTP 1.1 [RFC2616]). If maxstale is assigned a value, then the document is willing to accept content that has exceeded its expiration time by no more than the specified number of seconds. | |
enctype | false | Valid only when the value of the method is "post" | ECMAScript Expression | application/x-www-form-urlencoded | valid media encoding type |
An ECMAScript expression which returns a character string that indicates
the media encoding type of the submitted document (when the value of the method is "post").
Values defined by the specification are:
|
<goto>
<fetch>
, in conjunction with <goto>
, is used to transfer execution to a
different CCXML document in a multi-document CCXML application. The <fetch>
tells the platform
to find, load, and parse a given CCXML document. After the fetch completes, the CCXML application can then issue a
<goto>
to execute the now-fetched document.
Below is a small snippet of code from the CCXML application's event handler. We execute a
<fetch>
operation, and continue on to assign to a state variable, and maybe handle more events.
Eventually, the fetch completes, the CCXML platform services the event, and the application performs the
<goto>
.
<fetch next="'http://www.web.com/control.ccxml'"/> <--control continues here-> <assign name="state_var" expr="'fetch_wait'"/> </transition> <!-- ……… --> <transition state="fetch_wait" event="fetch.done" name="evt"/> <goto fetchid="evt.fetchid"/> </transition>
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 DetailsName | 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 will 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 ingore them anyway --> <fetch next="'http://www.example.com/fakefetch1.ccxml'"/> <fetch next="'http://www.example.com/fakefetch2.ccxml'"/> </transition> <transition event="fetch.done" name="evt"> <if cond="myGoodFetchID == evt.fetchid"> <!-- only matched if we have fetched http://www.example.com/goodfetch.ccxml --> <goto fetchid="evt.fetchid"/> </if> </transition> </eventprocessor> </ccxml>
<createccxml>
<createccxml>
is used to create another CCXML session, which begins execution with the document
identified by this element. The term "session" is not meant to imply a particular form of implementation. A CCXML
session exists for each concurrently executing CCXML document. A session provides independent execution and a
separate variable space for the CCXML documents it executes. A session is associated with one or more event sources
and will receive events only from those endpoints. The execution of a CCXML document MAY add
or subtract event sources from a session. The new CCXML session has no relation to its creator once spawned, and has
a wholly separate lifetime and address space.
Execution returns from the <createccxml>
element immediately, and the CCXML interpreter can
continue on while the new CCXML session is established and loads its initial document. If the new session is
successfully established or a failure occurs an event is generated and is delivered to the session that executed the
<createccxml>
element.
<createccxml>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
next | true | ECMAScript Expression | none | a valid URL | An ECMAScript expression which returns the URI of the resource to be fetched. | |
namelist | false | Var List | none | List of ECMAScript Variable names |
A list of zero or more whitespace separated CCXML variable names.
These variables will be submitted to the server, with the same qualification
as used in the namelist.
When an ECMAscript variable is submitted to the server, its value is 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". | |
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 will 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 is interpreted as a time interval. This time interval is interpreted by the new CCXML session as the maximum time it should 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.fetch 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 is 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 | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned is interpreted as a time interval. This indicates that the document is willing to use content that has exceeded its expiration time (cf. 'max-age' in HTTP 1.1 [RFC2616]). If maxstale is assigned a value, then the document is willing to accept content that has exceeded its expiration time by no more than the specified number of seconds. | |
enctype | false | Valid only when the value of the method is "post" | ECMAScript Expression | application/x-www-form-urlencoded | valid media encoding type |
An ECMAScript expression which returns a character string that indicates
the media encoding type of the submitted document (when the value of the method is "post").
Values defined by the specification are:
|
<exit>
<exit>
ends execution of the CCXML session. All pending events are discarded, and there is no
way to restart CCXML execution.
<exit>
Attribute DetailsName | 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 is ECMAScript undefined. This value is stored as a property of the exit event. | ||
namelist | false | Var List | none | List of ECMAScript Variable names | A list of one or more whitespace separated CCXML unqualified variable names to be returned. These variable names and their associated values will be set as properties of the exit event. |
A CCXML document executing the <exit>
will generate a ccxml.exit
event to the
parent session. The exiting document will be identified on the exit event by its session ID.
<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 DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
label | false | ECMAScript Expression | none | An ECMAScript expression which returns a character string which may 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. It is delivered to the document which issued the request.
The fields of this event are:
Field Name | Details |
---|---|
name |
fetch.done |
fetchid |
The internally generated unique fetch identifier |
uri |
The URI of the fetch request. |
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:
Field Name | Details |
---|---|
name |
error.fetch |
fetchid |
The internally generated unique fetch identifier |
reason |
A string description of the fetch error. |
uri |
The URI of the fetch request. |
ccxml.exit
- CCXML Document Exit EventThis event is generated when a CCXML document
executes an <exit>
.
This event is only generated when the session executing the
<exit/>
has a parent session. This event is sent to the
parent session and not the session executing the <exit/>
.
The fields of this event are:
Field Name | Details |
---|---|
name |
ccxml.exit |
sessionid |
the identifier of the exiting session; this is the same value returned to the
sessionid attribute of the <createccxml> which created this session; |
expr |
the value of the <exit> expr attribute; |
namelist |
If the namelist attribute was specified in the
<exit> , this property is a string valued array of the names in the list. The length of the
property is equal to the number of names in the list. The actual values are stored in the " values "
sub-object. |
values.* |
Each name in the namelist is a property whose value is the value of the name at
the time the <exit> was executed. |
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 SHOULD generate this event when the CCXML
document is first loaded, both at session startup and after transferring control to a new document with the
<goto>
. This event would be processed after the platform had executed the document initialization
including executing any elements under the <ccxml>
.
The fields of this event are:
Field Name | Details |
---|---|
name |
ccxml.loaded |
sessionid |
the identifier of the session on which this document is executing; |
parent |
the identifier of the session which issued the <createccxml>
to start this document; if this document was started directly by the CCXML platform, the identifier is 0 |
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 the 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:
Field Name | Details |
---|---|
name |
ccxml.kill |
sessionid |
the identifier of the session |
reason |
a string describing the reason the platform sent the kill event. Content of this field is platform-specific, and is only for informative purposes. |
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 and has begun execution of it.
The fields of this event are:
Field Name | Details |
---|---|
name |
ccxml.created |
sessionid |
The identifier of the newly created CCXML session. This is the same identifier as
was returned on the sessionid attribute of the <createccxml> request that created
the session. |
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:
Field Name | Details |
---|---|
name |
error.createccxml |
sessionid |
The identifier of the failing CCXML session. This is the same identifier as was
returned on the sessionid attribute of the <createccxml> request that created the
session. |
reason |
A string description of the error encountered. |
error.unsupported
- CCXML Unsupported OperationThis event is generated when an OPTIONAL operation that is not supported by the platform is executed.
The fields of this event are:
Field Name | Details |
---|---|
name |
error.unsupported |
reason |
A string description of the error encountered. |
CCXML does not provide any mechanism for interacting with callers but relies on separate dialog environments such as VoiceXML [ VOICEXML ]. Whenever interaction with a caller is required a CCXML session can initiate a separate dialog provided by a VoiceXML capability or some other technology. When the interaction is complete, control returns to the CCXML session which can use any results returned by the dialog environment to decide what should happen next.
Dialogs initiated by CCXML sessions are not tied to any single dialog language or technology. Any dialog system which fulfils CCXML's requirements MAY be used for interaction with the caller. Examples of dialog systems include VoiceXML, SALT [ 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.
A CCXML program initiates a dialog using the <dialogstart>
element. Execution of this element
connects a dialog environment to a connection and instructs it to start interacting with the caller. For some dialog
environments it may take some time to initialize the dialog environment and thus the use of the
<dialogstart>
element alone may cause the caller to hear silence, or "dead air". To avoid this
situation CCXML provides an ability to ready a dialog environment prior to connecting and starting it, this is done
using the <dialogprepare>
element. Any dialog that has been either started with
<dialogstart>
, or prepared with <dialogprepare>
can be terminated using the
<dialogterminate>
element. CCXML implementations MUST support the
<dialogprepare>
, <dialogstart>
, and <dialogterminate>
elements though the exact behaviour may vary depending on the dialog environments supported.
The following examples illustrate the valid use patterns for these three elements. Firstly the normal case of
preparing a dialog, starting it, then optionally terminating it before normal completion. This example illustrates
the use of <dialogprepare>
to ready a dialog while the call is left in alerting state. When the
alerting notification arrives the script executes a <dialogprepare>
to prepare a dialog and
associate it with the connection. When the dialog is prepared the script executes an <accept>
to
connect the call and then when the connection transitions to connected state, a <dialogstart>
element is used to execute the previously prepared dialog.
<transition event="connection.alerting" name="evt"> <dialogprepare src="..." connectionid="evt.connectionid"/> </transition> <transition event="dialog.prepared" name="evt"> <accept connectionid="session.dialogs[evt.dialogid].connectionid"/> </transition> <transition event="connection.connected" name="evt"> <dialogstart prepareddialogid="evt.dialogid" connectionid="evt.connectionid"/> </transition> (optionally) <transition event="???"> <dialogterminate dialogid="..." /> </transition>
The next example shows a single step dialog invocation without dialog preparation. In this case a connection in
alerting state is accepted and, when the transition to connected state occurs, a <dialogstart>
element is used to start the dialog.
<transition event="connection.alerting" name="evt"> <accept connectionid="evt.connectionid"/> </transition> <transition event="connection.connected" name="evt"> <dialogstart src="..." connectionid="evt.connectionid"/> </transition> (optionally) <transition event="???"> <dialogterminate dialogid="..." /> </transition>
The final example shows the case where a dialog which has been previously prepared is cancelled before a
<dialogstart>
has been issued. A dialog may be terminated when it is in the prepared state or
while it is being prepared such as might be the case if the caller hangs up at some arbitrary point. In this case the
<dialogterminate>
may be executed before or after the dialog.prepared
event is
processed.
<transition event="connection.connected"> name="evt"> <dialogprepare src="..." connectionid="evt.connectionid"/> </transition> <transition event="connection.disconnected" name="evt"> <dialogterminate dialogid="evt.connection.dialogid" /> </transition>
<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.
When preparation of the dialog competes successfully a dialog.prepared
event is posted to the event
queue of the CCXML session. If however the dialog cannot be prepared for any reason, an
error.dialog.notprepared
event is posted.
CCXML implementations MUST support dialog preparation though the processing carried out
as part of a <dialogprepare>
request is dialog manager specific. In the case of a dialog manager
that does not support preparation, the CCXML implementation MUST as a minimum, note the
values provided via the src
, namelist
, and connectionid
attributes, create a
Dialog object, and return a new unique value to the location defined by the dialogid
attribute.
The CCXML session selects what it believes to be the appropriate dialog manager based on the MIME type specified
by the type
attribute without retrieving the resource specified by the src
URI. If, when
the dialog manager retrieves the content, it finds the MIME type, as specified by the
HTTP headers, differs from that specifed by the
type
attribute, it SHOULD raise an error.dialog.notprepared
event
with a reason
indicating the type mismatch. The dialog manager MUST NOT ignore
the type mismatch or render the resource as a different type based on the
HTTP headers or on inspection of the document data. Refer to
the W3C guidelines for client handling of MIME types [MIME-TAG] for
further information.
<dialogprepare>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
src | true | ECMAScript Expression | none | a Dialog URL | An ECMAScript expression which returns a character string identifying the URI of the dialog document that the dialog interpreter should 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 is actually used.
Values defined by the specification are:
| |
namelist | false | Var List | none | List of ECMAScript Variable names |
A list of one or more whitespace separated CCXML variable names.
These variables will be submitted to the server, with the same qualification
as used in the namelist.
When an ECMAscript variable is submitted to the server, its value is 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". | |
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 will receive a dialog identifier value for the launched dialog interpreter instance. This identifier may be used on future invocations of dialogstart, dialogterminate, join, or unjoin. | |
connectionid | false | Can not be used with conferenceid | ECMAScript Expression | none | Connection IDs |
An Optional ECMAScript expression which returns the identifier of a connection.
The specified connection will be associated with the dialog being prepared.
If the attribute value is invalid, an error.semantic event will be thrown. |
conferenceid | false | Can not be used with connectionid | ECMAScript Expression | none | Conference IDs |
An Optional ECMAScript expression which returns the identifier of`a confe2ence bridge.
A connection will be allocated for the dialog being prepared.
If the attribute value is invalid, an error.semantic event will 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
specified by the connectionid or conferenceid attribute.
The following values can be used:
| |
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 is 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 | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned is interpreted as a time interval. This indicates that the document is willing to use content that has exceeded its expiration time (cf. 'max-age' in HTTP 1.1 [RFC2616]). If maxstale is assigned a value, then the document is willing to accept content that has exceeded its expiration time by no more than the specified number of seconds. | |
enctype | false | Valid only when the value of the method is "post" | ECMAScript Expression | application/x-www-form-urlencoded | valid media encoding type |
An ECMAScript expression which returns a character string that indicates
the media encoding type of the submitted document (when the value of the method is "post").
Values defined by the specification are:
|
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:
|
<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
includes either a URI reference to the initial document for the dialog or the identity of a previously prepared
dialog. The dialog executes on a separate logical execution thread (this MAY be a thread,
process, or system depending upon platform implementation) and does not block the processing of further events by the
CCXML session.
If the dialog cannot be started for any reason, an error.dialog.notstarted
event is posted to the
event queue of the CCXML session that processed the <dialogstart>
request. When the dialog
completes, a dialog.exit
event is posted to the event queue of the CCXML session that started it.
If the connectionid
attribute of <dialogstart>
is specified, and if the dialog
language allows access to telephony variables such as ANI, DNIS and UUI, values of these variables will be propagated
from the specified connection to the dialog application.
If the prepareddialogid
attribute is specified and a connectionid
or
conferenceid
attribute was specified on the prior <dialogprepare>
element, specifying
a different connectionid
or conferenceid
on the <dialogstart>
element
WILL result in the throwing of an error.dialog.notstarted
event.
The CCXML session selects the appropriate dialog manager based on the MIME type specified by the type
attribute without retrieving the resource specified by the src
URI. If, when the dialog manager
retrieves the content, it finds the MIME type, as specified by the
HTTP headers, differs from that specifed by the
type
attribute, it SHOULD raise an error.dialog.notstarted
event
with a reason
indicating the type mismatch. The dialog manager MUST NOT ignore
the type mismatch or render the resource as a different type based on the
HTTP headers or on inspection of the document data. Refer to
the W3C guidelines for client handling of MIME types [MIME-TAG] for
further information.
<dialogstart>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
src | false | This attribute may not be specified in conjunction with the prepareddialogid attribute. | ECMAScript Expression | none | a valid Dialog URL | An ECMAScript expression which returns a character string identifying the URI of the dialog document that the dialog interpreter should load and begin execution upon startup. |
prepareddialogid | false | This attribute may not be specified in conjunction with the src, type 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.
If the specified dialog identifier refers to an unknown dialog or a dialog that has already been executed, by way of another dialogstart element, an error.dialogwrongstate event is thrown. |
type | false | This attribute may 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 is actually used.
Values defined by the specification are:
|
namelist | false | This attribute may 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 will be submitted to the server, with the same qualification
as used in the namelist.
When an ECMAscript variable is submitted to the server, its value is 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". |
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 will receive a dialog identifier value for the launched dialog interpreter instance. This identifier may be used on future invocations of dialogterminate, join, or unjoin. | |
connectionid | false | Can not be used with conferenceid. | ECMAScript Expression | comes from the event being processed | Connection IDs |
An Optional ECMAScript expression which returns the identifier of a connection.
The specified connection will be associated with the dialog being prepared.
If both the connectionid and the conferenceid are omitted and the dialog was previously prepared
using a dialogprepare element with a connectionid or conferenceid specified, the interpreter
will use the id as specified on the dialogprepare element.
If neither the connectionid or conferenceid is specified and the dialog had not previously been prepared, the interpreter will use the id indicated in the current event being processed. For more information about connections and bridges, refer to Section 10 . If both connectionid and conferenceid are specified, an error.fetch event will be thrown. If the attribute value is invalid or there is no valid default value, an error.semantic event will be thrown. |
conferenceid | false | Can not be used with connectionid. | ECMAScript Expression | comes from the event being processed | Conference IDs |
An Optional ECMAScript expression which returns the identifier of a conference bridge.
If both the connectionid and the conferenceid are omitted and the dialog was previously prepared
using a dialogprepare element with a connectionid or conferenceid specified, the interpreter
will use the id as specified on the dialogprepare element.
If neither the connectionid or conferenceid is specified and the dialog had not previously been prepared, the interpreter will use the id indicated in the current event being processed. For more information about connections and bridges, refer to Section 10 . If both connectionid and conferenceid are specified, an error.fetch event will be thrown. If the attribute value is invalid or there is no valid default value, an error.semantic event will 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 can be used:
|
maxage | false | This attribute may not be specified in conjunction with the prepareddialogid attribute. | ECMAScript Expression | none | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned is 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 | This attribute may not be specified in conjunction with the prepareddialogid attribute. | ECMAScript Expression | none | An ECMAScript expression which returns a valid time value for the HTTP 1.1 request [RFC2616] | The character string returned is 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 | This attribute may not be specified in conjunction with the prepareddialogid attribute. Valid only when the value of the method is "post". | ECMAScript Expression | application/x-www-form-urlencoded | valid media encoding type |
An ECMAScript expression which returns a character string that indicates
the media encoding type of the submitted document (when the value of the method is "post").
Values defined by the specification are:
|
method | false | This attribute may not be specified in conjunction with the prepareddialogid attribute. | 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:
|
<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 sends a terminate request to the specified dialog.
A dialog terminated due to the processing of a <dialogterminate>
element
MAY still return data to the CCXML application using a dialog.exit
event if the
value of the immediate
attribute is false
or unspecified. The details of the data returned
are dialog environment specific.
If the immediate
attribute is set to true
the dialog does not return data to the CCXML
application and the CCXML interpreter SHALL post a dialog.exit
event
immediately.
<dialogterminate>
Attribute DetailsName | 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 will be thrown. | |
immediate | false | ECMAScript Boolean Expression | false |
true
false |
An ECMAScript Boolean expression, that identifies the termination style of the
dialog.
Valid values are:
|
The majority of communication between CCXML interpreter sessions and dialogs is by way of events. Dialog
environments post events to the CCXML interpreter event queue and a CCXML application can send an event to a dialog.
How this is handled on the dialog side is dialog manager and CCXML interpreter dependent. On the CCXML side it is
done by using <send>
and passing in the dialogid
that was received as a result of
processing a <dialogstart>
.
The following are the CCXML events related to dialogs:
dialog.started
The dialog.started
event is thrown when a dialog is successfully started. The fields available in the
event are:
Field Name | Details |
---|---|
name |
'dialog.started' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to which the dialog connection is bridged
(usually the connectionid that was specified in the <dialogstart> ). If the
dialog is bridged to a conference the value will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection is bridged
(usually the conferenceid that was specified in the <dialogstart> ). If the
dialog is bridged to a connection the value will be undefined. |
dialog.exit
The dialog.exit
event is thrown when a dialog terminates either normally or following a
<dialogterminate>
request. The fields available in the event are:
Field Name | Details |
---|---|
name |
'dialog.exit' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to which the dialog connection is bridged
(usually the connectionid that was specified in the <dialogstart> ). If the
dialog is bridged to a conference the value will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection is bridged
(usually the conferenceid that was specified in the <dialogstart> ). If the
dialog is bridged to a connection the value will be undefined. |
namelist |
List of items that are stored on the values sub-object. |
values.* |
Values returned from the dialog. |
dialog.disconnect
The dialog.disconnect
event is thrown when a dialog requests it be disconnected from its current
call. The dialog is not terminated, but simply requests the CCXML application end the call. The fields available in
the event are:
Field Name | Details |
---|---|
name |
'dialog.disconnect' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to which the dialog connection is bridged
(usually the connectionid that was specified in the <dialogstart> ). If the
dialog is bridged to a conference the value will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection is bridged
(usually the conferenceid that was specified in the <dialogstart> ). If the
dialog is bridged to a connection the value will be undefined. |
namelist |
List of items that are stored on the values sub-object. |
values.* |
Values returned from the dialog. |
dialog.transfer
The dialog.transfer
event is thrown when a dialog requests a transfer of its current call. The fields
available in the event are:
Field Name | Details |
---|---|
name |
'dialog.transfer' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to which the dialog connection is bridged (usually
the connectionid that was specified in the <dialogstart> ). If the dialog is
bridged to a conference the value will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection is bridged (usually
the conferenceid that was specified in the <dialogstart> ). If the dialog is
bridged to a connection the value will be undefined. |
type |
A string value specifying the transfer type. |
URI |
A URI describing the destination to which this call should be transfered. The format of this information is protocol and platform specific but might consist of a telephone URI [ RFC2806 ] or a SIP URI [ RFC3261 ]. |
namelist |
List of items that are stored on the values sub-object. |
values.* |
Dialog transfer parameters. This is where a dialog language can specify more
information about the transfer request. For example with VoiceXML this could contain all the attributes of the
<transfer> . |
maxtime |
A string in CSS2 format that specifies the maximum amount of time the transfer should stay connected. If the amount of time is unlimited the value will be 0s. |
connecttimeout |
A string in CSS2 format that specifies the maximum amount of time to spend while attempting to connect the call. |
aai |
A string of application-to-application information to be passed to the destination party when establishing the transfer. |
dialog.terminatetransfer
The dialog.terminatetransfer
event is thrown when a ongoing transfer must be terminated, for example
due to a "hotword" recognition. As part of handling of the dialog.terminatetransfer
event, the CCXML
Application should terminate the outgoing call leg and return the media stream of the original call to the dialog
using the <join>
tag. The fields available in the event are:
Field Name | Details |
---|---|
name |
'dialog.terminatetransfer' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to which the dialog connection is bridged
(usually the connectionid that was specified in the <dialogstart> ). If the
dialog is bridged to a conference the value will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection is bridged
(usually the conferenceid that was specified in the <dialogstart> ). If the
dialog is bridged to a connection the value will be undefined. |
reason |
A string value specifying the reason the transfer needs to be returned. |
error.dialog.notstarted
The error.dialog.notstarted
event is thrown when the processing of a <dialogstart>
element fails because the dialog cannot be started for some reason. The fields available in the event are:
Field Name | Details |
---|---|
name |
'error.dialog.notstarted' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to which the dialog connection could not be
started (usually the connectionid that was specified in the <dialogstart> ). If
the dialog was being connected to a conference the value will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection could not be
started (usually the conferenceid that was specified in the <dialogstart> ). If
the dialog was being connected to a connection the value will be undefined. |
reason |
A description of the reason the dialog could not be started. |
error.dialog.wrongstate
The error.dialog.wrongstate
event is thrown when a dialog request such as
<dialogterminate>
has been received by the dialog environment but it cannot be completed because
the dialog is not in a suitable state. The fields available in the event are:
Field Name | Details |
---|---|
name |
'error.dialog.wrongstate' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to which the dialog connection is bridged
(usually the connectionid that was specified in the <dialogstart> ). If the
dialog is bridged to a conference the value will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection is bridged
(usually the conferenceid that was specified in the <dialogstart> ). If the
dialog is bridged to a connection the value will be undefined. |
reason |
A description of the reason the dialog is in the wrong state. |
dialog.user.*
The dialog.user.*
event is thrown when a dialog sends a user event to the CCXML session that
initiated it. The fields available in the event are:
Field Name | Details |
---|---|
name |
'dialog.user.*' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to which the dialog connection is bridged
(usually the connectionid that was specified in the <dialogstart> ). If the
dialog is bridged to a conference the value will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection is bridged
(usually the conferenceid that was specified in the <dialogstart> ). If the
dialog is bridged to a connection the value will be undefined. |
namelist |
List of items that are stored on the values sub-object. |
values.* |
Values associated with the event. |
dialog.prepared
The dialog.prepared
event is thrown when a dialog has been successfully prepared following the
execution of a <dialogprepare>
element. The fields available in the event are:
Field Name | Details |
---|---|
name |
'dialog.prepared' |
dialogid |
The ID of the dialog. |
connectionid |
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 will be undefined. |
conferenceid |
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 will be undefined. |
error.dialog.notprepared
The error.dialog.notprepared
event is thrown when the processing of a
<dialogprepare>
element fails. The fields available in the event are:
Field Name | Details |
---|---|
name |
'error.dialog.notprepared' |
dialogid |
The ID of the dialog. |
reason |
A description of the reason the dialog could not be prepared. |
connectionid |
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 will be undefined. |
conferenceid |
The identifier of the conference to which the dialog connection attempting to be
prepared (usually the conferenceid that was specified in the <dialogprepare> ).
If the dialog was prepared without a conference the value will be undefined. |
dialog.transfer.complete
This event is sent from the CCXML application to the Dialog which uses this to fill transfer results (i.e. for VoiceXML platforms to fill field item results). The fields of this event are:
Field Name | Details |
---|---|
results.* |
The data that SHOULD be filled in the dialog as transfer results. |
For a complete source code example of how to support transfer please see the section below titled VoiceXML 2.0 Example.
An instance of the Dialog boject is associated with each dialog created by <dialogstart>
and
referenced in the session.dialogs
array.
Dialog Properties | Definitions |
---|---|
id |
this property is the ECMAScript string value of the Dialog identifier, which uniquely identifies each instance of the Dialog class |
connectionid |
Identifies the connection that is driving a media stream to the dialog. If the
media stream to the dialog is not being driven by a connection then this property will be undefined. Note: connectionid and conferenceid properties are mutually exclusive. |
conferenceid |
Identifies the connection that is driving a media stream to the dialog. If the
media stream to the dialog is not being driven by a connection then this property will be undefined. Note: connectionid and conferenceid properties are mutually exclusive. |
type |
an ECMAScript expression which returns a character string that specifies the MIME type of the document that loaded the dialog. |
src |
Is an ECMAScript expression which returns a character string identifying the URI of the dialog document. |
duplex |
duplex in conjunction with the connectionid or
conferenceid property identifies the media source of the dialog.The value of this property can be either "full", "half" or "undefined". When a bidirectional dialog is created duplex will be set to "full". A unidirectional dialog will have the duplex property
set to "half" indicating that this dialog is receiving a media stream from a connection or conference.If the dialog does not have a source duplex will be "undefined". |
CCXML expressions are valid ECMAScript [ ECMASCRIPT ] expressions, assignable to variables with valid ECMAScript names. For further details please see section 3.4.
<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'" />
It is illegal to make an assignment to a variable that has not been explicitly declared using
<var>
or a var
statement within a <script>
. Attempting to assign
to an undeclared variable causes an error.semantic
event to be thrown. Please see
Section 9.5 for a detailed description of error events.
Variables declared without an explicit initial value MUST be initialized to the
ECMAScript value undefined
by the implementation.
Note that when an ECMAScript object, e.g. "obj
", has been properly initialized then its properties,
for instance "obj.prop1
", can be assigned without explicit declaration. An attempt to declare ECMAScript
object properties such as "obj.prop1
" results in an error.semantic
event being thrown.
CCXML uses an ECMAScript scope chain (please see section 3.4.2) to
allow variables to be declared at different levels of hierarchy in an application. For instance, a variable declared
at ccxml (document) scope can be referenced anywhere within that document, whereas a local variable declared in a
<transition>
is only available within that element.
The implementation MUST define 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 |
Variables within this scope are provided by CCXML implementation and are read-only. They are visible to documents within the CCXML application. See Section 8.3 for further details. |
application |
Variables within this scope are not explicitly declared and can be modified by CCXML programs. They are visible to documents within the CCXML application. See Section 8.4 for further details. |
ccxml |
Variables within this scope are declared with <var> and
<script> elements that are children of <ccxml> . They are initialized in
document order when the document is loaded. They exist while the document is loaded. They are visible only within
that document. |
transition |
Each <transition> element has a scope that exists while the
implementation is processing the executable content within that <transition> , and which is
visible to the elements of that <transition> . Variables with transition scope are declared by
<var> and <script> child elements of <transition> . The
child <var> and <script> elements of <transition> are
initialized in document order when the executable content is executed. |
The implementation MUST instantiate a variable within the scope of the closest containing scope element. The fully-qualified name of a variable is the name of the variable's scope object prepended with a dot to the name of the variable. The implementation MUST allow reference to variables by their fully qualified names. The implementation MUST allow reference to variables without requiring use of their fully qualified names. In the case of like-named variables declared in different scopes, the implementation MUST reference the variable in the closest containing scope, unless the fully-qualified variable name is used.
The implementation MUST resolve variables by searching the enclosing
transition
scope first (if applicable) followed by the ccxml
scope,
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.
<var>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
name | true | ECMAScript Expression | 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 is determined from the position in the document at which the variable is defined. | |
expr | false | ECMAScript Expression | none | Valid ECMAScript Expression | Indicates the new value of the variable. This is the initial value. It must be a valid ECMAScript expression. |
<assign>
Attribute DetailsName | 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 will 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.
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.
<script>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
src | false | This attribute may not be specified in conjunction with the fetchid attribute. | Valid URL | none | a valid URL |
A URI which references a resource which is the script content, and which will be resolved
when the CCXML document is compiled. If both the src and fetchid are not
present, the script element content provides the script content.
If both are present the implementation must throw an error.fetch event.
Note that the value of the src attribute is not an ECMAScript expression in order to allow it to be resolved at compile-time. If the script cannot be fetched the implementation must throw an error.fetch event. |
fetchid | false | This attribute may not be specified in conjunction with the src attribute. | 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 is thrown. |
timeout | false | This attribute is only valid in conjunction with the src attribute. | Character string | none | Character string in CSS2 [CSS2] format | The character string is interpreted as a time interval. This interval begins when the script is requested; If the script has not been fetched at the end of this interval, an error.fetch event occurs. |
maxage | false | This attribute is only valid in conjunction with the src attribute. | Character string | none | A valid time value for the HTTP 1.1 request [RFC2616] | The character string is 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 | This attribute is only valid in conjunction with the src attribute. | Character string | none | A valid time value for the HTTP 1.1 request [RFC2616] | The character string is 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. |
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 are modified by the CCXML implementation during execution time of the script as the state of the executing CCXML session changes. For example, when the state of a Connection changes within a CCXML session, the value of the state property of the session Connection object will be updated by the CCXML implementation so that if the CCXML program's event handler evaluates the state variable, it will reflect the current state of the Connection object. 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.
session
is a top level object inside the ECMAScript session context.
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.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" name="evt"> <if cond="session.connections['1234'].id==evt.connid"> <-- if the disconnect is on the first connection, do something --> <else/> <exit/> </if> </transition>
session.conferences
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.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.
application
is a top level object inside the ECMAScript session context. Application
variables are not explicitly declared since they are properties of the application
object initialized by
the CCXML implementation. 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.
It is the responsibility of the CCXML implementation to properly initialize the
application
object and manage updates to application variables as they occur during the life-cycle of
the CCXML application.
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 developer 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 CCXML sessions can 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 are otherwise free to define and support any platform-specific
events they like. In addition, users/programmers may use <send>
to send arbitrary events to
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 the Event I/O Processor component is currently platform dependent but may be standardized at some point in the future by some other W3C specification.
Each running CCXML interpreter has a queue, into which it places incoming events, and sorts them
by arrival time. A CCXML programmer can only gain access to these queued events by using the
<eventprocessor>
element with associated <transition>
elements.
The CCXML session event queue generally operates in a First In, First Out (FIFO) manner with events to be processed being removed from the head and new events being placed at the tail. There are two exceptions to this behaviour: events where a time delay has been specified, and certain special events that are always placed at the head of the queue.
An event can be delivered to a CCXML session using a <send>
element in which
case an optional delay may be specified. When a delay is specified the event is delivered to the target CCXML session
but it is not placed on to the event queue until the delay time has elapsed. When the delay has elapsed the
event is placed at the tail of the queue.
There are two types of event that, when delivered to a CCXML session, are handled differently.
All 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.*
or ccxml.kill.*
events that are already on the queue.
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 '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 state 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.
An <eventprocessor>
is interpreted by an implicit Event Handler Interpretation Algorithm
(EHIA). The EHIA's main loop removes the first event from the CCXML session's event queue, and then selects from the
set of <transition>
s contained in the <eventprocessor>
. A
<transition>
always indicates a set of accepted event types, and MAY
indicate a further ECMAScript conditional expression to be evaluated. The <transition>
that
accepts the type for the just-removed event, has a satisfied conditional expression, and appears first in the
<eventprocessor>
in document order, is the selected <transition>
.
Once selected, the elements inside a <transition>
are executed in document order. 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 a ccxml.kill
event is received. In this case, the
CCXML interpreter will end the session if there are no <transition>
s that match the
ccxml.kill
event 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.
Code inside an <eventprocessor>
SHOULD run "instantaneously", 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>
.
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>
s, driven by incoming events, moving the machine to a new state and
creating side effects along the way.
If an event is not selected by any <transition>
within the <eventprocessor>
,
the CCXML platform SHOULD log the event using the "missed" label. The CCXML platform can
configure the "missed" label for any desired disposition. This SHOULD be equivalent to the
transition:
<transition event="*" name="ev"> <log label="'missed'" expr="ev.toString()"/> </transition>
<eventprocessor>
The <eventprocessor>
acts a container for <transition>
s. A valid CCXML
document MUST only have a single <eventprocessor>
.
<eventprocessor>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
statevariable | false | string | none | ECMAScript Variable name | This is a CCXML variable name, which is the name of the eventprocessor's state variable. This variable must be defined using the var or the script element in the ccxml scope. |
<eventprocessor>
can contain only <transition>
s .
<transition>
<transition>
specifies the actions to be
taken when it is selected. The <transition>
are examined by the EHIA in document order.<transition>
MUST satisfy three criteria:
statevariable
specified by the parent <eventprocessor>
MUST be currently set to one of the values listed in the <transition>
's
state attribute, if that attribute is present<transition>
's cond
attribute
MUST evaluate to true, if that attribute is presentname
property MUST match the pattern specified by the
<transition>
's event
attribute, if that attribute is present<transition>
with none of the attributes, state
, cond
, or
event
, will always be selected when encountered by the EHIA.
<transition>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
state | false | string | none | This indicates the current possible state(s) of the eventprocessor . More than one state name may be specified, separated by white space. | ||
event | false | string | none | This is a pattern that indicates a matching event type. Event types are dot-separated strings of arbitrary length. The character * is a wild-card, and will match zero or more characters of the processed event's type name. | ||
cond | false | ECMAScript Expression | true |
An ECMAScript expression which can be evaluated to true or false. If this attribute is present,
it must evaluate to true for the transition to be selected. Note: You can not access the value
of a the variable listed in the name attribute as it will not do the
assign until the transition has been selected.
| ||
name | 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 will be set to the received event object. The event object can only be referenced by this name while executing the transition . |
<transition>
Event MatchingThe event
attribute of a <transition>
specifies a pattern used to match event
names. If the state
matches the current state and the cond
attribute expression is true,
the <transition>
will be selected if the event
pattern matches the event name. Event
names are case-insensitive.
Pattern match examples
Pattern |
Matches |
---|---|
* |
any event name |
error.* |
error.fetch, error.dialog.notstarted |
error.*.* |
error.dialog.wrongstate |
err* |
any event name starting with "err" |
<send>
<send>
is used to send messages containing events or other information directly to another
CCXML Interpreter other external systems using an Event I/O Processor.
The event target of <send/>
is specified using the
target
and
targettype
attributes. These attributes control how the platform
should dispatch the event to its final destination.
The target
attribute specifies the unique identifier of the event target that the Event I/O Processor
should send the event to. This can be the value of a CCXML Session ID or a Dialog ID if you wish to send an event to
one of these respective targets. In the case where you are using some other Event I/O Processor this attribute should
be able to describe how to connect to the event destination (For example a SIP URL for SIP-INFO messages or a HTTP
URL for Web Services). If the value of the target
attribute is not supported, invalid or unreachable by
the Event I/O Processor the Platform MUST throw a error.send.targetunavailable
event.
The targettype
attribute controls what Event I/O Processor the event should be sent to. The default
value of this attribute is 'ccxml'. If the event targettype
specified is not supported the platform
MUST throw a error.send.targettypeinvalid
event.
A platform must support the following values for the targettype
attribute:
Value |
Details |
---|---|
ccxml |
CCXML Session Event Processor. |
dialog |
Dialog Event Processor. |
Platforms may support other types of Event I/O Processors, for example: Web-services, SIP or basic HTTP GET. However, platforms SHOULD name the Event I/O Processor beginning with "x-" to signify that they are platform dependent.
<send>
also specifies the content of the message to be sent. <send>
may
specify message content in one of two ways (the following mechanisms are mutually exclusive):
data
attribute with an OPTIONAL namelist
data
attribute specifies an ECMAScript expression that returns the name of the event.namelist
attribute specifies a space separated list of CCXML ECMAScript variables to be
included with the message.<var name="target" expr="'tel:+18005551212'"/> <var name="content" expr="'http://www.example.com/mycontent.txt'"/> <send target="target" targettype="'x-messaging'" data="'fax.SEND'" namelist="content"/>
xmlns
attribute with explicit content inline XML content specifying the message to sent the
xmlns:<namespace>
defines a namespace for the inline content
<send target="'csta://csta-server.example.com/'" targettype="'x-csta'" xmlns:csta="http://www.ecma.ch/standards/ecma-323/csta"> <csta:MakeCall> <csta:callingDevice>22343</callingDevice> <csta:calledDirectoryNumber>18005551212</csta:calledDirectoryNumber> </csta:MakeCall> </send>
If an explicit namespace is provided as in the xmlns attribute of the <send>
, this namespace
can be used to validate the content of the <send>
. A namespace specified on a
<send>
applies only to the attributes and content of the <send>
. Multiple
namespaces MAY be included in the <send>
to associate message content
with more than one namespace.
When an explicit namespace is specified for the <send>
, the content of the
<send>
is parsed but can be ignored by the sending CCXML Interpreter until the
<send>
is executed. XML namespace identifiers contained in the <send>
MUST be preserved and it is the responsibility of the Event I/O Processor responsible for
forwarding events to the <send>
target to parse the incoming message and remove the namespace
prefix, if required by the <send>
target.
The sending CCXML Interpreter MUST NOT alter the content of the
<send>
. The data contained within a <send>
MUST be
sent to the destination specified in the target attribute of <send>
using the Event I/O Processor
specified by the targettype attribute. When <send>
is used with inline XML
content, and the target is a CCXML session, the mapping of that XML content to event object properties is
implementation-specific, and outside the scope of this specification. Although the full set of requirements
for the Event I/O Processor is not within the scope of this specification, an event processor sending an event to a
CCXML Interpreter is required to generate an event which can be processed in a CCXML Session. See Section 9.1 for
details regarding the processing of incoming events by an CCXML Interpreter.
When a message is successfully sent to the target, a send.successful
event will be thrown. Note that
this does not mean that the target processed the message successfully. It is up to the target to generate events
specific to the message. These events are application specific.
If the send request fails, an event signifying the error will be returned to the CCXML Session. The failure events are documented at the end of this section.
<send>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
target | true | ECMAScript Expression | none | A valid target URL | An ECMAScript expression returning the target location of the event. The target attribute specifies the unique identifier of the event target that the Event I/O Processor should send the event to. | |
targettype | false | ECMAScript Expression | ccxml |
ccxml
dialog |
An ECMAScript expression which returns a character string that specifies
the type of the Event I/O Processor that the event should be dispatched to.
Values defined by the specification are:
| |
sendid | 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 will receive an internally generated unique string
identifier to be associated with the event being sent.
If this attribute is not specified, the event identifier is dropped. | |
delay | false | ECMAScript Expression | '0s' | An ECMAScript expression which returns a character string in CSS2 [CSS2] format |
The character string returned is interpreted as a time interval.
The send tag will return immediately, but the event is not dispatched until the delay interval
elapses.
Timers are useful for a wide variety of programming tasks, and can be implemented using this attribute.
Note: The queue for sending events is maintained locally. Any events waiting to be sent will be purged when the session that issued this request terminates. | |
xmlns:[YourNameSpacePrefix] | false | string | none | This returns a namespace identifying the contained message format. More than one xmlns attribute may be included. | ||
data | false | This attribute may not be specified in conjunction with inline content | ECMAScript Expression | none |
An ECMAScript expression which returns a character string that indicates the type of event
being generated. The event type may include alphanumeric characters and the "." (dot)
character. The first character may not be a dot or a digit.
Event type names are case-insensitive. If neither the data attribute or inline content is specified, an error.fetch event will be thrown. If used in conjunction with the inline content, an error.fetch will be thrown. | |
namelist | false | This attribute may not be specified in conjunction with inline content | Var List | none | List of ECMAScript Variable names |
A list of zero or more whitespace separated CCXML variable names to be included with the event.
When an ECMAscript variable is included with the event, its value is first
converted into a string.
If the variable is an ECMAScript Object, the mechanism by which it is included is not currently defined. Instead of including ECMAScript Objects directly, the application developer may explicitly include the properties of an Object. e.g. "date.month date.year". If used in conjunction with the inline content, an error.fetch will be thrown. |
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 to configure the event processor. The meaning of these hints is specific to the implementing platform and the event processor. |
<send>
ExamplesIn this example we send the current CCXML session a hello.jack
event that contains a single field. We
catch the event, log the field and exit:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <eventprocessor> <transition event="ccxml.loaded"> <var name="jacksvar" expr="'I am Jack\'s complete lack of surprise.'"/> <send target="session.id" targettype="'ccxml'" data="'hello.jack'" namelist="jacksvar"/> </transition> <transition event="hello.jack" name="evt"> <log expr="evt.jacksvar"/> <exit/> </transition> </eventprocessor> </ccxml>
In this example we send a event to our parent and then exit:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <eventprocessor> <transition event="ccxml.loaded"> <var name="jacksvar" expr="'I am Jack\'s inflamed sense of rejection.'"/> <send target="session.parentid" data="'hello.jack'" targettype="'ccxml'" namelist="jacksvar"/> <exit/> </transition> </eventprocessor> </ccxml>
In this example we catch a dialog.transfer
request and just return a error event back to the
dialog:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <eventprocessor> <transition event="dialog.transfer" name="evt"> <var name="reason" expr="'I am a jack's unsupported transfer.'"/> <send target="evt.dialogid" data="error.unsupported.transfer" targettype="'dialog'" namelist="reason"/> <exit/> </transition> </eventprocessor> </ccxml>
<move>
<move>
is used to move an event source (such as a Connection object) to an executing CCXML
session. When an event source is moved to a session, events originating from that source will be delivered to that
session's currently executing CCXML document. The event
OR the source
attribute
MUST be specified. If neither attribute is specified or both attributes are specified, an
error.fetch
event will be thrown.
A <move>
attempt may fail for a number of reasons. These reasons include:
<move>
;A <move>
is not allowed once an event source is associated with another object through an
implicit or explicit <join>. Moving event sources that are joined would disassociate the objects connected
through the join. For example the result of moving connection that has an active dialog would be two CCXML
sessions, one owning the connection, the other owning the dialog.
In the event of a <move>
failure, an error.move
event will be generated to
indicate that the <move>
attempt was unsuccessful. Otherwise, a move.successful
event will be generated against the session that performed the <move>
to indicate that the
request has completed successfully.
Since each CCXML session has an event queue, it is possible that a session executing a <move>
will already have events in its queue from the event source that is being moved. As an example, this situation
could easily occur with connection.alerting
and connection.disconnected
if the incoming
connection is abandoned before a CCXML platform initiates processing. Any such events will be removed from the
queue of the session performing the <move>
, and placed into the queue of the session that the
event source is being moved to. Each event moved in this manner will be inserted into the queue of the target
session as if it was a new event occuring in the context of that session. The order in which events are queued is
the order in which they appear in the event queue of the session performing the <move>
. If the
event
attribute is specified, then the referenced event is placed into the queue of the target session
before other queued events from the event source are inserted. Note that queueing rules governing the order in
which the inserted events will be processed continue to apply.
Like all CCXML elements, <move>
executes asynchronously. As such, there is a period of time
during which events generated by the event source being moved cannot be processed either by the session performing
the <move>
, or by the target session. If the <move>
fails, then these events
remain in the queue of the session that attempted the <move>
, and will be processed normally.
However, while the <move>
is being performed, events from event sources other than the one being
moved will continue to be processed according to the EHIA. As such, a failed <move>
request may
result in events being processed in a different order than if no <move>
operation was performed.
Note that the relative ordering of events from the event source being moved is not changed even as a result of such
a failure.
<move>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
source | false | This attribute may not be specified in conjunction with the event attribute. | ECMAScript Expression | none | (valid connection or dialog ID) |
An ECMAScript expression which returns a connectionID or dialogID.
The event source associated with this identifier will be moved to the target session.
Either the source or the event attribute has to be specified. If neither of them is specified, or if both are specified, an error.fetch event will be thrown. If the attribute value is invalid, an error.semantic event will be thrown. |
event | false | This attribute may not be specified in conjunction with the source attribute. | ECMAScript Expression | none | An ECMAScript expression which returns an event object. |
The event source from which the event object originated, if any, will be moved to the
target session. The event will also be sent to the target session to provide a notification.
Either the source or the event attribute has to be specified. If neither of them is specified, or if both are specified, an error.fetch event will be thrown. |
sessionid | true | ECMAScript Expression | none | A valid CCXML session id | An ECMAScript expression that identifies the session to which the event source will be moved. |
<cancel>
When a CCXML program uses <send>
to send an event and includes a delay
attribute,
the <cancel>
command will cancel the pending event, if possible.
The cancel operation will cancel a pending event by removing it from the event queue of the CCXML session
from which it has been sent. If the delay has expired
and the event has already been removed from the event queue, the <cancel>
request will fail and an
error.notallowed
event will be delivered to the event queue of the CCXML session that executed the
<cancel>
.
The <cancel>
element may be used to cancel events delivered to local or remote CCXML sessions.
Compliant CCXML implementations are REQUIRED to support the cancellation of local events but
may choose not to support the cancellation of remote events in which case an error.notallowed
event
should be thrown for such requests. The format of the event identifier returned by a <send>
request, and specified in the sendid
attribute of <cancel>
, is implementation
specific but is expected to uniquely define events across CCXML sessions.
<cancel>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
sendid | true | ECMAScript Expression | none | A valid event identifier | An ECMAScript expression which returns the value of the event identifier that was received when the send command was issued. |
error.notallowed
This error event is thrown when the execution of an element causes an invalid operation to be performed on a session and/or connection. The fields available in this event are:
Field Name |
Details |
---|---|
name |
' error.notallowed ' |
sessionid |
The ID of the affected session. |
connectionid |
The ID, if specified in the element being executed, of the affected connection or conference. |
reason |
A description of the reason the operation was denied. |
error.semantic
This error event is thrown when there is a semantic error in a CCXML element (ie. passing an incorrect value for an attribute, etc.).
The fields of this event are:
Field Name |
Details |
---|---|
|
' |
|
this property is set to the ECMAScript string value of the printable error message associated with this error |
|
this property is set to the ECMAScript string value of the name of the element that produced the error (ie
|
|
if available in the interpreter, this property is an object whose properties are the names of the attributes of the element in error; the value of each attribute property is the corresponding string value of the attribute |
error.send.targetunavailable
Could not connect to the target listed in <send>
. The fields available in this event are:
Field Name |
Details |
---|---|
name |
' error.send.targetunavailable ' |
sendid |
The ID of the affected event. |
reason |
A description of the reason the operation was denied. |
error.send.targettypeinvalid
Could not connect to the Event I/O Processor listed in <send>
. The fields available in this
event are:
Field Name |
Details |
---|---|
name |
' error.send.targettypeinvalid ' |
sendid |
The ID of the affected event. |
reason |
A description of the reason the operation was denied. |
error.send.failed
Message in the <send>
could not be sent for an unknown reason. The fields available in this
event are:
Field Name |
Details |
---|---|
name |
' error.send.failed ' |
sendid |
The ID of the affected event. |
reason |
A description of the reason the operation was denied. |
send.successful
This event is thrown when an event is successfully sent to a CCXML session. Receipt of the event does not imply the event has been processed by the receiver but simply that it has been sent without error. The fields available in this event are:
Field Name |
Details |
---|---|
name |
' send.successful ' |
sendid |
The ID of the send request as returned in the sendid attribute of the
<send> element. |
move.successful
This event is thrown when an event source is successfully moved to a CCXML session. The fields available in this event are:
Field Name |
Details |
---|---|
name |
' move.successful ' |
sourceid |
The ID of the event source that has been moved as specified either directly via
the source attribute or indirectly via the event attribute of the
<move> element. |
cancel.successful
This event is thrown when the sending of an event has been successfully cancelled. The fields available in this event are:
Field Name |
Details |
---|---|
name |
' cancel.successful ' |
sendid |
The ID of the sent event that has been cancelled as specified in the
name attribute of the <cancel> element. |
error.move
This event is thrown when a move request performed by a session fails to complete successfully. The fields available in this event are:
Field Name |
Details |
---|---|
name |
' error.move ' |
sourceid |
The ID of the event source referenced either directly via the
source attribute or indirectly via the event attribute of the
<move> element. |
sessionid |
The ID of the target session to which it was attempted to move the event source. |
reason |
A description of the reason for which the <move> request
failed. |
CCXML can generate arbitrarily-named events. While any event name is possible, there is a small set of well-known events that are generated as a matter of course, and which any telephone application SHOULD handle. There are three kinds of these events: connection events, language events and error events.
The first, and larger set, is present so a CCXML session can keep abreast of events happening with the telephone network. CCXML is designed to be neutral with respect to the telephony layer, so the event set MUST be very generic and capable of describing the behavior of a wide variety of systems (e.g., [Q931], [SS7], VoIP, etc).
All events received in a CCXML session must have a number of standard fields. It is the responsibility of the Event I/O Processor that delivered the event to make sure that they are present.
Attribute Name | Details |
---|---|
name |
A text string containing the string name of the event. |
eventid |
The unique identifier for the event. This should match the value of the
sendid attribute of <send> if the event was generated by a CCXML document. |
eventsource |
The unique identifier of the event source. If the event source can receive events
you can use this identifier in the target attribute of <send> . |
eventsourcetype |
The name of the Event I/O Processor that sent this event. If the event source can
receive events you can use this in the targettype attribute of <send> . |
CCXML applications are notified of Connection activities by events, which often reflect Connection state changes. Applications MAY also take actions which change the state of a Connection and which cause other events to be generated.
Connection events and their properties are specified in section 10.6: EventsLanguage Events are a general class of responses that occur as a result of the execution of elements within a CCXML document. These events may be further categorized as follows:
Event Handling Control: These events are detailed in section 9.3
CCXML uses its event handling mechanism to notify a CCXML document of errors that occur during execution. An error
notification takes the form of an error event that is added to the event queue of the CCXML document where the error
occurred. All error events are named with the prefix "error.*"
so that a properly defined
<transition>
can filter out error events.
Here is an example of a <transition>
that can be used to filter out and report error
events:
<transition event="error.*" name="evt"> <log expr="'an error has occurred (' + evt.reason+ ')'" /> <exit/> </transition>
All error events have a set of properties in common, shown in the following table:
Common Field Name | Definitions |
---|---|
name |
this property is set to the ECMAScript string value of the event name |
reason |
this property is set to the ECMAScript string value of the printable error message associated with this error |
In general, when an error occurs in a CCXML document, the corresponding error event is added to the front of the
CCXML document's event queue. This causes the CCXML document to process the error event immediately after the current
event.
A CCXML interpreter MAY provide the attributelist
property on the
error.ccxml
event. The attributelist
object MAY have just the
attribute and value in error, or MAY provide all the attributes and values.
Due to the nature of CCXML's event handling mechanism, some error scenarios are treated differently. These scenarios are described below.
Errors that occur during documentation initialization (elements that occur in the CCXML document before
<eventprocessor>
) occur outside of CCXML's event handling mechanism. These errors
SHOULD cause the CCXML thread of execution to terminate and notify the platform of the
document error.
<eventprocessor>
attributesAn <eventprocessor>
contains <transition>s
that comprise CCXML's event
handling mechanism. Since errors in <eventprocessor>
attribute evaluation could keep the EHIA from
correctly processing an event, these errors SHOULD cause the CCXML thread of execution to
terminate and notify the platform of the document error.
<transition>
attributes<transition>
attributes specify when the elements contained by the
<transition>
SHOULD be executed. Since errors in
<transition>
attribute evaluation could keep the <transition>
from correctly
handling the error event, these errors SHOULD cause the CCXML thread of execution to
terminate and notify the platform of the document error.
If an error occurs during the handling of an error event another error event will be raised and posted to the front of the event queue. In many cases this may be perfectly acceptable and the CCXML application may be able to successfully recover from the error. In some situations however this can lead to an infinite loop in the CCXML session. Implementations MAY choose to include some form of loop detection and to terminate the CCXML session when a loop is detected.
This section contains information on <accept>, <createcall>, <createconference>,
<destroyconference>, <disconnect>, <join>, <redirect>, <reject>, and
<unjoin>
.
The primary goal of CCXML is to provide call control throughout the duration of a call. Call control includes handling incoming calls, placing outgoing calls, bridging (or conferencing) multiple call legs, and ultimately disconnecting calls.
In CCXML call control occurs through three major concepts: Connections, Conferences and Bridges.
A Connection is an object modeling a resource by which two independent unidirectional media streams, and optionally any associated network signaling traffic, can be controlled by a CCXML session. This corresponds roughly to a "call leg" as the term is used informally. The picture below illustrates the media streams associated with the Connection c1.
A Bridge occurs when the input and/or output media streams of Connections or Conferences are linked or "joined"
together. The picture below depicts the result of a full duplex <join>
between the connections
c1 and c2.
A Conference is an object that controls the mixing of media streams for two or more Connections through Bridges.In the picture below, the connections c1 and c2 are joined in a full duplex mode to the conference C1.
These concepts are discussed in greater detail in the sections below.
The goals of the CCXML call model are to focus on relatively simple types of call control and to be sufficiently abstract so that the call model can be implemented using all major telephony definitions such as JAIN Call Control(JCC) [JSR021], [CSTA], and [S.100]. The JCC call model meets these requirements by providing an event model for connections which abstracts away many of the differences between telephone networks (e.g., [Q931], [SS7], VoIP, etc). Additionally, this call model is small and easily-understood so that concrete example programs can be written.
JCC was designed to be a cross-platform high-level event set to describe as generic a phone model as possible. The JCC call model consists of Addresses, Calls, Connections, and Providers. In the context of CCXML, it was felt that the Address, Call, and Provider objects would add more complexity than value, so these were omitted as explicitly visible objects. Instead the behavior of Connections became the focus.
The CCXML call model therefore is based on the behavior of Connections. A call is received or initiated under control of a CCXML session through the properties of a Connection.
Note that the JCC model is designed for endpoint devices only.
The CCXML call model is based on the behavior of Connections. A network call is received or initiated under control of a CCXML session through properties of a Connection.
<dialogstart>
implicitly creates a Connection and bridges it to another Connection or to a
Conference specified as an attribute of <dialogstart>
. In other words, to facilitate interaction
between a network party and a dialog, two connections are REQUIRED: one connection is
associated with the network call, and the other connection is associated with the dialog.
<dialogstart connectionid="c1" src="'example.vxml'" duplex="'full'">
Each Connection has one input by which it receives a media stream from another Connection or Conference.
Each Connection has one output media stream that can be directed to the inputs of multiple Connections and/or Conferences.
If a network call is active on a Connection, the media stream received from the network is the Connection output, and the Connection input media stream is transmitted to the network.
For a Connection created by <dialogstart>
, the Connection input media stream is available to a
recognizer under control of the CCXML session, and the Connection output media stream can be sourced from a resource
(such as a Text To Speech engine) under control of the CCXML session.
The state of a Connection object reflects events occurring at the telephony source it represents and actions taken by the CCXML document. The following state diagram shows the major aspects of Connection behavior, but omits some detail in favor of clarity (e.g. The ERROR state).
The list of valid states that a connection can be in is:
ALERTING
PROGRESSING
CONNECTED
FAILED
DISCONNECTED
ERROR
Connection Objects are created when a incoming call arrives to the platform via a
connection.alerting
event or via the execution of <createcall>
.
If a platform operational error occurs, the Connection will emit a
error.connection
event.
Connection Objects are automatically destroyed by the platform after they have reached the
DISCONNECTED
, FAILED
or ERROR
states. Platforms are responsible for deciding
when to remove unused Connection Objects, however platforms MUST maintain a Connection
Object at least through the <transition>
for the corresponding
connection.disconnected
, connection.failed
or
error.connection
event.
The PROGRESSING
and ALERTING
states have reflexive transitions. This
is intended to model protocols which have additional states at these points, and which MAY
exchange messages such as PROCEEDING
, ALERTING
, FACILITY
, or
NOTIFY
. Platforms MAY choose to implement additional states which
MAY be reflected in the substate
property of the Connection object. Additional
messages can be implemented with <send>
.
Action | Description | Event | End State |
---|---|---|---|
connection.alerting |
The CCXML document is being notified of an incoming call. | connection.alerting |
ALERTING |
<createcall> |
The CCXML document requests an outbound call. | connection.progressing |
PROGRESSING |
error.connection |
The CCXML connection had a platform operational error. | error.connection |
ERROR |
Action | Description | Event | End State |
---|---|---|---|
<accept> |
The CCXML document answers an incoming call. | connection.connected |
CONNECTED |
<reject> |
The CCXML document rejects an incoming call. | connection.failed |
FAILED |
<redirect> |
The CCXML document redirects an incoming call. | connection.redirected |
DISCONNECTED |
<merge> |
The CCXML document merges an incoming/connected call with another call at the network level. | connection.merged |
DISCONNECTED |
connection.alerting |
Network provided call progress update. | connection.alerting |
ALERTING |
connection.failed |
There was an error in the call state. | connection.failed |
FAILED |
connection.signal |
Additional Connection related information is available for processing by the CCXML application. | connection.signal |
ALERTING |
error.connection |
The CCXML connection had a platform operational error. | error.connection |
ERROR |
Action | Description | Event | End State |
---|---|---|---|
connection.progressing |
Network provided call progress update. | connection.progressing |
PROGRESSING |
connection.connected |
Call was answered. | connection.connected |
CONNECTED |
connection.failed |
There was an error in the call state. This could be due to busy, no answer or any other failure reason | connection.failed |
FAILED |
error.connection |
The CCXML connection had a platform operational error. | error.connection |
ERROR |
Action | Description | Event | End State |
---|---|---|---|
connection.disconnected |
Call was disconnected by the network/remote party. | connection.progressing |
DISCONNECTED |
connection.signal |
Additional Connection related information is available for processing by the CCXML application. | connection.signal |
CONNECTED |
<redirect> |
The CCXML document redirects an connected call. | connection.redirected |
DISCONNECTED |
<disconnect> |
The CCXML document disconnects an active call. | connection.disconnected |
DISCONNECTED |
<merge> |
The CCXML document merges an incoming/connected call with another call at the network level. | connection.merged |
DISCONNECTED |
error.connection |
The CCXML connection had a platform operational error. | error.connection |
ERROR |
An instance of the Connection Object is associated with each telephony event source. Each instance is uniquely identified by its connection identifier. All Connection instances have a set of properties in common, shown in the following table. Properties marked optional only appear on an instance of the Connection object if they have a value. Other properties will always be present.
Connection Properties | Optional | Definitions |
---|---|---|
connectionid |
false | This property is the ECMAScript string value of the Connection identifier, which uniquely identifies each instance of the Connection object. |
state |
false | This property identifies the current state of the Connection instance; the value of the state is a symbolic constant that is the name of the state. |
substate |
true | This property is a protocol-dependent property which allows further refinement of the state of a Connection, if desired. |
dialogid |
true | This property is the identifier of an associated dialog, if there is one currently using the connection. |
endpoint |
false | If this connectionid is bridged to another connection, conference or
dialog through the execution of a <join> , the endpoint property identifies the
source conferenceid , connectionid or dialogid driving the media stream
to this connection.This property will be updated each time a <join>/<unjoin> changes the media source to
this connection.If the connection does not have a media source after executing a <join> the endpoint will be
undefined.For example the creation of a half duplex bridge <join id1="con1" id2="con2" duplex="half" /> Result Connection[con1].endpoint = "con2" Connection[con2].endpoint = "undefined" |
duplexmode |
false | duplexmode in conjunction with endpoint identifies the
media source and direction of a bridge created through execution of a <join> tag. The value
of this property can be either "full", "half" or "undefined".When a bidirectional bridge is created duplexmode will be set to "full". A unidirectional bridge
will have the duplexmode property set to "half" indicating that this connection is receiving a
media stream from the connection, conference or dialog identified by endpoint.If the connection does not have a source duplexmode will be "undefined". This property will be
updated each time a <join> /<unjoin> changes the media direction between
this connection and the endpoint property. |
local |
true | This property is a URI which addresses the interpreter platform; for an incoming call, this is the called URI; for a redirected incoming call, this is also the most recent redirection, and the prior values are contained in the "redirect" property; for an outgoing call, this is the calling URI; |
remote |
true | This property is a URI which addresses the remote device; for an incoming call, this is the calling URI; for a redirected incoming call, this is the requester of the most recent redirection, and prior values are contained in the "redirect" property; for an outgoing call, this is the called URI; |
protocol |
true |
This property is a reference to an object defining protocol information for the protocol used on this
connection; the referenced object defines information which applies to all connections using this protocol,
and it has at least two properties:
For example, the assignment of protocol-dependent user-to-user information to a variable
tmp
from a Connection instance referenced by the variable cx would be:<assign name="tmp"
expr="cx.protocol[cx.protocol.name].uui"/>
|
redirect |
true |
This property is an array representing the connection redirection paths; the first element,
Connection.redirect[0] , is the original number, and the last element is the most recent
redirected number; each element of the array MAY define any of the following four
properties:
|
aai |
true | This property is the application-to-application information passed during connection setup. |
originator |
true | This property is set to either "local" or "remote" and indicates the originator of
the connection; for an incoming call, this property is set to "remote"; for an outgoing call, it is set to
"local"; For example, the assignment of the originating URI to a variable uri from a Connection instance
referenced by the variable cx would be:<assign name="uri" expr="cx[cx.originator]"/> |
Platforms MAY choose to add properties to Connection instances. By convention, the properties MUST begin with an underscore, "_", to identify them as platform-dependent.
CCXML applications are notified of Connection activities by events, which often reflect Connection state changes. Applications may also take actions which change the state of a Connection and which cause other events to be generated.
All Connection events have a set of properties in common, shown in the following table. Fields marked optional only appear on the event object if they have a value. Other fields will always be present.
Common Field Names | Optional | Definitions |
---|---|---|
name |
false | This property is set to the ECMAScript string value of the event name. |
connectionid |
false | This property is the ECMAScript string value of the ID of the Connection object associated with this event. |
protocol |
true | This property is an ECMAScript string which identifies the protocol used by the event source; although this property is OPTIONAL, it is recommended that platforms provide it in order to allow applications to tailor their behavior (see Appendix E for a suggested set of protocol identifiers) |
info |
true | This property provides a reference to an object which MAY contain platform or protocol dependent information specific to the event. |
reason |
true | This property, although not provided by every event, when present provides a code indicating the status of the operation which triggered this event, or a reason for the occurrence of this event. |
connection |
false | An ECMAScript object reference to the Connection object identified by the
connectionid property for this event. |
Platforms MAY choose to add properties to events. By convention, the properties MUST begin with an underscore, "_", to identify them as platform-dependent.
CCXML applications can use <createconference>
to create a new conference, or
to attach to an existing conference. The CCXML application can then connect or disconnect existing
connections/conferences/dialogs to the new conference using <join>
and <unjoin>
(as described in Section 10.4). When a session no longer requires the use of a conference, it
uses <destroyconference>
to detach from the conference. Asynchronous events will be sent to the
CCXML document upon completion of each of these operations.
Each Conference Object has one logical output and multiple inputs. The actual output streams of a Conference Object are derived by mixing all its input streams, less any contributed audio of an individual Connection, Conference Object who receives that output. The output of a Conference Object can be directed to the inputs of multiple Connections and/or Conference Object (as a result of bridging).
Some telephony call control definitions do not define a separate Conference Object, instead defining a conference simply as a call with more than two parties. In order to accommodate the widest range of underlying telephony API's, CCXML requires explicit use of a Conference Object whenever two or more audio streams are mixed.
Unlike connections and dialogs, which are local to a single session (but can be moved between
sessions using <move>
), conferences are global across all sessions, and can be bridged with the
connections/conferences/dialogs of any session. Conferences can be named in order to facilitate the use of that
conference in other sessions. Assigning a name using the confname
attribute allows other sessions to
access the created conference by performing a <createconference>
with the same value for
confname
. Conferences are 'reference counted' and continue to exist so long as at least one session
exists that has attached to the conference using <createconference>
without a corresponding
<destroyconference>
. When a session terminates, it implicitly detaches from any conferences to
which it is still attached. Note that it is not necessary for a session to share a conference by assigning it a name
in order for other sessions to make use of that conference. Other sessions may still establish bridges to a
conference using <join>
and <unjoin>
, regardless of whether or not they have
accessed the conference using <createconference>
; only the conference ID is required for this.
Because conferences are global, it is not legal to perform a <move> against a conference.
NOTE: A simple two-party call does not require the use of a conference object. This is discussed in Section 10.4.
An instance of the Conference class is associated with each Conference Object created by
<createconference>
and referenced in the session.conferences
array.
Conference Properties | Definitions |
---|---|
|
this property is the ECMAScript string value of the Conference identifier, which uniquely identifies each instance of the Conference class |
bridges |
this property is an ECMAScript array of connection, conference, and dialog identifiers that reflect the entities currently bridged with the conference. |
A "bridge" is a relationship between the input and/or output streams of Connections or Conference Objects. The bridge concept and the details of its behavior are fundamental to CCXML.
Even in the simplest case of a network party interacting with a dialog, two Connections are
REQUIRED, and a bridge is established between them implicitly by the action of
<dialogstart>
.
More complex situations, such as two-party calls, two-party calls with "hot" word recognition, conference control,
and "coaching" scenarios, all involve the use of multiple Connections and explicit control of one or more bridges
between them by using <join>
and <unjoin>
.
The nature of bridges, and the behavior of <join>
and <unjoin>
, is concerned
with the mapping between the media stream inputs and outputs of Connections and Conferences:
<dialogstart>
, the Connection input
media stream is available to a recognizer under control of the CCXML session, and the Connection output media
stream can be sourced from a resource (such as a Text To Speech engine) under control of the CCXML session.<join>
has a duplex attribute to distinguish between two-way bridges and one-way
bridges. For example, <join>
ing Connection A to Connection B with duplex=full
will
direct the A output to the B input, and the B output to the A input. If instead the same <join>
is
done with duplex=half
, it will direct the B output to the A input, and will not have any effect on the B
input or the A output.
A simple two-party call between Connections A and B can thus be achieved by <join>
ing A to B
with duplex=full
.
For "hot word" recognition on a two-party call, a two-way (full duplex) bridge MUST be
established between two network Connections, and a one-way (half duplex) bridge MUST be
established from one of the network Connections to a third Connection that is associated with a dialog. There are
several ways this arrangement can be achieved, depending on the initial states of the three Connections. For example,
if the network party on Connection A is initially interacting with a dialog on Connection D (i.e., a full duplex
bridge exists between them), all that is needed then is to do a <join>
of Connection A to
Connection B (the other network party) with duplex=full
. This example highlights an important and subtle
aspect of the behavior of <join>
when one, or both, of the Connections being joined is already in
one or more established bridges:
If a <join> requires a Connection to "listen" and the Connection is already listening to a different source, this existing stream relationship is torn down automatically.
Note that <join>
cannot be used to add a Connection to an existing two-party bridge in order to
create a 3-way Conference. Instead, this functionality can be achieved by first using
<createconference>
to create a Conference object and then <join>
ing all three
Connections to this Conference. If a two-way bridge exists between A and B, and A is then <join>
ed full duplex to C, the result will be a two-party bridge between A and C and a one-way bridge from A to B.
From the perspective of a CCXML application, there are two ways that bridges can be manipulated. They may be manipulated implicitly, through elements such as <createcall> (with 'joinid') and <dialogprepare>/<dialogstart> (with 'connectionid'/'conferenceid'), or explicitly via <join> and <unjoin>.
Bridges that are established implicitly are physically realized as soon as a platform is capable of doing so; however, the inability to establish the bridge immediately upon execution of a <createcall>/<dialogprepare> does not constitute an error. In the case of <dialogprepare>, the actual bridge is not established until the execution of a corresponding <dialogstart>. However, with <createcall>, it may not be possible to establish the actual bridge until the call connects, or it may only be possible to establish the bridge in a single direction prior to the time that the call enters the CONNECTED state. As a result, when using <createcall> with 'joinid', an event will be generated when the requested bridge is established. This event is independent of connection-related events such as 'connection.connected', and may occur before or after such events depending on when the bridge is actually realized. If the bridge is established successfully, the 'conference.joined' event is generated. If the requested bridge cannot be established even after the call enters the CONNECTED state, an error.conference.join' event will be generated - although it may be determined before this time that the bridge cannot be established. Note that the call itself will proceed independently of whether or not the bridge can be established; for instance, it is possible to receive both an 'error.conference.join' event and a 'connection.connected' event for a single call initiated using <createcall>.
In contrast to implicit bridges, explicit requests by an application to perform a <join> are performed immediately independently of the state of the underlying resource. A CCXML application is permitted to perform a <join> regardless of the current state of an underlying entity. For instance, a CCXML application can join two connections where one (or even both) of the connections is in the ALERTING state, providing early media on the ALERTING connection. If the CCXML implementation does not support a requested <join> due to the current state of an underlying entity, then this will result in an error.conference.join event with the 'reason' field set appropriately.
As an aid to understanding, the outcomes of all possible <join>
operations are shown
diagrammatically below for three different initial conditions:
<join>
s:initially | (A)(B) |
join A to B half | A <----- B |
join A to B full | A <====> B |
join B to A half | A -----> B |
join B to A full | A <====> B |
<join>
s:initially | A -----> B |
join A to B half | A <----- B |
join A to B full | A <====> B |
join B to A half | A -----> B |
join B to A full | A <====> B |
join A to C half | A -----> B & A <----- C |
join A to C full | A -----> B & A <====> C |
join C to A half | A -----> B & A -----> C |
join C to A full | A -----> B & A <====> C |
join B to C half | (A) & B <----- C |
join B to C full | (A) & B <====> C |
join C to B half | A -----> B & B -----> C |
join C to B full | (A) & B <====> C |
<join>
s:initially | A <====> B |
join A to B half | A <----- B |
join A to B full | A <====> B |
join B to A half | A -----> B |
join B to A full | A <====> B |
join A to C half | A -----> B & A <----- C |
join A to C full | A -----> B & A <====> C |
join C to A half | A <====> B & A -----> C |
join C to A full | A -----> B & A <====> C |
join B to C half | A <----- B & B <----- C |
join B to C full | A <----- B & B <====> C |
join C to B half | A <====> B & B -----> C |
join C to B full | A <----- B & B <====> C |
In summary, <join>
behavior always respects three invariants:
<join>
is established between the two
Connections/Conferences referenced in the <join>
. In particular, any existing stream
relationship between these two Connections/Conferences is torn down automatically if it conflicts with the
specified relationship.<join>
requires a Connection to "listen" and the
Connection is already listening to a different source, this existing stream relationship is torn down
automatically.<join>
and
<unjoin>
operations.
To illustrate some typical invocations of <join>
invariants a few example scenarios are
presented below. In the first scenario, connection c1 is bridged to a conference C1, via a
<join>
where the duplex mode is full.
After <join id1="'C1'" id2="'c1'" duplex="'full'">
Session object properties session.connections['c1'].endpoint == 'C1' session.connections['c1'].duplex == 'full' session.conferences['C1'].bridges['c1'] == 'c1'
If c1 then became a participant in a <dialogstart>
where d1 represents a
connection to a dialog and the duplex mode is full, the original picture would change as follows:
After <dialogstart connectionid="'c1'" src="'example.vxml'" duplex="'full'">
session.connections['c1'].endpoint == 'd1' session.connections['c1'].duplex == 'full' session.connections['c1'].dialogid == 'd1' session.conferences['c1'].bridges['c1'] == 'c1' session.dialogs['d1'].connectionid == 'c1' session.dialogs['d1'].duplex == 'full'
The <dialogstart>
required c1 to "listen" to d1, however, c1 was already
in an established bridge listening to C1. Consequently, the full duplex bridge between c1 and C1
is changed to a half duplex, where c1 is not allowed to "listen" to C1 and a full duplex bridge is
established between c1 and d1.
In this second scenario, c1 and c2 have been joined into a conference, C1.
After <join id1="'C1'" id2="'c1'" duplex="'full'"> and: <join id1="'C1'" id2="'c2'" duplex="'full'">
session.connections['c1'].endpoint == 'C1' session.connections['c1'].duplex == 'full' session.connections['c2'].endpoint == 'C1' session.connections['c2'].duplex == 'full' session.conferences['C1'].bridges['c1'] == 'c1' session.conferences['C1'].bridges['c2'] == 'c2'
If a <join>
is then executed that specifies c2 and C1 as participants and the
duplex mode is half, the bridge between c2 and C1 will be re-established with C1 able to
"listen" to c2, but c2 no longer able to "listen" to C1.
After <join id1="C1" id2="c2" duplex="'half'">
session.connections['c1'].endpoint == 'C1' session.connections['c1'].duplex == 'full' session.connections['c2'].endpoint == 'undefined' session.connections['c2'].duplex == 'undefined' session.conferences['C1'].bridges['c1'] == 'c1' session.conferences['C1'].bridges['c2'] == 'c2'
Note connection c2 does not have a source therefore the endpoint and duplex properties are undefined
In this third scenario, there are three connections c1, c2 and c3. Connections c1 and c2 are connected with a half duplex bridge, connection 3 is not bridged at this point.
After <join id1="'c1'" id2="'c2'" duplex="'half'"> Session object properties session.connections['c1'].endpoint == 'c2' session.connections['c1'].duplex == 'half' session.connections['c2'].endpoint == 'undefined' session.connections['c2'].duplex == 'undefined' session.connections['c3'].endpoint == 'undefined' session.connections['c3'].duplex == 'undefined'
Connections c2 and c3 do not have a media source therefore the endpoint and duplex properties are undefined.
A full bridge is established between connections c2 and c3, connection c1 is still receiving from c2.
After <join id1="'c2'" id2="'c3'" duplex="'full'"> session.connections['c1'].endpoint == 'c2' session.connections['c1'].duplex == 'half' session.connections['c2'].endpoint == 'c3' session.connections['c2'].duplex == 'full' session.connections['c3'].endpoint == 'c2' session.connections['c3'].duplex == 'full'
<accept>
When a CCXML document receives a connection.alerting
event within an
<eventprocessor>
, the execution of an <accept>
within the
<transition>
block will cause the underlying platform to signal the telephony system to connect
the call. The CCXML document MAY then initiate interactive dialog sessions with the incoming
caller, or perform other telephony operations (e.g., place outgoing calls, join calls, etc).
<accept>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
connectionid | false | ECMAScript Expression | comes from the event being processed | Connection IDs |
An ECMAScript expression which returns a string that is the identifier of a Connection
on which the incoming call is signaled.
If the connectionid attribute is omitted, the interpreter will accept using the
id indicated in the current event being processed.
If the attribute value is invalid or there is no valid default value, an error.semantic event will be thrown. | |
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 or passed to the network accepting the connection.
This information may consist of protocol-specific parameters.
Note: The meaning of these hints is specific to the implementing platform and protocol. |
An accepted incoming call will result in the generation of a connection.connected
event.
<redirect>
When a CCXML document executes a <redirect>
within the
<transition>
block, this will cause the underlying platform to signal the telephony system to send
the call to a specified destination. The use of <redirect>
is only valid when a call is in the
ALERTING and CONNECTED states.
<redirect>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
connectionid | false | ECMAScript Expression | comes from the event being processed | Connection IDs |
An ECMAScript expression which returns a string that is the identifier of a Connection
on which a call is active or on which an incoming call is being signaled.
This call will be redirected.
If the connectionid attribute is omitted, the interpreter will redirect using the
id indicated in the current event being processed.
If the attribute value is invalid or there is no valid default value, an error.semantic event will be thrown. | |
dest | true | ECMAScript Expression | none | A Valid URL | An ECMAScript expression which returns a string that is the target of the outbound telephone call. A platform must support a telephone URI, as described in [RFC2806] or a SIP URI as described in [RFC3261]. | |
reason | false | ECMAScript Expression | none | An ECMAScript expression which returns a string that is the reason the call is being redirected. | ||
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 or passed to the network redirecting the connection.
This information may consist of protocol-specific parameters.
Note: The meaning of these hints is specific to the implementing platform and protocol. |
A redirected incoming call will result in the generation of a connection.redirected
event.
<reject>
When a CCXML document receives a connection.alerting
event within an
<eventprocessor>
, the execution of a <reject>
within the
<transition>
block will cause the underlying platform to signal the telephony system to reject the
call.
<reject>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
connectionid | false | ECMAScript Expression | comes from the event being processed | Connection IDs |
An ECMAScript expression which returns a string that is the identifier of a Connection
on which an incoming call is being signaled.
This call will be rejected.
If the connectionid attribute is omitted, the interpreter will reject using the
id indicated in the current event being processed.
If the attribute value is invalid or there is no valid default value, an error.semantic event will be thrown. | |
reason | false | ECMAScript Expression | none | An ECMAScript expression which returns a string that is the reason the call is being rejected. | ||
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 or passed to the network rejecting the connection.
This information may consist of protocol-specific parameters.
Note: The meaning of these hints is specific to the implementing platform and protocol. |
A rejected incoming call will result in the generation of a connection.failed
event.
<createcall>
A CCXML document can attempt to place an outgoing call with <createcall>
. This element will
instruct the platform to allocate a Connection and attempt to place an outgoing call to a specified address. The
element is non-blocking, and the CCXML document is immediately free to perform other tasks, such as initiating dialog
interaction with another caller. The CCXML interpreter will receive an asynchronous event when the call attempt is
completed. An <eventprocessor> <transition>
block can handle this event and perform further
call control, such as conferencing. If the call was successfully placed, the transition block can also initiate a
dialog interaction with the called party.
<createcall>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
dest | true | ECMAScript Expression | none | A Valid URL | An ECMAScript expression which returns a string that is the target of the outbound telephone call. A platform must support a telephone URI, as described in [RFC2806] or a SIP URI as described in [RFC3261]. | |
connectionid | 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 will receive the identifier of the Connection on which the outgoing call is attempted. | |
aai | false | ECMAScript Expression | none |
An ECMAScript expression which returns a string of application-to-application information
to be passed to the destination endpoint when establishing the connection.
Note: Even if an implementation platform accepts the aai data, certain protocols and network elements may prevent the transmission to the target endpoint. If the platform does not support the transmission of aai data it should raise a connection.progressing event and indicate that the use of aai is not supported. | ||
callerid | false | ECMAScript Expression | none |
An ECMAScript expression which returns a string defining the caller identity to be used when
making the outbound connection. The format of this information is protocol and platform specific
but might consist of a telephone URI, as described in [RFC2806]
or a SIP URI as described in [RFC3261].
Note: An implementation platform is not required to use the specified data and certain protocols and network elements may prevent its use. If the platform does not support the specification of callerid it should raise a connection.progressing event and indicate that the use of callerid is not supported. | ||
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 when establishing the outbound connection.
This information may consist of protocol-specific parameters, protocol selection guidelines,
or routing hints.
Note: The meaning of these hints is specific to the implementing platform. | |
timeout | false | ECMAScript Expression | none | An ECMAScript expression which returns a character string in CSS2 [CSS2] format | The character string returned is interpreted as a time interval. This interval begins when createcall is executed. The createcall will fail if not completed by the end of this interval. A completion is defined as the call getting to a CONNECTED state as signaled by a connection.connected event. A failed createcall will return the connection.failed event. | |
joinid | false | ECMAScript Expression | none | (valid connection, conference, or dialog ID) | An ECMAScript expression that identifies a connection, conference, or dialog ID that the new call will be joined to. This is equivalent, from the perspective of the CCXML application, to performing a <join> immediately following the <createcall> except that no events specific to the join will be generated. However, platforms may use knowledge about the connection/conference/dialog to which the new call will be connected to optimize the call creation process. | |
joindirection | false | ECMAScript Expression | both |
both
calltransmit callreceive |
An ECMAScript expression that defines the direction of the
media flow between the newly created connection, and the existing
connection/conference/dialog referenced by joinid:
|
The execution of <createcall>
will result in the generation of one or more
connection.progressing
events (depending on platform support for call progress) and a
connection.connected
event on success and a connection.failed
event on failure.
<createcall>
examplesThe following example illustrates the simplest use of <createcall>
.
<createcall dest="'tel:1235551234'"/>
This example illustrates the use of several attributes of <createcall>
. A SIP URI is provided
as the originators caller id, a selection of protocol specific parameters are provided (callingDevice and
callCharacteristics) and a string of application specific data is provided to be presented to the remote endpoint.
The connection id for the new connection is returned in the variable "myConidVar".
<var name="myConidVar"/> <createcall dest="'sip:+1-212-555-1212:1234@gateway.com;'" callerid="'sip:j.doe@big.com'" connectionid="myConidVar" aai="'This is application specific data'" hints="{callingDevice: 'notSpecified', callCharacteristics: 'voiceUnitCall'}" />
<createconference>
A CCXML document can attempt to create or attach to a Conference Object using
<createconference>
. This element will instruct the implementation to allocate a Conference Object
using the specified options. The successful execution of <createconference>
will result in the
generation of a conference.created
event. If for any reason the implementation is unable to create the
Conference Object using the specified options it MUST fail with a
error.conference.create
event.
<createconference>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
conferenceid | 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 will receive the conference identifier. A conference identifier should be globally unique, so that conferences can be uniquely addressed and possibly connected to. It should be in URI format. | |
confname | false | ECMAScript Expression | none | valid conference URL |
An ECMAScript expression which returns a string that is the name of the conference.
The conference name corresponds to the conference identifier that will be returned in the variable
specified in the conferenceid attribute.
If the named conference does not exist, the platform must create a conference object as requested and return the value of the conference identifier to the variable specified in the conferenceid attribute. If a conference already exists the platform must return the conference identifier of the previously created conference. | |
reservedtalkers | false | ECMAScript Expression | none |
An ECMAScript expression which returns the number of guaranteed speaker slots the conference mixer
should reserve. If the conference already exists, then this attribute will be ignored.
If the conference mixer is unable to reserve this many speaker slots, the createconference must fail with a error.conference.create event. | ||
reservedlisteners | false | ECMAScript Expression | none |
An ECMAScript expression which returns the number of guaranteed listener slots the conference mixer
should reserve. If the conference already exists, then this attribute will be ignored.
If the conference mixer is unable to reserve this many listener slots, the createconference must fail with a error.conference.create event. | ||
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 when creating the conference.
Note: The meaning of these hints is specific to the implementing platform and the event processor. |
<destroyconference>
A CCXML document can attempt to detach from an
existing Conference Object using <destroyconference>
. This destroys the
conference if no other sessions are attached to it. The target Conference
Object is identified using the conferenceid
attribute. The successful execution of
<destroyconference>
will result in the generation of a conference.destroyed
event. If
for any reason the implementation is unable to deallocate the Conference Object it MUST fail
with a error.conference.destroy
event.
<destroyconference>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
conferenceid | true | ECMAScript Expression | none | Conference IDs |
An ECMAScript expression which returns a string that is the identifier of the conference that
should be destroyed.
If the attribute value is invalid an error.semantic event will be thrown. | |
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 when destroying the conference.
Note: The meaning of these hints is specific to the implementing platform and the event processor. |
<join>
A CCXML document can attempt to create a bridge between any two connections, conferences, or dialogs using
<join>
. This element
instructs the implementation to bridge the
connections, conferences, or
dialogs specified using the id1
and id2
attributes in accordance with media options specified by the
other attributes of <join>
. The successful execution of<join>
will
result in the generation of a conference.joined
event. If for any reason the implementation is unable to
create the bridge using the specified
options it MUST fail with a error.conference.join
event.
Joining two objects that are owned by separate CCXML sessions will result in the generation of a
conference.joined
to each of the sessions. However if the implementation is unable to join the objects
an error.conference.join
will only be sent to the session issued the <join>
.
<join>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
id1 | true | ECMAScript Expression | none | (valid connection, conference, or dialog ID) |
An ECMAScript expression which returns a string that is the identifier of a Connection, Dialog or Conference.
If the attribute value is invalid an error.semantic event will be thrown. | |
id2 | true | ECMAScript Expression | none | (valid connection, conference, or dialog ID) |
An ECMAScript expression which returns a string that is the identifier of a Connection, Dialog or Conference.
If the attribute value is invalid an error.semantic event will be thrown. | |
duplex | false | ECMAScript Expression | full |
full
half |
An ECMAScript expression that returns a character string equal to "half" or "full", which
defines the direction of the media flow between id1 resource and id2 resource.
Refer to the discussion of bridging in Section 10.4 .
The duplex attribute determines whether the join will establish a half-duplex
(unidirectional) or full-duplex (bi-directional) bridge.
The following values can be used:
| |
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 or passed to the network when the two specified Connections, Dialogs or
Conferences (id1 and id2) are joined. This information may consist of protocol-specific parameters.
Note: The meaning of these hints is specific to the implementing platform and the underlying protocol. | |
entertone | false | ECMAScript Expression | 'true' |
'true'
'false' A Valid URL |
An ECMAScript expression that returns a character string that is used to play a tone or a
custom wav file to the conference participants when another caller joins.
The following values can be used:
| |
exittone | false | ECMAScript Expression | 'true' |
'true'
'false' A Valid URL |
An ECMAScript expression that returns a character string that is used to play a tone or a
custom wav file to the conference participants when another caller exits.
The following values can be used:
| |
autoinputgain | false | ECMAScript Boolean Expression | true |
true
false |
An ECMAScript Boolean expression that tells the conference
mixer if it should use AGC to determine the input gain for a leg.
If a platform does not support AGC, it should ignore this attribute.
The following values can be used:
| |
autooutputgain | false | ECMAScript Boolean Expression | true |
true
false |
An ECMAScript boolean expression that tells the conference
mixer if it should use AGC to determine the output gain for a leg.
If a platform does not support AGC, it should ignore this attribute.
The following values can be used:
| |
dtmfclamp | false | ECMAScript Boolean Expression | true |
true
false |
An ECMAScript Boolean expression that tells the conference
mixer if it should attempt to remove detected DTMF tones.
If a platform does not support removal of DTMF tones, it should ignore this attribute.
The following values can be used:
| |
toneclamp | false | ECMAScript Boolean Expression | true |
true
false |
An ECMAScript Boolean expression that tells the conference
mixer if it should attempt to remove loud single-frequency tones from the audio stream.
If a platform does not support removal of tones, it should ignore this attribute.
The following values can be used:
|
<unjoin>
A CCXML document can attempt to tear down a bridge between two existing connections, conferences, or dialogs
using <unjoin>
. This element will instruct the implementation to tear down
the bridge between two
connections/conferences/dialogs specified using the id1
and id2
attributes. The
successful execution of<unjoin>
will result in the generation of a
conference.unjoined
event. If for any reason the implementation is unable to
terminate the
bridge between the specified connections/conferences/dialogs, or if no such bridge exists, it
MUST fail with a error.conference.unjoin
event.
Unjoining two objects that are owned by separate CCXML sessions will result in the generation of
a conference.unjoined
to each of the sessions. However if the implementation is unable to join the
objects an error.conference.unjoin
will only be sent to the session issued the
<unjoin>
.
<unjoin>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
id1 | true | ECMAScript Expression | none | (valid connection, conference, or dialog ID) |
An ECMAScript expression which returns a string that is the identifier of a Connection, Dialog or Conference.
If the attribute value is invalid an error.semantic event will be thrown. | |
id2 | true | ECMAScript Expression | none | (valid connection, conference, or dialog ID) |
An ECMAScript expression which returns a string that is the identifier of a Connection, Dialog or Conference.
All media streams between the two specified Connections, Dialogs or Conferences (id1 and id2 ) will be torn down.
If the attribute value is invalid an error.semantic event will be thrown. | |
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 or passed to the network when the two specified Connections, Dialogs or
Conferences (id1 and id2) are unjoined. This information may consist of protocol-specific parameters.
Note: The meaning of these hints is specific to the implementing platform and the underlying protocol. |
<disconnect>
A CCXML document MAY disconnect a call leg on a Connection by using
<disconnect>
. The underlying platform will send the appropriate protocol messages to perform the
disconnect, and send an asynchronous event to the CCXML document when the disconnect operation completes.
If the connection had been bridged when the <disconnect>
request was made, the
platform will tear down all bridges to the connection and send a conference.unjoined
to the CCXML
document once the media paths have been freed.
Note the platform is not required to generate the connection.disconnected
or
conference.unjoined
in any particular order.
<disconnect>
Attribute DetailsName | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
connectionid | false | ECMAScript Expression | comes from the event being processed | Connection IDs |
An ECMAScript expression which returns a string that is the id of a call leg that should be
disconnected.
If the connectionid attribute is omitted, the interpreter will disconnect using the
id indicated in the current event being processed.
If the attribute value is invalid or there is no valid default value, an error.semantic event will be thrown. | |
reason | false | ECMAScript Expression | none | An ECMAScript expression which returns a string that is the reason the call is being disconnected. | ||
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 or passed to the network disconnecting the connection.
This information may consist of protocol-specific parameters.
Note: The meaning of these hints is specific to the implementing platform and protocol. |
A disconnected call will result in the generation of a connection.disconnected
event. A
<disconnect>
MUST specify a connectionid
attribute.
<merge>
Many of the network environments in which a CCXML implementation may be expected to operate provide facilities by which two existing calls can be merged into a single call at the network level. The following diagram illustrates this for the case where user A has two independent calls with users B and C, and utilizes this functionality to merge the calls together:
Figure 1: Initial Call State | Figure 2: State Following Merge |
The diagram illustrates the call control connections, or sessions, that exist between users A, B, C and the network that connects them; the media streams between users is not shown on the above diagram and may differ from the path for call control that is shown. The media path between users may or may not be affected as a result of the merge, depending on the properties of the underlying network; typically any media streams to user A would be terminated since call control sessions between user A and the network are terminated.
There are many different implementations of the merging capabilities described above, across both PSTN and Voice-over-IP networks. Known implementations include the following:
Different implementations may also have different restrictions on when and how merge functionality can be used. Some implementations might allow calls that are alerting to be merged, whereas others might only operate on calls that are already in the connected state. In addition, some implementations might only be able to merge calls in which one of the calls is an outbound call that specifically identifies the associated inbound call when that outbound call is placed (via hints on <createcall>).
The <merge> element allows two calls being handled by a particular CCXML session to be merged together at the network level, if supported by the underlying network and CCXML platform.
If successful, the two referenced calls will be merged at the network level, and the connections to the CCXML platform associated with those calls will be terminated. A connection.merged event will be generated on each of the two calls affected by a merge. If the merge fails, then a single error.merge event will be thrown which identifies both of the connections against which the merge was performed.
Name | Required | Attribute Constraints | Type | Default Value | Valid Values | Description |
---|---|---|---|---|---|---|
connectionid1 | true | ECMAScript Expression | none | Connection IDs |
An ECMAScript expression which returns a string that is the identifier of the first connection
that is to be merged. The order (connectionid1 vs. connectionid2) of the Connections does not matter.
If the attribute value is invalid an error.semantic event will be thrown. | |
connectionid2 | true | ECMAScript Expression | none | Connection IDs |
An ECMAScript expression which returns a string that is the identifier of the second connection
that is to be merged.
If the attribute value is invalid an error.semantic event will be thrown. | |
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 or passed to the network when merging the two connections. This information
MAY consist of protocol-specific parameters.
Note: The meaning of these hints is specific to the implementing platform and the underlying protocol. |
This section defines the events related to telephony operations including events related to the call state, success and failure events for the various telephony operations.
connection.alerting
This event is emitted when a Connection transitions to the ALERTING
state, or is notified of call
progress in the ALERTING
state.
The fields of this event are:
Field Name | Details |
---|---|
name |
" connection.alerting " |
|
The ID of the Connection associated with this event |
protocol * |
The platform protocol ID of the Connection protocol |
info * |
An object which provides additional platform or protocol dependent
information |
connection |
an ECMAScript object reference to the Connection object identified by the
connectionid property for this event |
Information provided by the protocol prior to connection is accumulated and stored with the identified Connection
object. This information will be available when the connection.alerting
event is delivered to the
application. Any further information provided by the protocol prior to connection MAY be
provided in subsequent connection.alerting
events, and made available in the updated Connection object.
Alternatively, this data MAY be delivered in connection.signal
events, and made
available in the updated Connection object. This behavior is platform dependent.
Call related information provided after connection will result in connection.signal
events.
connection.progressing
This event is emitted when a Connection transitions to the PROGRESSING
state as a result of
<createcall>,
or is notified of call progress in the PROGRESSING
state.
The fields of this event are:
Field Name | Details |
---|---|
name |
" connection.progressing " |
|
The ID of the Connection associated with this event |
protocol * |
The platform protocol ID of the Connection protocol |
info * |
An object which provides additional platform or protocol dependent
information |
connection |
an ECMAScript object reference to the Connection object identified by the
connectionid property for this event |
Subsequent connection.progressing
events MAY be generated to support
protocols which exchange multiple messages during the PROGRESSING
state.
connection.connected
This event is emitted when a Connection transitions to the CONNECTED
state as a result of
<accept>.
The fields of this event are:
Field Name | Details |
---|---|
name |
" connection.connected " |
|
The ID of the Connection associated with this event |
protocol * |
The platform protocol ID of the Connection protocol |
info * |
An object which provides additional platform or protocol dependent
information |
connection |
an ECMAScript object reference to the Connection object identified by the
connectionid property for this event |
connection.disconnected
This event is emitted when a Connection transitions to the DISCONNECTED
state, as a result of either
CCXML action or off-platform events.
The fields of this event are:
Field Name | Details |
---|---|
name |
" connection.disconnected " |
|
The ID of the Connection associated with this event |
protocol * |
The platform protocol ID of the Connection protocol |
reason * |
A disconnection reason code |
info * |
An object which provides additional platform or protocol dependent
information |
connection |
an ECMAScript object reference to the Connection object identified by the
connectionid property for this event |
connection.redirected
This event is emitted when a Connection transitions to the DISCONNECTED
state as a result of
<redirect>
.
The fields of this event are:
Field Name | Details |
---|---|
name |
" connection.redirected " |
|
The ID of the Connection associated with this event |
protocol * |
The platform protocol ID of the Connection protocol |
reason * |
A redirect result code. |
info * |
An object which provides additional platform or protocol dependent
information |
connection |
an ECMAScript object reference to the Connection object identified by the
connectionid property for this event |
connection.merged
This event is emitted when a Connection transitions to the DISCONNECTED state as a result of a successful <merge>. A CCXML application will always receive two connection.merged events, one for each affected connection. The fields of this event are:
Field Name | Required? | Details |
---|---|---|
name |
Required | "connection.merged" |
connectionid |
Required | The ID of the Connection associated with this event, on which the merge succeeded |
mergedid |
Required | The ID of the Connection with which the Connection referenced by this event was merged |
protocol |
Optional | The platform protocol ID of the Connection protocol |
info |
Optional | An object which provides additional platform or protocol dependent information |
connection |
Optional | ECMAScript object reference to the Connection object identified by the connectionid property for this event |
connection.failed
This event is emitted when a Connection transitions to the FAILED
state, when an incoming or outgoing
call fails to complete its connection.
The fields of this event are:
Field Name | Details |
---|---|
name |
" connection.failed " |
|
The ID of the Connection associated with this event |
protocol * |
The platform protocol ID of the Connection protocol |
reason * |
A failure reason code |
info * |
An object which provides additional platform or protocol dependent
information |
connection |
an ECMAScript object reference to the Connection object identified by the
connectionid property for this event |
error.connection
This event is emitted when a Connection transitions to the ERROR
state.
The fields of this event are:
Field Name | Details |
---|---|
name |
"
error.connection " |
connectionid |
The ID of the Connection associated with this event |
protocol * |
The platform protocol ID of the Connection protocol |
reason * |
An error code if one is available |
info * |
An object which provides additional platform or protocol dependent
information |
connection |
an ECMAScript object reference to the Connection object identified by the
connectionid property for this event |
connection.signal
This event is emitted when a Connection is notified of new data available when in the CONNECTED
,
PROGRESSING
or ALERTING
state. The fields of this event are:
Field Name | Details |
---|---|
name |
" connection.signal " |
connectionid |
The ID of the Connection associated with this event |
protocol * |
The platform protocol ID of the Connection protocol |
info * |
An object which provides additional platform or protocol dependent information |
connection |
an ECMAScript object reference to the Connection object identified by the
connectionid property for this event |
Examples where connection.signal
could be generated include:
The data provided within the connection.signal
event is protocol dependent. This data
MAY be used to initiate a dialog (for example, if all REQUIRED
information is now available), or to message other platform components.
Signalling delivered on the media stream after a successful <dialogstart>
MAY not be available to the CCXML application. This behavior is platform dependent.
All available call setup information is provided in the Connection object when the first
connection.alerting
event is generated. Any further information provided by the protocol prior to
connection MAY be provided in subsequent connection.alerting
events, and made
available in the updated Connection object. Alternatively, this data MAY be delivered in
connection.signal
events, and made available in the updated Connection object. This behavior is platform
dependent.
Call related information provided after connection will result in connection.signal
events.
The Connection Object MAY be updated with new or changed information as the result of a
connection.signal
event.
This event is emitted when a conference has been successfully established using
<createconference>
. The fields of this event are:
Field Name | Details |
---|---|
name |
" conference.created " |
conferenceid |
The ID of the Conference associated with this event |
conference |
An ECMAScript object reference to the Conference object identified by the conferenceid property for this event |
This event is emitted when a
session detaches from a conference using <destroyconference>
.
Note that this does not imply that the underlying conference has necessarily been destroyed,
since there may be other sessions attached to that conference. The fields of this event are:
Field Name | Details |
---|---|
name |
" conference.destroyed " |
conferenceid |
The ID of the Conference associated with this event |
This event is emitted when two resources (which are connections or conferences) have been bridged using
<join>
. The fields of this event are:
Field Name | Details |
---|---|
name |
" conference.joined " |
id1 |
The ID of the Connection or Conference representing a resource associated with this event |
id2 |
The ID of the Connection or Conference representing a resources associated with this event |
This event is emitted when a bridge is torn down between two resources using <unjoin>
.
A conference.unjoined
may also be emitted when the platform unjoins a connection due
to processing a <disconnect>
request or asynchronous connection.disconnected
event.
The fields of this event are:
Field Name | Details |
---|---|
name |
" conference.unjoined " |
id1 |
The ID of the Connection or Conference representing a resource associated with this event |
id2 |
The ID of the Connection or Conference representing a resources associated with this event |
The processing associated with the <createconference>
failed. The fields in this event are:
Field Name |
Details |
---|---|
name |
" error.conference.create " |
conferenceid |
The ID of the affected conference. |
reason |
A description of the reason the operation failed. |
The processing associated with the <destroyconference>
failed. The fields in this event
are:
Field Name |
Details |
---|---|
name |
" error.conference.destroy " |
conferenceid |
The ID of the affected conference. |
reason |
A description of the reason the operation failed. |
The processing associated with the <join>
failed. The fields in this event are:
Field Name |
Details |
---|---|
name |
" error.conference.join " |
id1 |
The ID of the Connection or Conference representing a resource associated with this event |
id2 |
The ID of the Connection or Conference representing a resources associated with this event |
reason |
A description of the reason the operation failed. |
The processing associated with the <join>
failed. The fields in this event are:
Field Name |
Details |
---|---|
name |
" error.conference.unjoin " |
id1 |
The ID of the Connection or Conference representing a resource associated with this event |
id2 |
The ID of the Connection or Conference representing a resources associated with this event |
reason |
A description of the reason the operation failed. |
error.merge
This event is emitted when a <merge> attempt fails.. Only one event will be generated, which references both connections. The fields of this event are:
Field Name | Required? | Details |
---|---|---|
|
Required | "error.merge" |
|
Required | The ID of the first Connection identified when the <merge> was invoked |
|
Required | The ID of the second Connection identified when the <merge> was invoked |
|
Required | A descrpition of the reason why the <merge> failed |
Caller calls an 800 number and after some interaction with an IVR system places an outbound call to a friend.
<?xml version="1.0" encoding="UTF-8"?> <ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0"> <!-- Create our ccxml level vars --> <var name="in_connectionid" expr="''" /> <var name="out_connectionid" expr="''" /> <!-- Set our initial state --> <assign name="currentstate" expr="'initial'" /> <eventprocessor statevariable="currentstate"> <!-- Deal with the incoming call --> <transition state="initial" event="connection.ALERTING" name="evt"> <assign name="in_connectionid" expr="evt.connectionid" /> <accept connectionid="in_connectionid" /> </transition> <transition state="initial" event="connection.CONNECTED" name="evt"> <assign name="currentstate" expr="'in_vxml_session'" /> <!-- VoiceXML dialog is started on a separate thread - see pin.vxml --> <dialogstart namelist="session.id" connectionid="in_connectionid" src="'pin.vxml'" /> </transition> <!-- happens when pin.vxml VoiceXML dialog thread exits --> <transition state="in_vxml_session" event="dialog.exit" name="evt"> <createcall dest="evt.values.telnum" name="out_connectionid" /> <assign name="currentstate" expr="'calling'" /> </transition> <transition state="calling" event="connection.FAILED" name="evt"> <!-- tell the caller there was a error --> <dialogstart namelist="session.id" connectionid="in_connectionid" src="'error.vxml'" /> <assign name="currentstate" expr="'oub_failed'" /> </transition> <!-- happens when called party picks up the phone --> <transition state="calling" event="connection.CONNECTED" name="evt"> <assign name="out_connectionid" expr="evt.connectionid" /> <!-- tell the callee he is receiving a call --> <dialogstart namelist="session.id" connectionid="out_connectionid" src="'callee.vxml'" /> <assign name="currentstate" expr="'outb_ready_to_join'" /> </transition> <transition state="oub_failed" event="dialog.exit" name="evt"> <exit /> </transition> <!-- happens when callee's vxml dialog (callee.vxml exits) --> <transition state="outb_ready_to_join" event="dialog.exit" name="evt"> <join id1="in_connectionid" id2="out_connectionid" /> <assign name="currentstate" expr="'wtg_for_joined'" /> </transition> <transition state="wtg_for_joined" event="ccxml.joined" name="evt"> <assign name="currentstate" expr="'active'" /> </transition> <!-- Lets clean up the call --> <transition state="active" event="connection.DISCONNECT" name="evt"> <if cond="evt.connectionid == in_connectionid"> <disconnect connectionid="out_connectionid"/> <exit /> </if> <assign name="currentstate" expr="'in_vxml_session'" /> <!-- start VoiceXML dialog again to see if caller wants to make another call --> <dialogstart namelist="session.id" connectionid="in_connectionid" src="'pin.vxml'" /> </transition> <!-- Catch disconnects in unexpected states --> <transition event="connection.DISCONNECT"> <exit /> </transition> </eventprocessor> </ccxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2001/vxml http://www.w3.org/TR/voicexml20/vxml.xsd" version="2.0"> <form id="pin"> <block> Welcome to Acme's Calling Card </block> <field name="pin" type="digits"> <prompt> Please say your PIN number </prompt> <filled> <if cond="pin.length != 8"> <clear namelist="pin"/> <else/> <submit next="checktime.asp" namelist="pin"/> </if> </filled> </field> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form> <block> Sorry. The Party you are trying to call is unavailable. <exit/> </block> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form> <block>You have a call. Connecting</block> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form id="form2"> <!--.asp consults back-end database before filling this value--> <assign name="timeleft" expr="600"/> <block> Time remaining is <value expr="timeleft"/> seconds </block> <field name="telnum" type="digits" > <prompt> Please speak the telephone number you want to call </prompt> <filled> <if cond="telnum.length != 7"> <clear namelist="telnum"/> <else/> <exit namelist="telnum"/> </if> </filled> </field> </form> </vxml>
Different callers call into a conference through an agreed upon telephone number. When each one of them joins the conference he is told how many people are there in the conference and those already in the conference are informed about a new entrant to the conference. Similarly when someone hangs up, the fact that a conference participant has exited is announced. A conference object is created at the beginning of the conference and is destroyed when all the participants have hung up.
<?xml version="1.0" encoding="UTF-8"?> <ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0"> <var name="in_connectionid" expr="''" /> <var name="currentstate" expr="'initial'" /> <eventprocessor statevariable="currentstate"> <transition state="initial" event="connection.alerting" name="evt"> <assign name="currentstate" expr="'alerting'" /> <assign name="in_connectionid" expr="evt.connectionid" /> <accept connectionid="in_connectionid" /> </transition> <transition state="alerting" event="connection.connected" name="evt"> <assign name="currentstate" expr="'fetching'" /> <fetch next="'http://www.example.org/conference.asp'" namelist="in_connectionid" /> </transition> <transition state="fetching" event="fetch.done" name="evt"> <goto fetchid="evt.fetchid" /> </transition> </eventprocessor> </ccxml>
<?xml version="1.0" encoding="UTF-8"?> <ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0"> <var name="conf_id" expr="'''" /> <var name="currentstate" expr="'starting'" /> <var name="in_connectionid" expr="'0f0c0d@host1.com'" /> <!-- above value is the value submitted to conference.asp--> <eventprocessor statevariable="currentstate"> <transition state="starting" event="ccxml.loaded" name="evt"> <createconference conferenceid="conf_id" /> </transition> <transition state="starting" event="conference.created" name="evt"> <assign name="currentstate" expr="'fetching'" /> <fetch next="'http://www.example.org/conference.asp'" namelist="in_connectionid conf_id" /> </transition> <transition state="fetching" event="fetch.done" name="evt"> <goto fetchid="evt.fetchid" /> </transition> </eventprocessor> </ccxml>
<?xml version="1.0" encoding="UTF-8"?> <ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0"> <var name="currentstate" expr="'ready_to_conf'" /> <var name="in_connectionid" expr="'ff0d01@host2.com'" /> <var name="conf_id" expr="'0a4602@host1.com'" /> <!-- above values are the values submitted to conference.asp--> <eventprocessor statevariable="currentstate"> <transition event="ccxml.loaded" name="evt"> <dialogstart connectionid="in_connectionid" src="'vconference.asp'" /> <assign name="currentstate" expr="'announcing'" /> </transition> <transition state="announcing" event="dialog.exit" name="evt"> <join entertone="false" exittone="false" id1="conf_id" id2="in_connectionid" /> </transition> <transition state="announcing" event="conference.JOINED" name="evt"> <assign name="currentstate" expr="'active'" /> <dialogstart conferenceid="conf_id" src="'newcaller.vxml'" /> </transition> <transition state="active" event="connection.DISCONNECTED" name="evt"> <dialogstart conferenceid="conf_id" src="'leave.vxml'" /> <assign name="currentstate" expr="'fetching'" /> <fetch next="'http://www.example.org/teardown.asp'" namelist="in_connectionid conf_id" /> </transition> <transition state="fetching" event="fetch.done" name="evt"> <goto fetchid="evt.fetchid" /> </transition> </eventprocessor> </ccxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form> <block> Welcome to the W3C conference. There are already <value expr="'3'" /> participants in the conference. <!--above value is based on count kept by vconference.asp--> </block> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form> <block> A new participant has entered the conference. </block> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form> <block> Someone just left the conference. </block> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0"> <var name="currentstate" expr="'destroying'" /> <var name="conf_id" expr="'0a4602@host1.com'" /> <var name="in_connectionid" expr="'ff0d01@host2.com'" /> <!-- above values are the values submitted to teardown.asp--> <eventprocessor statevariable="currentstate"> <transition event="ccxml.loaded" name="evt"> <exit /> <!-- just exit and destroy the session --> </transition> </eventprocessor> </ccxml>
<?xml version="1.0" encoding="UTF-8"?> <ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0"> <assign name="currentstate" expr="'destroying'" /> <assign name="conf_id" expr="'0a4602@host1.com'" /> <assign name="in_connectionid" expr="'ff0d01@host2.com'" /> <!-- above values are the values submitted to teardown.asp --> <eventprocessor statevariable="currentstate"> <transition event="ccxml.loaded" name="evt"> <destroyconference conferenceid="conf_id" /> <exit /> </transition> </eventprocessor> </ccxml>
This program is a Personal Assistant that operates as an automated answering service.
A subscriber to this service would receive a phone number to the automated service. When a caller wants to talk to the subscriber, he calls the given number. This automated system asks who the caller is, and records the audio. Then the system calls the current number of the target person, and asks if the call should be connected.
If so, the calls are bridged. If not, then the original caller is warned and disconnected.
<?xml version="1.0" encoding="UTF-8"?> <ccxml xmlns="http://www.w3.org/2002/09/ccxml" version="1.0"> <var expr="'initial'" name="currentstate" /> <var name="in_connectionid" /> <var name="dlg_onhold" /> <var name="out_connectionid" /> <var name="accepted" /> <eventprocessor statevariable="currentstate"> <transition event="connection.alerting" name="evt" state="initial"> <assign expr="evt.connectionid" name="in_connectionid" /> <accept /> </transition> <transition event="connection.connected" name="evt" state="initial"> <assign expr="'welcoming_caller'" name="currentstate" /> <dialogstart src="'welcome_message.vxml'" /> </transition> <transition event="dialog.exit" state="welcoming_caller"> <!-- place the caller on hold --> <dialogstart dialogid="dlg_onhold" connectionid="in_connectionid" src="'holdmusic.vxml'" /> <!-- Contact the target. The number here is server-generated --> <assign expr="'contacting_target'" name="currentstate" /> <createcall dest="'tel:+1-555-555-6666'" connectionid="out_connectionid" /> </transition> <transition event="connection.connected" name="evt" state="contacting_target"> <!-- Ask the target if (s)he would like to accept the call --> <assign expr="'waiting_for_target_answer'" name="currentstate" /> <dialogstart src="'outbound_greetings.vxml'" /> </transition> <transition event="dialog.exit" name="evt" state="waiting_for_target_answer"> <assign expr="evt.accepted" name="accepted" /> <if cond="accepted == 'false'"> <!-- disconnect the called party (but still notify the other one) --> <disconnect connectionid="out_connectionid" /> </if> <assign expr="'stop_hold'" name="currentstate" /> <dialogterminate dialogid="dlg_onhold" /> </transition> <transition event="dialog.exit" name="evt" state="stop_hold"> <if cond="accepted == 'false'"> <assign expr="'voice_mail'" name="currentstate" /> <dialogstart connectionid="in_connectionid" src="'vm.vxml'" /> <else /> <assign expr="'playing_connecting'" name="currentstate" /> <dialogstart connectionid="in_connectionid" src="'connecting.vxml'" /> </if> </transition> <transition event="dialog.exit" name="evt" state="playing_connecting"> <join id1="in_connectionid" id2="out_connectionid" /> <assign expr="'talking'" name="currentstate" /> </transition> <transition event="connection.disconnected" name="evt"> <if cond="evt.connectionid == in_connectionid"> <exit /> </if> </transition> </eventprocessor> </ccxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form> <record name="recording"> <prompt> You have reached the personal assistant for Bill Lumbergh of InnoTech. If is about the new TPS format please call Dom Portwood to get the new cover sheet. If this is for any other reason go on and state your name and I will decide if I want to take your call. Oh ya, if this is Milt, we're gonna need to go ahead and move you downstairs into storage B. We have some new people coming in, and we need all the space we can get. So if you could go ahead and pack up your stuff and move it down there, that would be terrific, OK </prompt> <filled> OK, thanks. <submit next="postRecordingAndExit.vxml" namelist="recording" /> </filled> </record> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <var name="willaccept"/> <form> <field id="answer"> <grammar src="yesnogrammar.grxml" /> <prompt> Hi bill, you have a message from <audio src="dynamicallyRecordedName.wav" /> Would you like to take it? Say Yes, or No. </prompt> <filled> <if cond="answer=='yes'"> Just a moment, please hold. <assign name="willaccept" value="true" /> <exit namelist="willaccept" /> <elseif cond="answer==no" /> OK, goodbye. <assign name="willaccept" value="false" /> <exit namelist="willaccept" /> </if> </filled> </field> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form> <prompt> Transferring you to voice mail hell. </prompt> <block> <goto next="voicemail.vxml" /> </block> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form> <prompt> Just a moment, please hold... </prompt> <block> <exit /> </block> </form> </vxml>
<?xml version="1.0" encoding="UTF-8"?> <vxml xmlns="http://www.w3.org/2001/vxml" version="2.0"> <form id="Form"> <block> <prompt bargin="false"> When a man loves a woman Can't keep his mind on nothin' else He'd trade the world For a good thing he's found If she is bad, he can't see it She can do no wrong Turn his back on his best friend If he puts her down. </prompt> <goto next="holdmusic.vxml" /> </block> </form> </vxml>
The Call Processing Language (CPL) is an XML based language that can be used to describe and control Internet telephony services. Its focus is user scripting of call handling behavior for incoming calls. It is designed to be suitable for running on a server where users may not be allowed to execute arbitrary programs, and so is not Turing-complete.
The latest version of CPL can be found linked from the IETF IP Telephony (IPTEL) Working Group charter page.
CallXML [CALLXML] is a markup language created by Voxeo Corporation that includes both voice and call-control functionality. CallXML is an XML based markup language used to describe the user interface of a telephone, voice over IP, or multi-media call application to a CallXML browser.
CallXML was designed to make it easy for Web developers to create applications that can interact with and control any number or type of calls, including:
For more information please see http://community.voxeo.com .
The description of CSTA [CSTA] from http://www.ecma-international.org/ is as follows:
"CSTA specifies an Applications Interface and Protocols for monitoring and controlling calls and devices in a communications network.
These calls and devices may support various media and can reside in various network environments such as IP, Switched Circuit Networks and mobile networks. CSTA however, abstracts various details of underlying signalling protocols (e.g. SIP/H.323) and networks for the applications."
The architecture of CCXML would allow a platform to be based on CSTA for the underlying telephony protocol (similar to how a platform could be based on SIP or ISDN Q.931) while still providing the CCXML execution environment for ease of integration with voice browsers.
TXML (Telera's Extensible Markup Language) [TXML] is an XML based language designed by Genesys (formerly Telera) for remotely controlling the behavior of Point of Presence (POP) servers.
TXML provides the syntax for the XML Pages, which are generated at the customer's application at the premises and used by a POP server to execute actions on behalf of the customer's application. The XML Pages are simple ASCII text files that are either stored in a Web server's directory at the premises or generated by scripts at the premises server. The XMLPages are requested from the premises server via HTTP requests made by a client on the POP gateway.
The language includes elements for
Go here for more documentation.
SIP, the Session Initiation Protocol, is a signaling protocol for Internet conferencing, telephony, presence, events notification and instant messaging. As a signaling protocol, SIP sits "below" the application description level of VoiceXML and CCXML. We expect many CCXML and VoiceXML browsers to support SIP signaling.
This section is Normative.
The CCXML DTD is located at http://www.w3.org/TR/ccxml/ccxml.dtd.
This section is Normative.
This appendix defines a normative XML Schema for CCXML. The CCXML schema is located at http://www.w3.org/TR/ccxml/ccxml.xsd.
This section is Normative.
This section describes the details of how CCXML and VoiceXML 2.0 work together to provide dialog functionality in CCXML.
The CCXML application behaviors described below are guidelines and applications are not required to support the full set of VoiceXML interactions. Platforms however should support the events and methods specified below to allow CCXML applications to implement the behaviors documented in this Appendix.
Since HTTP is a stateless protocol, application servers typically use cookie-based and/or URL rewriting techniques to enable stateful interactions with the server. Authors should be aware that application servers employing cookie-based management techniques will view concurrently executing CCXML and VoiceXML applications as independent (the CCXML and VoiceXML cookie stores are independent). Authors wishing to correlate CCXML and VoiceXML data at the server can use URL rewriting or alternatively employ the CCXML sessionid variable together with the connectionid or conferenceid as a common, unique key across the CCXML and VoiceXML applications.
CCXML and VoiceXML 2.0 need to be able to exchange events between the browsers. The method of the message passing is up to the platform but it is assumed that there is some basic capacity in place.
Each running CCXML session has an event queue used to process CCXML events, independently
of VoiceXML event processing by the dialogs created by that CCXML session. The execution of certain CCXML elements,
such as <dialogterminate>
and <send>
, may cause events to be sent to the
VoiceXML browser; similar, certain VoiceXML elements such as <transfer>
will result in the
generation of dialog events delivered to the CCXML session that owns the dialog in question. The sections below
define the eventing relationship between the CCXML and VoiceXML environments.
VoiceXML 2.0 provides limited capabilities for handling asynchronous or unexpected events. Since CCXML is designed around a robust event processing mechanism, and since the CCXML session manages connections to the underlying network, processing of asynchronous events - which may be delivered through externally accessible event I/O processors - typically occurs primarily within the CCXML application, which can then control the VoiceXML session as appropriate. The VoiceXML dialog can therefore focus exclusively on interaction with the user.
When a VoiceXML dialog is bridged to a connection with an associated call leg, the standard
VoiceXML session variables obtain their values from the call leg. Otherwise, these variables are undefined. VoiceXML
Session variables are updated whenever there is a update to the associated connection or conference. CCXML defines an
additional read-only VoiceXML session variable called session.connection.ccxml
with the following
sub-properties:
namelist
supplied in a CCXML
<dialogprepare>
or <dialogstart>
invocation. The length of the array is equal
to the number of names in the namelist
. The actual values are stored in the
session.connection.ccxml.values
variable.session.connection.ccxml.namelist
array is a sub-property of this variable which
evaluates to the value of the name at the time <dialogprepare>
or
<dialogstart>
was executed.<dialogprepare>
When a CCXML application processes a <dialogprepare>
element it prepares a VoiceXML application
with the URI that is passed in on the <dialogprepare>
element.
Normally it is expected that a VoiceXML dialog environment will use the <dialogprepare>
request
as an opportunity to fetch the initial document indicated by the src
and namelist
attributes along with any referenced resources such as <audio>
, <script>
, and
<grammar>
elements marked as prefetchable.
Even if a VoiceXML dialog environment is unable to perform any useful preparation the CCXML implementation
MUST support the <dialogprepare>
element and deliver a
dialog.prepared
event in response. The implementation MUST as a minimum, note
the values provided via the src
, namelist
, and connectionid
attributes, create
a Dialog object, and return a new unique value to the location defined by the dialogid
attribute.
<dialogstart>
When a CCXML application processes a <dialogstart>
element it starts up a VoiceXML application
on the connection with the URI that is passed in on the <dialogstart>
element or to the dialog
that was prepared using <dialogprepare>
and specified using the prepareddialogid
attribute.
<dialogterminate>
When a CCXML application processes a <dialogterminate>
it causes a
"connection.disconnect.hangup"
event to be thrown to the VoiceXML application. As far as the VoiceXML
application knows the call was just disconnected. The VoiceXML application still has a chance to return data to the
CCXML application by using <exit>
in its <catch>
statement.
<exit>
When a VoiceXML application processes a VoiceXML <exit>
it will cause the VoiceXML application
to exit and return the contents of the namelist
attribute to the CCXML application in the
"dialog.exit"
event in the following form:
<exit namelist="foo bar jar"/>
maps into an event that looks like the following:
dialog.exit values.foo values.bar values.jar
and could be accessed in a CCXML Application like this:
<!-- Process the incoming call --> <transition state="dialogActive" event="dialog.exit" name="evt"> <log expr="'Houston, the dialog foo: [' + evt.values.foo + ']'" /> <log expr="'Houston, the dialog bar: [' + evt.values['bar'] + ']'" /> <var name="xxx" expr="'jar'/> <log expr="'Houston, the dialog jar: [' + evt.values[xxx] + ']'" /> <exit /> </transition>
If the VoiceXML application is returning data using the expr
attribute the data will be stored in
"values"
.
<!-- Process the incoming call --> <transition state="dialogActive" event="dialog.exit" name="evt"> <log expr="'Houston, the dialog using expr [' + evt.values + ']'" /> <exit /> </transition>
<disconnect>
When the VoiceXML application processes a <disconnect>
element it causes a
"dialog.disconnect"
event to be thrown in the CCXML application. It is then up to the CCXML application
to disconnect the call and sends back a "connection.disconnect.hangup"
event by
using the <dialogterminate>
element. The following is an example of what would happen:
<disconnect>
."dialog.disconnect"
event from the VoiceXML application. It interprets this as a
request from the VoiceXML application to "please disconnect me".<transition>
element intended to handle the "dialog.disconnect"
event.<disconnect>
element as the child of the transition
event. This would disconnect the call.<transition>
element intended to
handle the "connection.disconnected"
event.<transition>
element has a child element which performs a
<dialogterminate>
on the dialog.Here is the example CCXML code that completes the disconnect and returns the
"connection.disconnect.hangup"
event back to VoiceXML:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <var name="dialogid"/> <eventprocessor statevariable="mystate"> <transition event="dialog.disconnect" name="myevent"> <assign name="dialogid" expr="myevent.dialogid"/> <disconnect connectionid="myevent.connectionid" /> </transition> <transition event="connection.disconnected" > <dialogterminate dialogid="dialogid"/> </transition> </eventprocessor> </ccxml>
<transfer>
When a VoiceXML application processes a <transfer>
element it is handled within CCXML via
series of events between the VoiceXML platform and the CCXML application. The type of transfer is controlled in
VoiceXML 2.0 by the bridge
attribute. If the value of bridge
is "true
" this
will come in with a transfer type of "bridge
" and if the value is "false
" it will have a
type of "blind
". Here is an example of the logic to support the VoiceXML 2.0 transfer types:
<transfer>
causing a dialog.transfer
event
to be sent to the CCXML Session.<transition>
to handle the dialog.transfer
event. This transition should implement the logic in the following steps.type
attribute of the dialog.transfer
event is "blind
" perform the
following:
<redirect>
to move the call to URI specified in the
dialog.transfer
eventtelephone.disconnect.transfer
event to inform the VoiceXML
session that the <transfer>
is complete.type
attribute of the dialog.transfer
event is "bridge
" perform the
following:
<createcall>
to create an outgoing call leg.<createcall>
completes with a connection.connected
event then do the
following:
maxtime
timer.connection.disconnected
event comes in for the original party:
connection.disconnect.hangup
to the VoiceXML session.connection.disconnected
event comes in for the new party:
<join>
the original connection back to the dialog full dupexdialog.transfer.complete
event to the dialog with a reason of
far_end_disconnect
.maxtime
event comes in:
<join>
the original connection back to the dialog full dupexdialog.transfer.complete
event to the dialog with a reason of
maxtime_disconnect
dialog.terminatetransfer
event comes in:
<join>
the original connection back to the dialog full dupexdialog.transfer.complete
event to the dialog with a reason of
near_end_disconnect
<createcall>
fails with a connection.failed
event then do the
following:
dialog.transfer.complete
event to the VoiceXML dialog with the failure reason.type
attribute of the dialog.transfer
event is bridge
, and if early
media is desired/permissible, then the above steps should be performed with the following exceptions:
<createcall>
to create the outgoing call leg, the joinid
attribute should be specified and should refer to the connection ID of the inbound leg associated with the
dialog performing the <transfer>
;connection.connected
event, start a maxtime timer
(if needed), but do not perform a <join>
(since the calls are already joined).dialog.terminatetransfer
The VoiceXML interpreter is responsible for throwing this event when a "hotword" grammar is matched while performing a bridged transfer.
When a caller hangs up on one of the connections the VoiceXML dialog is not automatically disconnected. The CCXML
application then needs to send a "connection.disconnect.hangup"
event to the VoiceXML application
by using the <dialogterminate>
element so it can complete any
cleanup that is required. The VoiceXML application can then still return data to the CCXML application by using the
VoiceXML <exit>
element.
The following example code shows how you would duplicate the standard VoiceXML 2.0 Interpreter Context in a CCXML Application. This example is not meant to be a complete application and does not handle all error events but is rather meant to give an overview of what such an application may look like.
You may also download the source of this application.
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml"> <!-- Declare the vars we are going to use --> <var name="in_connectionid" /> <var name="out_connectionid" /> <var name="dialogid" /> <var name="vxml_maxtime"/> <!-- Set an initial state --> <var name="mystate" expr="init"/> <eventprocessor statevariable="mystate"> <!-- - Deal with an incoming call --> <transition state="init" event="connection.alerting" name="evt"> <!-- Save off the connection id --> <assign name="in_connectionid" expr="evt.connectionid" /> <accept connectionid="evt.connectionid"/> </transition> <!-- - Call is connected so lets start the dialog --> <transition state="init" event="connection.connected" name="evt"> <dialogstart connectionid="evt.connectionid" src="http://www.example.com/dialog.vxml" dialogid="dialogid"/> <assign name="mystate" expr="'connected'" /> </transition> <!-- - Dialog is active --> <transition state="connected" event="dialog.started" name="evt"> <assign name="mystate" expr="'dialogActive'" /> </transition> <!-- - Dialog requests that we disconnect the call --> <transition state="dialogActive" event="dialog.disconnect" name="evt"> <disconnect connectionid="evt.connectionid" /> <assign name="mystate" expr="'disconnecting'" /> </transition> <!-- - We have disconnected the call. We need to send an - event to the dialog saying we are done. --> <transition state="disconnecting" event="connection.disconnect" name="evt"> <dialogterminate dialogid="dialogid"/> </transition> <!-- - Dialog has exited after we disconnected the call. - We just are going to exit from this CCXML session... --> <transition state="disconnecting" event="dialog.exit" name="evt"> <exit/> </transition> <!-- - The caller disconnected. We need to send the event up to - the Dialog and change our state. --> <transition state="dialogActive" event="connection.disconnect" name="evt"> <dialogterminate dialogid="dialogid"/> <assign name="mystate" expr="'userDisconnect'" /> </transition> <!-- - Dialog has exited after the caller hungup. - We just are going to exit from this CCXML session... --> <transition state="userDisconnect" event="dialog.exit" name="evt"> <exit/> </transition> <!-- - - Handle an transfer request from a VXML script. - --> <transition state="dialogActive" event="dialog.transfer" name="evt"> <!-- Branch on transfer type --> <if cond="evt.type == 'blind'"> <!-- Bridge == false. We are going to just redirect the call --> <!-- Update our state var --> <assign name="mystate" expr="'redirecting'" /> <!-- And redirect to the uri specified in the event --> <redirect connectionid="in_connectionid" dest="evt.URI" /> <!-- Just send the success event to the dialog --> <send data="connection.disconnect.transfer" target="dialogid" targettype="'dialog'"/> <else/> <!-- Bridge == true. In this case we need to place a call and bridge the calls --> <!-- save off maxtime --> <assign name="vxml_maxtime" expr="evt.maxtime" /> <!-- Update our state var --> <assign name="mystate" expr="'calling'" /> <!-- Place the call using the num from the transfer request --> <createcall dest="evt.URI" name="out_connectionid" aai="evt.aai" timeout="evt.connecttimeout"/> </if> </transition> <!-- - We will get the following events but we do not do anything - because in VoiceXML 2.0 you just ignore redirect errors. - We do however process the dialog.exit and shutdown - the CCXML Session. --> <transition state="redirecting" event="connection.redirected" name="evt"> </transition> <transition state="redirecting" event="connection.failed" name="evt"> </transition> <transition state="redirecting" event="dialog.exit" name="evt"> <exit/> </transition> <!-- - - Handle bridge=true Events - - This first event is for if the outbound call failed. - --> <transition state="calling" event="connection.failed" name="evt"> <!-- Just send the error event to the dialog --> <assign name="results" expr="evt.reason"/> <send data="dialog.transfer.complete" target="dialogid" targettype="'dialog'" namelist="results" /> <!-- Update our state var back to the original state --> <assign name="mystate" expr="'dialogActive'" /> </transition> <!-- - The outbound call has been answered. --> <transition state="calling" event="connection.connected" name="evt"> <!-- Update our state var back to show that we are connected --> <assign name="mystate" expr="'outgoing_call_active'" /> <!-- Join the two calls together --> <join id1="in_connectionid" id2="in_connectionid" duplex="full" /> </transition> <!-- - We will get here once the join completes. --> <transition state="outgoing_call_active" event="conference.joined" name="evt"> <!-- If maxtime has been set then we setup a timer --> <if cond="vxml_maxtime != undefined"> <send data="maxtime" target="session.id" delay="vxml_maxtime" sendid="maxtime_sendid"/> </if> </transition> <!-- - Deal with someone disconnecting. --> <transition state="outgoing_call_active" event="connection.disconnected" name="evt"> <!-- Cancel any maxtime events that are waiting to be fired --> <if cond="maxtime_sendid != undefined"> <cancel sendid="maxtime_sendid"/> <assign name="maxtime_sendid" expr="undefined"/> </if> <!-- Branch off based on what call leg this is for and send the proper event to the dialog --> <if cond="evt.connectionid == out_connectionid"> <assign name="results" expr="far_end_disconnect" /> <send data="dialog.transfer.complete" target="dialogid" targettype="'dialog'" namelist="results" /> <!-- Update our state var back to the original state --> <assign name="mystate" expr="'dialogActive'" /> <else /> <!-- Set our state to show that the original caller is disconnected. --> <assign name="mystate" expr="'userDisconnected'" /> <dialogterminate dialogid="dialogid"/> </if> </transition> <!-- - Deal with a "hotword" type event where the dialog - requests that we stop the transfer. --> <transition state="outgoing_call_active" event="dialog.terminatetransfer" name="evt"> <!-- Change our state to show we are dealing with hotword stuff --> <assign name="mystate" expr="'hotword'" /> <!-- Cancel any maxtime events that are waiting to be fired --> <if cond="maxtime_sendid != undefined"> <cancel sendid="maxtime_sendid"/> <assign name="maxtime_sendid" expr="undefined"/> </if> <!-- unjoin our connections --> <unjoin id1="in_connectionid" id2="out_connectionid"/> </transition> <!-- - Calls have been unjoined. --> <transition state="hotword" event="conference.unjoined" name="evt"> <!-- Rejoin the first connection to the dialog --> <join id1="in_connectionid" id2="dialogid"/> <!-- Disconnect the outbound call --> <disconnect connectionid="out_connectionid"/> </transition> <!-- - Send an event to the dialog once we are all back together again. --> <transition state="hotword" event="conference.joined" name="evt"> <!-- Build up our event --> <assign name="results" expr="near_end_disconnect" /> <send data="dialog.transfer.complete" target="dialogid" targettype="'dialog'" namelist="results" /> <!-- Update our state var back to the dialogActive state --> <assign name="mystate" expr="'dialogActive'" /> </transition> <!-- - Deal with connection.disconnect events in the hotword state. - We are only going to deal with stuff if it the event is - for the incoming call. --> <transition state="hotword" event="connection.disconnect" name="evt"> <if cond="evt.connectionid == in_connectionid"> <dialogterminate dialogid="dialogid"/> <!-- Update our state var to the userDisconnect state --> <assign name="mystate" expr="'userDisconnect'" /> </if> </transition> <!-- - Deal with the maxtime event during a call transfer. - Should this happen we just disconnect the outbound call let - and get back to the dialogActive state. - - Step one is to disconnect the call... --> <transition state="outgoing_call_active" event="vxml_maxtime" name="evt"> <assign name="maxtime_sendid" expr="undefined"/> <assign name="mystate" expr="'maxtime'" /> <disconnect connectionid="out_connectionid"/> </transition> <!-- - Once we have the disconnect event we verify that we - got it for the outbound call and rejoin the dialog to the - inbound call. If the inbound call disconnected - we are going to go on and forward the event along - and wait for the dialog to exit. - --> <transition state="maxtime" event="connection.disconnected" name="evt"> <if cond="evt.connectionid == out_connectionid"> <join id1="dialogid" id2="in_connectionid"/> <else /> <dialogterminate dialogid="dialogid"/> </if> </transition> <!-- - - We are rejoined. Update our state and send the transfer - event back to the dialog. - --> <transition state="maxtime" event="conference.joined" name="evt"> <!-- Update our state var back to the dialogActive state --> <assign name="mystate" expr="'dialogActive'" /> <assign name="results" expr="maxtime_disconnect" /> <send data="dialog.transfer.complete" target="dialogid" targettype="'dialog'" namelist="results" /> </transition> <!-- - Dialog has exited while we were in a hotword state. - We just are going to exit from this CCXML session... --> <transition state="maxtime" event="dialog.exit" name="evt"> <exit/> </transition> <!-- - - Deal with any extra random events that may come in. - --> <!-- - Make sure that we deal with any extra dialog events - by ending the session. A real ccxml app would do something - better here. --> <transition event="dialog.*" name="evt"> <exit/> </transition> <!-- - And do the same for any exit events. --> <transition event="error.*" name="evt"> <exit/> </transition> <!-- - And last but not least catch any connection.disconnect - events that made it past us. --> <transition event="connection.disconnect" name="evt"> <exit/> </transition> </eventprocessor> </ccxml>
This section defines a list of recommended telephony protocol names to be used in CCXML platforms. Platforms MUST use the following list when available. If the protocol is not defined in this list the platform MUST prefix the name with an underscore, "_", to identify them as platform-dependent.
Protocol Name | Details |
---|---|
sip | Session initiation protocol [ RFC3261 ]. |
h323 | ITU H.323 Voice over IP protocol [ H.323 ]. |
q931 | ISDN q.931 call control [ Q.931/DSS1 ]. |
ss7 | Signaling System 7 [ SS7 ]. |
csta | ECMA Computer Supported Telecommunications Applications [ CSTA ]. |
pots | Plain Old Telephone Service. |
cas | Channel Associated Signaling. |
This version of CCXML was written with the participation of members of the W3C Voice Browser Working Group, and a special thanks is in order for the following contributors:
This W3C specification is based upon a former CCXML specification, contributed to the Voice Browser Working Group in April 2001. The CCXML authors were:
This appendix registers a new MIME media type, "application/ccxml+xml
".
application
ccxml+xml
None.
charset
This parameter has identical semantics to the charset
parameter of the
application/xml
media type as specified in [RFC3023].
By virtue of CCXML content being XML, it has the same considerations when sent as
"application/ccxml+xml
" as does XML. See RFC 3023, section 3.2.
Several CCXML instructions may cause arbitrary URIs to be referenced. In this case, the security issues of RFC1738, section 6, should be considered.
In addition, because of the extensibility features for CCXML, it is possible that
"application/ccxml+xml
" may describe content that has security implications beyond those described
here. However, if the processor follows only the normative semantics of this specification, this content will be
ignored. Only in the case where the processor recognizes and processes the additional content, or where further
processing of that content is dispatched to other processors, would security issues potentially arise. And in
that case, they would fall outside the domain of this registration document.
This specification describes processing semantics that dictate behavior that must be followed when dealing with, among other things, unrecognized elements.
Because CCXML is extensible, conferment "application/ccxml+xml
" processors can expect that
content received is well-formed XML, but it cannot be guaranteed that the content is valid CCXML or that the
processor will recognize all of the elements and attributes in the document.
This media type registration is for CCXML documents as described by this specification.
There is no single initial octet sequence that is always present in CCXML documents.
CCXML documents are most often identified with the extensions ".ccxml
".
TEXT
RJ Auburn, <rj@voxeo.com>
.
COMMON
The CCXML specification is a work product of the World Wide Web Consortium's Voice Browser Working Group. The W3C has change control over these specifications.
For documents labeled as "application/ccxml+xml
", the fragment identifier notation is exactly that
for "application/xml
", as specified in RFC 3023.
This section is Normative.
A document is a Conforming CCXML Document if it meets all of the following conditions:
<ccxml>
root element which includes a version
attribute of
"1.0"<ccxml>
element designates the CCXML namespace. This can be achieved by declaring an
xmlns
attribute or an attribute with an xmlns
prefix [XMLNS]. The namespace for CCXML is defined to be "http://www.w3.org/2002/09/ccxml"It is recommended that the <ccxml>
element indicate the location of the CCXML schema (see
Appendix C) via the xsi:schemaLocation
attribute from [SCHEMA2]:
xsi:schemaLocation="http://www.w3.org/2002/09/ccxml http://www.w3.org/TR/ccxml/ccxml.xsd"
There may be a DOCTYPE declaration in the document prior to the root element. If present, the public identifier
included in the DOCTYPE declaration must reference the CCXML DTD (Appendix B) using its Formal Public
Identifier:
<!DOCTYPE ccxml PUBLIC "-//W3C//DTD CCXML 1.0//EN" "http://www.w3.org/TR/ccxml/ccxml.dtd">
The system identifier may be modified appropriately. The DTD subset must not be used to override any parameter entities in the DTD.
Here is an example of a Conforming CCXML Document:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0" xmlns="http://www.w3.org/2002/09/ccxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2002/09/ccxml http://www.w3.org/TR/ccxml/ccxml.xsd"> <eventprocessor> <transition event="connection.alerting" name="evt"> <log expr="'Hello World'"/> <exit/> </transition> </eventprocessor> </ccxml>
Note that in this example, the recommended xmlns:xsi
and xsi:schemaLocation
attributes
are included. Note also, the inclusion of an XML declaration. An XML declaration like the one above is not required
in all XML documents. CCXML document authors are strongly encouraged to use XML declarations in all their
documents. Such a declaration is required when the character encoding of the document is other than the default
UTF-8 or UTF-16 and no encoding was determined by a higher-level protocol.
The CCXML language or these conformance criteria provide no designated size limits on any aspect of CCXML documents. There are no maximum values on the number of elements, the amount of character data, or the number of characters in attribute values.
The CCXML namespace may be used with other XML namespaces as per [XMLNS], although such documents are not strictly conforming CCXML documents as defined above. Future work by W3C will address ways to specify conformance for documents involving multiple namespaces.
A CCXML Processor is a program that can parse and process Conforming CCXML Documents. In a CCXML Processor, the XML parser must be able to parse and process all XML constructs defined by XML 1.0 [XML] and Namespaces in XML [XMLNS]. This XML parser is not required to perform validation of a CCXML document as per its schema or DTD; this implies that during processing of a CCXML document it is optional to apply or expand external entity references defined in an external DTD.
A Conforming CCXML Processor must correctly understand and apply the semantics of each markup element as described by this document.
When a Conforming CCXML Processor encounters elements or attributes, other than xml:lang
and
xml:base
, in a non-CCXML namespace it may:
There is, however, no conformance requirement with respect to performance characteristics of the CCXML Processor.