VoiceXML 2.1 Development Guide

<link> element

The link tag allows the developer to easily implement a document or application scoped grammar and transition/event handler for a caller’s input. This element is usually placed in the application root document at the vxml level in order to implement global grammars/event handlers. Upon a successful link grammar recognition, we can either throw an event, transition the caller to another form or document, (or a specific form within another document). Note that grammars contained within the link element are always scoped to its parent element, thus, specifying a scope for a link grammar is disallowed.

Note that at least one voice recognition field or menu must be present in order for the link to execute on a given page.

usage

attributes

dtmf	Data Type: CDATA	Default: Optional
	The dtmf attribute indicates the dtmf key which can be used in conjunction with any other voice grammar specified within the link itself to validate a successful grammar match.
event	Data Type: NMTOKEN	Default: Optional
	The event attribute allows the developer to specify an event to be thrown to the application. If both the event and next attributes are specified for the link, then the event will take precedence, although this behavior is deprecated in the VXML 2.0 implementation. Therefore, it is recommended that you use one or the other for future compatibility.
eventexpr	Data Type: CDATA	Default: Optional
	The eventexpr attribute specifies an ECMAScript expression that evaluates to the event being thrown to the application. As mentioned, either platform defined events, or user-defined events may be indicated in this attribute. Please note that either event or eventexpr may be used within the parent element, but not both.
expr	Data Type: CDATA	Default: Optional
	The expr attribute evaluates to an ECMAScript value that defines the target URI. Either expr or next may be specified, but not both.
fetchaudio	Data Type: CDATA	Default: Optional
	The fetchaudio attribute specifies the URI of the .wav file to play to the caller in the event of an extended document fetch. Essentially, while the fetch is being made, it allows the developer to play some filler music to the caller rather than presenting only silence.
fetchhint	Data Type: (prefetch\|safe)	Default: safe
	Fetchhint is used to specify when the resource should be fetched during application execution. The possible values and their descriptions are: prefetch : Begin the resource fetch upon initial document execution safe: Only fetch the resource when it is specifically called in the application Note that the Voxeo platform will always not prefetch content by default. As such, a developer should specify a value of ''prefetch" if resources are to be made available prior to execution of application content.
fetchtimeout	Data Type: CDATA	Default: 5s
	The fetchtimeout attribute allows the developer to specify how much time to allow on a fetch before throwing an error.badfetch event. This can be specified globally by using the fetchtimeout property in the application root document. If not specified, it will default to 5 seconds. Also note the strict formatting of this value; if specified, the time value must have the ‘s’ denomination appended to it, else an error.badfetch is thrown: <link next="MyPage.vxml” fetchtimeout=”5s”/> See Appendix C exceptions for further information.
maxage	Data Type: CDATA	Default: Optional
	The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable age, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.
maxstale	Data Type: CDATA	Default: Optional
	The maxage and maxstale attributes replace the VXML 1.0 caching attribute for compliance to the w3c vxml 2.0 specification. The value for this attribute specifies the maximum acceptable staleness, in seconds, of the resource in question. However, it is strongly advised not to rely on this attribute for cache-control; caching is always best controlled by the hosting server's response headers. If no headers are specified, then no cache control will be present, regardless of the value set for the maxage and maxstale attributes.
message	Data Type: CDATA	Default: Optional
	The message attribute allows the developer to include a descriptive message along with the event that is being thrown. The message being thrown is accessible in the catch elements shadow variable _message.
next	Data Type: CDATA	Default: Optional
	The next attribute denotes the destination URI or form item to transition the caller to when the link grammar is matched. The value can be a full URI: *<link next=”http://MyServer.com/MyFile.vxml”>* or a relative URI: *<link next=”MyFile.vxml”>* In addition, it can also indicate a particular form within the current document, where the pound sign precedes the form item name: *<link next=”#AnotherForm”>* Or lastly, it can indicate a specific form in another document: *<link next=”AnotherDocument.vxml#AnotherForm”>*

shadow variables

none

parents

children

code samples

<Link event-message> sample

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

<vxml version = "2.1" xmlns="http://www.w3.org/2001/06/vxml">

<meta name="copyright" content="2012 Voxeo Corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<catch event="hell">
<prompt> <value expr="_message"/></prompt>
</catch>

<link event="hell"
message="'wow. you sure caught hell for that answer'">
<grammar xml:lang="en-us" root="TOPLEVEL">
<rule id="TOPLEVEL">
<one-of>
<item> democrats </item>
<item> republicans </item>
</one-of>
</rule>
</grammar>
</link>

<form id="F1">

<field name="F_1">
<prompt> who should win the next election, democrats or republicans? </prompt>
<grammar xml:lang="en-us" root="TOPLEVEL">
<rule id="TOPLEVEL">
<item> dummy </item>
</rule>
</grammar>
</field>

<filled>
<prompt> now why would someone say dummy?</prompt>
</filled>
</form>
</vxml>

<Link expr-maxage-maxstale> sample

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

<vxml version = "2.1" xmlns="http://www.w3.org/2001/06/vxml">

<meta name="copyright" content="2012 Voxeo Corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<var name="LinkExprVar" expr="'MyNextPage.vxml'"/>

<link expr="LinkExprVar" maxage="5000" maxstale="5000">
<grammar xml:lang="en-us" root="TOPLEVEL">
<rule id="TOPLEVEL">
<item> estrada </item>
</rule>
</grammar>
</link>

<form id="F1">

<field name="F_1">
<prompt> say estrada to kick off the link. </prompt>
<grammar xml:lang="en-us" root="myrule">
<rule id="myrule">
<item> dummy <tag>out.F_1 = "dummy" </tag></item>
</rule>
</grammar>
</field>

<filled>
<prompt> now why would someone say dummy?</prompt>
</filled>
</form>
</vxml>

<Link next-fetchhint-fetchaudio-fetchtimeout> sample

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

<vxml version = "2.1" xmlns="http://www.w3.org/2001/06/vxml">

<meta name="copyright" content="2012 Voxeo Corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<var name="LinkExprVar" expr="'MyNextPage.vxml'"/>

<link next="MyNextPage.vxml" fetchhint="safe" fetchaudio="MyAudioFile.wav" fetchtimeout="10s">
<grammar xml:lang="en-us" root="TOPLEVEL">
<rule id="TOPLEVEL">
<item> estrada <tag> out.LinkExprVar = "estrada"</tag></item>
</rule>
</grammar>
</link>

<form id="F1">

<field name="F_1">
<prompt> say estrada to kick off the link. </prompt>
<grammar xml:lang="en-us" root="TOPLEVEL">
<rule id="TOPLEVEL">
<item> dummy </item>
</rule>
</grammar>
</field>

<filled>
<prompt> now why would someone say dummy?</prompt>
</filled>

</form>
</vxml>

<Link eventexpr-dtmf-message> sample

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

<vxml version = "2.1" xmlns="http://www.w3.org/2001/06/vxml">

<meta name="copyright" content="2012 Voxeo Corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<var name="MyEvent" expr="'hell'"/>

<catch event="hell">
<prompt> <value expr="_message"/></prompt>
</catch>

<link eventexpr="MyEvent" dtmf="1" message="'I like Ike'">
<grammar xml:lang="en-us" root="TOPLEVEL">
<rule id="TOPLEVEL">
<item> democrats </item>
</rule>
</grammar>
</link>

<link eventexpr="MyEvent" dtmf="2" message="'good answer, Johnee Jingo'">
<grammar xml:lang="en-us" root="TOPLEVEL">
<rule id="TOPLEVEL">
<item> republicans </item>
</rule>
</grammar>
</link>

<form id="F1">

<field name="F_1">
<prompt>
who should win the next election?
You can press 1 or say democrats, or
you can press 2 or say republicans.
</prompt>

<grammar xml:lang="en-us" root="TOPLEVEL">
<rule id="TOPLEVEL">
<item> dummy </item>
</rule>
</grammar>
</field>

<filled>
<prompt>
Now why would someone say dummy?
</prompt>
</filled>
</form>
</vxml>

additional links

W3C 2.0 Specification

ACCOUNT LOGIN

ANNOTATIONS: EXISTING POSTS

MattHenry

2/4/2008 5:58 PM (EST)

One point of confusion that comes up when using fetchaudio is how this affects prompt queuing and document fetching. Note that prompt queueing and prompt execution are two entirely separate hings, and it is strongly advised that developers who are interested in this topic closely read the specification for clarity on the difference:

http://www.w3.org/TR/voicexml20/#dml4.1.8

As this topic has come up a few times, it seemed as if we should illustrate this in a little greater detail, so here goes:

When you declare the fetchaudio property, this will clear the prompt queue, and thus play the <prompt> within your block that does the submit prior to the submission. One thing that is important to remember here is that this can cause some confusion when executing TTS and audio resources. For instance, assume the following document that submits data:

<form>
<field name="F1">
<audio src="audio_1.wav"/>
..
<filled>
<audio src="standby.wav"/>
<submit next="target.jsp" namelist="F1" fetchaudio="pulse.wav"/>
</filled>
</block>
</form>

And further take into account that the XML output of "target.jsp" looks like this:

<form>
<block name="B2">
<audio src="audio_2.wav"/>
<exit/>
</block>
</form>

The chronological order of audio execution in this case will be as follows:

1) audio_1.wav
2) user input is gathered
3) standby.wav
4) document fetch occurs
5) pulse.wav (fetchaudio)
6) audio_2.wav

But what happens is we take out the 'fetchaudio' attribute from the <submit> in our invoking document? Here is where things get a little confusing, but bear in mind that this order of execution is per the specification:

1) audio_1.wav
2) user input is gathered
3) document fetch occurs
4) standby.wav
5) audio_2.wav

I hope that this will help to proactively save some time & frustration for our developers as applications are in the formative stages, rather than finding out about this at the last minute.

~Matt

tonyward

2/6/2008 5:01 PM (EST)

Matt,
Is there any way I can set a universal event for my application? I know with the combination of universal grammar and link element I can achieve this. But I m not able to get them to work. In my application I want 2 universal words "Start Over" and "Repeat". Where "Start Over" would start the application again for the user and "Repeat" would only repeat the last question. Any suggestions?

Thanks.

mikethompson

2/6/2008 5:28 PM (EST)

Tony,

You should be able to setup a link grammar which is active throughout your entire application. If you are unable to get this to work, please open a private account ticket with application logs and we can help you troubleshoot it.

Best,
Mike Thompson
Voxeo Corporation

mtatum111

10/10/2008 10:58 AM (EDT)

This is another question that I have come across in my vxml review. I don't under how any of these could be the correct answer. The correct answer is supposed to be D. It is my understanding that <field>, <object>, <record>, <initial>, <subdialog> all do have implicitly defined variables. However, I don't think that <menu>, <log>, <throw> or <link> do. Do you have any explanation as to why the author thinks D is the correct answer.

Which of the following elements implicitly define a variable?

A) <field>, <object>, <record>, <initial>, <subdialog>, <menu>
B) <field>, <object>, <record>, <initial>, <subdialog>, <log>
C) <field>, <object>, <record>, <initial>, <subdialog>, <throw>
D) <field>, <object>, <record>, <initial>, <subdialog>, <link>

MattHenry

10/10/2008 11:47 AM (EDT)

Hello Melissa,

I'm not sure what content you are referencing here (Jim Larson VXML training guides, perhaps?), but I think I can understand why "D" would be the correct answer. Per the VXML spec, "When a link is matched, application.lastresult$ is assigned", which seems to back up the assertion that <link> has an implicitly defined variable.

http://www.w3.org/TR/voicexml20/#dml2.5

I don't see anything in the spec that explicitly states a direct answer to your question, but the above quotation does seem to lend credence to the fact that "D" would be the right answer.

~Matt

mtatum111

10/10/2008 11:58 AM (EDT)

Matt, thanks so much. This did in fact come from James Larson's vxmlguide.com. I have been studying that to prepare for the exam.
Thanks for giving me your opinion and pointing me to the spec.

MattHenry

10/10/2008 12:12 PM (EDT)

Melissa,

I am very glad that I could help, and I wish you luck on your test. As a word of advice when taking the test, be *very* prepared for trick questions, and spend a lot of time reading each question very carefully, as quite a few questions are phrased so as to misdirect: Quite a few of them are along the lines of "If a plane carrying French Canadians crashes on the border of the US and Canada, where do they bury the survivors..."

Cheers,

~Matt

poonam007

4/14/2010 12:29 PM (EDT)

jdyer

4/14/2010 3:45 PM (EDT)

Hello,

We did see your posting, but aside from the obligatory 'Hello', I am not sure how we can be of help here. Is there a question on this element we can perhaps clarify? We'll be standing by for your response at this time.

Regards,

John Dyer
Customer Engineer
Voxeo Support

nbr_15

3/13/2012 8:05 AM (EDT)

Hello,

Is there any way to put two forms in the link tags.

For example : I have two forms and I want to use link for everyone.

First form is use ASR Recognition.
Second form is use DTMF.

voxeoshanesmith

3/19/2012 4:09 PM (EDT)

Hi,

I'm not exactly sure what you mean. The only valid children of link are grammars. You can have 2 links, one with a dtmf grammar and one with a voice grammar and each can have it's own form as a destination. If I've misunderstood, please let me know. If you can open a support ticket directly and paste in the application debugger logs, I'd be happy to investigate further.

Regards,
Shane Smith
Voxeo Corporation

Status of Voxeo's Hosted Services: [link=http://status.voxeo.com/]status.voxeo.com/[/link]

Prophecy 11 Now Available: [link=http://docs.voxeo.com/prophecy/11.0/home.htm]docs[/link] | [link=http://www.voxeo.com/prophecy/]download[/link]