VoiceXML 2.1 Development Guide Home  |  Frameset Home
  Passing Querystring Variables using ASP/JSP/PHP/CF  |  TOC  |  tutorial Event Logging  

Tutorial: ColdFusion Dynamic Grammars

ThisTutorial describes how to create a simple grammar whose utterances and return values are pulled from a database using the ColdFusion server side language. In order for this code to properly execute, you must have ColdFusion Server running on a publicly available webhost, and ensure that a simple Microsoft Access database structure is supported on the host. Again, the voxeo free webhosting does not support the ColdFusion markup, so you will need to find a webhost that does.


In this lesson, we will learn:


Step 1: Our Starting Point

Since we have all gone through the previous tutorials, we now know how to create a simple voice dialog by use of the <field> and <grammar> elements. Lets examine our 'traditional' code structure, and then decide how using a server side backend for our grammar can improve things:
 

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

<meta name="maintainer" content="yourEmail@somewhere.com"/>
     
  <form id="Stan">

    <field name="Kubrick">
      <grammar src="dynamic.cfm#KUBRICK" type="text/gsl"/>
         
      <prompt>
        What is your favorite Stanley Kubrick movie?
      </prompt>

    <filled namelist="Kubrick">

      <if cond="Kubrick == 'two thousand one'">
        <prompt>
          Open the pod bay doors hal.
        </prompt>

      <elseif cond="Kubrick == 'clockwork orange'"/>
        <prompt>
          Viddy well, little droogies.
        </prompt>

      <elseif cond="Kubrick == 'doctor strangelove'"/>
        <prompt>
          Precious. Bodily. Fluids!
        </prompt>

      <elseif cond="Kubrick == 'the killing'"/>
        <prompt>
          Put the money in the bag!
        </prompt>

      <elseif cond="Kubrick == 'lolita'"/>
        <prompt>
          Humbert Humbert is thinking bad thoughts.
        </prompt>

      <elseif cond="Kubrick == 'barry lydon'"/>
        <prompt>
          Pistol duelling is best left to those who can hit what they aim at.
        </prompt>

      <elseif cond="Kubrick == 'day of the fight'"/>
        <prompt>
          Put up your dukes.
        </prompt>

      <elseif cond="Kubrick == 'the shining'"/>
        <prompt>
          Danny's not here missus Torrance!
        </prompt>
      <else/>
      </if>
    </filled> 
  </field>
</form>
</vxml>


The above code allows the caller to state his or her favorite Stanley Kubrick movie, but from looks of it, it isn't going to be easily manageable if we decide to add more choices to our grammar. After all, we are ignoring a significant portion of Stan the Man's body of work. But lets go even further out on a limb and say that we are really lazy, and might not want to make all these modifications at once? Or maybe we will decide that we want to remove previous entries? Ladies and Germs, that's where we will want to use some server side programming to lighten the load. Wouldn't it be easier if all we had to do was to add a single entry into a database, and the grammar utterance and resultant return value would be added into the code for us? You bet it would! And for this, we are going to need a bolshy rookerful of ColdFusion to help us out.


Step 2: Creating our Datasource

The first thing that we will need to do is to open MS Access and create a new database. For purposes of simplicity, let's name it 'dynamic.mdb'.  We will then create a structure with a single column named 'Title'. We will add the following entries under our 'Title' column, being certain that our entries are all in lower-case:


Still with us, droogies? Let's save our database, and name it 'KubrickTable' and be done with it. Primary Key? We don't need no grazhny Primary Key, although you can define one if you like. Now, all we need to do is to make sure that the .mdb file is uploaded to the same directory on the CF server where our VoiceXML code will reside.


Step 3: Configuring our Datasource in CF Administrator

The next thing we will need to do is to make sure that the CF server knows that we have a new database, so we will need to log into the CF Administrator. After doing so, we will choose 'ODBC Datasources', then 'Add' a datasource of Microsoft Access(mdb) type. The next step in line is to enter the information about the datasource name, (which we will also name 'Kubrick'), and then we can specify the database location. Click the 'browse' button, and hunt through the directory structure until you find the 'dynamic.mdb' file. Once you have this nailed down, click the 'Update' button, and then the 'Verify' button to ensure that everything is real horrorshow with our datasource.


Step 4: Authoring our Dynamic Grammar Template

Now that we have the 'guts' of our dynamic grammar completed, we will now write the necessary query that will grab the info from the database, and fill out the grammar when the page is accessed. Let's open a new text file, and call it 'dynamic.cfm' Up until now, our traditional grammar structure would look like this:


KUBRICK [
[two thousand one]    {<KubrickMovie  "two thousand one">}
]


But, we need to fill the values in dynamically, so we won't be adding any explicit grammar utterances or returns. Instead, we will create a 'hollow' grammar structure, and put a CFQUERY at the top to gather the values from our database:


<CFQUERY NAME="q1" DATASOURCE="Kubrick">
SELECT * FROM KubrickTable
</CFQUERY>

KUBRICK [
<CFOUTPUT query="q1">

(#Title#) {<KubrickMovie  "#Title#">}
</CFOUTPUT>  ]


What the heck is all this crazy nonsense? Lets break it down into bite size, portions that us ColdFusion novices can readily understand:

<CFQUERY NAME="q1" DATASOURCE="Kubrick">
designates the queryname  and the datasource used
SELECT * FROM KubrickTable
essentially states 'select all entries from our database'
</CFQUERY>
end query statement

KUBRICK [
our standard, plain-jane Rulename that the VoiceXML file references
<CFOUTPUT query="q1">
outputs our database records to the CF variables named 'Title'


(#Title#) {<KubrickMovie  "#Title#">}
surrounded by parenthesis, is the utterance values that will be output by the DB lookup
'KubrickMovie' is our field/grammar slotname, and within the double quotes, the grammar return value which is again populated by the DB lookup
</CFOUTPUT>  ]
end the CFOUTPUT QUERY, and end the grammar construct with a ']'


That's all there is to it. The few lines of code that we have written for our dynamic grammar file will handle outputting our humble, 11-entry grammar, and it can output the same grammar file even if we have 100 entries. With this bite-sized chunk of code, all that we need to do is to add entries into our database, and the .cfm code will create the grammar syntax around our entries. Dont believe me? Try bringing up your 'dynamic.cfm' file up in a web browser.  You should see:

KUBRICK[
(two thousand one) {<KubrickMovie  "two thousand one">}
(doctor strangelove) {<KubrickMovie  "doctor strangelove">}
(the killing) {<KubrickMovie  "the killing">}
(lolita) {<KubrickMovie  "lolita">}
(full metal jacket) {<KubrickMovie  "full metal jacket">}
(eyes wide shut) {<KubrickMovie  "eyes wide shut">}
(paths of glory) {<KubrickMovie  "paths of glory">}
(barry lydon) {<KubrickMovie  "barry lydon">}
(day of the fight) {<KubrickMovie  "day of the fight">}
(clockwork orange) {<KubrickMovie  "clockwork orange">}
(the shining) {<KubrickMovie  "the shining">}
]




Step 5: Uploading our code, and Beyond the Infinite

We can add or remove entries in our database, and the change to the grammar file will be evident immediately upon a browser refresh. Let's save our Voicexml file as 'Hal.vxml', and upload it into the same directory as our dynamic grammar file and our MS Access database. All that remains is for you to call the application, and revel in your own superior server side knowledge. Red Rum!

Download the Code!

  Motorola source code

What we learned:




  ANNOTATIONS: EXISTING POSTS
draftbeer80
12/21/2006 5:38 AM (EST)
Hi!

The explanation was vivid and clear even to a dummy like me!  Hehhe.  But I hope you could tell me if it is possible to create a dynamic grxml grammar using mysql?  I noticed that you used <cfquery> tag to send a query to coldfusion.  I was kind of wondering if there is a way to do something similar to mysql.  Is that an equivalent tag for that matter?  If none, then, can I include php script in my grxml grammar?  If it helps, I am using voxeo prophecy 7.0 platform and I am trying to create an external grxml grammar.

Thanks a bunch!
Chris ;-D
jbassett
12/21/2006 7:47 AM (EST)
Hello.

You should be able to do something like that. There is a forum thread on this where a user gives us an example of what he was trying here.

http://evolution.voxeo.com/forums/home.jsp?xt=1166705083935&bb-cid=10&bb-tid=147689&bb-name=masterforum#forum

He did not get back with us as to whether he got his specific code working, but this will give you an idea using PHP and MYSQL.

Thanks
Jesse Bassett
Voxeo Support
draftbeer80
12/21/2006 10:04 PM (EST)
Thank you very much jesse for your reply and thanks for pointing me to the forums.  Hehhehe.  I found out just now that there's a forum. 

Thanks again
Chris ;-D

login

  Passing Querystring Variables using ASP/JSP/PHP/CF  |  TOC  |  tutorial Event Logging  
© 2003-2008 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site