SIPMethod 4.0 fully supports converged multi-model applications - mixing web, VoIP and web services capabilities in a single application. It supports SIP Servlet Specification 1.1, Java Servlet Specification 2.5 and Java API for Web Services 2.0.

SIPMethod 4.0 comes with the all-new Web Console to allow you easily manage and monitor the server and applications.

For production environment, SIPMethod 4.0 can be deployed as in clusters to provide high availability and load balance.

SIPMethod Application Server 4.0 can be downloaded for 30 day evaluation.

ShareThis

Lately, the Voxeo Designer platform has become increasingly popular. However, it can be somewhat limited in terms of call control. Customers who are used to a combination of CCXML and VoiceXML may be turned away by this idea. Well, fear not, as we can easily integrate CCXML and Designer now, adding that game-changing call control aspect that CCXML brings to the table. Why use a CCXML front end, you say? Well, lots of reasons. CCXML brings call control, conferencing, whisper dialogs, hold dialogs, as well as the ability to pass in parameters to your Designer application. Whether it’s “you have a call from John Smith, press 1 to accept this call,” or a simple repeating hold music dialog, it is now possible with Designer dialogs.

So now let’s take a look at how we put it all together. Let’s assume that you already have a basic Designer application established. At this point, we don’t care what it does. Now, we need to write a CCXML front end for it.

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml">
  <var name="myDialogID"/>
  <eventprocessor>

    <transition event="connection.alerting">
      <log expr="'Preparing to answer the call.'"/>
      <accept/>
    </transition>

    <transition event="connection.connected">
      <log expr="'Caller has connected.  Executing VoiceXML dialog now.'"/>
      <dialogstart src="'helloworld.vxml'" type="'application/voicexml+xml'" dialogid="myDialogID"/>
    </transition>

    <transition event="dialog.exit">
      <log expr="'The dialog is now complete.  Exiting application.'"/>
      <exit/>
    </transition>

    <transition event="error.*">
      <log expr="'An error has occured (' + event$.reason + ').  Exiting application.'"/>
      <exit/>
    </transition>

  </eventprocessor>
</ccxml>

This simple CCXML code snippet accept a user’s call, and launches a VoiceXML dialog titled helloworld.vxml. Now, all we need to do is modify the “src” attribute to reference the Designer application. How, you ask? Well, it’s a little tricky, but far from impossible. All we need to do is grab the Designer URL from the Application Debugger (or the Prophecy Log Viewer, for all the local installations out there). The full URLs will look something like this, and may require copying the link to the clipboard (in Evolution, at least) in order to see the entire thing:

Evolution Designer:

  http://evodesigner-internal.voxeo.com/CallRouter?vr.application.id=XXXX
  (where XXXX is your specific Application ID)

Prophecy Designer:

  http://127.0.0.1:9992/CallRouter?vr.application.id=X
  (where X is your specific Application ID)

We can then inject this into the <dialogstart> keeping everything else the same. The dialog “type” remains “application/voicexml+xml” since Designer is pure VoiceXML behind the scenes, coupled with a custom GUI.

Now let’s take a look at the finalized code, with our Designer dialog in place.

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml">
  <var name="myDialogID"/>
  <eventprocessor>

    <transition event="connection.alerting">
      <log expr="'Preparing to answer the call.'"/>
      <accept/>
    </transition>

    <transition event="connection.connected">
      <log expr="'Caller has connected.  Executing Designer dialog now.'"/>
      <dialogstart src="'http://127.0.0.1:9992/CallRouter?vr.application.id=1'" type="'application/voicexml+xml'" dialogid="myDialogID"/>
    </transition>

    <transition event="dialog.exit">
      <log expr="'The dialog is now complete.  Exiting application.'"/>
      <exit/>
    </transition>

    <transition event="error.*">
      <log expr="'An error has occured (' + event$.reason + ').  Exiting application.'"/>
      <exit/>
    </transition>

  </eventprocessor>
</ccxml>

And there you have it — a basic application which launches a Designer dialog. Hopefully this will help shed some light on how developers can combine the utility of CCXML with the usability of Voxeo Designer.

Jeff Menkel
VXML Certified Developer

ShareThis

This blog covers some of the basic concepts about SIP servlet technology and demonstrate a simple SIP proxy server using SIP servlet programming model.

What is a Servlet and a Servlet Container?

A servlet is  a Java component which is managed by a servlet Container and which responds to messages of an application protocol.

A servlet container, typically part of an application server, manages the lifecycle of servlets, sends and receives the messages for servlets. It also provides other services such as security to servlets as well.

The following diagram shows the relationship of a servlet, servlet container, application server, and Java virtual machine.

When needed, the servlet container loads the servlet class, instantiates (a.k.a. new()) the servlet and invokes its init() method with the configuration in the form of ServletConfig object. Once initialized, the servlet is able to serve the messages. The servlet container repeatedly invokes the servlet’s service() method with the incoming messages in the form of ServletRequest and ServletResponse objects. The servlet container can deactivate a servlet by invoking its destroy() method and makes the servlet eventually be garbage collected.

As you can tell, the lifecycle of a servlet is rather simple. The service() method is where all the interesting actions are during its life. What a servlet does in its service() method fundamentally depends on the application protocol the servlet supports.

What is a HTTP and a SIP Servlet?

Simply speaking, a HTTP servlet is a kind of servlet that supports HyperText Transfer Protocol, and a SIP servlet is a kind of servlet that supports Session Initiation Protocol. If you are familiar with Object Oriented programming, you should be able to think of the following class diagram.

The latest HTTP servlet specification (and the generic servlet specification) is Servlet 2.5. The latest SIP servlet specification is SIP Servlet 1.1. You may notice that the APIs of both specifications are quite similar. However there are many subtle differences due to the differences of the protocols.

The most fundamental difference of a HTTP servlet and a SIP servlet is what a servlet can do in the service() method.

HTTP is a synchronous protocol where a HTTP servlet is expected to receive a HTTP request and respond with a HTTP response before it can serve another HTTP request. In the HttpServlet.service(HttpServletRequest request, HttpServletResponse response) method, a HTTP servlet is expected to process the request and write the output into the response within the method invocation.

SIP is an asynchronous protocol where a SIP servlet can receive a SIP request and response at any time. In the SipServlet.service(SipServletRequest request, SipServletResponse response) method, only one of the parameters - either the request or the response - is valid. The SIP servlet is expected to receive the request or response in the service() method but can either process it within the method invocation or save it for processing at a later time. A SIP servlet can also issue requests or responses at any time as long as the servlet is in the initialized state.

How to write a SIP servlet?

Writing a SIP servlet starts with creating a subclass of the SipServlet class. Instead of overwriting the service() method, you typically overwrite one of the doXXX() methods.

The doXXX() methods are defined to modularize the logic within the service() method. The default implementation of SipServlet.service() method calls one of the doXXX() methods based on the type of the message it receives. For example, for a SIP INVITE request, doInvite() method is invoked.

Because most of SIP protocol details, such as message parsing, retransmission, transaction and dialog management, are abstracted away from a SIP servlet, the logic with these doXXX() methods shall just focus on the high level functionality.

Here I demonstrate how easy it is to write a stateful SIP proxy with a SIP servlet - just 4 lines of code, including one optional line.

public class ProxyServlet extends SipServlet {
  public void doInvite(SipServletRequest request) throws ServletException, IOException {
    if (request.isInitial()) {
      Proxy proxy = request.getProxy();
      proxy.setRecordRoute(true); //optional
      proxy.proxyTo(request.getRequestURI());
    }
  }
}

In the doInvite() method, I first check to see if the request is an initial request - a request that doesn’t match any existing SIP dialogs. If true, I simply create a Proxy object out of the request. I can optionally invoke Proxy.setRecordRoute() method to indicate this SIP proxy records the route. Then just simply proxy the request to its destination by invoking Proxy.proxyTo() method with the original request URI.

That’s it - now I have a functional stateful SIP proxy. What about all the complex Proxy Behavior in RFC 3261? The SIP servlet container has taken care of most of the standard work once it knows the SIP dialog associated the INVITE request is intended for proxy. Isn’t this wonderful to an application developer?

How to build a SIP servlet application?

A typical SIP servlet application probably involves more than just one SIP servlet class. In order for the SIP servlet container to properly load and run a SIP servlet application, the application has to be assembled into a hierarchical directory structure with additional deployment descriptors, as shown in the following.

  |-- WEB-INF
  |     |-- classes  (where all the java classes are)
  |     |   |-- com
  |     |       |-- voxeo
  |     |           |-- sipmethod
  |     |               |-- tutorial
  |     |                   |-- one
  |     |                       |-- ProxyServlet.class
  |     |-- lib (where all the library JARs are, if any)
  |     |-- sip.xml (optional SIP deployment descriptor XML)
  |     |-- web.xml (optional HTTP deployment descriptor XML)
  |-- index.html (document files)

The root of the hierarchy is where all the documents, such as index.html, are, although there is none in this tutorial.

A special directory under root is WEB-INF, which is where all other stuff are, such as Java classes, libraries, deployment descriptors, etc.

All the Java classes including servlets shall be placed under WEB-INF/classes directory. The above diagram shows how ProxyServlet.class is placed. WEB-INF/lib is where all the third-party libraries (i.e. JARs) are, in which I don’t have any in this tutorial. All the deployment descriptors - sip.xml and web.xml - are also under WEB-INF directory.

A deployment descriptor is an XML file that conveys information about how the application is assembled and to be deployed. In other words, these are meta data about the application.

With the latest servlet standards, these meta data can also be specified in the Java classes using Java annotations. For example, to specify deployment information about the ProxyServlet, we add a class level annotation - @SipServlet - to specify the name for the servlet

@javax.servlet.sip.annotation.SipServlet(name="Proxy")
public class ProxyServlet extends SipServlet {
  ...
}

sip.xml is the deployment descriptor for all the SIP related meta data. Here I specify the application name, the default timeout value for proxy and the main servlet of the application. (These information can be specified using Java annotation as well.)

      <sip-app xmlns="http://www.jcp.org/xml/ns/sipservlet"
               xmlns:javaee="http://java.sun.com/xml/ns/javaee">
        <app-name>SIP Proxy Server</app-name>
        <main-servlet>Proxy</main-servlet>
        <proxy-config>
          <proxy-timeout>300</proxy-timeout>
        </proxy-config>
      </sip-app>

I don’t have web.xml in this tutorial. I will cover web.xml when talking about converged applications.

Typically we package the above directory structure into a Servlet Archive (SAR) using the standard Java Archieve (JAR) format, which is essentially a ZIP file. Here is the SAR file of the above SIP proxy sample.

How to deploy and run a SIP servlet application?

Deploying a SIP servlet application typically means deploying the SAR of the application to a SIP servlet container. Running the SIP servlet container typically runs all the SIP servlet applications deployed within that container.

The exact steps of deploying and running a SIP servlet application depends on which SIP servlet container and application server you use. The following steps are based on SIPMethod Application Server.

1. Make sure you have JDK 1.5 or later installed on your system.
2. Install SIPMethod Application Server 4.0 (beta). Let’s call where SIPMethod Application Server is installed <sm_home>.
3. Remove all all the files and directories under <sm_home>/apps. This step is to simplify the application routing since we haven’t talked about the concept of Application Router yet.
4. Copy the SAR file of the above sample into <sm_home>/apps directory.
5. Assuming environment variable JAVA_HOME is pointing to where the JDK is installed, running <sm_home>/bin/startup.[bat | sh] shall start SIPMethod Application Server.
6. Now your SIP proxy server is up and running.

To test your SIP proxy server, you can try any softphone that can be configured with an outbound proxy server. Once you configure SIPMethod Application Server as the outbound proxy server (by default, SIPMethod listens on port 5060 on all local IPs), the call made from the softphone shall be proxied through your SIP servlet based SIP proxy server to its destination.

Hopefully this blog gives you some basic ideas about SIP servlet programming. There are still quite a lot to be covered, such as converged applications, application composition, etc. So stay tuned for more SIP servlet programming blogs.

ShareThis

Hi, I’m Dustin, and I’m a VoiceXML Certified Developer. This is the part where you all clap and welcome me and we spend the next hour talking about our feelings. Since this is my first blog on the interweb, I’ll spare you the pain this time and skip right to the meat and potatoes.

In this week’s Developer’s Corner blog, we’ll explore Answering Machine Detection - or Call Progress Analysis(CPA) if you wanna get technical. The kicker here is we’re not writing a complex CCXML to do it. In fact, we’re not going to write a single line of code today; we’re gonna whip it all up real quick and easy like in Designer - it’s Shake and Bake™, and you helped.

This blog assumes you have some working knowledge of the Designer tool. If not, check out our starter tutorial about Designer. This blog is geared towards our hosted platform; if you’re using a Premise installation of Prophecy, check out the bottom of this post where I’ve detailed the differences.

So what is CPA?

The Voxeo Call Progress Analyzer (CPA) offers customizable answering machine detection.  It uses advanced Digital Signal Processing (DSP) and voice activity detection to analyze the audio signal after a call is connected, making it possible to programmatically determine if the answering party is a human speaker, an answering machine, a modem or Cylon. Ok, so I made the Cylon part up…that part’s still in beta. Voxeo recently enabled Call Progress Analysis(CPA or Answering Machine Detection) on its shared hosting platform for Evolution Designer, so we figured we should probably let you know how to use it.

Creating our Project

If you’re not already logged into Evolution, go ahead and do so now. Click Evolution Designer and this should open a new window with the manage projects popup. Select Create a new project, New Project and click Next. Go ahead and enter a name and description for your project here and click Save. We don’t need the ‘Start’ step, so left-click on it and select Remove. This should bring us back to our call flow with only one step: Initial Step. Go ahead and click on this and click the blue plus sign at the bottom.

This will bring up the create step dialog. Let’s name this step CPA Result, because we’re creative like that, and select Decision as the type. Back at the call flow diagram now, we should see our new step. Go ahead and click on it and click Add. Let’s name our first rule Human. Click Browse and select CPA Result from the Data Variable pull down and click Ok. We’re checking to see if our string equals human, so go ahead and type human in the box next to the VC icon and click Add Condition. Under Select Destination click the blue plus and create a Prompt step and name it Human, click Save and then Ok. Repeat the rule creation process again, instead using machine instead of human. We’ll also need to create a ‘When No Rules Apply’ step, so click the blue plus one more time and create a Prompt step called Unknown. This is where our callee will be sent if CPA can’t figure out what they are. With all that completed, our step should now look like this:

All that’s left to do know is edit our Human, Machine and Unknown steps. We’ll need to add TTS for each open, so open them up and click New Audio. In my example, I simply put ‘CPA says you are a human/machine/etc’ and selected the Destination as the Hangup step. You, however, are free to get fancy here and create human and machine specific logic and input steps. Once we’re done here, all that’s left to do is click Publish and map our project up in Application Manager.

On our Evolution start page, click Application Manager then Add Application at the bottom. We should have a few options for application type here but we’ll want to select Evolution Designer and click Next. Now we’ll just need to fill in a name for our app, select it from the pulldown, click Create Application and we’re just about set. If you don’t already have an Evolution Designer token, you’ll want to grab one from the Voxeo support team. Open a new support ticket in your account from the Evolution home page or send an email to support@voxeo.com with your account name and the application you’d like the token for. Once we have this in hand, we can start launching outbound Designer calls by popping the URL below in our favorite browser and replace YOURPHONENUMBER with the number you wish to dial and YOURTOKENID with the token ID provided to you by the support team.

http://api.voxeo.net/SessionControl/VoiceXML.start ?numbertodial=YOURPHONENUMBER &tokenid=YOURTOKENID &voxeo-cpa-maxtime=4000 &voxeo-cpa-maxsilence=1000 &voxeo-cpa-runtime=20000

So what do these settings mean? I’ll steal some information directly from our docs to explain:

• voxeo-cpa-maxsilence The ‘cpa-maxsilence’ parameter is used to identify the end of voice activity.  When activity begins, CPA will measure the duration until a period of silence greater than the value of ‘cpa-maxsilence’ is detected.  Armed with start and end timestamps, CPA can then calculate the total duration of voice activity.  A value of 800 to 1200ms is suggested for this parameter.
• voxeo-cpa-maxtime The ‘cpa-maxtime’ parameter is the “measuring stick” used to determine ‘human’ or ‘machine’ events.  If the duration of voice activity is less than the value of ‘cpa-maxtime’, the called party is considered to be ‘human.’  If voice activity exceeds the ‘cpa-maxtime’ value, your application has likely called a ‘machine.’  The recommended value for this parameter is between 4000 and 6000ms.
• voxeo-cpa-runtime The ‘cpa-runtime’ parameter specifies the maximum amount of time CPA should listen for events.  If the ‘runtime’ exprires, CPA will return an “unknown” result.  Therefore, ‘cpa-runtime’ should always be longer than the average answering machine outgoing message.  We recommend a value of at least 15000-20000ms.

Possible CPA events:

These will be populated to the CPA Result variable within Designer as a string value.

• human
• machine
• beep
• modem
• faxtone
• sit

Enabling CPA for Prophecy Designer

Enabling CPA for Designer on a Premise installation of Prophecy is fairly simple. The wrapper that handles all the logic is already there, we just need to tell Designer to look out for CPA result. Assuming you installed Prophecy in the default path, open up C:\Program Files\Voxeo\Designer\config\GlobalVariables.conf. At the bottom of this file, paste in this line: voxeo_cpa_result=CPA Result

That’s it. Restart the Designer service by clicking the Prophecy tray icon and select Restart Services and Voxeo Prophecy Designer.

Publishing your project on a Premise installation

Once you’ve clicked Publish on your completed Designer project, return to Management Console(Prophecy tray icon > Prophecy home > Management Console) and select the Call Routing menu option. Scroll down until you find the route named Designer. Click the App Name drop down and select your project. Verify App Version is set to Latest and then scroll to the bottom of the page and click Save Changes. To test our new outbound application, open the Prophecy SIP phone(Prophecy tray icon > SIP Phone), open up your web browser and paste in this URL:

http://127.0.0.1:9998/VoiceXML.start ?numbertodial=sip:user@127.0.0.0.1:5070 &tokenid=designer &voxeo-cpa-maxtime=4000 &voxeo-cpa-maxsilence=1000 &voxeo-cpa-runtime=20000

ShareThis

SIPMethod Application Server is a SIP application server based on SIP Servlet technology. Its latest release (beta 3) passes JSR 289 TCK, which means now SIPMethod is in full compliance with JSR 289 specification.

SIPMethod supports not only SIP servlets but also HTTP servlets and Web Service endpoints. It enables the development of converged applications - applications that mix VoIP, Web and SOA capabilities.

SIPMethod is available for download for evaluation purpose right now. Please do check it out if you are interested in building cool Web 2.0 applications with VoIP.

ShareThis

Note – this post demonstrates the use of VoiceXML subdialogs. The examples below were tested on the Voxeo Prophecy platform. To download the Prophecy software and run these examples locally, go to http://www.voxeo.com/prophecy/.

What are Subdialogs?

Subdialogs are a powerful, but often misunderstood, part of the VoiceXML specification that can be used to create reusable components for telephone applications.

The official W3C VoiceXML specification defines subdialogs thusly:

A subdialog is like a function call, in that it provides a mechanism for invoking a new interaction, and returning to the original form. Variable instances, grammars, and state information are saved and are available upon returning to the calling document. Subdialogs can be used, for example, to create a confirmation sequence that may require a database query; to create a set of components that may be shared among documents in a single application; or to create a reusable library of dialogs shared among many applications.

One of the most confusing aspects of subdialogs is that they run in a completely separate execution context from the dialog that invokes them (the parent dialog). However, once developers get over this conceptual hurdle, the real power of subdialogs becomes apparent.

Fun with Subdialogs

One of the things I like most about subdialogs is their reusability. I often find myself in situations where I need to collect input from a caller in several steps that are generally the same (i.e., a series of digits), but each has a specific validation requirement.

For example, in order to process a credit card payment there are several pieces of information that need to be obtained form a caller – credit card number, CVV number, expiration date, etc. All have the same common characteristic that they are a series of digits, but all have unique verification requirements. Valid credit card numbers have specific lengths and must pass a “mod 10″ check. CVV numbers are specific lengths for different card types.

As with a typical function call in any programming language, parameters can be passed into a VoiceXML subdialog when it is invoked. These parameters often take the form of a string of text to be read out to the caller, or a number that is used to count actions. However, we also have the option of passing more complex data types into a subdialog call

We can pass JavaScript arrays and custom object into a subdialog, or we can pass some of the native object types in JavaScript. For example, every function that is declared in JavaScript is also an instance of the JavaScript Function Object. So a JavaScript function that is declared in a parent dialog can be passed into a subdialog as a parameter.

For example, consider the following simple subdialog:

<form id=”S_1″>

<!– Parameters passed into subdialog –>
<var name=”myPrompt” />
<var name=”myFunction” />

<catch event=”noinput nomatch”>
  <prompt>That was not valid input. Try again.</prompt>
  <reprompt/>
</catch>

<field name=”getInput” type=”digits”>

 <prompt><value expr=”myPrompt”/></prompt>
  <filled>
    <if cond=”myFunction(getInput)”>
     <return namelist=”getInput”/>
    <else/>

     <clear/>
     <throw event=”nomatch”/>
    </if>
  </filled>
</field>

This subdialog accepts two parameters – a prompt that is read out to the caller, and a function that is used to validate the input. The conditional logic in the <filled> block assumes that the function returns a boolean (true/false).

This same subdialog structure can be used to collect input that meets a wide range of validation criteria. To use this subdialog to collect a 5-digit zip code, we would set the parameters as follows:

// JavaScript function to determine length of a string variable
function isFive(x) {
  if (x.length == 5 ) {
    return true;
  }
return false;
}

<var name=”myPrompt” expr=”‘Please enter your five digit zip code.’”/>
<var name=”myFunction” expr=”isFive”/>

To use this subdialog to collect and validate a credit card numbers, we would set the parameters as follows:

// JavaScript function to perform a mod 10 check
function mod10Check(x) {
    // logic of mod 10 check
    return true;
}
return false;
}

<var name=”myPrompt” expr=”‘Please enter your credit card number.’”/>
<var name=”myFunction” expr=”mod10Check”/>

A sample VoiceXML document, demonstrating how this same basic subdialog can be used to collect different kinds of input can be found here.

As this discussion shows, subdialogs are a tremendously powerful tool that can enhance the reusability of code and reduce the maintenance requirements of telephone applications. So, if you find yourself in a situation where you need to collect the same type of input from a caller several times during a call flow, take a look at subdialogs.

Their power and reusability have the potential to make your life a lot easier.

ShareThis

This was just a short little demo that was designed to show how VoiceXML can be used with embedded JavaScript/ECMAScript. It performs three basic steps:

• Connects to www.istwitterdown.com

• Uses JavaScript to parse the result
• Relays result to caller using Text-To-Speech

If you’d like to hear it, you can actually call it - but do note the Big Caveat noted farther down in the article - at either of these numbers:

• 1-206-701-7091
• sip:9996078017@sip.voxeo.net
• skype:+990009369996078017

WALKING THE CODE

So let’s take a walk through the code. The first part is simply the initial VoiceXML starting statements, a declaration of a variable called “MyData” and the start of a form called “F1″:

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1">
  <var name="MyData"/>
  <form id="F1">

The next part is a JavaScript function that uses the JavaScript “getElementsByTagName” function to walk the HTML of the page that is loaded in:

    <script>
      <![CDATA[
          function GetData(d,t,n)  {
            return (d.getElementsByTagName(t).item(n).firstChild.data);
          }
      ]]>
    </script>

Now I can’t claim credit for this code - I really just modified the example provided in the VoiceXML documentation for the <data> element. The way to think about it is this - the system loads the entire document requested by the <data> element into memory as an XML tree (even though it is in fact HTML). The ‘getElementsByTagName’ function then walks the XML tree to find the tag requested.

Let’s look at how I called the function to see how this makes sense:

    <block>
      <data name="MyData" src="http://www.istwitterdown.com/"/>
      <assign name="status" expr="GetData(MyData,'a',0)"/>

Now the first line uses the <data> command in VoiceXML to retrieve the contents of the web page at www.istwitterdown.com and assign that to a variable called “MyData”.

The second line calls the JavaScript function above with the “MyData” variable and says that I am interested in all the <a> tags and specifically the first <a> tag (numbered “0″). Now to figure out what tag I wanted, I didn’t honestly do anything overly brilliant. I just went to www.istwitterdown.com, did a “View Page Source” in my browser and then looked for where the word “No” appeared in the body text. Now this site happens to have a very simple page structure and so finding the node to use was trivial:

<body>
<h1><a href="link removed">No</a></h1>

So the site had the content I wanted (”No” or “Yes”) right in the very first <a> tag. Filling in the contents of the getElementsByTagName call with the variables sent to the JavaScript function, it looked like this:

d.getElementsByTagName('a').item(0).firstChild.data

Which translates to wanting the “data” of the first <a> tag in the document. In this case, “No” or “Yes”.

This data is then assigned to the VoiceXML variable “status”.

The rest of the VoiceXML app is then simply branching on what the “status” variable is. If it is “No”, then Twitter is up. (A bit of a double negative kind of thing going on.) If it is anything else, the site is down:

      <if cond="status=='No'">
          <prompt>Twitter is currently up.  Yea!</prompt>
      <else/>
          <prompt>Twitter is currently down. </prompt>
      </if>
    </block>
   </form>
</vxml> 

I then close off the block, the form and the VXML file. Note that I could have checked to see if status==’Yes’ but I just made the assumption that if it was not “No” then there was a problem with Twitter.

THE BIG CAVEAT

Which does bring me to the big caveat of this application - because I was relying on some other web site (istwitterdown.com in this case) I made a big assumption that the external site would work!

It didn’t.

When I was out at OSCON, I was delighted by the fact that at one point Twitter was actually down! However, throughout all the time that Twitter was down and despite multiple browser hard refreshes, the www.istwitterdown.com site always said “No”, meaning Twitter was up.

Oops.

Now, the site did work in the past. I know because I used it successfully when Twitter was going up and down earlier this year. However, sometime along the way whatever logic the folks at the site were using to detect that Twitter was down seemed to stop working. Or, at least it stopped working on the day that I was testing it. Maybe it’s working now… I don’t know… the good news is that Twitter hasn’t been down much at all in recent weeks.

Anyway, it’s a good lesson that if you rely on external sites, you do need to ensure that the external site is in fact giving you the correct data that you want.

WRAPPING UP

I hope this little example gave you a useful glimpse into how VoiceXML’s <data> tag can be used to pull in web pages and how JavaScript can be used to parse those web pages. More information can be found on the VoiceXML documentation page for the data element. I would encourage you to read both the main documentation page as well as the comments to that page.

In my next blog posts walking through my subsequent OSCON 2008 demos, I’ll explore what else can be done with the data element and other tools. Stay tuned…

THE WHOLE CODE

For those of you who want to do a straight copy-and-paste to play with the code, here it is in its entirety:

<?xml version="1.0" encoding="UTF-8"?>
<vxml version = "2.1">
  <var name="MyData"/>
  <form id="F1">
    <script>
      <![CDATA[
          function GetData(d,t,n)  {
            return (d.getElementsByTagName(t).item(n).firstChild.data);
          }
      ]]>
    </script>
    <block>
      <data name="MyData" src="http://www.istwitterdown.com/"/>
      <assign name="status" expr="GetData(MyData,'a',0)"/>
      <if cond="status=='No'">
          <prompt>Twitter is currently up.  Yea!</prompt>
      <else/>
          <prompt>Twitter is currently down. </prompt>
      </if>
    </block>
   </form>
</vxml> 

Technorati Tags:
voicexml, voxeo, javascript, ecmascript, oscon, oscon2008

ShareThis

• CCXML Workshop, Part 1

• CCXML Workshop, Part 2

Each video runs between 1 to 1.5 hours and are part of a half-day tutorial session that Moshe gave a year ago at SpeechTEK 2007.

Technorati Tags:
tutorials, ccxml, voicexml, speechtek, voxeo

ShareThis

Please do check it out if you are interested in seeing the future of our application platform - and please do send along any comments and feedback that you have. We definitely do appreciate it all.

Technorati Tags:
voxeo, prophecy, windows, linux, macosx

ShareThis

First lets get a proper definition for variable scope.  The scope of a variable defines when and where the variable exists and may be accessed. When the VXML browser exits the scope where the variable is defined, the variable is out-of-scope and cannot be accessed. When a variable is in scope, it can be accessed by both VoiceXML and ECMAScript.

Here is a table of the different scope levels of variables in VXML:

Scopes	Declared In	Initialized In	Where accessible	Becomes Unavailable
Session	By the VXML browser	At the beginning of a session	Anytime during the session	At the end of the session
Application	In the root document	When VXML browser loads the root document	Throughout the application	When the VXML browser leaves the root document
document	In the <vxml> document	When the VXML browser loads the document	Within the <vxml> element	When VXML browser leaves the document
dialog	In the <field> element of a <form> or <menu> element	When the VXML browser loads the element	Within the element	When the VXML browser leaves the element
anonymous	In a <block>, <filled> or <catch> element	When the VXML browser begins to interpret the element	Within the element	When the VXML browser leaves the element

Here is an example of document scoped variable.  As you can see it is accessible throughout the current VXML document.

<?xml version=”1.0″?>
<vxml version=”2.0″>

<var name = “counter” expr = “0″/>

<form id=”F_1″>
<!– additional VXML code –>
<filled>
<assign name=”counter” expr = “counter + 1″/>
</filled>
</form>

<form id=”F_2″>
<!– additional VXML code –>
<filled>
<assign name=”counter” expr = “counter + 2″/>
</filled>
</form>

</vxml>

Here is an example of a dialog scoped document.  In form “F_1″ the value of “counter” after the assign <element> would be 1.  In form “F_2″ the value after the <assign> value would be 2.

<?xml version=”1.0″?>
<vxml version=”2.0″>

<form id=”F_1″>
<!– additional VXML code –>
<filled>
<var name = “counter” expr = “0″/>
<assign name=”counter” expr = “counter + 1″/>
</filled>
</form>

<form id=”F_2″>
<!– additional VXML code –>
<filled>
<var name = “counter” expr = “0″/>
<assign name=”counter” expr = “counter + 2″/>
</filled>
</form>

</vxml>

It is also good to know that variable references will match the closest applicable scope. You can prefix a reference with a scope name, such as application.counter, for clarity or to resolve ambiguity.

We hope this clears up a little confusion about VXML variables and where they are defined and when they can accessed.

Jeremy Richmond
VXML Certified Developer

ShareThis