Passing variables to and from VoiceXML

So now you know all about how to pass in parameters to your brand new CCXML 1.0 W3C application. Now we'll show you how to take those variables, and send them to VoiceXML via dialog, and how to send them back to CCXML once you're done. First let's reitterate what we already know (and we'll keep it simple):

Passing in parameters...

The token string:

http://api.voxeo.net/SessionControl/CCXML10.start?tokenid=abc123&foo=123&bar=456

The CCXML application:

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

<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml">



<meta name="author" content="Jeff Menkel"/>

<meta name="copyright" content="2008 Voxeo Corporation"/>

<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>



<var name="foo" expr="session.values.foo"/>

<var name="bar" expr="session.values.var"/>



  <eventprocessor>



    <transition event="ccxml.loaded">

     <log expr="'*** token initiated ***'"/>

     <log expr="'FOO = ' + foo"/>

     <log expr="'BAR = ' + bar"/>

     <exit/>

    </transition>



  </eventprocessor>

</ccxml>

This, of course, allows us to use the session.values session variable to reference the parameters we pass in via token string. But what if we want to do more than just pass in parameters? What if we want to send them to another document afterwards? Well, we can do that, too!

Passing variables to VoiceXML

Now, we can take the variables we've assigned, and pass them to a VoiceXML dialog by utilizing the namelist attribute of the <dialogstart> element. You can pass as many as you wish, separating each with a single space:



<ccxml version="1.0">



<meta name="author" content="Jeff Menkel"/>

<meta name="copyright" content="2008 Voxeo Corporation"/>

<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>



<var name="Larry" expr="'1'"/>

<var name="Curly" expr="'2'"/>

<var name="Moe" expr="'3'"/>



  <eventprocessor>



    <transition event="connection.alerting">

      <log expr="'**** ACCEPTING CALL ****'"/>

      <accept/>

    </transition>



    <transition event="connection.connected">

      <log expr="'***** CALL WAS ANSWERED *****'"/>

      <dialogstart src="'threeStooges.xml'" type="'application/voicexml+xml'" namelist="Larry Curly Moe"/>

    </transition>



    <transition event="error.dialog.notstarted">

        <log expr="'**** DIALOG FAILED TO START ****'"/>

        <exit/>

    </transition>



    <transition event="dialog.exit">

      <log expr="'***** CALL EXITING *****'"/>

      <exit/>

    </transition>



  </eventprocessor>

</ccxml>

These namelist variables are then stored within the session.connection.ccxml read-only session variable. Per the W3C CCXML Specification, this session variable has the following sub-properties:

session.connection.ccxml.sessionid - This variable evaluates to the CCXML Session ID to which the VoiceXML dialog is currently associated.
session.connection.ccxml.dialogid - This variable evaluates to the CCXML Dialog ID for the current dialog.
session.connection.ccxml.connectionid - This variable evaluates to the CCXML Connection ID to which the VoiceXML dialog is currently bridged. This variable is undefined if the dialog is not bridged to a connection.
session.connection.ccxml.conferenceid - This variable evaluates to the CCXML Conference ID to which the VoiceXML dialog is currently bridged. This variable is undefined if the dialog is not bridged to a conference.
session.connection.ccxml.values - This associative array contains the names and values of the parameters attribute supplied in a CCXML <dialogprepare> or <dialogstart> invocation.

In this case, we're interested in the last one on the list: session.connection.ccxml.values. Going back to our previous example, we pass the namelist variables and can use this session variable to reference these in our VoiceXML dialog.

session.connection.ccxml.values.Larry
session.connection.ccxml.values.Curly
session.connection.ccxml.values.Moe



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

<vxml version="2.1">

<form id="MainMenu">

 <var name="myVar1" expr="session.connection.ccxml.values.Larry"/>

 <var name="myVar2" expr="session.connection.ccxml.values.Curly"/>

 <var name="myVar3" expr="session.connection.ccxml.values.Moe"/>

  <block>

    <prompt>

      The three stooges were named <value expr="myVar1"/>, <value expr="myVar2"/>, and <value expr="myVar3"/>.

    </prompt>

  </block>

</form>

</vxml>

Passing variables back to CCXML

We've seen how to pass variables via the <dialogstart> namelist, but now that we're done with our dialog, how do we continue to use these values in CCXML? Here's how:



<exit namelist="myVar1 myVar2 myVar3"/>

...and here's how it will look inside a complete VoiceXML document:



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

<vxml version="2.1">

<form id="MainMenu">

 <var name="myVar1" expr="session.connection.ccxml.values.Larry"/>

 <var name="myVar2" expr="session.connection.ccxml.values.Curly"/>

 <var name="myVar3" expr="session.connection.ccxml.values.Moe"/>

  <block>

    <prompt>

      The three stooges were named <value expr="myVar1"/>, <value expr="myVar2"/>, and <value expr="myVar3"/>.

    </prompt>

    <exit namelist="myVar1 myVar2 myVar3"/>

  </block>

</form>

</vxml>

Once we perform our exit, which has it's own namelist array, we transition control back to our CCXML document. Assuming the dialog executed normally, once completed it will kick back to the dialog.exit transition, where we can reference (and assign) our VoiceXML session variables.

To minimize confusion, let's reuse our previous CCXML application example, but modify it a bit:



<ccxml version="1.0">



<var name="Larry" expr="'1'"/>

<var name="Curly" expr="'2'"/>

<var name="Moe" expr="'3'"/>



  <eventprocessor>



    <transition event="connection.alerting">

      <log expr="'**** ACCEPTING CALL ****'"/>

      <accept/>

    </transition>



    <transition event="connection.connected">

      <log expr="'***** CALL WAS ANSWERED *****'"/>

      <dialogstart src="'threeStooges.xml'" type="'application/voicexml+xml'" namelist="Larry Curly Moe"/>

    </transition>



    <transition event="error.*">

        <log expr="'**** ERROR! ****'"/>

        <exit/>

    </transition>



    <transition event="dialog.exit">

       <log expr="'*** DIALOG EXITED ***'"/>

       <!-- return values from VoiceXML -->

       <log expr="'Return value 1 = ' + event$.values.myVar1"/>

       <log expr="'Return value 2 = ' + event$.values.myVar2"/>

       <log expr="'Return value 3 = ' + event$.values.myVar3"/>

       <!-- we can now exit knowing what our return values are -->

       <exit/>

    </transition>



  </eventprocessor>

</ccxml>

Need some downloadable code?

Your mission, should you choose to accept it, is to download the code and recreate these scenarios on your own. This tutorial will self-destruct in five seconds...

So hurry and download the source code now!

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

H: Passing in Application Parameters

| TOC

| I: CCXML 1.0 Objects