VoiceXML 2.1 Development Guide

<catch> element

The catch element is used to intercept application and user-defined errors, conditions, and messages, thereby allowing the developer to assign event handlers on a scoped basis. The content nested within the catch element will only be executed when its particular event is thrown. See Appendix C for further information on catching and handling events.

usage

attributes

cond	Data Type: CDATA	Default: Optional (true)
	The cond attribute specifies a Boolean expression, which must equate to ‘true’ in order for the content to be visited and executed. Any standard ECMAScript Boolean value is valid for this attribute.
count	Data Type: CDATA	Default: Optional
	The count attribute allows the developer fine grained control over event handling upon multiple event occurrences. When an event is thrown for the first time, the catch element with a count of 1 will be executed. Upon the second instance of the same event, the FIA will look for a catch handler with a count value of 2, if one exists, otherwise, it will simply execute the catch handler with the count of 1 again.
event	Data Type: NMTOKEN	Default: Optional
	The event attribute specifies the event name that must be thrown in order for the catch element to execute, either a platform-defined error such as error.badfetch, or any user-defined error that is designated by the throw element.

shadow variables

_event	The _event shadow variable equates to a string specifying the event name that caused the exception, thereby making it available for the developer to log or submit the resultant exception/error to a database, or to save it to another local variable to get an application ‘error report’.
_message	The _message shadow variable will equate to the value of any user-defined message that is explicitly thrown. Currently, Voxeo has no platform-defined messages for any standard events, such as *error.badfetch* or *error.semantic*, so any caught messages must be user-defined.

parents

children

code samples

<Catch event> sample

<Catch shadow variables> sample

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

<vxml version = "2.1">

<meta name="author" content="Matthew Henry"/>
<meta name="copyright" content="2005 voxeo corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<catch event="MyUserDefinedEvent">
<prompt><value expr="_message"/>and the event is
<value expr="_event"/></prompt>
<goto next="aTotallyBogusPage.vxml"/>
</catch>

<catch event="error.badfetch">
<prompt>our error for the bogus go to statement is a
<value expr="_event"/></prompt>
</catch>

<form id="F_1">

<block>
<prompt>getting ready to throw an event to be caught.</prompt>
</block>

<block>
<throw event="MyUserDefinedEvent"
message="'here is the catch message'"/>
</block>

</form>

</vxml>

<Catch event-cond> sample

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

<vxml version = "2.1">

<meta name="author" content="Matthew Henry"/>
<meta name="copyright" content="2005 voxeo corporation"/>
<meta name="maintainer" content="YOUR_EMAIL@HERE.COM"/>

<catch cond="false" event="MyUserDefinedEvent">
<prompt>
since the condition attribute is not true,
this handler will not get executed.
</prompt>
</catch>

<catch cond="true" count="1" event="MyUserDefinedEvent">
<prompt>since the condition attribute is true, this
handler will get executed.</prompt>
<goto nextitem="B_2"/>
</catch>

<catch cond="true" count="2" event="MyUserDefinedEvent">
<prompt>this must be the second time this error
has been caught. the thrown message is
<value expr="_message"/>. </prompt>
</catch>

<form id="F1">

<block name="B_1">
<prompt>getting ready to throw an event to be caught.</prompt>
<throw event="MyUserDefinedEvent"/>
</block>

<block name="B_2">
<throw event="MyUserDefinedEvent" message="'here is the message'"/>
</block>

</form>

</vxml>

additional links

W3C 2.0 Specification

ANNOTATIONS: EXISTING POSTS

awirtz

12/3/2004 2:19 PM (EST)

The "Appendix C" hyperlink is broken.

MattHenry

12/6/2004 10:29 AM (EST)

Hi Aaron,

Thanks for the <catch>. I'll see about correcting this on the next documentation build.

~Matt

alexey.timofeev

11/28/2006 2:45 AM (EST)

I have root.vxml:
<vxml version="2.1">
<form id="start">
<assign name="var" expr="'TEST'" />
<submit next="next.vxml" />
</form>
</vxml>
And next.vxml:
<vxml version="2.1">
<form id="get">
<block>
<audio src="hello.wav"/>
<assign name="status" expr="'delivered'"/>
<submit next="http://host/set_status.php" namelist="status"/>
</block>
</form>
</vxml>
set_status.php must receive status of each call even if error in VXML occured.
Sometimes i receive this log message:

f-NONE 23:18:01.702: Fetch thread 8: Started fetch of URL: http://webhosting.voxeo.net/15322/www/next.vxml start time: 2006/11/24 23:18:1.702
f-NONE 23:18:01.702: Fetch thread 8: Fetch request headers:
user-agent: Motorola VoxGateway/2.0
accept: application/voicexml+xml, application/srgs+xml, application/srgs, text/x-vxml, */*
cache-control: max-age=0
cache-control: max-stale=0
cache-control: no-cache
pragma: no-cache
referer: http://webhosting.voxeo.net/15322/www/root.vxml
x-NONE 23:18:01.702: URLFetcher::fetchURL(): Attempting fetch. timeout=40000 proxy=squid123.orl.voxeo.net:3128 [http://webhosting.voxeo.net/15322/www/next.vxml]
Session event: name="connection.CONNECTION_DISCONNECTED", callid="7c9d2304ec73e0569ae8ff3a824d1ae3", _callstarttime="2006.11.24.23.18.01.353", _callendtime="2006.11.24.23.18.01.712"
x-NONE 23:18:01.858: HUNGUP -- dispatching to enclosing class
x-NONE 23:18:01.858: HUNGUP (NEAR-END)
x-NONE 23:18:01.858: In transfer = false inpostdial = false
x-NONE 23:18:01.858: Attempting to unblock main thread from fetch wait.
x-NONE 23:18:01.858: ok, hangup callback exiting.
Session warning: event was not handled
Session event: name="call.CALL_INVALID", callid="7c9d2304ec73e0569ae8ff3a824d1ae3"

As I understand, user hung up before submit to next.vxml. Please advice what
event should i handle in root.vxml to make submit to set_status.php if such
situation occured. Also please describe when events
connection.CONNECTION_DISCONNECTED and call.CALL_INVALID occure. I used site
search but found nothing about these events and how should i handle them in my
scripts.

jbassett

11/28/2006 6:18 AM (EST)

Hello,

Here is some information on the connection.disconnect.hangup event. With voicexml, in order for this event to always be caught, you MUST have a speech recognition field present. If there is not an existing field, you can always create a dummy field with 'garbage' grammar to ensure your disconnect is caught.

Here is a link that further explains the issue:
http://docs.voxeo.com/voicexml/2.0/frame.jsp?page=mot_disconnectevents.htm

Thanks
Jesse Bassett
Voxeo Support

alexey.timofeev

12/21/2006 10:08 AM (EST)

Hi,
I have a form:
<form id="start">
<field name="action" type="digits">
<prompt>Hello!</prompt>
<grammar mode="dtmf" src="" type="application/srgs+xml"/>
<catch event="maxspeechtimeout nomatch error.maxspeechtimeout">
<goto next="#repeat"/>
</catch>
<catch
event="connection.disconnect.hangup error.badfetch error.telephone.disconnect cancel exit">
<goto next="#repeat"/><exit/>
</catch>
<noinput>
<goto next="#repeat"/>
</noinput>
<nomatch>
<goto next="#repeat"/>
</nomatch>
</field>
<filled mode="all">
<goto next="#repeat"/>
</filled>
</form>
And log messages:
x-NONE 00:01:56.458: Nuance SessionEndedException noted:NuanceSpeechChannel.play({}): SessionEndedException -- TELEPHONY_CHANNEL_CLOSED (telephony channel closed)
x-NONE 00:01:56.458: HUNGUP -- dispatching to enclosing class
x-NONE 00:01:56.458: HUNGUP (NEAR-END)
x-NONE 00:01:56.458: In transfer = false inpostdial = false
x-NONE 00:01:56.458: ok, hangup callback exiting.
d-NONE 00:01:56.458: <new-dialog-state name="repeat"/>

And i received message "error.semantic.fatal Trying to speak to user who has already hung up". So, call was broken but that event was not handled and script went to dialog "repeat". How can I handle this event in my scripts?

MattHenry

12/21/2006 4:47 PM (EST)

Alexey,

The error message that you are seeing is detailed in our documentation:

-------------------------------------------------------------------

http://docs.voxeo.com/voicexml/2.0/mot_loggermessages.htm

error.semantic.fatal Trying to record from user after a hangup
OR
error.semantic.fatal Trying to listen to user after a hangup.

While this message appears intimidating, it is simply reporting a non-issue for all practical purposes. In essence, when a user hangs up while within a <record>, or <field>, then the document must explicitly <exit> after catching & performing any clean up. To illustrate, the following code would indeed throw this error message if a user hung up while in the middle of a recording session:

<catch event="connection.disconnect.hangup">
<log expr=" '*********** CAUGHT THE EVENT ************' "/>
</catch>

However, to get around this error, then all we need to do is code an explicit <exit> event:

<catch event="connection.disconnect.hangup">
<log expr=" '*********** CAUGHT THE EVENT ************' "/>
<exit/>
</catch>

~Matthew Henry

codingace

1/23/2008 2:22 PM (EST)

I take it there is no way to catch at the application level? May I assume I have to catch a hangup on each voicexml page?

VoxeoDustin

1/23/2008 4:21 PM (EST)

Hey,

There sure is. You'll simply need to create a root document that contains your <catch>.

For example:

root.vxml
--------
<?xml version="1.0"?>
<vxml version="2.1">

<catch event="connection.disconnect.hangup">

<exit/>

</catch>

</vxml>

leaf.vxml
--------
<?xml version="1.0"?>
<vxml version="2.1" application="root.vxml">



</vxml>

Note: The <catch> event must be scoped at the <vxml> level and that your leaf documents must have a voice reco field for the event to be caught.

Thanks,
Dustin

crishvi

5/19/2008 7:07 AM (EDT)

Hello,
I want to implement the following situation.A menu has few choice elements and for each choice element it has it's respective URI.Now i'm catching the event of error.badfetch .What i want to do is when the event is caught for the first time i want to try connecting that URI again without the user intervention and so on for a couple of times and then disconnect.

Please suggest me what can be done to implement the above situation.And also asap

Thanks,
Rishvi

VoxeoDustin

5/19/2008 9:23 AM (EDT)

Hey,

You can handle multiple badfetch errors in this fashion. This example assumes once you've received a valid choice, you assign the variable "choiceURI" the URI you wish to transition to.

<catch event="error.badfetch">
<submit expr="choiceURI" method="POST" namelist="myVar"/>
</catch>

<catch event="error.badfetch" count="3">
<log expr="*** MULTIPLE BAD FETCHES - ENDING SESSION ****'"/>
<prompt> Sorry, we seem to be having technical difficulties. Please try again later</prompt>
<exit/>
</catch>

Cheers,
Dustin

crishvi

5/20/2008 5:35 AM (EDT)

hello,
Thanks a ton for the quick reply.

Rishvi

mtatum111

9/17/2008 12:18 PM (EDT)

Hi, if you have the following - what happens if the caller says "what" at the prompt "What Month?".

Since we don't have attribute of count=1 at <catch>, I wasn't sure if it defaulted to <catch event = "noinput nomatch help" count = "2">
Which month of the year?

Thanks for any clarification

<form>
<field name = "month">
<grammar root = "month" version = "1.0" xml:lang = "en">
<rule id = "month">
<one-of>
<item>January</item>

<item>December</item>
</one-of>
</rule>
</grammar>
<prompt count = "1"> What month? </prompt>
<catch event = "noinput nomatch help" count = "2">
Which month of the year?
</catch>
<catch event = "noinput nomatch help" count = "3">
Which month of the year? For example, January.
</catch>
<catch event = "noinput nomatch help" count = "4">
<prompt> Transferring. Please hold. </prompt>
<goto next = "transfer_caller"/>
</catch>
</field>
</form>

<form id ="transfer_caller">
<transfer name="call" dest = "phone://8006667777">
<filled> <exit/> </filled>
</transfer>
</form>

VoxeoDustin

9/17/2008 12:35 PM (EDT)

Hey Melissa,

In this particular case, the default nomatch/noinput handler will be caught on the first instance of nomatch/noinput - 'I did not understand what you said. Please try again.' All subsequent nomatch/noinput events will be handled by the particular catch event that they match.

Cheers,
Dustin

mtatum111

10/9/2008 10:23 PM (EDT)

In reviewing for my test, I have come across the following question

given the following events which of the following are valid <catch> elements? I know that B is valid. But, wouldn't D be valid as well?
Thanks for any clarification
error.unsupported.builtin
error.unsupported.format
error.unsupported.language

A) <catch event = "unsupported"> ... </catch>
B) <catch event = "error.unsupported"> ... </catch>
C) <catch event = "all"> ... </catch>
D) <catch event = "error.unsupported.builtin error.unsupported.format error.unsupported"> ... </catch>

voxeoJeffK

10/10/2008 12:50 AM (EDT)

Hi,

D) <catch event = "error.unsupported.builtin error.unsupported.format error.unsupported"> ... </catch>

is logically and syntactically correct, but it does not meet the requirements of the question. The question requires that you catch the three events listed. Choice 'D' will catch those three events, BUT it will also catch the other error.unsupported events:

error.unsupported.objectname
error.unsupported.element

regards,
Jeff K.

gomse

9/3/2009 3:07 AM (EDT)

Hi,
Suppose I have a form as below
<vxml>
<form id="1">
<catch event="evt1">
</catch>
<catch event="evt2">
</catch>
<field name="input1">

<noinput>
<throw event="evt2"/>
</noinput>
<catch event="evt3">
</catch>
</field>
<field name="input2">
</field>
</form>
</vxml>

Suppose the field for input1 has executed and no input has been received. then, the event 'evt2' is thrown. This event is caught by the catch handler in the form's scope.(I hope my understanding is correct and the error is propagated from field's scope to form's scope). Now, once the catch handler for 'evt2' has executed, where will execution proceed to? Will the browser continue to execute the field for 'input2' or will it come out of the form '1'? Thanks for any clarification.

Gomse

voxeoJeffK

9/3/2009 3:24 AM (EDT)

Hello Gomse,

The execution returns to the field. As per the VoiceXMl spec:

5.2.4 catch element selection

An element inherits the catch elements ("as if by copy") from each of its ancestor elements, as needed.

For a simple example of:

<form id="1">
<catch event="evt2">
</catch>

<field name="input1">

<noinput>
<throw event="evt2"/>
</noinput>

The platform implicitly copies the catch handler into the field scope as well. This causes the code to act as though it looked like this:

<form id="1">
<catch event="evt2">
</catch>

<field name="input1">

<noinput>
<throw event="evt2"/>
</noinput>

<catch event="evt2">
</catch>

Regards,
Jeff Kustermann
Voxeo Support