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:

How to use a datasource to create a dynamic grammar
Basic query techniques that pull the resultant values from a database
How to output those values 'on-the-fly' into our grammar structure

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:

two thousand one
doctor strangelove
the killing
lolita
full metal jacket
eyes wide shut
paths of glory
barry lydon
day of the fight
clockwork orange
the shining

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!

Source code

What we learned:

How to create and map a datasource in CF Administrator
How to construct a CFQUERY to select the records from our datasource
How to output our query results to a dynamic grammar template
Stanley Kubrick is a God among filmmakers
Comparatively speaking, Michael Bay is a soulless hack, who really should be ashamed of himself

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

messer

9/2/2008 7:58 PM (EDT)

Hi,

Could the example above be done using a flat file instead of a DB?

Mark

voxeoJohn

9/2/2008 9:24 PM (EDT)

Hi Mark,

You could certainly make use of some [b]grep[/b]to pull out required fields from a flat file, that would be just one possible way of accomplishing this on the serverside. However, without some more specific examples of what you are trying to accomplish here; accurately coming up with a solutions would be slightly difficult. =]

I saw that you opened up a support ticket on this very issue. If privacy and/or confidentiality is a concern please post back to that ticket with a more detailed description of what you are trying to accomplish, if not you can certainly post here to share with the 'class'. Once we have received that and we will certainly be more then happy to assist. We are always more then happy to assist all of our developers!

Regards,

John
Customer Engineer

a888333

2/13/2009 2:46 AM (EST)

Do you have any sample code that will pull data using ASP from a MS Access Database? Thanks.

VoxeoDustin

2/13/2009 9:34 AM (EST)

Hey,

Unfortunately, I do not have any samples of ASP writing to an Access database, as our ability to support the myriad of server-side offerings is somewhat limited. However, the only difference between doing this for the web and doing it with VoiceXML is that it will need to output valid VoiceXML instead of HTML. I've linked below a basic intro to combining server-side and VoiceXML, and if you need any examples of ASP and MS Access, a Google search should net plenty of options.

http://www.vxml.org/qs_vars.htm

Let me know if we can be of further assistance.

Cheers,
Dustin Hayre
Customer Support Engineer 2
Voxeo Support

Passing Querystring Variables using ASP/JSP/PHP/CF

| TOC

Event Logging