CallXML 3.0 Development Guide

<fetch> element

The new <fetch> element, in combination with CallXML 3.0's native support for xpath expression, delivers a powerful way to separate the voice user interface, (VUI), from back-end logic. When using this powerful new addition to the CallXML arsenal, you can develop a fully-realized application without needing to embed server-side markup, (such as ASP/PHP/JSP/etc), within the XML itself. Using <fetch> properly, you can retrieve a document from the url specified in the value attribute, and store the contents of the document in the variable name specified by the var attribute.

usage

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.
type	Data Type: (integer\|string\|xml)	Default: Optional
	The 'type' attribute allows the developer to specify the data type that is returned from a fetch: This can be useful where a developer needs to access an external document that is not well-formed XML to access string or integer data in the CallXML context.
value	Data Type: string - URI	Default: none - attribute is required
	The 'value' attribute of the `<fetch>` element is used to specify an .xml or .txt document that the CallXML should retrieve and execute. Used with standard XPath expressions, this allows the developer to bring the external document content to within the CallXML 3.0 context.
var	Data Type: (variable name)	Default: none - attribute is required
	The 'var' attribute defines the variable that will store the fetched document's contents within the CallXML 3.0 context. The variable name is then referenced within the other elements of the document, (such as within a 'value' attribute of a container element), to output the contents of the fetched document.

code samples

<3.0 fetch-value-var>

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

<callxml version="3.0">

<fetch value="Test.xml" var="myxml" type="xml"/>

<with value="$myxml;">
<assign var="overHyped1" expr="/var/myxml/hype[1]/text()"/>
<assign var="allHype" expr="list( /var/myxml/hype/text() )"/>

<say>
The top over hyped movie of all time is $overHyped1;
</say>

<wait value="2s"/>

<say>
The top over hyped movies of all time are $allHype;
</say>

</with>

</callxml>

<test.xml>

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

<movies>
<hype>star wars episode 1, the phantom menace</hype>
<hype>kill bill volume 2</hype>
<hype>anything by michael bay</hype>
</movies>

<3.0 fetch-submit-method>

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

<callxml version="3.0">

<do label="D_1" choices="yes, no" value="myValue">
<say>
Is there anything dumber looking than a festive sweater on a dog?
</say>
<wait value="5s"/>
<say>you can say yes, or no</say>

<on event="choice">
<assign var="myVar" value="$session.lastchoice;"/>
<fetch value="FetchTarget.cfm" submit="myVar" method="GET" var="myValue"/>
</on>

</do>
</callxml>

Implement threading CallXML

Here we will use threading in CallXML and spawn a child session which will inject events back to our parent session <parent.xml>

<?xml version="1.0" encoding="UTF-8"?>
<callxml version="3.0">
<assign var="parentSessionID" value="$session.ID;"/>
<block>
<run value="child.xml" submit="*"/>
<fetch value="http://myServer.com/delay.jsp" var="myValue"/>

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

<child.xml>

<?xml version="1.0" encoding="UTF-8"?>
<callxml version="3.0">
<wait value="10s"/>
<sendevent value="time_out" session="$parentSessionID;"/>
</callxml>

additional links

none

ANNOTATIONS: EXISTING POSTS

moshe

4/23/2007 2:25 PM (EDT)

If a fetch fails, what event(s) does it throw? I don't see anything documented here, in Appendix E, the Xpath tutorial, or the "on" element.

voxeojeff

4/23/2007 4:16 PM (EDT)

Hello Moshe,

Upon testing some of the sample code located in the CallXML 3 documentation (fetch element), I received the following errors when intentionally trying to 'break' the code:

event: error "execution" (failed to execute fetch element (Server error 404))
event: error "document" (unhandled event "event="onerror", event="", type="execution"")

The code that was tested can be located here:

http://docs.voxeo.com/callxml/3.0/fetch.htm

Regards,

Jeff Menkel
Voxeo Corporation

awirtz

6/19/2007 7:18 PM (EDT)

This example is broken. In order for Xpath to operate properly on nodes within a variable, the "fetch" tag which populated the variable must be sprinkled with the magical undocumented fairly dust of "type="xml"" I assume this magic causes the variable to be instantiated as not only a string, but also an Xpath object.

As so:
<fetch value="Test.xml" var="myxml" type="xml"/>

-Aaron

voxeojeff

6/19/2007 9:46 PM (EDT)

Hi Aaron,

Thanks for bringing this to our attention! I will run this by our documentation specialists so we can get this fixed. :-)

Cheers,

Jeff Menkel
Voxeo Corporation

hira_muzamil

3/21/2009 7:49 AM (EDT)

HI

what if we want to call a function of our application

because if i try to access it this way

<fetch value="http://licalhost/Clients/updateCallers">

it prompts an io error/server failure

voxeoJeffK

3/21/2009 8:12 AM (EDT)

Hello,

As per our discussion in Live Support chat applications running in our Hosted network can only access publicly available URLs. Running the application from your own locally installed prophecy will allow you to connect to the PHP server on your computer via Localhost.

Regards,
Jeff Kustermann
Voxeo Support