callxml elements

CallXML 3.0 Development Guide

<run> element

This element will run/start a new session, and fetches a CallXML document to use for the session from the URL or URI specified by value. The rule for <run> is that you can only run to a root level <block> in a document, even if "run"-ing to the same document:


<run value="same_doc.xml#another_block_in_this_doc"/>

The submit attribute can be used to pass copies of CallXML browser variables from the parent session with the HTTP(S)/FTP operation used to fetch the new document. The method attribute is used to select whether to use HTTP(S) GET/POST or FTP binary/ASCII.

usage

<run cache="(yes|no)" id="(element id)" method="(GET|POST|BIN|ASC)" submit="(variable name)" test="CDATA" value="URI" value-is="STRING" value-is-not="STRING" var="(variable name)">

attributes

cache	Data Type: (yes\|no)	Default: none - attribute is optional
	Allows manual override over the caching mechanism. If this attribute is empty the default system caching is used. "yes" should force the system to use the cache all the time, "no" means that no cache should be used at all.
id	Data Type: (element id)	Default: none - attribute is optional
	The new 'id' attribute in CallXML3.0 is applicable to all container and action elements. Specifying this attribute allows yet another level of control and event handling when events occur and are caught by the `<on>` element. When an event occurs, the handler will first check the event, and then verify that the handler has a handler specific to the 'id' attribute to execute. This allows the developer to plan a specific course of action for events based on where in the application that they occur.
method	Data Type: (GET\|POST\|BIN\|ASC)	Default: none - attribute is optional
	The method attribute specifies the HTTP method to use when sending the request. Allowable values for the method attribute are: "get" for HTTP GET "post" for HTTP POST "bin" for FTP binary transport "asc" for FTP ASCII transport Any other values defined for this attribute will result in a fatal error. If no method is specified, then it will always default to 'GET'.
submit	Data Type: (variable name)	Default: none - attribute is optional
	List of variables to submit to the called URL/URI can be "all" or "" for everything, or a comma delimited list of variables to submit: submit = "Variable1, Variable2, Variable3, Variable5, Variable9"* Note that you can also specify "nothing" if no variables are to be submitted. If non-existant variable names are specified a fatal error will result. Also, if "all" or "*" is specified, no other variable names should be listed with it.
test	Data Type: CDATA	Default: Optional
	The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document.
value	Data Type: URI	Default: none - attribute is required
	Either a full URL (http://MyServer.com/MyDocument.xml) or a local URI pointing to a <block> label in the same CallXML file (e.g., #main_menu). Supported URL formats include: http:// Read data https:// Read data (over a secure connection) ftp:// Read data An empty or invalid value will result in a fatal error. Invalid values are: value="[optional url]#" value="[optional url]#foo", and "foo" does not exist as a label in the document Domain names can contain port numbers and login information, for instance: value="ftp://me:door@ftp.me.com:2345/myapp/start.xml"
value-is	Data Type: STRING	Default: none - attribute is optional
	Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution.
value-is-not	Data Type: STRING	Default: none - attribute is optional
	Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution.
var	Data Type: (variable name)	Default: none - attribute is optional
	A valid variable name in which to store the new session ID.

code samples

<3.0 run value-cache-submit-method-var-test>

<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="3.0">

<assign var="parentSessionID" value="$session.ID;"/>

<do label="D_0" repeat="3">


<run value="timer.xml" submit="*" method="get"
var="timerSessionID" test="1 != 1"/>


<run value="timer.xml" submit="*" method="get"
var="timerSessionID" test="'foo' = 'bar'"/>


<run value="timer.xml" submit="*" method="get"
var="timerSessionID" test="'foo' = 'foo'"/>

<playaudio format="audio/wav"
value="groovyMusic.wav"/>

<on event="externalevent:time_out">
<prompt value="Your call has timed out"/>
<hangup/>
</on>

</do>

</callxml>

<timer.xml>

<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="3.0">

<wait value="12s"/>

<sendevent value="time_out" session="$parentSessionID;"/>

</callxml>

<3.0 FetchAudioParent.xml> - masking long fetches

<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="3.0">





<assign var="parentSessionID" value="$session.ID;"/>

<do label="D_0">
<log>*** STARTING THE PARENT SESSION ***</log>
<run value="FetchAudioChild.xml" submit="*" method="get"
var="timerSessionID" />

<playaudio format="audio/wav"
value="Spidey.wav"/>

<on event="externalevent">
<log>*** WITHIN THE PARENT AGAIN ***</log>
<log>*** LIST SLASHDOT: $session.eventvalue; ***</log>
</on>

</do>

</callxml>

additional links

none

ANNOTATIONS: EXISTING POSTS

jpw

1/23/2008 3:42 AM (EST)

when you say the run command will run/start a "new session" what does "session" mean from a practical point of view?

(a) how does the child access one of the 'parent' variables passed in via the submit= ?.

(b) if the 'child' modifies the variable, does that get passed back to the 'parent' when the child terminates. For that matter, does *anything* happen at the parent when the child terminates? Or is the only communication from the child to the parent via <sendevent>s?

Other questions:
(c) is there any way for the child to send a big wad of data, like a variable containing the xml results from a fetch, back to the parent?

mikethompson

1/23/2008 1:06 PM (EST)

Hello JPW,

The <run> session spawns an independent child session, which means the parent is unaware it exists. However, the child session can communicate with the parent by sending events and having external event handlers in the parent. Also, The child session inherits variables/values passed in submit attribute.

(a) I was able to throw a test together in a couple of minutes to verify my hunch. The answer is the variables are maintained across parent and child sessions. You can reference the variables in the child session just as if you were in the parent. Observe:

*******PARENT SESSION**********

<callxml version="3.0">

<assign var="parentSessionID" value="$session.ID;"/>
<assign var="MyVar1" value="Foooooo"/>

<do>

<run value="mychild.xml" submit="*" method="get" var="timerSessionID"/>

<playaudio value="football.wav"/>

<on event="externalevent:time_out">
<prompt value="Your call has timed out"/>
<hangup/>
</on>

</do>

</callxml>

*******CHILD SESSION*********

<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="3.0">

<log value="**************************************************************************"/>
<log value="**************************************************************************"/>
<log value="********************Let's Check Variables*****************************************"/>
<log value="**************************************************************************"/>
<log value="##################### $MyVar1;###########################################"/>

<wait value="12s"/>

<sendevent value="time_out" session="$parentSessionID;"/>

</callxml>

In the child session, I did indeed see "Foooooo" as the result for MyVar1. :)

(b) As far as passing modified variables back to the parent, we do not have a means to do this at present. It would tend to cause problems, as when returning back to the parent document, we blatantly see <assign var="MyVar1" value="Foooooo"/>, which will simply reset the value. However, if you *really* wanted to pass back variables with <run>, you will need to involve server-side scripting. For example, use PHP in your child session to store the newly modified variables in a database. Then, when your parent session gets the external event for time_out, you could access that database and pull your new values. The easier approach is just to use <goto> and modify your call flow accordingly.

(c)No, for the same reason as (b)

It is also worth noting, when doing run, if a variable of XML type is sent, it can't be used directly. You will want to do an assignment like this:

<assign var="AllPrompts_target" value="$AllPrompts;" type="xml"/>

Then use the variable AllPrompts_target as an XML variable.

Hope this helps,
Mike Thompson
Voxeo Corporation