CallXML 2.0 Development Guide

| TOC

This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

Appendix D: Best Practices

This series of documents will cover the suggested best practices that will allow you to write superior CallXML applications with a minimum of hassle. We will cover the optimal coding techniques that will ensure that your applications run smooth as glass, and as cool as ice. While not a complete dissertation of the CallXML language, this guide should serve as a good starting point for your CallXML application tuning needs.

Case Sensitivity

CallXML 2.0 is case sensitive -- all element and attributes must be in lowercase, not mixed case or upper case, as illustrated below:

Valid:



<playaudio>

<getdigits>

<ontermdigit value="1">

Invalid:



<hl>PlayAudio>

<getDigits>

<ontermdigit Value="2">

Element Nesting and Navigation

Nesting is allowed with block elements, but care needs to be excercised when creating navigation logic. Navigation is not allowed to nested blocks when the initializing block sits outside of the nesting block's scope; i.e.:



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

<callxml version="2.0">



  <block label="B0" next="#B2">

    <log value="**** ENTERING B0 ****"/>



    <block label="B1" next="#B2">

      <log value="**** ENTERING B1 ****"/>

    </block>



    <block label="B2" next="#B4">

      <log value="**** ENTERING B2 ****"/>

    </block>



    <block label="B3">

      <log value="**** ENTERING B3 ****"/>

    </block>



  </block>



  <block label="B4" next="#B3">

<!-- This 'next' target of '#B3' will never be executed,  -->

<!-- as it sits outside of the nested block scope -->

    <log value="**** ENTERING B4 ****"/>

  </block>

Be aware that using <goto next> in place of the 'next' block attribute will not function for navigation between nested blocks. Therefore, it is recommended that you not use the <goto> element within your code unless transitioning to an entirely separate page, or submitting variables is required by your application.

Also note that any subsequent documents will not be able to 'see' nested blocks as valid navigation identifiers. For example, if we were in another document, then having a <goto> or <block next> target of 'MyDoc.xml#B3' would throw an 'event: error "document" (invalid target for goto or next attribute)' message to the Voxeo Logger.

Order of Execution

For consistency, the behavior of actions following event handlers inside of a container (<block>, <inputaudio>, etc) has changed. Previously actions following event handlers could be executed in some situations. With CallXML 2.0, they will not be executed, as evidenced below:



<callxml version="2.0">



  <block>

    <text>please leave your message.</text>

    <recordaudio value="mailto:bob@home.com" maxsilence="4s" maxtime="45s"/>

    <onmaxsilence/>

    <onmaxtime/>

    <playaudio value="thankyou.wav">

  </block>



  <block>

    <playaudio value="holdmusic.wav"/>

  </block>



</callxml>

In CallXML 2.0, the 'thankyou.wav' file will never be played, however the 'holdmusic.wav' file will always be played in both CallXML 1.0 and 2.0.

Telephony Event Handling

When writing an application with <onanswer> or <reject> elements, note that best practices dictate that you immediately transition to a new starting block, else we run the risk of other handler events not getting properly executed. Nesting the contents of your entire CallXML document within an <onanswer> element is also inadvisable for the very same reason. For example, the following code sample shows that neither the <block> nor the <text> element will ever be executed:



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

<callxml version="2.0">

  <onanswer>



    <block label="B1" repeat="3">

      <text termdigits="*"> press the star key now </text>



      <ontermdigit value="*">

        <log value="*** USER PRESSED STAR ***"/>

      </ontermdigit>



    </block>



  </onanswer>

</callxml>

However, 'smart' coding dictates that we would structure our document like what follows in order to get the functionality that we want:



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

<callxml version="2.0">

  <onanswer>

    <goto value="#B1"/>

  </onanswer>



   <block label="B1" repeat="3">

      <text termdigits="*"> press the star key now </text>



      <ontermdigit value="*">

        <log value="*** USER PRESSED STAR ***"/>

      </ontermdigit>



   </block>



</callxml>

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

C: CallXML Variables

| TOC

| E: Exceptions & Errors