There are many free hosted VoiceXML platforms out there to try out new ideas, prototype applications, etc. I use one of them on a regular basis. Unfortunately, each time I need dynamically generated grammars in my application, I’m stuck. I have to roll my own solution (typically by launching a Web server on my machine, opening a temporary port in our firewall …). Ouch!
All of this is no longer necessary, thanks to our new NuGram Hosted Server, which we launched two weeks ago at SpeechTEK. In this post, I will show how to add dynamic grammars to a standard, VoiceXML 2.1 compliant application. You won’t need to install or deploy any Web server technology. All you’ll need is:
- Eclipse 3.2 or higher with NuGram IDE installed;
- an account on grammarserver.com;
- an account on Evolution Developer Portal to deploy and test the VoiceXML application. (You can use any VoiceXML 2.1 platform, of course, but the example uses some non-standard objects exposed in ECMAScript by the Evolution VoiceXML interpreter.)
The sample application
I will illustrate the whole process of adding dynamic grammars to a VoiceXML application by developing a very simple-minded voice-activated auto-attendant-like application. The application will simply ask for a name and tell you the associated extension number.
Step 1 – Edit your grammar
You first need to create a new file in NuGram IDE to edit the grammar. We’ll call it name.abnf. (The actual name and location of the file in your workspace doesn’t really matter as we will be able to choose a different name when publishing it on the grammar server.) The file should have the following content:
#ABNF 1.0 ISO-8859-1;
language en-US;
tag-format <semantics/1.0>;
root $name;
public $name =
[$pre_filler] $directoryEntry [$post_filler]
{out.extension = rules.directoryEntry.extension;}
;
$directoryEntry =
@alt
@for (entry : entries)
( [ @word employee.firstname ]
@word employee.lastname
@tag "out.extension = '" entry.extension "';" @end
)
@end
@end
;
$post_filler = please;
$pre_filler = I would like to speak with | can I talk to;
As you can see, this is mainly ABNF with some extensions for the dynamic parts of the grammar.
Step 2 – Publish your grammar
In the ABNF editor, press Alt-Ctrl-Shift-P or right-click in the editor and select the Publish menu item in the contextual menu. This will open a dialog box in which you enter the grammar name on NuGram Server. (Of course, you first need to configure the publishing feature appropriately in the Eclipse Preferences. You’ll need to specify the server address, which is http://www.grammarserver.com:8082, your user name, and password). Since this is an English grammar, we’ll call it en/name.abnf.
That’s it! We are now ready to write our VoiceXML application.
Step 3 – Add the grammar to your VoiceXML application
Dynamic grammars are instantiated by sending instantiation contexts to NuGram Server, together with the name of the grammar. An instantiation context is simply a set of key/value pairs encoded as a JSON object. The context is passed to NuGram Server using a very simple HTTP-based interface. In VoiceXML, we’ll use the data element for this. Once the dynamic grammar is instantiated, the URI of the generated grammar is returned to the VoiceXML application for use in a grammar element.
To simplify the application code, I wrote a few ECMAScript helper functions. You can get them here. They must be put in a file named gsapi.js in the same folder as the VoiceXML application itself. Note that some of these functions rely on global objects provided by the Voxeo VoiceXML interpreter.
Now let’s start writing the VoiceXML document. We must begin with the usual XML header and the root element and a script element to include the ECMAScript helper functions:
<?xml version="1.0"?>
<vxml xmlns="http://www.w3.org/2001/vxml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.w3.org/2001/vxml
http://www.w3.org/TR/voicexml21/vxml.xsd"
version="2.1">
<script src="gsapi.js"/>
The next step is to set up the connection with NuGram Server:
<script>
var grammarUri = null;
setupGrammarServer('www.grammarserver.com:8082', 'UserName', 'Password');
</script>
This only assigns values to a few of variables. No magic here. The interesting part follows. We must now create a session on NuGram Server and instantiate the dynamic grammar. We will do this inside a form element:
<form id="start">
<block>
<script>
initiateSessionCreation();
</script>
<data name="createSessionResponse" srcexpr="serverUrl()"
method="post" namelist="account password operation resource"/>
<script>
setupSessionId(createSessionResponse);
</script>
The first script element sets up a number of variables, while the second one extracts the session ID from the response to the data element.
The instantiation context is then sent to NuGram Server in the same way:
<script><![CDATA[
initiateInstantiation('en/name.abnf',
{"entries":[{"firstname":"dominique",
"lastname":"boucher",
"extension":"4231"},
{"firstname":"yves",
"lastname":"normandin",
"extension":"4225"}]});
]]></script>
<data name="createGrammarResponse" srcexpr="serverUrl()"
method="post" namelist="account password operation resource context"/>
<script>
grammarUri = getGrammarUri(createGrammarResponse);
</script>
<goto next="#ask"/>
</block>
</form>
Of course, the context is hard-coded here. In a real application, it would probably be the result of a request to a database or a web service.
The initiateInstantiation function sets a few variables. In particular, the context variable is set to a JSON representation of the seconod argument to initiateInstantiation. (The Voxeo VoiceXML interpreter provides the JSON object, which can be used to serialize and deserialize JSON strings.)
The XML document returned by the data element will contain, upon successful completion, the URI of the generated grammar. The getGrammarUri function simply extracts this URI. We can now use this URI in a grammar element:
<form id="ask">
<field name="name">
<prompt>Please say the name of the person you would like to reach.</prompt>
<grammar srcexpr="grammarUrl(grammarUri) "/>
<filled>
<prompt>
The extension is
<value expr="application.lastresult$.interpretation.extension"/>.
</prompt>
<goto next="#end"/>
</filled>
<catch event="connection.disconnect.hangup">
<goto next="#end"/>
</catch>
<catch event=".">
Sorry. I did not understand.
<goto next="#end"/>
</catch>
</field>
</form>
The final step is to release the session on NuGram Server:
<form id="end">
<block>
<script>
initiateSessionDestroy();
</script>
<data name="deleteSessionResponse" srcexpr="serverUrl()"
method="post" namelist="account password operation resource"/>
<prompt>Bye Bye!</prompt>
<disconnect/>
</block>
</form>
</vxml>
This is it! Plain VoiceXML 2.1 compliant code, no web application to deploy! You are ready to test the application.
Advantages
The advantages of this approach are manifold. They are explained in more depth in our latest whitepaper, but let me summarize them:
- No web server to deploy, which means shorter development times;
- Dynamic grammars can be tested and debugged using the same, very sophisticated IDE used for static grammars;
- Static grammars can seamlessly evolve to dynamic grammars without sacrificing debugging and tuning capabilities.
- Generated grammars can be output in various formats (ABNF, GrXML, Nuance GSL). You thus have a technology that is engine-agnostic (NuGram IDE fully supports the most popular semantic interpretation tags, like SISR, Nuance OSR, and Nuance 8.5).
What do you think? Let us know! Our NuGram Beta Program is an opportunity for you to help us enhance our offering and make sure that your needs will be fulfilled.
