VoiceXML 2.1 Development Guide

<data> element

The <data> element is a new addition to the VoiceXML2.1 specification that allows the developer to fetch content from an XML source without having to use any server side logic, and without having to transition to a new dialog. The XML data fetched by the <data> element is bound to ECMAScript through the named variable that exposes a read-only subset of the W3C Document Object Model (DOM).

The <data> element shares the same scoping rules as the <var> element. If a <data> element has the same 'name' value as a pre-declared variable in the same scope, the variable is assigned a reference to the DOM exposed by the <data> element.

Be aware that there is a platform limitation regarding the maximum amount of text data that can be fetched using this element, which equates to 200 kilobytes; any file that exceeds this limit will throw an error.semantic event.

Also be aware that the access-control allow element for the fetched content is entirely optional; content that does not have this element specified can still be retrieved on the Voxeo platform.

Also note that if the XML data source itself is not well-formed content, then a fatal error.semantic event will be thrown to the application.

usage

attributes

enctype	Data Type: CDATA	Default: Optional
	The enctype attribute specifies the MIME type encoding for any data submitted via the namelist attribute. The possible vales for this attribute are ‘x-www-form-urlencoded’, (default), or ‘multipart/form-data’, (for binary data submissions, such as recorded audio).
fetchaudio	Data Type: CDATA	Default: Optional
	The fetchaudio attribute specifies the URI of the .wav file to play to the caller in the event of an extended document fetch. Essentially, while the fetch is being made, it allows the developer to play some filler music to the caller rather than presenting only silence.
fetchhint	Data Type: (prefetch\|safe)	Default: safe
	Fetchhint is used to specify when the resource should be fetched during application execution. The possible values and their descriptions are: prefetch : Begin the resource fetch upon initial document execution safe: Only fetch the resource when it is specifically called in the application Note that the Voxeo platform will always not prefetch content by default. As such, a developer should specify a value of ''prefetch" if resources are to be made available prior to execution of application content.
fetchtimeout	Data Type: CDATA	Default: 5s
	The ‘fetchtimeout’ attribute is used to indicate how long, (in seconds or milliseconds), the interpreter should attempt to fetch the content before throwing an error.badfetch exception. See Appendix C for further information.
maxage	Data Type: CDATA	Default: Optional
	The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable age, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.
maxstale	Data Type: CDATA	Default: Optional
	The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable staleness, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.
method	Data Type: (GET\|POST)	Default: Optional (GET)
	The method attribute specifies the HTTP method to use when sending the request. If unspecified, then the value of ‘GET’, (default) is assumed, unless the submission of multipart/form-data is encountered, in which case the implied method will be ‘POST’.
name	Data Type: ID	Default: Required
	The name attribute specifies the name of the ECMAScript form item variable. Each name assigned to an data element must be unique, else a fatal error.badfetch will be thrown.
namelist	Data Type: NMTOKEN	Default: Optional
	The namelist attribute specifies a space-separated list of variables to send to the URI indicated by the src or srcexpr attributes. Note that if the namelist attribute is left unspecified, then no variables will be submitted to the destination URI.
src	Data Type: string - URI	Default: Required
	The src attribute specifies the URI where the external XML <data> content is located. Note that either 'src' or 'srcexpr' may be specified, but not both.
srcexpr	Data Type: CDATA	Default: Optional
	The srcexpr attribute evaluates to an ECMAScript value that defines the target URI. Either srcexpr or src may be specified for the element, but not both.

shadow variables

none

parents

children

none

code samples

<data-name-src> sample

<?xml version="1.0" ?>

<vxml version = "2.1">

<meta name="author" content="Matthew Henry"/>
<meta name="copyright" content="2005 voxeo corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<var name="MyData"/>

<form id="F1">
<block>
<data name="MyData" src="MyData.xml"/>
<assign name="document.MyData" expr="MyData.documentElement"/>

<goto next="#F2"/>
</block>
</form>

<form id="F2">

<script>
<![CDATA[
function GetData(d, t) {
return (d.getElementsByTagName(t).item(0).firstChild.data);
}
]]>
</script>

<block>

<prompt>
The values are <value expr="GetData(MyData, 'child1')"/>.
the next value is <value expr="GetData(MyData, 'child2')"/>.
the next value is <value expr="GetData(MyData, 'child3')"/>.
the next value is <value expr="GetData(MyData, 'child4')"/>.
the next value is <value expr="GetData(MyData, 'child5')"/>.
</prompt>

</block>
</form>
</vxml>

<MyData.xml>

<?xml version="1.0" ?>
<xml>
<parent>
<child1>value number one</child1>
<child2>value number two</child2>
<child3>value number three</child3>
<child4>value number four</child4>
<child5>value number five</child5>
</parent>
</xml>

<Data-srcexpr-namelist-method> sample

<?xml version="1.0" ?>

<vxml version = "2.1">

<meta name="author" content="Matthew Henry"/>
<meta name="copyright" content="2005 voxeo corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<var name="MyData"/>
<var name="Var1" expr="'Corey Feldman'"/>
<var name="Var2" expr="'Corey Haim'"/>
<var name="MyXMLDest" expr="'MyData.cfm'"/>

<form id="F1">
<block>
<data name="MyData" srcexpr="MyXMLDest" namelist="Var1 Var2"
method="get"/>
<assign name="document.MyData" expr="MyData.documentElement"/>
<goto next="#F2"/>
</block>
</form>

<form id="F2">

<script>
<![CDATA[
function GetData(d, t) {
return (d.getElementsByTagName(t).item(0).firstChild.data);
}
]]>
</script>

<block>
<prompt>
Heres a good joke for you.
<break strength="medium"/>
So
<value expr="GetData(MyData, 'child1')"/>
and
<value expr="GetData(MyData, 'child2')"/>
walk into a bar.
<break strength="medium"/>
Then they get eaten by Marlun Brando.
</prompt>
</block>
</form>
</vxml>

<MyData.cfm>

<?xml version="1.0" ?>

<cfheader name="Cache-Control" value= "no-cache">
<cfheader name="Expires" value="#Now()#">

<CFOUTPUT>
<xml>
<parent>
<child1>#url.Var1#</child1>
<child2>#url.Var2#</child2>
</parent>
</xml>
</CFOUTPUT>

additional links

none

ANNOTATIONS: EXISTING POSTS

awirtz

1/27/2005 6:14 PM (EST)

The W3 DOM Core Level 1 specification can be found at:
http://www.w3.org/TR/2000/WD-DOM-Level-1-20000929/

DaveMorris

1/28/2006 1:42 PM (EST)

I tried to get an application running for about 4 hours using this data tag. What finally made it work correctly was to remove the <?xml> and also the <xml> tag from the MyData.cfm template. That's bizarre, isn't it? I was getting xml parse errors until I got rid of the xml tags.

DaveMorris

2/5/2006 6:41 PM (EST)

I presume the external program referenced by <data> can return an XML with multiple items. How does one iterate through those items?

I presume it would be something like:

<for( var i = 0; i < arraysize; i++ )>
<prompt><value expr="lookupdata.getElementsByTagName('Thing').item(i).firstChild.data"/>
</for>

Does that work?

MattHenry

2/6/2006 11:26 AM (EST)

Hiya Dave,

You are close. If you want to use the <foreach> to iterate through your items, we need to put all the node values into an array first. The code you have would simply output -one- of the node values. I'll try and put together some illustrative sample code to our docs on this topic today, time permitting.

~Matt

MattHenry

2/6/2006 5:43 PM (EST)

Hiya Dave,

I cooked this sample script up for you guys today that illustrates using the <foreach> to loop through an array of values returned by a <data> call. I did change the XML file to suit this request, and I think I'll eventaully replace the sample code above with this updated example.

Let me know if you have any questions, or run into any problems.

~Matthew Henry

===MyFile.vxml===

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

<vxml version="2.1" xmlns:voxeo="http://community.voxeo.com/xmlns/vxml">

<var name="myData"/>
<var name="myArray"/>

<form id="F1">
<block>
<data name="myData" src="myData.xml"/>
<assign name="document.myData" expr="myData.documentElement"/>

<goto next="#F2"/>
</block>
</form>

<form id="F2">

<script>
<![CDATA[

// grab the values of node 'n', and append the values to an array
function assignArray(d, n, r) {

var j=(d.getElementsByTagName(r).length);
var subArray = new Array();
for(var i = 0; i < j; i++) {

subArray[i] = d.getElementsByTagName(n).item(i).firstChild.data;

}
return subArray;
}

]]>
</script>

<block>

<prompt>
<audio src="valuesAre.wav">
the returned values from the XML document are
</audio>
</prompt>

<assign name="myArray" expr="assignArray(myData, 'child', 'child')" />
<log expr="'***** myArray = ' + myArray"/>

<foreach item="nodeHolder" array="myArray">

<log expr="'~~~' + nodeHolder"/>

<prompt>
<value expr="nodeHolder"/>
<break/>
</prompt>

</foreach>

</block>
</form>

</vxml>

=== myData.xml ====

<?xml version="1.0" ?>

<xml>
<parent>
<child>value number one</child>
<child>value number two</child>
<child>value number three</child>
<child>value number four</child>
<child>value number five</child>
</parent>
</xml>

Magician

8/7/2007 10:59 AM (EDT)

I am trying to save intermediate results back to my business/data layer at each step within an involved process.

What is the "best practice" method for triggering a POST defined by <data>?

It appears from your samples (cool tricks, btw), that using <assign> will do the job without any unwanted side effects. If this is the method, I'm supposing the the value is my previously defined <data> object. Since nothing is returned, should the name be "null" or "void", of the name of the data object.

How is this magic done at Voxeo?

Magician

mikethompson

8/7/2007 4:00 PM (EDT)

Hello Magician,

I'm not sure I understand your question about best practice for triggering a POST with <data>. Are you asking at what point in your application you should submit the data? If this is the case, it's entirely up to you when you would like to do this. There's no better or worse time. I would just make sure you do it during at a time where your call flow is not disrupted too badly. I would also check this tutorial out for best practices for posting data:

http://docs.voxeo.com/voicexml/2.0/t_17mot.htm

Regarding your second question, <data> has the ability to both retrieve and send data. As such, you may not want to follow the above example provided by Mr. Henry for your POST needs. Again, the above tutorial should be very helpful to you.

Best,
Mike Thompson
Voxeo Corporation

kqian

9/28/2007 10:45 AM (EDT)

Hi:

I tried to write a simple code in the java servlet with this <data> tag, but it seems that the tag simply can not be understand. I'm currently use Genesys Framework 7.2, which should support VXML 2.1

Here is the code:
<?xml version="1.0" encoding="utf-8" ?>
<vxml xmlns="http://www.w3.org/2001/vxml" version="2.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.w3.org/2001/vxml http://www.w3.org/TR/2007/REC-voicexml21-20070619/vxml.xsd">
<script src="../Languages/en-US/PlayConstantsTTS.js" />
<script src="../Languages/en-US/PlayBuiltinTypeTTS.js" />
<script>var f = new Format(); var pb; var i;</script>
<form>
<var name="stores" expr="''" /> <block>
<data name="locations" src="DataServlet.java" />
<prompt>Testing</prompt>
</block>
</form>
</vxml>

I took out the <script> part to parse the result because it seems not able to understand the Data tag.

The error I got says: http://www.w3.org/2001/vxml|data is an invalid tag;...

Please help.

mikethompson

9/28/2007 4:00 PM (EDT)

Hello,

I am not familiar with the Genesys debugging tools, or what VXML elements their platform supports, so I am not able to offer assistance in that regard. However, have you tried running this application on our hosted environment? I can tell you with certainty, we absolutely support the use of <data>.

If you are not familiar with our platform, here is a quick start guide to help you get started:

http://evolution.voxeo.com/docs/quickStart.jsp

Best,
Mike Thompson
Voxeo Corporation

jcian

9/26/2008 3:52 PM (EDT)

Hi!

I am trying to figure out how to greet my user with a friendly "please wait while I retrieve data" message before I actually make the call to get the data, and am running into an issue. It seems that no matter what I try, the fetch always executes as soon as my application loads, and then my "please wait" message fires after the waiting has already occurred! Is there any way (short of actually requesting some voice input from the user and tacking that onto my data URL) to get the platform to read my "please wait" message first, and then do the actual fetch? Here is a sample of what I have (I tried to break things up into seperate forms hoping it would help, but it didnt):

<?xml version="1.0"?>
<vxml version="2.1">
<script src="somescript.js"/>
<form id="main_menu">
<block>
<prompt>
Please wait while I retrieve the data.
</prompt>
<goto next="#list_stuff"/>
</block>
</form>
<form id="list_stuff">
<var name="data"/>
<block>
<data name="xmlData" src="http://someserver.somedomain/somexml.xml" fetchtimeout="10s"/>
<assign name="data" expr="parseXml(xmlData)"/>
</block>

<block>
<foreach item="thing" array="data">

</foreach>
</block>
</form>
</vxml>

VoxeoDustin

9/26/2008 4:08 PM (EDT)

Hey,

You almost had it! Since VoiceXML will prefetch the data, we can leverage one or both of two options:

1) fetchaudio - this will play an audio file we specify while the document is being fetched.

<property name="fetchaudio" value="please_hold.wav"/> 
<property name="fetchaudiodelay" value="50ms"/> 
<property name="fetchaudiominimum" value="5s"/> 

2) dummy field - by requiring user input, we prevent the data in the form from being fetched until after the first field times out. We set the timeout property low so there is no delay added.

<?xml version="1.0"?>
<vxml version="2.1">
<form id="main_menu">
<field>
<property name="timeout" value="50ms"/>
<grammar type="text/gsl"> [ aergonaeggegmmfjr ] </grammar>
<prompt>
Please wait while I retrieve the data.
</prompt>
<catch event="noinput nomatch">
<goto next="#list_stuff"/>
</catch>
<filled>
<goto next="#list_stuff"/>
</filled>
</field>
</form>

<form id="list_stuff">
<var name="data"/>
<block>
<data name="xmlData" src="http://someserver.com/yourdoc.xml" fetchtimeout="10s"/>
</block>

</form>
</vxml>

Cheers,
Dustin

amarar

1/10/2009 5:59 PM (EST)

Is it possible to update an XML document's node values before sending it as an input(namelist variable) in the data tag?

voxeojeremyr

1/10/2009 9:15 PM (EST)

Hi,

Could you provide a little more detail into what you are trying to accomplish? Would you like to send the entire XML as a variable on the name list or just fetch the data using the <data> tag, modify a value then send off that value?

Standing by,
Jeremy Richmond
Voxeo Support

kunalp25

4/15/2009 11:56 AM (EDT)

I am having some issues parsing the xml content from our server.

What if the XML is formatted as such:

<?xml version="1.0" encoding="utf-8"?>
<parameters xmlns:ivr="http://xxxxxxxxxxxx" xmlns:xs="http://www.w3.org/2001/XMLSchema-instance">
<parameter name="id" value="value"/>
<parameter name="anothername" value="anothervalue"/>
<parameters>

The getElementByTag name will return a node for a parameter tag right? How would I access the name and value pairing for the nodes themselves?

Thank you.

kunalp25

4/15/2009 3:16 PM (EDT)

I feel like I should always post if I get to the answer. For the attributes inside a node use:

node.attributes.getNamedItem("the item you want").value.

node being the node item from the nodelist.

mikethompson

4/15/2009 3:33 PM (EDT)

Hello Kunal,

Thank you for posting back your findings. It is always great to see developers contributing to the annotations in our documentation!

Best,
Mike Thompson
Voxeo Corporation

MattHenry

4/15/2009 3:43 PM (EDT)

There are many ways to skin a cat as they say. Another possible solution would be to use the 'getAttribute' function, as illustrated below:

<var name="nameData"/>
<var name="idData"/>

..
<form>

<block>
<data src="....."/>

<assign name="nameData" expr="MyData.getElementsByTagName('parameter').item(0).getAttribute('name');"/>

<assign name="idData" expr="MyData.getElementsByTagName('parameter').item(0).getAttribute('id');"/>

<log expr="'nameData = ' + nameData"/>
<log expr="'idData = ' + idData"/>

<block>

</form>

Cheers,

~Matt

rbrazier

3/29/2010 1:25 PM (EDT)

Voxeo team:

Does your implementation of the <data> tag support JSON documents, or is it XML-only? If you don't have it on your roadmap, I'd consider JSON support a must-have in the future--a number of the other large IVR vendors are adding native JSON support through the <data> element.

Thanks for any help/info you can provide,
-Rob Brazier

MattHenry

3/29/2010 9:27 PM (EDT)

Hello Rob,

The Prophecy VXML browser does indeed support JSON to a limited degree (ie stringify and parse), but I'm not sure if the usage below is what you are looking for...can you confirm, and perhaps provide a use-case that illustrates the kind of functionality that you are looking for? Assuming that we have a business case, or enough developer demand that would dictate that we start working on a feature extension, we would be happy to consider it:

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1">
<form>
<field name="F_1" type="boolean">
<prompt>womp bop a loo womp, ba dop bam boom.</prompt>
<filled>
<log expr="'******* lastR = ' + JSON.stringify(application.lastresult$)"/>
</filled>
</field>
</form>
</vxml>

~Matt

learnvxml

5/3/2010 6:05 PM (EDT)

Does Voxeo's implementation of <data> support fetching XML document generated by a server-side application running on an application server? That is what I need. I tried and failed.

The documentation says:

"The <data> element is a new addition to the VoiceXML2.1 specification that allows the developer to fetch content from an XML source without having to use any server side logic, "

Here is my code snippet:

<var name="web_service" expr="'get_account'"/>
<var name="ani" expr="6307891234"/>
<data name="acct" src="http://uscgetaccount.appspot.com" namelist="web_service ani" method="GET"/>

Here is the error I got:

VoiceException: error.semantic
Malformed URL: Error parsing URL.
Context URL: http://sites.google.com/site/learnvxml/santo/
URL: http://uscgetaccount.appspot.com?ani=6307891234&web_service=account
Exception: Bad host/file position

voxeoJohn

5/3/2010 11:07 PM (EDT)

Hello,

Sure this most certainly works, however I would suggest fetching it as an E4X object, as illustrated in the following example:

---- VXML -----
<?xml version="1.0" encoding="UTF-8"?>
<vxml version="2.1">
<var name="lookupResponse" expr="new XML()"/>
<var name="lookupData"/>
<var name="currentLocalHour"/>
<var name="MyXMLDest" expr="'date.php'"/>
<form id="Form1">
<block>
<data name="lookupData" srcexpr="MyXMLDest" method="get" ecmaxmltype="e4x"/>
<var name="currentLocalHour" expr="Number(lookupResponse.hour)"/>
<log expr="'@@@@@: ' + currentLocalHour"/>
<if cond="currentLocalHour >= 9 && currentLocalHour <= 18">
<prompt> <break/> we are open, happy happy happy </prompt>
<else/>
<prompt>we are closed, sad sad sad</prompt>
</if>
</block>
</form>
</vxml>

---PHP ----

<?
header("Content-type: text/xml");
print ('<time>');
print ('<hour>');
print date(H);
print ('</hour>');
print ('</time>');
?>

Doing so allows you to use E4X notation to access relevant node data, which is much easier them DOM (at least in my personal opinion). I sincerely hope this example is helpful to you, and if there are any other questions please let us know!

Regards,

John Dyer
Customer Engineer
Voxeo Support

learnvxml

5/4/2010 5:41 AM (EDT)

Thanks John for your quick response!

First time hearing about E4X. Found the specs from ECMA, and learned about it. Makes sense to use E4X rather than DOM!

1. Why is ecmaxmltype attribute not documented in this <data> page?
2. This attribute is not a W3C standard (yet). Is it a Voxeo extension?
3. Will my code lose portability across VXML platforms by using the ecmaxmltype attribute?
4. To make your example work, should it first convert DOM to an Object using XML(), and access hour within time object (time.hour)?

<data name="lookupData" srcexpr="MyXMLDest" method="get" ecmaxmltype="e4x"/>
<assign name="lookupResponse" expr="XML(lookupData)"/>
<assign name="currentLocalHour" expr="Number(lookupResponse.time.hour)"/>

Sorry for the barrage of questions!
Appreciate your guidance.
Santhana.

voxeoJeffK

5/4/2010 6:26 AM (EDT)

Hello Santhana,

I'll put your questions in order:

1. Why is ecmaxmltype attribute not documented in this <data> page?

You point out a valid documentation omission, and we apologize. Voxeo is taking steps to increase documentation completeness.

2. This attribute is not a W3C standard (yet). Is it a Voxeo extension?

Yes, this is an extension beyond the W3C spec that was included to assist some existing customers.

3. Will my code lose portability across VXML platforms by using the ecmaxmltype attribute?

Correct, this would be the case. Since the ecmaxmltype attribute is a Voxeo specific extension there would be reduced portability of code. Voxeo always strives to maintain adherence to the spec, and in this case the extension is simply for ease of use, and not mandatory.

4. To make your example work, should it first convert DOM to an Object using XML(), and access hour within time object (time.hour)?

<data name="lookupData" srcexpr="MyXMLDest" method="get" ecmaxmltype="e4x"/>
<assign name="lookupResponse" expr="XML(lookupData)"/>
<assign name="currentLocalHour" expr="Number(lookupResponse.time.hour)"/>

E4X represents values as primitive data types (strings, integers, arrays, etc.) natively rather than objects as with the DOM. Are you experiencing any difficulties with the code as it is?

Regards,
Jeff Kustermann
Voxeo Support

learnvxml

5/4/2010 8:41 AM (EDT)

THANK YOU Jeff! You guys are GREAT in providing support.

If ecmaxmltype="e4x" attribute will not be portable, I would like to stick to DOM. I already have my DOM code written and tested in other platforms, and wondering how to make it work in Voxeo platform.

1. What is the reason that my <data> code failed in Voxeo?
2. I would like to understand the cause of failure and resolve it, instead of switching to E4X now.

Thanks again Voxeo!
Santhana

Here is my code snippet:

<var name="web_service" expr="'get_account'"/>
<var name="ani" expr="6307891234"/>
<data name="acct" src="http://uscgetaccount.appspot.com" namelist="web_service ani" method="GET"/>

Here is the error I got:

VoiceException: error.semantic
Malformed URL: Error parsing URL.
Context URL: http://sites.google.com/site/learnvxml/santo/
URL: http://uscgetaccount.appspot.com?ani=6307891234&web_service=account
Exception: Bad host/file position

voxeoJohn

5/4/2010 1:24 PM (EDT)

Hello,

Well this was a tricky one, as it deffinitly took me a minute or two to catch it, but the issue here was a missing / in the URL. Changing src="http://uscgetaccount.appspot.com" => src="http://uscgetaccount.appspot.com/" resolved the behavior in my tests. I have also attached a updated GIST that should help illustrate this furhter ( https://gist.github.com/4db932454671898c5b2c ). I do hope this is helpful, and if there are any other questions please let us know!

Regards,

John Dyer
Customer Engineer
Voxeo Support

romilly1

5/10/2010 6:51 PM (EDT)

Hi guys,

Just wondering if there's a way to make an asynchronous HTTP request to our webserver during the execution of the VXML and not have the interpreter wait for a (valid) response from the webserver, rather just continue on the execution?

It seems the <data> tag not only waits for a response (making it synchronous), but also waits for a valid response.

VoxeoDante

5/11/2010 12:56 AM (EDT)

Hello,

Any of the available options for making a HTTP call are going to be synchronous from within VXML. If you have a number of requests that you need to make, but do not want to have the application wait, you can look at writing a small proxy that will take in a short request, and respond quickly, then perform the rest of what you need it to quietly in the background.

This may or may not work depending on what your needs are, but it is an option that others have used in the past.

I hope that helps.

Regards,
Dante Vitulano