Tutorial: External Document Navigation

This tutorial is based on the things you accomplished in Lessons 1, 2, and 3. If you haven't yet done those Lessons, you'll need to go through them first.

In this tutorial, we will:

learn how to link to external callxml files with the goto action element
upload the new hello world app and try it out

Step 1: creating external goto elements

In the previous Lesson, we ended up with a callxml file that looked like this...



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

<callxml version="3.0">

 <do label="hello" choices="choice1 (1, one),choice2 (2, two)">

  <prompt value="helloworld"/>

  <wait value="5s"/>

  <on event="choice:choice1">

   <goto value="#one"/>

  </on>



  <on event="choice:choice2">

  <goto value="#two"/>

  </on>



  <on event="choice:nomatch">

  <say>this is not a valid choice. try again.</say>

  <goto value="#hello"/>

  </on>

 </do>



 <do label="noinput">

  <say>you didn't press, or say anything. Try again.</say>

  <goto value="#hello"/>

 </do>



 <do label="one">

  <say>you pressed D T M F one.</say>

  <exit/>

 </do>



 <do label="two">

  <say>you pressed D T M F two.</say>

 <exit/>

 </do>



 <on event="error">

 <sendemail from="MyApp@here.com"

  to="YourEmail@there.net" type="debug">

  We caught an error in our application. Details follow...

 </sendemail>

 </on>



</callxml>

This was our first step in learning to use the <goto> element, but there is more that we can accomplish using <goto>. Using the <goto> element we can link external callxml files together in much the same way that you can link HTML files using the anchor (<a>) element. In order to do that we will need to first modify our existing <goto> elements to route the execution to another callxml file when a user input is recognized successfully:



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

<callxml version="3.0">



 <do label="hello" choices="choice1 (1, one),choice2 (2, two)">

  <prompt value="helloworld"/>

  <wait value="5s"/>



  <on event="choice:choice1">

   <goto value="helloworld-one.xml"

         method="get"/>

  </on>



  <on event="choice:choice2">

   <goto value="helloworld-two.xml"

         method="get"/>

  </on>



  <on event="choice:nomatch">

  <say>this is not a valid choice. Try again.</say>

  <goto value="#hello"/>

  </on>

 </do>



  <do label="noinput">

    <say>you didn't press, or say anything. Try again.</say>

    <goto value="#hello"/>

  </do>



  <on event="error">

   <sendemail from="MyApp@here.com"

     to="YourEmail@there.net" type="debug">

     We caught an error in our application. Details follow...

   </sendemail>

  </on>

</callxml>

We now have two <goto> elements that link to other callxml documents. Notice that we have also modified the 'value' attribute to point to a relative URL, as opposed to a container element label that resides within our original file. We could link to any other callxml file, even one on a different web server, but for this example we are linking to callxml files located at the same webserver and directory as our original "helloworld.xml" file.

Also note that since we are linking to external files we no longer need container elements "one" and "two" in this file, but we will need to create two additional files.

Step 2: Creating our first additional file

With the modifications we made to our "helloworld.xml" file above we need to create the files to which we are linking or else we will encounter an error. The first file that we need to create should be named "helloworld-one.xml" and should be located in the same place as your "helloworld.xml" file (refer back to Lesson 1 if you need some help here). The "helloworld-one.xml" file should be crafted as follows:



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

<callxml version="3.0">



 <do label="one">

  <say>you chose option one.</say>

     <exit/>

 </do>



 <on event="error">

 <sendemail from="MyApp@here.com"  to="YourEmail@there.net" type="debug">

  We caught an error in our application. Details follow...

 </sendemail>

 </on>

</callxml>

Step 3: Creating our second additional file

All that remains now is to create our second additional file. It should be named "helloworld-two.xml" and should be located at the same place as your other two files. "helloworld-two.xml" should read as follows:



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

<callxml version="3.0">



 <do label="two">

  <say>you chose option two.</say>

    <exit/>

 </do>



 <on event="error">

 <sendemail from="MyApp@here.com" to="YourEmail@there.net" type="debug">

  We caught an error in our application. Details follow...

 </sendemail>

 </on>



</callxml>

These new files behave identically to the container elements "one" and "two" in our previous tutorial, only now, these <goto>targets are quite obviously self-contained external files. Note also that if we wanted to get frisky, we could also specify a target with more granularity by specifying a container name preceding by the "pound" sign along with the actual relative, or fully qualified URL. To clarify, the following syntax applies:



 <goto value="[URL]#[container name]"/>

In the case of this tutorial, any of these <goto> statements are equivalent:



 <goto value="helloworld-one.xml"/>

 <goto value="helloworld-one.xml#one"/>

 <goto value="http://myserver.com/helloworld-one.xml"/>

 <goto value="http://myserver.com/helloworld-one.xml#one"/>

Step 4: upload, and try it out

Your updated hello world callxml application is now done. Call the number associated with your callxml application, and you'll find that the results of this tutorial work just like the previous one -- except now we know how to use goto's to link to other callxml files!

callxml 3.0 source code

ANNOTATIONS: EXISTING POSTS

lambchops7

7/12/2007 10:15 AM (EDT)

I just started to program in callxml. When I "do" and press any number, the flow seems to be fine, but when I "do" and press the # key, the stream seems to terminate. It doesn't seem to recognize the # event and hangs up.

In the log viewer, it states:
SRE::PR: The current input doesn't match any in-grammar expression.
SRE stopped
GOT RECO EVENT - NO MATCH
event: unknown "nomatch"
parser event = 12, par = "nomatch", var = "(NULL)", val = "(NULL)"
Hangup()

Can someone elucidate? Thanks.

VoxeoDante

7/12/2007 2:31 PM (EDT)

Hello,

I can understand this behavior may seem strange. The truth is, there is a very good explanation for the described behavior.

In CALLXML, the # key is designated as a terminating character. If this key is pressed in a call it will end the current state the call is in. This is why when you press the # key the application seems to end.

I hope this answers your question. If not, please let me know.

All the Best,
Dante Vitulano

benwhalley

6/7/2010 8:36 AM (EDT)

Hi - I'm not clear on the function of this do block in the example:

<do label="noinput">
<say>you didn't press, or say anything. Try again.</say>
<goto value="#hello"/>
</do>

The block isn't referenced here, so I'm wondering if this is an undocumented equivalent to <noinput> in voicexml?

B

voxeoblehn

6/7/2010 10:56 AM (EDT)

Hello,

I believe the confusion here lies in naming of the label. CallXML, like VoiceXML will execute in a top down fashion, so given the example the only way this <do> element will be executed is if no input is received in the previous <do> block.

We are going to listen for caller choices in the first <do> block, however, if no choice is made we continue to move down and hit our next <do>, which coincidentally is named "noinput" - the execution of this <do> requires no caller interaction so we just perform the prompt and execute the <goto> which brings us back to the top of the document.

Hopefully this clarifies things, essentially, we could have named the second <do> label "foo" if we wanted, however, we took the literal route and named it "noinput."

If you still have any questions or concerns, please let us know.

Regards,

Brian Lehnen
Voxeo Support

Introduction to Document Navigation

| TOC

| Recording Audio