Data Exchange

To exchange data between the VoiceXML platform and an application server, you can use the <submit>, <subdialog>, or <data> tag. The platform can interact with an application server in the same way as a web browser does using these tags. The interaction is a series of HTTP GETs or HTTP POSTs where the application server processes these requests and returns valid VoiceXML.

The way this process works is that first, the caller starts a VoiceXML dialog with the VoiceXML platform and the platform makes a HTTP request to go fetch a VoiceXML document from an application server. The application server then parses the script you have written (.php, .jsp, .asp, etc.) and dynamically generates a VoiceXML document to be sent back to the platform. The platform parses the document and interacts with the caller. How the platform interacts with the application server using the <submit>, <subdialog>, and <data> tags is explained below.

Using the Submit Tag

The <submit> tag performs a GET or POST that will trigger a page transition. This means that document level variables will be lost once the new page is fetched and parsed. To preserve some of the current execution context, the <submit> tag can send document level variables as POST or GET variables to your application server script. This application server script gets parsed by your application server, which can then process variables sent to it before generating a VoiceXML document to be parsed by the VoiceXML platform to interact with the caller.

Here is an example that demonstrates the use of the <submit> tag:

Record.vxml:

<?xml version="1.0"?>
<vxml version="2.0">
  <form>
    <record name="msg" beep="true" maxtime="10s" finalsilence="4000ms" dtmfterm="true" type="audio/x-wav">
      <prompt timeout="5s">
        Record a message after the beep.
      </prompt>
      <noinput>
        I didn't hear anything, please try again.
      </noinput>
    </record>

  <field name="confirm">
    <grammar>
      Yes|No
    </grammar>
    <prompt>
      Your message is <audio expr="msg"/>.
    </prompt>
    <prompt>
      To keep it, say yes. To discard it, say no.
    </prompt>
    <filled>
      <if cond="confirm=='Yes'">
        <submit next="http://mightyserver.com/Save.php" namelist="msg" method="post" enctype="multipart/form-data"/>
      </if>
      <clear/>
    </filled>
  </field>
  </form>
</vxml>

Save.php

<?php
echo "<?xml version=\"1.0\" encoding=\"latin-1\"?>";
?>

<!DOCTYPE vxml SYSTEM "file:/DTD2304.dtd">

<vxml version="2.0">
  <form id="greeting">
    <block>

<?php
  if (isset($_FILES['msg'])) {
    echo "<prompt bargein=\"false\">found the audio attachment</prompt>\n";
  }
  if (isset($_FILES['msg']) && is_uploaded_file($_FILES['msg']['tmp_name'])) {
    move_uploaded_file($_FILES['msg']['tmp_name'],"temp.ul");
    $timestamp = time();
    $cmdline = `/usr/local/bin/sox -t ul -r 8000 temp.ul $timestamp.wav`;
    unlink("temp.ul");
    echo "<prompt bargein=\"false\">Audio saved as <say-as
    type=\"acronym\">$timestamp</say-as> dot wave.</prompt>\n";
  } else {
    echo "<prompt bargein=\"false\">Audio not saved.</prompt>\n";
  }
?>

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

From this example, the document-level variable “msg” gets passed by Plum DEV through the <submit> tag to the .php script, Save.php, on the application server. If the voice recording is a valid file, the VoiceXML document that gets generated by the application server will inform the user by saying, “Audio saved as 1181336379 [random value for $timestamp] dot wave.”

Using the Subdialog Tag

The <subdialog> tag is similar to a function call executed by a GET or POST. It allows you to execute a new VoiceXML document in a new context, but once the <subdialog> is complete, control will be returned to the parent document at the same location that the subdialog was called. The way this process works is that the <subdialog> tag sends document level variables to your application server script. Once the application server script gets parsed by the application server and generates a VoiceXML document, this VoiceXML document becomes a “subdialog” of your original VoiceXML document. Below is a diagram that shows how multiple subdialogs can be used before returning context back to the original VoiceXML document.

Here is an example that demonstrates the use of the <subdialog> tag:

parent.vxml:

<?xml version="1.0"?>
<vxml version="2.1">
  <form>
    <subdialog name="random" src="subdialog.php"/>
    <block>
      The grass is <value expr="random.stuff1"/>.
      The sky is <value expr="random.stuff2"/>.
      The sun is <value expr="random.stuff3"/>.
    </block>
  </form>
</vxml>

subdialog.php:

<?php
header("Content-type: text/xml");
echo("<?xml version=\"1.0\"?>\n");
$random1 = "green";
$random2 = "blue";
$random3 = "yellow";
?>

<vxml version="2.0">
  <form>
    <block>
      <var name="stuff1" expr="'<?php echo($random1)?>'"/>
      <var name="stuff2" expr="'<?php echo($random2)?>'"/>
      <var name="stuff3" expr="'<?php echo($random3)?>'"/>
      <return namelist="stuff1 stuff2 stuff3"/>
    </block>
  </form>
</vxml>

From this example, parent.vxml can use the variables that are passed to it from subdialog.php. “stuff1”, “stuff2”, “stuff3” get sent back to parent.vxml with the string values of “green”, “blue”, and “yellow” attached to them respectively. Thus, Plum DEV would play the following:

The grass is green. The sky is blue. The sun is yellow.

Using the Data Tag

The <data> tag is also like a function call executed by a GET or POST. It differs from the <subdialog> tag in that it does not execute a remote VoiceXML document, but instead expects the remote application to return an XML or JSON result. The <data> tag sends document level variables to your application server script, which generates an XML or JSON file to be returned to Plum DEV. The file is then mapped directly into an ECMAScript DOM object for XML responses or just a generic ECMAScript object for JSON responses for Plum DEV to reference as a variable.

Here is an example that demonstrates the use of the <data> tag:

data.php:

<?php
header("Content-type: text/xml");
echo("<?xml version=\"1.0\"?>\n");
$random1 = "green";
$random2 = "blue";
$random3 = "yellow";
?>

<colors>
<color><?php echo($random1);?></color>
<color><?php echo($random2);?></color>
<color><?php echo($random3);?></color>
</colors>

parent.vxml:

<?xml version="1.0"?>
<vxml version="2.1">
  <form>
    <data name="thedata" src="data.php"/>
      <block>
        The grass is <value expr=
        "thedata.documentElement.childNodes.item(0).firstChild.toString()"/>.
        The sky is <value expr=
        "thedata.documentElement.childNodes.item(1).firstChild.toString()"/>.
        The sun is <value expr=
        "thedata.documentElement.childNodes.item(2).firstChild.toString()"/>.
      </block>
  </form>
</vxml>

From this example, parent.vxml can use the variables that are passed to it from data.php. (A small note on XML: You can create and name a tag anything you want, as long as the tag is closed off properly within the XML document.) Note that data.xml is similar to subdialog.php in that both files can return the strings “green”, “blue”, and “yellow” back to the VoiceXML document. Thus, the VoiceXML document would play the following:

The grass is green. The sky is blue. The sun is yellow.

Here is that same example using a JSON document:

data.php:

<?php
header("Content-type: application/json");
$random1 = "green";
$random2 = "blue";
$random3 = "yellow";
echo(json_encode(array('colors'=>array($random1, $random2, $random3))));

<code>
parent.vxml:

<?xml version="1.0"?>
<vxml version="2.1">
  <form>
    <data name="thedata" src="data.php" accept="application/json"/>
      <block>
        The grass is <value expr="thedata.colors[0]"/>
        The sky is <value expr="thedata.colors[1]"/>
        The sun is <value expr="thedata.colors[2]"/>
      </block>
  </form>
</vxml>

Submit vs. Subdialog vs. Data

Which tag to use often comes down to personal preference, coding style and the particular problem you are trying to solve. Sometimes, you might only need to collect a few inputs from your VoiceXML document and transition completely to a new page using the <submit> tag. This method helps minimize code complexity, keeps your code functionally separated, and moves the majority of the logic to the application server (perfect if you are less comfortable with VoiceXML).

Other times it is easier to code the various segments as function calls using the <subdialog> tag. This method makes code more reusable and further segments functionality. However, it can increase complexity within the VoiceXML code because you will need to create and process the return values of the <subdialog>.

Finally, sometimes you'd rather keep all call logic within the VoiceXML document and use the <data> tag. This method allows you to generate completely static VoiceXML scripts and only have the application server generate basic XML or JSON documents. This approach will create the most complex VoiceXML scripts and the simplest application server code.