Copyright © 2004 W3C ® ( MIT , ERCIM, Keio ), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.
This document describes CCXML, or the Call Control eXtensible Markup Language. CCXML is designed to provide telephony call control support for VoiceXML [VOICEXML] or other dialog systems. CCXML has been designed to complement and integrate with a VoiceXML interpreter. Because of this there are many references to VoiceXML's capabilities and limitations. There are also details on how VoiceXML and CCXML can be integrated. However it should be noted that the two languages are separate and are not REQUIRED in an implementation of either language. For example CCXML could be integrated with a more traditional Interactive Voice Response (IVR) system and VoiceXML or other dialog systems could be integrated with some other call control systems.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This specification describes the Call Control XML (CCXML) markup language that is designed to provide telephony call control support for VoiceXML or other dialog systems. This document has been produced as part of the W3C Voice Browser Activity, following the procedures set out for the W3C Process. The authors of this document are members of the Voice Browser Working Group ( W3C Members only ).
This version of the specification has a large number of editorial changes to clarify sections that were ambiguous or incomplete. A number of sections have been completely rewritten. Major changes include:
For a detailed list please see Changes in Last Call Working Draft.
This is a W3C Last Call Working Draft for review by W3C Members and other interested parties. Last Call means that the Working Group believes that this specification is technically sound and therefore wishes this to be the Last Call for comments. If the feedback is positive, the Working Group plans to submit it for consideration as a W3C Candidate Recommendation. Comments can be sent until 28 May 2004.
Although an Implementation Report Plan has not yet been developed for this specification, the Working Group currently expects to require at least two independently developed interoperable implementations of each required feature, and at least one implementation of each feature, in order to exit the next phase of this document, the Candidate Recommendation phase. To help the Voice Browser Working Group build such a report, reviewers are encouraged to implement this specification and to indicate to W3C which features have been implemented, and any problems that arose.
This document is for public review. Comments and discussion are welcomed on the public mailing list < www-voice@w3.org >. To subscribe, send an email to <www-voice-request@w3. org> with the word subscribe in the subject line (include the word unsubscribe if you want to unsubscribe). The archive for the list is accessible on-line.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document has been produced under the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.
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 VoiceXML [VOICEXML] or other dialog systems.
CCXML can provide a complete telephony service application, comprised of Web server CGI compliant application logic, one or more CCXML documents to declare and perform call control actions, and to control one or more dialog applications that perform user media interactions
Since platforms implementing CCXML MAY choose to use one of many telephony call control definitions ( JAIN Call Control [ JSR021 ], ECMA CSTA [ CSTA ], S.100 [ S.100 ], etc.), the call control model in CCXML has been designed to be sufficiently abstract so that it can accommodate all major definitions. For relatively simple types of call control, this abstraction is straightforward. The philosophy in this regard has been to "make simple things simple to do." Outdial, transfer (redirect), two-party bridging, and many forms of multi-party conferences fall within this classification.
Figure 1 shows the architecture of a telephony implementation consisting of three primary components:
The Telephony Web Application may or may not be integrated with the Voice Web Application.
The Telephony Control and Dialog Control Interfaces may be implemented as an API or protocol.
The components as shown in the figure below represent logical functions, and are not meant to imply any particular architecture.
Figure 1
CCXML is designed to complement VoiceXML by providing advanced telephony functions. It also can be used as a third-party call control manager in any telephony system. This document contains references to VoiceXML's capabilities and limitations, as well as details on how VoiceXML and CCXML can be integrated.
The CCXML specification originated from the desire to handle call control requirements that were beyond the scope of the VoiceXML specification. The following requirements are addressed by this specification:
CCXML and VoiceXML implementations are not mutually dependent. A CCXML implementation may or may not support voice dialogs, or may support dialog languages other than VoiceXML.
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.
All asynchronous event processing is handled in a CCXML Session. Every executing VoiceXML Dialog has an associated CCXML Session. It runs on a session separate from the VoiceXML Dialog. When an event is delivered to a user's voice session (now a coupling of an active VoiceXML Dialog and its CCXML Session), it is appended to the CCXML Session's queue of events. The CCXML Session spends almost all its time processing the event at the head of the event queue. Meanwhile, the VoiceXML Dialog can interact with the user, undisturbed by the incoming flow. Most VoiceXML implementations never need to consider event processing at all.
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:
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.
This simple CCXML document shows an example of a "hello world" application that is started due to an incoming call where the application simply assigns a value to a variable, prints a message to the platform log and exits:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0"> <eventprocessor> <transition event="connection.alerting" name="evt"> <var name="MyVariable" expr="'This is a CCXML Variable'"/> <log expr="'Hello World. I just made a variable: ' + MyVariable"/> <log expr="'Lets hang up on this incoming call as this is an example.'"/> <exit/> </transition> </eventhandler> </ccxml>
This CCXML document shows an example of how to process a incoming call event and answer or reject the call based on the phone number of the calling party:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0"> <eventprocessor> <transition event="connection.alerting" name="evt"> <log expr="'The phone number the user called is' + evt.connection.remote + '.'"/> <if cond="evt.connection.remote == '8315551234'"> <log expr="'Go away! we do not want to answer the phone.'"/> <reject/> <else/> <log expr="'We like you! We are going to answer the call.'"/> <accept/> </if> </transition> <transition event="connection.connected"> <log expr="'Call was answered, we are now going to disconnect it.'"/> <disconnect/> </transition> <transition event="connection.disconnected"> <log expr="'Call has been disconnected. We should now end the CCXML session.'"/> <exit/> </transition> </eventhandler> </ccxml>
This is an example of running a simple VoiceXML dialog from CCXML. The application answers a incoming phone call and then connects it to a VoiceXML dialog that returns a value that is then logged to the platform:
<?xml version="1.0" encoding="UTF-8"?> <ccxml version="1.0"> <!-- Lets declare our state var --> <var name="state0" expr="'init'"/> <eventprocessor statevariable="state0"> <!-- Process the incoming call --> <transition state="'init'" event="connection.alerting"> <accept/> </transition> <!-- Call has been answered --> <transition state="'init'" event="connection.connected" name="evt"> <log expr="'Houston, we have liftoff.'"/> <dialogstart src="'gimme.vxml'"/> <assign name="state0" expr="'dialogActive'" /> </transition> <!-- Process the incoming call --> <transition state="'dialogActive'" event="dialog.exit" name="evt"> <log expr="'Houston, the dialog returned [' + evt.values.input + ']'" /> <exit /> </transition> <!-- Caller hung up. Lets just go on and end the session --> <transition event="connection.disconnected" name="evt"> <exit/> </transition> <!-- Something went wrong. Lets go on and log some info and end the call --> <transition event="error.*" name="evt"> <log expr="'Houston, we have a problem: (' + evt.reason + ')'"/> <exit/> </transition> </eventhandler> </ccxml>
<?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 |
<dialogstart> | Start a dialog session's execution |
<dialogterminate> | Stop a dialog session's execution |
<disconnect> | Terminate a phone connection |
<else> | Used in <if> statements |
<elseif> | Used in <if> statements |
<eventprocessor> | Block of event-processing statements |
<exit> | Ends execution of the CCXML session |
<fetch> | Preload a CCXML file |
<goto> | Move execution to a new location |
<if> | Conditional logic |
<join> | Connect two audio sources |
<log> | Log to the platform debug log |
<move> | Move a event to another ccxml session |
<redirect> | Redirect an incoming call to a new endpoint |
<reject> | Reject an incoming phone call |
<script> | Run ECMA Script |
<send> | Generate an event |
<transition> | A single event-processor block |
<unjoin> | Disconnect two audio sources |
<var> | Declare a variable |
A CCXML session begins with the execution of a CCXML document.
The flow of the execution can be changed with the help of
<if>
, <elseif>
,
<else>
, <fetch>
, and
<goto>
. Most of a CCXML session's execution will
take place within an <eventprocessor>
, which
processes a stream of incoming events.
A CCXML session can consist of multiple CCXML documents,
traversed by use of <goto>
and
<fetch>
.
A new CCXML session has a new session object (session.*), where initially the length of the connection array is 0. A CCXML session contain multiple active connections.
A CCXML session may launch a new CCXML session using
<createccxml>. The new CCXML session executes in an
independent context and variable space from the original CCXML
session, completely independent of the lifetime of the original
session. Sessions can communicate by sending messages via
<send>
.
The media type application/ccxml+xml
will be
registered for CCXML documents.
The proposed definition of the media type is at J The CCXML Media Type
This media type should be used for a XML document containing a CCXML document.
Here are the details of 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
DetailsAttribute Name | Details |
---|---|
version |
The version of this CCXML document (REQUIRED). The initial version number is 1.0. |
xml:base |
The base URI for this document as defined in [XML-BASE]. As in [HTML], a URI which all relative references within the document take as their base. (OPTIONAL) |
<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
DetailsAttribute Name | Details |
---|---|
name |
The name of the metadata property. |
content |
The value of the metadata property. |
http-equiv |
The name of an HTTP response header. |
<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
DetailsAttribute Name | Details |
---|---|
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
DetailsAttribute Name | Details |
---|---|
cond |
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 DetailsAttribute Name | Details |
---|---|
cond |
An ECMAScript expression which can be evaluated to true or false. |
<else>
<else>
is a synonym for <elseif
cond="true"/>
.
<else>
Attribute
DetailsAttribute Name | Details |
---|---|
none | none |
<fetch>
and <goto>
<fetch>
, together with
<goto>
, is used to transfer execution to a
different CCXML document in a multi-document CCXML application. In
CCXML we break the document transition into two parts. The
<fetch>
tells the platform to find, load, and
parse a given CCXML document. Execution returns from the element
immediately, and the CCXML application can continue on while the
platform works to get the target document ready for execution. When
the <fetch>
completes, the session which issued
the fetch receives a fetch completion event. It can then issue a
<goto>
to immediately start executing the
now-fetched document.
Below is a small snippet of code from the CCXML application's
event handler. We execute a <fetch>
operation,
and continue on to assign to a state variable, and maybe handle
more events. Eventually, the fetch completes, the CCXML platform
services the event, and the application performs the
<goto>
.
<fetch next="'http://www.web.com/control.ccxml'"/> <--control continues here-> <assign name="state_var" expr="'fetch_wait'"/> </transition> <!-- ……… --> <transition state="fetch_wait" event="fetch.done" name="evt"/> <goto fetchid="evt.fetchid"/> </transition>
There's no requirement to <goto>
previously-fetched documents, but it is wasteful to not do so.
Asynchronous execution of a <fetch>
initiates
a request for the CCXML document identified by its attributes.
Execution immediately continues with the element following the
fetch. When the asynchronous request has completed, the fetch
completion event will be generated. If the fetch fails for any
reason, a fetch fail event will be generated instead.
When <fetch>
is executed synchronously, the
CCXML session blocks until the fetch completes, and the fetch
completion event is stored as identified by the synch
attribute. In this case, the element following the
<fetch>
will not be executed until fetch
completes. The properties of the fetch completion event can be
tested to determine the result of the fetch request, so that error
handling alternatives can be provided.
A <goto>
transfers control to the document
identified by the fetch ID. The execution of a
<goto>
does not depend upon whether the target
document was fetched synchronously or asynchronously. However, the
fetch completion event MUST have arrived
before the <goto>
is executed, otherwise, an
error event is generated.
When a <goto>
is executed, the target
document replaces the current document in its session. Event
sources associated with this session are inherited by the target
document. Execution of the current document terminates.
Platforms are responsible for clearing out unused fetch resources. When a session is terminated any associated fetches MAY be released.
<fetch>
Attribute
DetailsAttribute Name | Details |
---|---|
next |
an ECMAScript expression which returns the URI of the CCXML document to be fetched. |
namelist |
a list of zero or more whitespace separated CCXML variable names. These variable names and their associated values will be included in the URI sent to the server, with the same qualification used in the namelist. |
method |
an ECMAScript expression which
returns a character string that indicates the HTTP method to use. Valid
values are " get " and " post ". The
default is " get ". |
fetchid |
is an ECMAScript left-hand-side expression which receives an internally generated unique string identifier to be associated with the completion event. This identifier can be tested by the fetch completion event handler to distinguish among several outstanding fetch requests. If this attribute is not specified, the fetch ID can be acquired from the fetch completion event. Every fetch request will receive a unique fetch ID, even requests for the same document. |
synch |
is an ECMAScript left-hand-side
expression that is set to the fetch completion event. The
specification of this attribute in a <fetch>
implies a blocking fetch, which will be executed synchronously. If
this attribute is not specified, the fetch is asynchronous. |
timeout |
is an ECMAScript expression
returning a string in CSS2 [CSS2] format interpreted as a time interval.
The interval begins when the <fetch> is
executed. The fetch will fail if not completed at the end of this
interval. A failed fetch will return the error.fetch
event. |
<goto>
Attribute
DetailsAttribute Name | Details |
---|---|
fetchid |
an ECMAScript expression which
returns the fetch ID of a document referenced in a fetch completion
event. The fetch ID can be acquired in a <fetch>
with the fetchid attribute. The fetch completion event
also provides a property whose value is the fetch ID of the
document fetched. |
<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 DetailsAttribute Name | Details |
---|---|
next |
an ECMAScript expression which returns the URI of the CCXML document that will begin execution in the new session. |
namelist |
a list of zero or more whitespace separated CCXML variable names. These variable names and their associated values will be included in the URI sent to the server, with the same qualification used in the namelist. |
method |
an ECMAScript expression which
returns a character string that indicates the HTTP method to be used, by
the new session, when fetching the initial document. Valid values
are " get " and " post ". The default is
" get ". |
start |
an ECMAScript expression which returns an event object which is the initial event for the new session. This event will be the first event sent to the document started by this element. The endpoint which originated this event will be inherited by the new session. This attribute is OPTIONAL. |
sessionid |
an ECMAScript left-hand-side expression that is set to an internally generated unique string identifier which identifies the newly created session. This attribute is OPTIONAL. |
timeout |
is an ECMAScript expression
returning a string in CSS2 [ CSS2 ] format interpreted as a time
interval. The time interval is interpreted by the new CCXML session
as the maximum time it should wait for completion of the fetch for
the initial document specified by the next attribute.
If the new CCXML session is unable to fetch the initial document
within the timeout interval, an
error.createccxml event MUST
be thrown. |
<exit>
<exit>
ends execution of the CCXML session.
All pending events are discarded, and there is no way to restart
CCXML execution.
<exit>
Attribute
DetailsAttribute Name | Details |
---|---|
expr |
A return ECMAScript expression (e.g. 0 or 'oops!'). This attribute is OPTIONAL ; if omitted, a value of zero is assumed. This value is stored as a property of the exit event. |
namelist |
a list of zero or more whitespace separated CCXML unqualified variable names to be returned which will be set as properties of the exit event. |
A CCXML document executing the <exit>
will
generate a ccxml.exit
event to the parent session. The
exiting document will be identified on the exit event by its
session ID.
<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
DetailsAttribute Name | Details |
---|---|
label |
an ECMAScript expression which returns a character string which MAY be used, for example, to indicate the purpose of the log |
expr |
An ECMAScript expression evaluating to a string to be logged |
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>
.
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. Unlike other events,
the ccxml.kill.unconditional
event is the only event
that cannot be caught by an application; it will unconditionally
terminate the session end.
The fields of this event are:
Field Name | Details |
---|---|
name |
ccxml.kill |
sessionid |
the identifier of the session |
reason |
a string describing the reason the platform sent the kill event. Content of this field is platform-specific, and is only for informative purposes. |
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. The requirements on a dialog environment are very small so that VoiceXML, SALT [ SALT ], and even traditional IVR languages and platforms MAY be used with CCXML. A CCXML platform MAY support interaction with several dialog systems with the selection of the particular technology being based on the MIME type specified when the dialog is initiated.
All CCXML elements that manipulate dialogs are asynchronous with control returning immediately to the CCXML session after the operation is initiated. The CCXML session is notified when the dialog operation successfully completes, or fails, by an asynchronous event.
A CCXML program initiates a dialog using the
<dialogstart>
element. Execution of this element
connects a dialog environment to a connection and instructs it to
start interacting with the caller. For some dialog environments it
may take some time to initialize the dialog environment and thus
the use of the <dialogstart>
element alone may
cause the caller to hear silence, or "dead air". To avoid this
situation CCXML provides an ability to ready a dialog environment
prior to connecting and starting it, this is done using the
<dialogprepare>
element. Any dialog that has
been either started with <dialogstart>
, or
prepared with <dialogprepare>
can be terminated
using the <dialogterminate>
element. CCXML
implementations MUST support the
<dialogprepare>
,
<dialogstart>
, and
<dialogterminate>
elements though the exact
behaviour may vary depending on the dialog environments
supported.
The following examples illustrate the valid use patterns for
these three elements. Firstly the normal case of preparing a
dialog, starting it, then optionally terminating it before normal
completion. This example illustrates the use of
<dialogprepare>
to ready a dialog while the call
is left in alerting state. When the alerting notification arrives
the script executes a <dialogprepare>
to prepare
a dialog and associate it with the connection. When the dialog is
prepared the script executes an <accept>
to
connect the call and then when the connection transitions to
connected state, a <dialogstart>
element is used
to execute the previously prepared dialog.
<transition event="connection.alerting" name="evt"> <dialogprepare src="..." connectionid="evt.connectionid"/> </transition> <transition event="dialog.prepared" name="evt"> <accept connectionid="session.dialogs[evt.dialogid].connectionid"/> </transition> <transition event="connection.connected" name="evt"> <dialogstart prepareddialogid="evt.dialogid" connectionid="evt.connectionid"/> </transition> (optionally) <transition event="???"> <dialogterminate dialogid="..." /> </transition>
The next example shows a single step dialog invocation without
dialog preparation. In this case a connection in alerting state is
accepted and, when the transition to connected state occurs, a
<dialogstart>
element is used to start the
dialog.
<transition event="connection.alerting" name="evt"> <accept connectionid="evt.connectionid"/> </transition> <transition event="connection.connected" name="evt"> <dialogstart src="..." connectionid="evt.connectionid"/> </transition> (optionally) <transition event="???"> <dialogterminate dialogid="..." /> </transition>
The final example shows the case where a dialog which has been
previously prepared is cancelled before a
<dialogstart>
has been issued. A dialog may be
terminated when it is in the prepared state or while it is being
prepared such as might be the case if the caller hangs up at some
arbitrary point. In this case the
<dialogterminate>
may be executed before or
after the dialog.prepared
event is processed.
<transition event="connection.connected"> name="evt"> <dialogprepare src="..." connectionid="evt.connectionid"/> </transition> <transition event="connection.disconnected" name="evt"> <dialogterminate dialogid="evt.connection.dialogid" /> </transition>
<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 then new dialog may be associated with a connection
by specifying the connectionid
attribute. The
association with the connection may be overridden by specifying a
connectionid
or conferenceid
on a
subsequent <dialogstart>
request.
When preparation of the dialog competes successfully a
dialog.prepared
event is posted to the event queue of
the CCXML session. If however the dialog cannot be prepared for any
reason, an error.dialog.notprepared
event is
posted.
CCXML implementations MUST support
dialog preparation though the processing carried out as part of a
<dialogprepare>
request is dialog manager
specific. In the case of a dialog manager that does not support
preparation, the CCXML implementation MUST
as a minimum, note the values provided via the src
,
namelist
, and connectionid
attributes,
create a Dialog object, and return a new unique value to the
location defined by the dialogid
attribute.
The CCXML session selects what it believes to be the appropriate
dialog manager based on the MIME type specified by the
type
attribute without retrieving the resource
specified by the src
URI. If, when the dialog manager
retrieves the content, it finds the MIME type, as specified by the
HTTP
headers, differs from that specifed by the type
attribute, it SHOULD raise an
error.dialog.notprepared
event with a
reason
indicating the type mismatch. The dialog
manager MUST NOT ignore the type mismatch
or render the resource as a different type based on the
HTTP
headers or on inspection of the document data. Refer to the W3C
guidelines for client handling of MIME types [MIME-TAG] for further
information.
<dialogprepare>
Attribute DetailsAttribute Name | Details |
---|---|
src |
Is an ECMAScript expression which returns a character string identifying the URI of the dialog document that the dialog interpreter should prepare. |
type |
An OPTIONAL ECMAScript expression which returns a character string that specifies the MIME type of the document, and as a result, determines which dialog manager environment is actually used. A MIME type of "application/xml+vxml" requests a VoiceXML interpreter instance. A MIME type of "audio/wav" requests a dialog manager that merely plays wave files. If omitted, the type attribute defaults to "application/xml+vxml". |
namelist |
An OPTIONAL
list of one or more CCXML variable names. These variable names and
their associated values will be added to the URI, specified by the
src attribute, as a query string. The complete URI,
including query string, is sent to the selected dialog
manager. |
dialogid |
An OPTIONAL
ECMAScript left-hand-side expression that will receive a dialog
identifier value for the launched dialog interpreter instance. This
identifier may be used on future invocations of
<dialogstart> or
<dialogterminate> . |
connectionid |
Is an OPTIONAL ECMAScript expression which returns the identifier of a connection. The specified connection will be associated with the dialog being prepared. |
conferenceid |
Is an ECMAScript expression which returns an identifier of a conference bridge. A connection will be allocated for the dialog being prepared. |
<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.
The connectionid
or conferenceid
attribute may be specified on the <dialogstart>
element even if a connectionid
attribute has been
specified on a previous <dialogprepare>
element
for this dialog. In this case the new value will override the value
specified on the <dialogprepare>
element and the
dialog will be associated with the newly specified
connectionid
or conferenceid
.
The CCXML session selects the appropriate dialog manager based
on the MIME type specified by the type
attribute
without retrieving the resource specified by the src
URI. If, when the dialog manager retrieves the content, it finds
the MIME type, as specified by the HTTP headers, differs from
that specifed by the type
attribute, it SHOULD raise an error.dialog.notstarted
event with a reason
indicating the type mismatch. The
dialog manager MUST NOT ignore the type
mismatch or render the resource as a different type based on the
HTTP
headers or on inspection of the document data. Refer to the W3C
guidelines for client handling of MIME types [MIME-TAG] for further
information.
<dialogstart>
Attribute DetailsAttribute Name | Details |
---|---|
connectionid |
Is an ECMAScript expression which
returns an identifier of a connection. A connection will be
allocated for the dialog being started, and this connection will be
bridged to the connection specified by connectionid .
The connectionid attribute is OPTIONAL ; if omitted, the interpreter will use the
id indicated in the current event being processed. For more
information about connections and bridges, refer to Section 10. Only one of connectionid
or conferenceid can be specified. If both are
specified an error.semantic event will be thrown. |
conferenceid |
Is an ECMAScript expression which
returns an identifier of a conference bridge. A connection will be
allocated for the dialog being started, and this connection will be
bridged to the conference specified by conferenceid .
The conferenceid attribute is OPTIONAL ; if omitted, the interpreter will use the
id indicated in the current event being processed. For more
information about connections and bridges, refer to Section 10 . Only one of connectionid
or conferenceid can be specified. If both are
specified an error.semantic event will be thrown. |
prepareddialogid |
Is an OPTIONAL ECMAScript expression which returns a
dialog identifier of a dialog previously prepared by the execution
of a <dialogprepare> element. If the specified
dialog identifier refers to an unknown dialog or a dialog that has
already been executed, by way of another
<dialogstart> element, an
error.dialogwrongstate event is thrown.
This attribute may not be specified in conjunction with the
|
src |
Is an OPTIONAL ECMAScript expression which returns a
character string identifying the URI of the dialog document that
the dialog interpreter SHOULD load and
begin executing upon startup.
This attribute may not be specified in conjunction with the
|
type |
An OPTIONAL
ECMAScript expression which returns a character string that
specifies the MIME type of the document, and as a result,
determines which dialog manager environment is actually used. A
MIME type of "application/xml+vxml" requests a VoiceXML interpreter
instance. A MIME type of "audio/wav" requests a dialog manager that
merely plays wave files. If omitted, the type attribute defaults to
"application/xml+vxml".
This attribute may not be specified in conjunction with the
|
namelist |
An OPTIONAL
list of one or more CCXML variable names. These variable names and
their associated values will be added to the URI, specified by the
src attribute, as a query string. The complete URI,
including query string, is sent to the selected dialog manager.
This attribute may not be specified in conjunction with the
|
dialogid |
An OPTIONAL
ECMAScript left-hand-side expression that will receive a dialog
identifier value for the launched dialog interpreter instance. This
identifier may be used on future invocations of
<dialogterminate> . |
duplex |
An OPTIONAL
bridging mode specification for the dialog connection. Valid values
are half or full , default is
full . This determines the type of bridge between the
connection associated with the dialog and the connection or
conference specified by the connectionid or
conferenceid attribute. For more information about
connections and bridges, refer to Section
10. |
<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 DetailsAttribute Name | Details |
---|---|
dialogid |
An ECMAScript expression which returns
a character string identifying the dialog. This dialogid was
returned in the variable identified by the dialogid
attribute of a previous <dialogstart> or
<dialogprepare> request or as the value of
dialogid in a dialog.started or
dialog.prepared event. |
immediate |
An OPTIONAL
termination style specification. Specifies whether the dialog
SHOULD be terminated immediately. Valid
values are true , for immediate termination, or
false . The default is false . |
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 null. |
conferenceid |
The identifier of the conference to
which the dialog connection is bridged (usually the
conferenceid that was specified in the
<dialogstart> ). If the dialog is bridged to a
connection the value will be null. |
dialog.exit
The dialog.exit
event is thrown when a dialog
terminates either normally or following a
<dialogterminate>
request. The fields available
in the event are:
Field Name | Details |
---|---|
name |
'dialog.exit' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to
which the dialog connection is bridged (usually the
connectionid that was specified in the
<dialogstart> ). If the dialog is bridged to a
conference the value will be null. |
conferenceid |
The identifier of the conference to
which the dialog connection is bridged (usually the
conferenceid that was specified in the
<dialogstart> ). If the dialog is bridged to a
connection the value will be null. |
namelist |
List of items that are stored on the
values sub-object. |
values.* |
Values returned from the dialog. |
dialog.disconnect
The dialog.disconnect
event is thrown when a dialog
requests it be disconnected from its current call. The dialog is
not terminated, but simply requests the CCXML application end the
call. The fields available in the event are:
Field Name | Details |
---|---|
name |
'dialog.disconnect' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to
which the dialog connection is bridged (usually the
connectionid that was specified in the
<dialogstart> ). If the dialog is bridged to a
conference the value will be null. |
conferenceid |
The identifier of the conference to
which the dialog connection is bridged (usually the
conferenceid that was specified in the
<dialogstart> ). If the dialog is bridged to a
connection the value will be null. |
namelist |
List of items that are stored on the
values sub-object. |
values.* |
Values returned from the dialog. |
dialog.transfer
The dialog.transfer
event is thrown when a dialog
requests a transfer of its current call. The fields available in
the event are:
Field Name | Details |
---|---|
name |
'dialog.transfer' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to
which the dialog connection is bridged (usually the
connectionid that was specified in the
<dialogstart> ). If the dialog is bridged to a
conference the value will be null. |
conferenceid |
The identifier of the conference to
which the dialog connection is bridged (usually the
conferenceid that was specified in the
<dialogstart> ). If the dialog is bridged to a
connection the value will be null. |
type |
A string value specifying the transfer type. |
URI |
A URI describing the destination to which this call should be transfered. The format of this information is protocol and platform specific but might consist of a telephone URI [ RFC2806 ] or a SIP URI [ RFC2543 ]. |
namelist |
List of items that are stored on the
values sub-object. |
values.* |
Dialog transfer parameters. This is
where a dialog language can specify more information about the
transfer request. For example with VoiceXML this could contain all
the attributes of the <transfer> . |
maxtime |
A string in CSS2 format that specifies the maximum amount of time the transfer should stay connected. If the amount of time is unlimited the value will be 0s. |
connecttimeout |
A string in CSS2 format that specifies the maximum amount of time to spend while attempting to connect the call. |
aai |
A string of application-to-application information to be passed to the destination party when establishing the transfer. |
dialog.terminatetransfer
The dialog.terminatetransfer
event is thrown when a
ongoing transfer must be terminated, for example due to a "hotword"
recognition. As part of handling of the
dialog.terminatetransfer
event, the CCXML Application
should terminate the outgoing call leg and return the media stream
of the original call to the dialog using the
<join>
tag. The fields available in the event
are:
Field Name | Details |
---|---|
name |
'dialog.terminatetransfer' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to
which the dialog connection is bridged (usually the
connectionid that was specified in the
<dialogstart> ). If the dialog is bridged to a
conference the value will be null. |
conferenceid |
The identifier of the conference to
which the dialog connection is bridged (usually the
conferenceid that was specified in the
<dialogstart> ). If the dialog is bridged to a
connection the value will be null. |
reason |
A string value specifying the reason the transfer needs to be returned. |
error.dialog.notstarted
The error.dialog.notstarted
event is thrown when
the processing of a <dialogstart>
element fails
because the dialog cannot be started for some reason. The fields
available in the event are:
Field Name | Details |
---|---|
name |
'error.dialog.notstarted' |
dialogid |
The ID of the dialog. |
conid |
The identifier of the connection or
conference to which the dialog connection was to have been bridged
(the conid that was specified in the
<dialogstart> ) |
reason |
A description of the reason the dialog could not be started. |
error.dialog.wrongstate
The error.dialog.wrongstate
event is thrown when a
dialog request such as <dialogterminate>
has
been received by the dialog environment but it cannot be completed
because the dialog is not in a suitable state. The fields available
in the event are:
Field Name | Details |
---|---|
name |
'error.dialog.wrongstate' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to
which the dialog connection is bridged (usually the
connectionid that was specified in the
<dialogstart> ). If the dialog is bridged to a
conference the value will be null. |
conferenceid |
The identifier of the conference to
which the dialog connection is bridged (usually the
conferenceid that was specified in the
<dialogstart> ). If the dialog is bridged to a
connection the value will be null. |
reason |
A description of the reason the dialog is in the wrong state. |
dialog.user.*
The dialog.user.*
event is thrown when a dialog
sends a user event to the CCXML session that initiated it. The
fields available in the event are:
Field Name | Details |
---|---|
name |
'dialog.user.*' |
dialogid |
The ID of the dialog. |
connectionid |
The identifier of the connection to
which the dialog connection is bridged (usually the
connectionid that was specified in the
<dialogstart> ). If the dialog is bridged to a
conference the value will be null. |
conferenceid |
The identifier of the conference to
which the dialog connection is bridged (usually the
conferenceid that was specified in the
<dialogstart> ). If the dialog is bridged to a
connection the value will be null. |
namelist |
List of items that are stored on the
values sub-object. |
values.* |
Values associated with the event. |
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. |
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. |
An instance of the Dialog class is associated with each dialog
created by <dialogstart>
and referenced in the
session.dialogs
array.
Dialog Properties | Definitions |
---|---|
id |
this property is the ECMAScript string value of the Dialog identifier, which uniquely identifies each instance of the Dialog class |
connectionid |
The identifier of the connection to
which the dialog connection is bridged (usually the
connectionid that was specified in the
<dialogstart> ). If the dialog is bridged to a
conference the value will be null. |
conferenceid |
The identifier of the conference to
which the dialog connection is bridged (usually the
conferenceid that was specified in the
<dialogstart> ). If the dialog is bridged to a
connection the value will be null. |
type |
an ECMAScript expression which returns a character string that specifies the MIME type of the document that loaded the dialog. |
src |
Is an ECMAScript expression which returns a character string identifying the URI of the dialog document. |
duplex |
Equal to "half" or "full". The type of bridge between the connection associated with the dialog and the connection or conference the dialog is connected to. |
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 EMCAScript undefined
. The values of
variables MAY be subsequently changed with
<assign>
.
Variables are declared explicitly by <var>
:
<var name="sessionid" /> <var name="currentstate" expr="'initial'" />
It is illegal to make an assignment to a variable that has not
been explicitly declared using <var>
or a
var
statement within a <script>
.
Attempting to assign to an undeclared variable causes an
error.semantic
event to be thrown. Please see Section 9.5 for a detailed description of error
events.
Variables declared without an explicit initial value MUST be initialized to the ECMAScript value
undefined
by the implementation.
Note that when an ECMAScript object, e.g. "obj
",
has been properly initialized then its properties, for instance
"obj.prop1
", can be assigned without explicit
declaration. An attempt to declare ECMAScript object properties
such as "obj.prop1
" results in an
error.semantic
event being thrown.
CCXML uses an ECMAScript scope chain (please see section 3.4.2) to allow
variables to be declared at different levels of hierarchy in an
application. For instance, a variable declared at ccxml (document)
scope can be referenced anywhere within that document, whereas a
local variable declared in a <transition>
is
only available within that element.
The implementation MUST define two
scopes - ccxml
and transition
. The
relationship between these two scopes is shown below.
Figure x: Variable Scoping
A description of the two scopes is provided in the table below.
Scope Name | Details |
---|---|
ccxml |
Variables within this scope are
declared with <var> and
<script> elements that are children of
<ccxml> . They are initialized in document order
when the document is loaded. They exist while the document is
loaded. They are visible only within that document. |
transition |
Each <transition>
element has a scope that exists while the implementation is
processing the executable content within that
<transition> , and which is visible to the
elements of that <transition> . Variables with
transition scope are declared by <var> and
<script> child elements of
<transition> . The child <var>
and <script> elements of
<transition> are initialized in document order
when the executable content is executed. |
The implementation MUST instantiate a variable within the scope of the closest containing scope element. The fully-qualified name of a variable is the name of the variable's scope object prepended with a dot to the name of the variable. The implementation MUST allow reference to variables by their fully qualified names. The implementation MUST allow reference to variables without requiring use of their fully qualified names. In the case of like-named variables declared in different scopes, the implementation MUST reference the variable in the closest containing scope, unless the fully-qualified variable name is used.
The implementation MUST resolve
variables by searching the enclosing transition
scope
first (if applicable) followed by the ccxml
scope,
unless the variable reference is qualified with a scope prefix.
If the variable includes a scope prefix, the implementation MUST resolve the variable by searching the named scope.
If a variable is declared more than once, the implementation
MUST evaluate the expr
attribute of each subsequent declaration, and assign the result to
the variable declared by the first <var>
.
Variables can be assigned new values using
<assign>
:
<assign name="currentstate" expr="'cleanup'" />
The implementation MUST evaluate the
ECMAScript expression contained in the expr
attribute
of <assign>
, and assign the results to the
variable referenced in the name
attribute.
The implementation MUST throw an
error.semantic
event if an attempt is made to make an
assignment to a variable that has not been explicitly declared
using either a <var>
, or a var
statement within a <script>
.
<var>
Attribute
DetailsAttribute Name | Details |
---|---|
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 declared. |
expr |
Indicates the new value of the variable. This is the initial value. It MUST be a valid ECMAScript expression. |
<assign>
Attribute
DetailsAttribute Name | Details |
---|---|
name |
is an ECMAScript left-hand-side expression. |
expr |
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. 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 DetailsAttribute Name |
Details |
---|---|
src |
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 expr
attributes are not present, the script element content provides the
script content. If both are present the implementation MUST throw an error.badfetch event.
Note that the value of this attribute is not an ECMAScript
expression in order to allow it to be resolved at compile-time. If
the script can not be fetched the implementation MUST throw an error.badfetch
event. |
expr |
Equivalent to src , except that
the URI is dynamically determined by evaluating the given
ECMAScript expression. The expression must be evaluated each time
the script needs to be executed. If the expression is invalid, such
as a semantic error, the implementation MUST throw an error.semantic event. If
the expression does not evaluate to a valid URI or the URI cannot
be fetched, the implementation MUST throw
an error.badfetch event. Support for this attribute is
OPTIONAL and if the implementation does
not support the expr attribute, it MUST throw an error.unsupported
event. |
charset |
The character encoding of the script
designated by src . 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. The default value is UTF-8 . |
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.
The top level variable inside the ECMAScript session is named
session
. The session scope is an independent scope
separate from the other ECMAScript variable scopes defined in a
CCXML session. Therefore, variables defined in the session scope
require explicit reference (for example, session.id
),
are not subject to the parent scope chain delegation model and 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.This section contains information on
<eventprocessor>
, <send>
,
<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 along with any
specified delay that has been requested. A CCXML programmer can
only gain access to these queued events by using
<eventprocessor>
.
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 DetailsAttribute Name | Details |
---|---|
statevariable |
is a CCXML variable name which is the
name of the <eventprocessor> 's state variable.
This variable must be defined using <var> or
<script> in the 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 DetailsAttribute Name | Details |
---|---|
state |
Indicates the current possible
state(s) of the <eventprocessor> . More than one
state name MAY be specified, separated by
white space. |
event |
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. If the pattern is delimited by the character '/', it is taken as an ECMAScript regular expression literal. |
cond |
An ECMAScript expression that
evaluates to true or false. If this attribute is present, it
MUST evaluate to true for the
<transition> to be selected. The default value
is true. |
name |
is an ECMAScript left-hand-side
expression that is 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 |
Matches |
---|---|
* |
any event name |
error.* |
error.fetch,
error.dialog.notstarted |
error.*.* |
error.dialog.wrongstate |
err* |
any event name starting with "err" |
/^.*\.dialog\..*$/ |
any event containing the substring ".dialog." |
<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. 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 DetailsAttribute Name | Details |
---|---|
target |
is an ECMAScript expression returning the target location of the event. (Required) |
targettype |
is an ECMAScript expression returning the type of the Event I/O Processor that the event should be dispatched to. The Default value is 'ccxml'. (Default == 'ccxml') |
sendid |
is an ECMAScript left-hand-side expression that is the target for the event identifier. The unique identifier for the generated event is written to the target. If not present, the event's identifier is dropped. (Optional) |
delay |
is an ECMAScript expression returning
a string in CSS2 [CSS2] format
interpreted as a time interval. The <send> tag
will return immediately, but the event not dispatched until the
delay interval elapses. Timers are useful for a wide variety of
programming tasks, and can be implemented using this attribute.
(Default == '0s') |
xmlns:[YourNameSpacePrefix] |
namespace identifying contained message format This attribute is OPTIONAL, but more than one xmlns attribute MAY be included. (Optional) |
data |
is an ECMAScript expression returning a 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. (Required) |
namelist |
A list of zero or more whitespace separated CCXML variables to be included along with the event. (Optional) |
hints |
is an OPTIONAL ECMAScript expression which returns an object containing 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 event processor. (Optional) |
<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"> <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"> <log expr="evt.jacksvar"/> <exit/> </transition> </eventhandler> </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"> <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> </eventhandler> </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"> <eventprocessor> <transition event="dialog.transfer"> <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> </eventhandler> </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.ccxml
event will be thrown.
If an attempt is made to move an event source that does not
belong to the session executing the <move>
an
error.notallowed
event will be thrown.
<move>
Attribute
DetailsAttribute Name | Details |
---|---|
source |
an ECMAScript expression which
returns a connection ID or a conference ID; The event source
associated with this identifier will be moved to the target
session. This attribute is OPTIONAL, but
can not be used in conjunction with the event
attribute. If used in conjunction with the event
attribute a error.semantic event will be thrown. |
event |
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. This
attribute is OPTIONAL, but can not be used
in conjunction with the source attribute. If used in
conjunction with the source attribute a
error.semantic event will be thrown. |
sessionid |
an ECMAScript string expression that identifies the session to which the endpoint will be added. |
<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 to which it has been
sent. If the delay has expired and the event has already been
removed from the event queue and delivered to the CCXML session
<eventprocessor>
, 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
DetailsAttribute Name | Details |
---|---|
sendid |
is an ECMAScript expression returning
the value of the event identifier 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 connection that has been
moved as specified in the source 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. |
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 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, which abstract interaction with the phone network, 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).
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>
TagAn <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>
Tag<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.
An error that occurs during the handling of an error event would result in another error event, which could lead to an infinite loop of error handling. If an error occurs during the handling of an error event, the CCXML session MUST terminate and notify the platform of the document errors.
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.
We've focused on relatively simple types of call control, and we have tried to make the call control model in CCXML sufficiently abstract so that it can be implemented using all major telephony definitions such as JAIN Call Control (JCC), ECMA CSTA, and S.100.
We've chosen an event model for connections based on JCC (JSR 021). It abstracts away many of the differences between the networks mentioned above. There may be better models than JCC, but it fits the bill for what we need at the moment: a small and easily-understood call model so we can write concrete example programs.
JCC was designed to be a cross-platform high-level event set to describe as generic a phone model as possible. The JCC call model consists of Addresses, Calls, Connections, and Providers. In the context of CCXML, we felt that the Address, Call, and Provider objects would add more complexity than value, so we omitted them as explicitly visible objects and focused on the behavior of Connections.
The CCXML call model therefore is based on the behavior of Connections. A call is received or initiated under control of a CCXML session through properties of a Connection.
In CCXML, a Connection is an object modeling a resource by which
two independent unidirectional media streams, and optionally any
associated network signaling traffic, can be controlled by a CCXML
session. This corresponds roughly to a "call leg" as the term is
used informally. <dialogstart>
implicitly
creates a Connection and bridges it to the Connection or Conference
specified as an attribute of the <dialogstart>
.
The behavior of Connections and bridges is discussed in Section
10.
Note that the JCC model is designed for endpoint devices only. Here is a fast description of the events. The descriptions and names are borrowed directly from the JavaSoft documentation.
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.
The list of valid states that a connection can be in is:
IDLE
ALERTING
PROGRESSING
CONNECTED
FAILED
DISCONNECTED
Connections begin in the IDLE
state and return to
it when all other actions have been completed. The state diagram
shows a DISCONNECTED
state with a dotted line
transition to IDLE
. These states are essentially
equivalent, IDLE/DISCONNECTED
, and the dotted line
transition occurs without the Connection emitting an event.
Platforms MAY choose to implement one or
both of these states but there is no impact to CCXML applications
as these states are transparent.
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 |
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 |
IDLE/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 |
CONNECTED |
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 |
Action | Description | Event | End State |
---|---|---|---|
connection.disconnected |
Call was disconnected by the network/remote party. |
connection.progressing |
DISCONNECTED/IDLE |
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 |
IDLE/DISCONNECTED |
<disconnect> |
The CCXML document disconnects an active call. |
connection.disconnected |
IDLE/DISCONNECTED |
Action | Description | Event | End State |
---|---|---|---|
The transition to IDLE
DISCONNECTED will occur automatically after a short period
of time, with no event emitted by the Connection, once the platform
recovers from the failure. |
DISCONNECTED/IDLE |
Action | Description | Event | End State |
---|---|---|---|
Once a Connection enters
DISCONNECTED , it transitions immediately to
IDLE without further events being generated and
without needing further action by the CCXML document. |
DISCONNECTED/IDLE |
If a platform operational error occurs, the Connection will emit
a connection.error
event, and transition to the
ERROR
state. A Connection will remain in the
ERROR
state until the error is corrected, and
MAY then spontaneously transition to
IDLE/DISCONNECTED
. It will not transition to any other
state from ERROR.
The PROGRESSING
and
ALERTING
states have reflexive transitions. This is
intended to model protocols which have additional states at these
points, and which MAY exchange messages
such as PROCEEDING
, ALERTING
,
FACILITY
, or NOTIFY
. Platforms MAY choose to implement additional states which
MAY be reflected in the
substate
property of the Connection object. Additional
messages can be implemented with <send>
.
An instance of the Connection class is associated with each telephony event source. Each instance is uniquely identified by its connection identifier. All Connection instances have a set of properties in common, shown in the following table. Properties marked optional only appear on an instance of the Connection class 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 class. |
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 connectionid is ever
specified in the creation of a bridge with a conference or another
connection via <join> , this property identifies
the connectionid of the second party in that bridge.
This property will be updated each time a <join>
is executed. |
duplexmode |
false | If connectionid is ever
specified in the creation of a bridge with a conference or another
connection via <join> , this property identifies
the duplex mode of that bridge. The value of this property is a
character string that will be equal to "half" or "full" depending
on whether the established bridge was unidirectional (for half
duplex) or bidirectional (for full duplex). This property will be
updated each time a <join> is executed. |
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[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 Conference Object. Once a Conference Object has been
created, the CCXML application can add Connection Objects (call
legs) to the Conference Object by using <join>
.
Connections can be removed by using <unjoin>
(<join>
and <unjoin>
are
described in Section 10.4). A Conference
Object can be destroyed using
<destroyconference>
. Asynchronous events will be
sent to the CCXML document upon completion of each of these
operations.
The Conference Object models a special resource that mixes audio streams. Each Conference Object has one output and multiple inputs. The output stream of a Conference Object is derived by mixing all its input streams. 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.
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 |
connections |
this property is the ECMAScript array of Connection class object references that the Conference has joined. |
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: every useful CCXML session involves their use.
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:
state
=
CONNECTED
), 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.<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.
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'">
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'">
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'">
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'">
<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
DetailsAttribute Name | Details |
---|---|
|
is an ECMAScript expression which
returns a string that is the identifier of a Connection on which an
incoming call is being signaled. The connectionid
attribute is OPTIONAL ; if omitted, the
interpreter will accept using the id indicated in the current event
being processed. |
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing information which
MAY be used by the implementing platform
or passed to the network when 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. |
An accepted incoming call will result in the generation of a
connection.connected
event.
<redirect>
When a CCXML document receives a
connection.alerting
or
connection.connected
event within an
<eventprocessor>
, the execution of a
<redirect>
within the
<transition>
block will cause the underlying
platform to signal the telephony system to send the call to a
specified destination.
<redirect>
Attribute DetailsAttribute Name | Details |
---|---|
|
is 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. The connectionid attribute is
OPTIONAL ; if omitted, the interpreter
will redirect using the id indicated in the current event being
processed |
dest |
is 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 [RFC2543] |
reason |
is an ECMAScript expression which returns a string that is the reason the call is being redirected |
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing information which
MAY be used by the implementing platform
or passed to the network when 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
DetailsAttribute Name | Details |
---|---|
|
is 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. The
connectionid attribute is OPTIONAL ; if omitted, the interpreter will reject
using the id indicated in the current event being processed. |
reason |
is an ECMAScript expression which returns a string that is the reason the call is being rejected |
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing information which
MAY be used by the implementing platform
or passed to the network when 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 DetailsAttribute Name | Details |
---|---|
dest |
is 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 [RFC2543] . |
|
is an ECMAScript left-hand-side expression that receives the identifier of the Connection on which the outgoing call is attempted. |
aai |
is an OPTIONAL 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
|
callerid |
is an OPTIONAL 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 [RFC2543] .
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 specification of
|
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing 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. |
use |
is an ECMAScript expression which
returns a string that is the identifier of the Connection to be
used for the outbound call; this attribute is mutually exclusive
with connectionid |
timeout |
is an ECMAScript expression returning
a string in CSS2 [ CSS2 ]
format interpreted as a time interval. The interval begins when
<createcall> is executed. The
<createcall> will fail if not completed by the
end of this interval. A failed <createcall> will
return the connection.failed event. |
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 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 DetailsAttribute Name | Details |
---|---|
|
is an ECMAScript left-hand-side expression that receives 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. |
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing information which
MAY be used by the implementing platform
or passed to the network when 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. |
confname |
is an OPTIONAL ECMAScript expression that returns the name
of a named conference to receive the conference identifier for. If
the named conference does not exist the platform MUST create a conference object as requested and
return the value of the conference identifier using the
conferenceid attribute. If a conference already exists
the platform MUST return the conference
identifier of the previously created conference. |
reservedtalkers |
is an OPTIONAL ECMAScript expression that returns the
number of guaranteed speaker slots the conference mixer should
reserve. If the conference mixer is unable to reserve this many
speaker slots the <createconference> MUST fail with a
error.conference.create event. |
reservedlisteners |
is an OPTIONAL ECMAScript expression that returns the
number of guaranteed listener slots the conference mixer must
reserve. If the conference mixer is unable to reserve this many
listener slots the <createconference> MUST fail with a
error.conference.create event. |
<destroyconference>
A CCXML document can attempt to destroy an existing Conference
Object using <destroyconference>
. This element
will instruct the implementation to deallocate the Conference
Object specified 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 DetailsAttribute Name | Details |
---|---|
|
is an ECMAScript expression which returns a string that is the identifier for the conference that SHOULD be destroyed. |
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing information which
MAY be used by the implementing platform
or passed to the network when 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. |
<join>
A CCXML document can attempt to create a bridge between an
existing Connection Object and/or Conference Object using
<join>
. This element will instruct the
implementation to bridge the Connection/Conference Objects
specified using the id1
and id2
attributes with the the other media options specified. The
successful execution of<join>
will result in the
generation of a conference.joined
event. If for any
reason the implementation is unable to join the Objects using the
specified options it MUST fail with a
error.conference.join
event.
<join>
Attribute
DetailsAttribute Name | Details |
---|---|
id1 |
is an ECMAScript expression which returns the identifier of a Connection or Conference. |
id2 |
is an ECMAScript expression which returns the identifier of a Connection or Conference. |
duplex |
an ECMAScript expression which returns
a character string that will be equal to "half" or "full". 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 (bidirectional) bridge. If the
attribute is not supplied, the default is a full-duplex bridge. If
duplex=half is specified, the id1
resource will be able to "hear" the id2 resource
(i.e., id2 output will be bridged to id1
input), but id2 will not "hear" id1 . If
duplex=full is specified, or the duplex
attribute is not supplied, the id1 resource will be
able to "hear" the id2 resource, and id2
will "hear" id1 . |
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing information which
MAY be used by the implementing platform
or passed to the network when 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. |
entertone |
is an OPTIONAL ECMAScript expression that is used to play a tone or custom wav file to the conference participants when another caller joins. Setting this to 'true' will play the default system beep, while setting it to 'false' will result in no alerting sound being played at all. The developer may also specify a URL value that points to a user-defined wav file to be played instead of the default system beep. (Default=true) |
exittone |
is an OPTIONAL ECMAScript expression that is used to play a tone or custom wav file to the conference participants when another caller exits. Setting this to 'true' will play the default system beep, while setting it to 'false' will result in no alerting sound being played at all. The developer may also specify a URL value that points to a user-defined wav file to be played instead of the default system beep. (Default=true) |
autoinputgain |
is an OPTIONAL ECMAScript boolean expression that tells the conference mixer if it should use AGC to determine input gain for leg. If a platform does not support AGC it should ignore this attribute. (Default=true) |
autooutputgain |
is an OPTIONAL ECMAScript boolean expression that tells the conference mixer if it should use AGC to determine output gain for leg. If a platform does not support AGC it should ignore this attribute. (Default=true) |
dtmfclamp |
is an OPTIONAL 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. (Default=true) |
toneclamp |
is an OPTIONAL 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. (Default=true) |
<unjoin>
A CCXML document can attempt to tear down a bridge between an
existing Connection Object and/or Conference Object using
<unjoin>
. This element will instruct the
implementation to tear down the Connection/Conference Objects
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 unjoin the
Objects using the specified options it MUST fail with a
error.conference.unjoin
event.
<unjoin>
Attribute
DetailsAttribute Name | Details |
---|---|
id1 |
is an ECMAScript expression which returns the identifier of a Connection or Conference. |
id2 |
is an ECMAScript expression which
returns the identifier of a Connection or Conference. All media
streams between the two specified Connections or Conferences (
id1 and id2 ) will be torn down. |
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing information which
MAY be used by the implementing platform
or passed to the network when 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. |
<disconnect>
A CCXML document MAY disconnect a call
leg on a Connection by using <disconnect>
. The
underlying platform will sent the appropriate protocol messages to
perform the disconnect, and send an asynchronous event to the CCXML
document when the disconnect operation completes.
A CCXML document MAY also disconnect a
dialog using <disconnect>
. When a dialog is
identified in <disconnect>
, the dialog is
notified of the disconnect occurrence. The dialog manager
MUST always accept a disconnect
notification, and does not provide a response.
<disconnect>
Attribute DetailsAttribute Name | Details |
---|---|
|
is an ECMAScript expression which
returns a connection identifier that is the id of the call leg that
SHOULD be disconnected. The
connectionid attribute is OPTIONAL ; if omitted, no connection operation will
be performed. |
|
is an ECMAScript expression which
returns a dialog identifier that is the id of the dialog that
SHOULD be sent a disconnect notification.
The dialogid attribute is OPTIONAL ; if omitted, no dialog disconnect
notification will be sent. |
reason |
is an OPTIONAL ECMAScript expression which returns a string that is the reason the call is being disconnected |
hints |
is an OPTIONAL ECMAScript
expression which returns an object containing information which
MAY be used by the implementing platform
or passed to the network when 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 disconnected call will result in the generation of a
connection.disconnected
event. A
<disconnect>
MUST
specify a connectionid
attribute, a
dialogid
attribute, or both.
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.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 |
connection.error
This event is emitted when a Connection transitions to the
ERROR
state.
The fields of this event are:
Field Name | Details |
---|---|
name |
" connection.error
" |
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 |
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 conference has been destroyed using
<destroyconference>
. 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>
. 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. |
Caller calls an 800 number and after some interaction with an IVR system places and 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 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 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 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 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" 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/> <assign name="application.pin" expr="pin" /> <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://acme.com/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://acme.com/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 confrenceid="conf_id" src="'leave.vxml'" /> <assign name="currentstate" expr="'fetching'" /> <fetch next="'http://acme.com/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"> <form> <field id="answer"> <grammar src="yesnogrammar" /> <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.
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.
One of the main areas that need to be dealt with is the VoiceXML 2.0 application receiving random events. At this point until there are extensions to VoiceXML to allow this it is assumed there is only a limited number of events that can be sent from the CCXML application to the VoiceXML application.
<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. The VoiceXML dialog environment
MUST NOT execute any part of the fetched
document and MUST NOT initiate the Form
Interpretation Algorithm (FIA).
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. 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 <send>
of the
"connection.disconnect.hangup"
event to the VoiceXML
application.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"> <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" > <send data="connection.disconnect.hangup" target="dialogid" targettype="'dialog'"/> </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.vxml.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.vxml.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.vxml.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.vxml.transfer.complete
event to the
VoiceXML dialog with the failure reason.dialog.terminatetransfer
The VoiceXML interpreter is responsible for throwing this event when a "hotword" grammar is matched while performing a bridged transfer.
dialog.vxml.transfer.complete
This event is sent from the CCXML application to the VoiceXML platform which uses this to fill transfer field item.
The fields of this event are:
Field Name | Details |
---|---|
results.* |
The data that SHOULD be filled in on the VoiceXML field item. |
For a complete source code example of how to support transfer please see the section below titled VoiceXML 2.0 Example.
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 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"> <!-- 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"> <send data="connection.disconnect.hangup" target="dialogid" targettype="'dialog'"/> </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"> <send data="connection.disconnect.hangup" target="dialogid" targettype="'dialog'"/> <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 values 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.vxml.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 != null"> <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 != null"> <cancel sendid="maxtime_sendid"/> <assign name="maxtime_sendid" expr="null"/> </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.vxml.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'" /> <send data="connection.disconnect.hangup" target="dialogid" targettype="'dialog'"/> </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 != null"> <cancel sendid="maxtime_sendid"/> <assign name="maxtime_sendid" expr="null"/> </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.vxml.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"> <send data="connection.disconnect.hangup" target="dialogid" targettype="'dialog'"/> <!-- 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="null"/> <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 /> <send data="connection.disconnect.hangup" target="dialogid" targettype="'dialog'"/> </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.vxml.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 [ RFC2543 ]. |
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 CCXML 1.0 as 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.