Introduction to CCXML, Part IIIn case you missed it, you can still read the previous section of this article: Introduction to CCXML, Part I.
In Part II of the Introduction to CCXML, we will become more familiar with the elements of the language and how they work together to create call control applications.
CCXML Test Platform
Note: CCXML is still in a draft stage. The specification will change. Also, the CCXML examples that you'll see in this series are tuned for Voxeo and may not work with another provider's implementation even though it conforms to the specification.
Basic CCXML elements
The root element, <ccxml>
Each CCXML application has a <ccxml> root element that encapsulates the rest of the CCXML tags. It has one attribute, version, which is required and whose value should be 1.0:
ex. <ccxml version="1.0">
Exiting a CCXML application with <exit>
By calling the <exit> element, the CCXML application stops executing, discards all pending events and throws a ccxml.exit event. If the CCXML application was started by another CCXML application via the <createccxml> element, then the calling application can catch this exit event, the return value of the expr attribute and the values of the namelist attribute.
ex. <exit expr="0" namelist="state0"/>
Spawing a new CCXML application with <createccxml>
The <createccxml> element contains only one attribute, src, which specifies the URL of the CCXML application to execute. Because CCXML interpreters are non-blocking, both CCXML applications will continue to execute at the same time. The called CCXML application can return values with the <exit> element described above.
ex. <createccxml src="notification.ccxml/>
Queuing a CCXML application with <fetch>
In a multi-document CCXML application where callers may be transitioned from one CCXML document to another, it's a good idea.
ex. <fetch next="conference.ccxml"/>
Once a CCXML document has been loaded, it will throw a ccxml.fetch.done event, which can be caught with a <transition> element. The <fetch> element is usually used in conjunction with the <goto> element, which transitions a user to another CCXML application.
When an event is triggered, the CCXML interpreter examines the <transition> handlers to see if there is a matching trigger for the event. The <eventhandler> element contains one or more <transition> elements. The element can contain two optional attributes:
- id - the name of the eventhandler
- statevariable - each <eventhandler> can be assigned a state variable that tracks the current state of a call. State variables will be covered later in the CCXML series.
ex. <eventhandler id="default" statevariable="state0">
It is unclear which events must be handled, so I would recommend creating <transition> handlers for all event triggers listed in Part I.
Each <transition> element contains the code that will be executed if the event attribute matches the current event that is being processed. For example, the following transition element will match the connection.CONNECTION_ALERTING event when a caller dials up the CCXML application. From the caller's perspective, this state is when the phone is ringing and waiting to be answered:
ex. <transition event="connection.CONNECTION_ALERTING" name="evt">
The <transition> element contains the following attributes:
- state - optional; used when you want to control which event handler is triggered based on the current state in addition to the event.
- event - required; one of the events defined in the list in Part I of the CCXML tutorial.
- cond - optional; contains an ECMAScript expression that must evaluate as true for the handler to be executed.
- name - optional; defines a local variable name that can be referred to within the <transition> element to access and set attributes of the call object.
The state, event, and cond attributes all define the criteria that must be matched for the <transition> element to be executed. This provides programmers with the ability to create fine grained handlers based upon state variable, call states and call conditions.
The <transition> elements will contain the majority of the call control code. Below is a list of CCXML elements that can be included within a <transition> element:
- <accept> - answers a call
- <createcall> - places an outbound call
- <join> - conferences two call legs
- <unjoin> - disconnects a two leg conference
- <createconference> - joins multiple call legs together
- <destroyconference> - breaks down a conference call
- <dialogstart> - executes a VoiceXML dialog
- <dialogterminate> - terminates the execution of a VoiceXML dialog
- <send> - triggers a defined event
- <disconnect> - ends the call
- <assign> - assigns a specified values to a CCXML variable
- <var> - defines a new CCXML variable
- <if> - conditional statement similar to VoiceXML
- <fetch> - pre-fetches a CCXML application and queues it for execution
- <goto> - transitions the call to another CCXML application
- <submit> - submits CCXML variables to another CCXML application
- <exit> - stops the CCXML application
These elements will be covered in detail later.