CallXML 3.0 Development Guide Home  |  Frameset Home


<case>  element


The <case> element is new to the CallXML3.0 markup, and is used in conjunction with the <switch> tag to execute specific blocks of code based on conditional logic. This combination of elements works exactly like the 'traditional' methods used in other markups for 'switch/case', in that the <switch> statement tests an expression against a number of <case> options, and then executes the statements associated with the first <case> that matches the <switch> value.

Also be aware that a developer can also use any of the aliases for the <block> element, which are identical in functionality, which allows you to pick a naming/programming scheme for container elements on a per-case basis that suits a developer's programming style. All of these identical <block> aliases are listed as follows:




usage

<case choices="(grammar value)" cleardigits="(true|false)" foreach="(comma delimited list of array values)" id="(element id)" label="(navigation identifier)" next="(navigation identifier)" repeat="(numeric value)" test="CDATA" test="CDATA" value="(string)" value-is="STRING" value-is-not="STRING" var="(variable name)">


attributes

choices Data Type: (grammar value) Default: Optional
The 'choices' attribute defines a list of comma delimited voice recognition utterances that will be active for the container element. Alternatively,  the attribute can contain a choice followed parantheses containing different words which equate to that choice. Note that both dtmf grammars, and spoken word grammar utterances can be defined; digit values always indicate dtmf input, whereas spelled 'literals' for numbers imply that the grammar must be spoken:


<say choices="1, one">press, or say one</say>


One can also define multiple matches to return the same value to the application by specifying the values in the following format:

ContainerElementName choices="ReturnValue (subchoice1, subchoice2)">

As such, either of the 'subchoice' utterances will be interpreted as 'ReturnValue'. To illustrate in greater detail:

<say choices="Beatles (john, paul, ringo, george),
              Rolling Stones (mick, keith, charlie, ron)"
      Say the name of a Beatle, or a Rolling Stone.
</say>


Lastly, developers can also make use of a built in number grammar for capturing a string of digit values by specifying [x DIGITS], where 'x' is the length of the string that you wish to collect:

<block choices="[5 DIGITS]">

This can also be modified to accept input of varying lengths by specifying [x-y DIGITS], where 'x' and 'y' are the minimum and maximum values for the length of the string being collected:

<block choices="[5-8 DIGITS]">

Note: You must add <assign var="settings.choices.completetimeout" value="10000ms"/> to set the wait time for variable digits. 10000ms=10s wait

cleardigits Data Type: (true|false) Default: false
This attribute's value is a Boolean, indicating whether the queued digits buffer should be cleared when this action starts. "true" clears the digits buffer; "false" leaves the contents of the digit buffer alone.
foreach Data Type: (comma delimited list of array values) Default: Optional
The 'foreach' attribute, usable on any CallXML3.0 container elements, should look familiar to many web developers. A developer can indicate a comma-delimited array of values to iterate through within 'foreach' attribute, and then use the 'var' attribute to specify the variable that will hold the current iteration value while in the enclosing container element.

Alternatively, 'foreach' uses the "container.value" variable to store the current iteration if the 'var' is unspecified.  and "container.value" will populate any unspecified 'value' attributes of  child elements of the container in question.
id Data Type: (element id) Default: none - attribute is optional
The new 'id' attribute in CallXML3.0 is applicable to all container and action elements. Specifying this attribute allows yet another level of control and event handling when events occur and are caught by the <on> element. When an event occurs, the handler will first check the event, and then verify that the handler has a handler specific to the 'id' attribute to execute. This allows the developer to plan a specific course of action for events based on where in the application that they occur.
label Data Type: (navigation identifier) Default: none - attribute is optional
This attribute designates the unique inter-document identifier of the parent element in question, and allows an easy way to navigate through applications as a destination 'anchor', as used in goto references
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.
repeat Data Type: (numeric value) Default: 1
The value for the repeat attribute indicates the number of times to execute the content contained by the parent element. If this attribute is explicitly specified, this must be a valid number, or an error will result.  Also note that if the value is zero the content will be skipped.
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.
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.
value Data Type: (string) Default: none - attribute is optional
The 'value' attribute is mappable to any of the container elements, (<block>, <with>, etc.), and specifies inheritance for attribute values that are enclosed within the container element. For instance, the below snippet will denote the values of 'test.wav' for the <playaudio>, <say>, and <log> elements :


<with value="test.wav"</hl>
  <playaudio />
<!-- equivalent to <playaudio value="test.wav">  -->
  <say />
<!-- equivalent to <say>test.wav</say>  -->
  <log />
<!-- equivalent to <log>test.wav</log>  -->
  </with>

value-is Data Type: STRING Default: none - attribute is optional
Another new attribute, 'value-is', grants the developer with the ability to perform conditional logic upon container elements, or action elements for the first time within the CallXML markup. The value specified in the 'value-is' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is' equate to 'true', then the element specified will execute. If the value equates to 'false' then the element will be skipped during document execution.
value-is-not Data Type: STRING Default: none - attribute is optional
Another new attribute, 'value-is-not', grants the developer with the ability to perform conditional logic upon container elements, or action elements, for the first time within the CallXML markup. The value specified in the 'value-is-not' attribute specifies a string to compare against any 'value' attributes. If the 'value' and 'value-is-not' equate to 'false', then the element specified will execute. If the value equates to 'true' then the element will be skipped during document execution.
var Data Type: (variable name) Default: none - attribute is required
Variable name to use when assigning a value. Not specifying this attribute will result in a fatal error.



code samples

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

<callxml version="3.0">


        <case choices="Laverne, Shirley">

    <!-- both the 'say' and 'wait' elements have the same -->
    <!-- implied attribute values for choice as the 'case' element -->
            <prompt>
            You can choose Laverne, or you can choose Shirley.
            </prompt>
         
            <wait value="5s"/>

            <on event="choice:Laverne">
        <prompt> You chose Laverne </prompt>
          </on>

            <on event="choice:Shirley">
<prompt> You chose Shirley </prompt>
  </on>
        </case>

</callxml>



<3.0 case-foreach-var>
<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">


        <case label="B1" foreach="one.wav, two.wav, three.wav" var="cxmlVar">

<!-- the 'foreach' and 'var'attributes set up a loop -->
<!-- construct that will iterate over the values defined in 'foreach' -->

            <playaudio value="$cxmlVar;"/>
            <say value="$cxmlVar;"/>
            <log value="$cxmlVar;"/>

          </case>

</callxml>



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

<callxml version="3.0">

        <case test="1=1">
        <prompt>
    this will execute, as 1 is equal to 1.
        </prompt>
        </case>

        <case test="'foo'='bar'">
        <prompt>
  this will NOT execute, as foo is not equal to bar.
        </prompt>
        </case>

        <case test="string">
        <prompt>
  this will execute, as the
  test element returns a non empty string.
        </prompt>
        </case>

</callxml>



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

<callxml version="3.0">


  <case value="feelgood.wav">

<!-- we do not need to define a 'value' attribute for the -->
<!-- enclosed elements, as the container element will -->
<!-- inherently populate these fileds with it's own -->
<!-- 'value' that is specified -->
    <playaudio/>
    <log/>
    <say/>
  </case>

</callxml>



<3.0 case-valueis-valueisnot>
<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">

  <!-- illustrates value-is attribute -->

        <case label="B1" value="foo" value-is="foo">
            <log/>
            <say>
    this will execute, as the value is equal to foo
  </say>
          </case>



        <case label="B2" value="foo" value-is="bar">
            <log/>
            <say>
    this will not execute, as the value is not equal to bar
  </say>           
        </case>

    <!-- illustrates value-is-not attribute -->

        <case label="B3" value="foo" value-is-not="foo">
            <log/>
            <say>
    this will not execute, as the value is not equal to bar
  </say>         
        </case>

        <case label="B4" value="foo" value-is-not="bar">
            <log/>
            <say>
    this will execute, as the value is not equal to bar
    </say>         
        </case>

</callxml>



<3.0 case-label-repeat>
<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">
  <case label="B1" repeat="1">
    <prompt>
      Here is the first case container.
    </prompt>
    <goto value="#B2"/>
  </case>

  <case label="B2" repeat="2">
    <prompt choices="*">
      Here is the second case container.
      If you wait before pressing the star key, you will hear
      this prompt play twice.
    </prompt>
    <on event="choice:*">
      <prompt>
        You pressed the star key
      </prompt>
    </on>
  </case>
</callxml>



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

<callxml version="3.0">

  <case label="B_1" next="#B_3">
    <prompt>
      once this container of TTS is executed, we will skip to case label
      B 3 via the next attribute
    </prompt>
  </case>


  <case label="B_2" next="Another_Document.xml">
    <prompt>
      And finally, we enter case label B 2, which is executed
      last
    </prompt>
  </case>


  <case label="B_3" next="#B_2">
    <prompt>
      And here we are in case label B 3
    </prompt>
  </case>

</callxml>



<3.0 case-id>
<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="3.0">

<!-- caller can say 'Zappa' at any point during the TTS -->
<!-- playback, and the event handlers will detect which -->
<!-- container element the user was in when the utterance was detected -->


<case id="C1" choices="Zappa">
<prompt value="Electric Aunt Jemima, Goddess of love"/>
<wait value="2s"/>
</case>


<case id="C2" choices="Zappa">
<prompt value="Your tacky maple buckwheats frizzle on the stove"/>
<wait value="2s"/>
</case>


<case id="C3" choices="Zappa">
<prompt value="Queen of my heart, please hear my plea"/>
<wait value="2s"/>
</case>


<case id="C4" choices="Zappa">
<prompt value="Electric Aunt Jemima, cook a bunch for me."/>
<wait value="2s"/>
</case>

<on event="choice:nomatch">
<log>** user said something that was not recognized ** </log>
<goto value="#C1"/>
</on>

<on event="choice" target="C1">
  <log>** a choice match occurred while in container element C1 **</log>
</on>

<on event="choice" target="C2">
  <log>** a choice match occurred while in container element C2 **</log>
</on>

<on event="choice" target="C3">
  <log>** a choice match occurred while in container element C3 **</log>
</on>

<on event="choice" target="C4">
  <log>** a choice match occurred while in container element C4 **</log>
</on>




</callxml>


<3.0 case-id>
<?xml version="1.0" encoding="UTF-8" ?>
<callxml version="3.0">

<!-- caller can say 'Zappa' at any point during the TTS -->
<!-- playback, and the event handlers will detect which -->
<!-- container element the user was in when the utterance was detected -->
<!-- http://docs.voxeo.com/images/tutorials/zappa.jpg -->


<case id="C1" choices="Zappa">
<prompt value="Electric Aunt Jemima, Goddess of love"/>
<wait value="2s"/>
</case>

<case id="C2" choices="Zappa">
<prompt value="Your tacky maple buckwheats frizzle on the stove"/>
<wait value="2s"/>
</case>


<case id="C3" choices="Zappa">
<prompt value="Queen of my heart, please hear my plea"/>
<wait value="2s"/>
</case>


<case id="C4" choices="Zappa">
<prompt value="Electric Aunt Jemima, cook a bunch for me."/>
<wait value="2s"/>
</case>

<on event="choice" target="C1">
  <log>** a choice match occurred while in container element C1 **</log>
</on>

<on event="choice" target="C2">
  <log>** a choice match occurred while in container element C2 **</log>
</on>

<on event="choice" target="C3">
  <log>** a choice match occurred while in container element C3 **</log>
</on>

<on event="choice" target="C4">
  <log>** a choice match occurred while in container element C4 **</log>
</on>




</callxml>


<3.0 case choices: DIGITS grammar>
<?xml version="1.0" encoding="UTF-8"?>

<callxml version="3.0">
      <case choices="[4 DIGITS]">
          <say>
          Enter your 4 digit pin.
          </say>
                  <wait value="5s"/>
          <on event="choice">
            <say> The pin you entered, was </say>
            <playnumber format="digits" value="$session.lastchoice;"/>
          </on>
      </case>
</callxml>



additional links

none


  ANNOTATIONS: EXISTING POSTS
saurin
6/25/2009 6:38 AM (EDT)
As per the description of Case element which says "The <case> element is new to the CallXML3.0 markup, and is used in conjunction with the <switch> tag to execute specific blocks of code based on conditional logic".

Could you please provide an example where you could used both <Switch> and <Case> element, to give proper understanding of using the case element as per description?
voxeoJeffK
6/25/2009 6:51 AM (EDT)
Hello,

Sure, here is a small script section that demonstrates their use in conjunction with each other:

<switch value="test" next="#quit">
  <case value-is="test" next="#match">
    <log>*** #1 Value is 'test' ***</log>
  </case>
  <case value-is-not="test" next="#nomatch">
    <log>*** #1 Value is not 'test' ***</log>
  </case>
</switch>

<block label="match" next="#quit">
  <log>*** #2 Value is 'test' ***</log>
</block>

<block label="nomatch" next="#quit">
  <log>*** #2 Value is not 'test' ***</log>
</block>

<block label="quit"/>

Regards,
Jeff Kustermann
Voxeo Support

login



© 2013 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site