| CallXML 3.0 Development Guide | Home | Frameset Home |
<on> element replaces the deprecated <on(EVENTNAME)> handlers from CallXML2.0, and is compliant to the XML events specification, (http://www.w3.org/TR/2003/REC-xml-events-20031014/).<onanswer><oncallfailure><oncparesult><onerror><onexternalevent><onhangup><onmaxdigits><onmaxsilence><onmaxtime><ontermdigits><on> element replaces the above elements when used in the following format:<on event="event:value"><ontermdigit value="#"><on event="termdigit:#"><on> element can also be used to trap user-defined events that are kicked off when using the new <throw> element:<throw event="myEvent">
..
<on event="myEvent">
<!-- do something here -->
</on>
| event | Data Type: (event type) | Default: none - attribute is required |
The 'event' attribute is used in conjunction with the <on> handler to specify the specific event name that we wish to filter. Using a generic handler, where we specify the exact condition to catch is much less cumbersome than the CallXML2.0 event handling scheme, where we had to define the correct element name of the event to catch. The standard syntax for this new method of simple event handling is as follows:
| ||
| next | Data Type: (navigation identifier) | Default: none - attribute is optional |
| The 'next' attribute sets the URL the CallXML platform will go to when the container ends. | ||
| target | Data Type: (element id) | Default: none - attribute is optional |
The 'target' attribute is another new enhancement to the restructured <on> element that permits the developer to specify what elements a handler can accept events from. At a code level, this means that we can include, or exclude events from a specific handler on a per-case basis, thereby allowing fine-grained control over the event handling schema within the application. | ||
| test | Data Type: CDATA | Default: Optional |
| The 'test' attribute is a new supplement to the CallXML markup that permits the developer to execute the contents of a container element, or action element, based on whether or not the specified condition is met. If the defined condition is met, then the code contained within the element is then executed. If the condition is not met, then the application resumes execution with the next sequential container container element in the document. | ||
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <do label="B1"> <prompt choices="1"> Press one now. Or press 2. Or hang up. Or dont press anything at all. </prompt> <getdigits var="Var_1" maxtime="3s"/> <on event="choice:1"> <prompt value="you pressed 1"/> </on> <on event="nomatch"> <prompt value="That isn't a valid selection"/> </on> <on event="maxtime"> <prompt value="you didnt press anything"/> </on> <on event="hangup"> <log> *** USER HUNG UP ***</log> </on> </do> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <do label="B1" choices="jack tripper, mister roper, chissy"> <say id="P1"> Who is your favorite member of the smash TV hit 'Threes Company'? </say> <say id="P2"> You have the option to choose any of these characters. </say> <say id="P3"> jack tripper, mister roper, or chrissy. </say> <say id="P4"> but you really should choose jack tripper, if you are smart. </say> <on event="choice:jack tripper" target="P1"> <log> *** RECO EVENT OCCURRED WITHIN P1 ***</log> <say> Jack is pretending to be gay so he can live with two hot girls. </say> </on> <on event="choice:jack tripper" target="P2"> <log> *** RECO EVENT OCCURRED WITHIN P2 ***</log> <say> Jack is pretending to be gay so he can live with two hot girls. </say> </on> <on event="choice:jack tripper" target="P3"> <log> *** RECO EVENT OCCURRED WITHIN P3 ***</log> <say> Jack is pretending to be gay so he can live with two hot girls. However, he is a little bit too convincing.... </say> </on> <on event="choice:jack tripper" target="P4"> <log> *** RECO EVENT OCCURRED WITHIN P4 ***</log> <say> Jack is pretending to be gay so he can live with two hot girls. </say> </on> <on event="choice:mister roper"> <say> mister roper is clueless to jack trippers heterosexuality. </say> </on> <on event="choice:chrissy"> <say> chrissy is a bombshell. </say> </on> </do> </callxml> |
| <?xml version="1.0" encoding="UTF-8"?> <callxml version="3.0"> <do label="D1"> <assign var="MycallerID" value="session.callerID"/> <prompt value="I bet you would like to hang up now, wouldn't you"/> <wait value="20s"/> <on event="hangup" test="1 = 2"> <log> *** THIS WILL NOT EXECUTE, AS 1 IS -NOT- EQUAL TO 2 ***</log> </on> <on event="hangup" test="'$MycallerID;' = '$MycallerID;'"> <log> *** THIS CAN EXECUTE, AS MycallerID IS EQUAL TO callerID ***</log> </on> <on event="hangup" test="1 =1 "> <log> *** THIS CAN EXECUTE, AS 1 -IS- EQUAL TO 1 ***</log> </on> <on event="hangup" test="'one'= 'one'"> <log> *** THIS CAN EXECUTE, AS 'one' -IS- EQUAL TO 'one' ***</log> </on> <on event="hangup" test="6 != 9"> <log> *** THIS CAN EXECUTE, AS 'one' -IS- EQUAL TO 'one' ***</log> </on> <on event="hangup" test="anyString"> <log> *** THIS CAN EXECUTE, AS THIS IS A NON-EMPTY STRING ***</log> </on> </do> </callxml> |
| <?xml version="1.0" encoding="UTF-8" ?> <callxml version="3.0"> <!-- sometimes, we want to 'mask' the fetch of a large document --> <!-- by playing audio during the fetch.--> <!-- To do so, we will use a parent+child architecture, --> <!-- and make use of the new '$session.eventvalue;' session variable--> <assign var="parentSessionID" value="$session.ID;"/> <do label="D_0"> <log>*** STARTING THE PARENT SESSION ***</log> <run value="FetchAudioChild.xml" submit="*" method="get" var="timerSessionID" /> <playaudio format="audio/wav" value="Spidey.wav"/> <on event="externalevent"> <log>*** WITHIN THE PARENT AGAIN ***</log> <log>*** LIST SLASHDOT: $session.eventvalue; ***</log> </on> </do> </callxml> |
| <?xml version="1.0" encoding="UTF-8" ?> <callxml version="3.0"> <!-- grab the RSS newsfeed, which will take a few --> <!-- seconds to fetch --> <fetch value="http://slashdot.org/index.rss" var="SlashDotNews" /> <with label="Assign" value="$SlashDotNews;"> <sendevent session="$parentSessionID;"/> </with> </callxml> |
| ANNOTATIONS: EXISTING POSTS |
esirkin
|
|
| In your examples you show use of <on event="maxtime"> as well as in examples in <recordaudio>. But this event is not listed in your list of possible events in your documentation on this page. A small nit, but could confuse the patients.
eric |
|
jbassett
|
|
| Hello,
You are correct. Good catch. I will go ahead and forward this on so we can get it properly added. Thanks Jesse Bassett Voxeo Support |
|
jpw
|
|
| so, it's been like 6 months. maxtime is still not listed. is maxtime legitimate? and if so, what's the difference in maxtime and maxsilence? Your reply to the previous customer from 200 days ago isn;t clear -- is the "good catch" that maxtime is wrong, or that it's not listed in the documentation? | |
voxeojeff
|
|
| Jpw,
According to Jesse's last posting here, the fact that he mentions that maxtime should be added indicates that it is indeed a valid event. As for maxtime vs. maxsilence, maxtime is used as a measuring stick to determine human vs. machine (cpa). Maxsilence is used to determine the end of voice activity. http://docs.voxeo.com/callxml/3.0/ansdetection_cxml30.htm Regards, Jeff |
|
jpw
|
|
| is the next= any different from putting a <goto> at the end of the <on> handler?
Also, does the next= have to be a url, or can it be a local label inside the same document? |
|
VoxeoDustin
|
|
| Hey JP,
The next attribute is pretty much the same as using a goto. When using next it will process the entire contents of the <on> handler, then go to the next document or block. You can transition through blocks by prefacing the block name with # in the next= attribute: <on event="choice:1" next="#B1"> <prompt value="you pressed 1"/> </on> Note that, like goto, it will only transition to blocks in the same scope or the root scope. |
|
zoop
|
|
| I need a little more assistance with the on event=external I'm just converting some callxml 2.0 code to 3.0 and looks like I'm missing something. I currently have something like this.
file1 <sendevent value="Ididsomething" session="$parentsession;"/> file2 <onexternalevent value="Ididsomething" next="#someblock"/> From looking at the example aove it doesn't appear to have a way to identify the "value" I see the with tag on the sendevent But how does the new <on> handle this? Thanks. |
|
VoxeoDustin
|
|
| Hey zoop,
You can access the value of the event like so: [code] <sendevent id="myEvent" value="foo" session="$parentSessionID;"/> <on event="externalevent:myEvent"> <log>*** WITHIN THE PARENT AGAIN ***</log> <log>*** LIST SLASHDOT: $session.eventvalue; ***</log> </on> [/code] Thanks, Dustin |
|
zoop
|
|
| Ok got another one for you. In Callxml 2.0 we had <onerror type="xxxxx"> in 3.0 is this now to be <on event="error:xxxx"> ? I don't see it documented well on this page. | |
voxeojeff
|
|
| Hello zoop,
Yes, you are correct. Specifying <on event="error:errorname"> will work. For example, lets say you specify a playaudio URL which does not exist. This results in a 404 error, and generates an event: error "telephony" (server error 404). The following handler will catch it: [code] <on event="error:telephony"> <say> there was an error! </say> <log> *** ERROR *** </say> </on> [/code] You can also make it a global error handler, by just specifying <on event="error">. Hope this helps, Jeff |
|
zoop
|
|
| Here is how it's done.
Document1 has: <on event="externalevent:SOMEID"/> Document2 sending to document1 <sendevent value="SOMEID" session="DOCUMENT1SESSIONID"/> Finally had time to test it out and see how to make it go. thanks for the help. |
|
mdesgiw
|
|
| Anybody know why this doesn't work? If we receive audio and it doesn't match any of our choices, we want to play the introductory message again and wait for user input.
<on event="choice:nomatch" target="B1"> <say choices="9">No Match.</say> </on> We test the above and can never get a "nomatch" condition for some reason. |
|
VoxeoDustin
|
|
| Hey,
Would you mind opening an account ticket with the relevant code and debugger output? Once we have this info in hand we'll have a better idea of why this is failing for you. Thanks, Dustin |
|
mdesgiw
|
|
| Should I care about the following debugger output?
I have a "on event=hangup" code block that seems to to get executed, but when I test hanging up on an outgoing call, the debugger still complains thusly: >>>event: error "linenotactive" (there is no active phone line to execute the action) >>>event: error "document" (unhandled event "event="onerror", event="", type="linenotactive"") >>>end of session My "on event=hangup" code is simply this: <on event="hangup"> <log>*** User hung up (page2.xml) ***</log> <hangup/> <exit/> </on> Presumably the "end of session" that the debugger reports is because of my "<exit/>" and "<hangup/>" commands, yes? Why does the debugger still insists on showing that a "error:linenotactive" (I assume that would be the syntax) event was raised and not handled by my code? I have tried to capture this event in the following ways. None of these "on" events captures the "linenotactive" event. What's up with that? <on event="error:linenotactive"> <log value="*** LINE NOT ACTIVE (error:linenotactive) ***" /> <hangup/> <exit/> </on> <on event="document:linenotactive"> <log value="*** LINE NOT ACTIVE (document:linenotactive) ***" /> <hangup/> <exit/> </on> <on event="onerror:linenotactive"> <log value="*** LINE NOT ACTIVE (onerror:linenotactive) ***" /> <hangup/> <exit/> </on> <on event=":linenotactive"> <log value="*** LINE NOT ACTIVE (:linenotactive) ***" /> <hangup/> <exit/> </on> If for any reason the line goes dead during an outbound call, how best to capture and handle that event? Thanks, Marc |
|
voxeojeff
|
|
| Hi Marc,
It's quite possible that you are trying to hang up a line which has already hung up, thus resulting in this error. If that's the case, then there is no cause for alarm here. However, to be sure... please go ahead and send us a complete debugger log illustrating this error so that we may examine it for you. To do so, 1) Open the debugger window, (Account => Application Debugger) 2) Call the application, and reproduce the error 3) Click the 'support' tab in the debugger, give a short description of the issue, and click on submit. Thanks, Jeff |
|
mdesgiw
|
|
| OK, so you think maybe one of my <hangup>s occurs after the line is already released?
Here's the log file. My <log> statement is executing, showing that the onhangup event fired and then I get the "linenotactive" message. Sounds like the line *is* already dead, but "linenotactive" is not in your docs. Shouldn't I be able to trap for that and respond accordingly? Using "error:linenotactive" appears to do nothing in an "on" event... Here's the log for an outgoing call for which I physically hung up when my prompts started playing: (note: actual domain name changed to "myserver" in the log below...) 00067 1ead 02:42:56 AM event: answer 00068 1ead 02:42:56 AM action: begin value="" 00069 1ead 02:42:56 AM BEGIN BLOCK: Label="MessageBlock" Value="" Next="" 00070 1ead 02:42:56 AM action: text "hello Marc" format="" termdigits="" choices="" cleardigits=0 00071 1ead 02:42:57 AM Log: *** going to xfer.xml#B1... *** 00072 1ead 02:42:57 AM now going to http://myserver.com/ivrlib/xfer.xml [click on link for full URL] 00073 1ead 02:42:57 AM action: goto value="http://myserver.com/ivrlib/xfer.xml#B1 Submit (method="GET" cache=""): 00075 1ead 02:42:57 AM document loaded: parsing click link to view 00076 1ead 02:42:57 AM action: begin value="" 00077 1ead 02:42:57 AM BEGIN BLOCK: Label="block___1___" Value="" Next="" 00078 1ead 02:42:57 AM action: begin value="ON" 00079 1ead 02:42:57 AM BEGIN BLOCK: Label="B1" Value="ON" Next="" 00080 1ead 02:42:57 AM SRE stopped 00081 1ead 02:42:57 AM Log: ExpertMode=ON 00082 1ead 02:42:57 AM action: text "time to respond. press five or say YES to confirm. ..." cleardigits=0... 00083 1ead 02:43:00 AM event: hangup 00084 1ead 02:43:00 AM action: begin value="ON" 00085 1ead 02:43:00 AM BEGIN BLOCK: Label="block___16___" Value="ON" Next="" 00086 1ead 02:43:00 AM Log: *** User hung up (xfer.xml) *** 00087 1ead 02:43:00 AM event: error "linenotactive" (there is no active phone line to execute the action) 00088 1ead 02:43:00 AM event: error "document" (unhandled event "event="onerror", event="", type="linenotactive"") 00089 1ead 02:43:00 AM end of session |
|
VoxeoDustin
|
|
| Hey Marc,
Jeff is correct that the hangup handler is at fault: <on event="hangup"> <log>*** User hung up (page2.xml) ***</log> <hangup/> <exit/> </on> Will cause an issue because we've already hungup. Simply removing the <hangup/> should resolve the linenotactive error. You can catch this error by implementing: <on event="error:document"> <!-- on --> </on> Do note, that in most cases, you will not want to issue a hangup in an error handler, but an exit, which will implicitly disconnect the call leg. In the case of any fatal error, the call leg will already be disconnected, so reissuing a hangup during the error handler will simply throw another error - not good. ;) Let me know if you have further questions. Cheers, Dustin |
| login |