Hello this is your Traffic Manager speaking!

As a fun experiment and to highlight ZXTM's flexibility in hosting applications I decided to make ZXTM speak with the help of an API provided by an interesting company Twilio.

Twilio are a company providing an in-cloud API for voice communications. With their REST API you can make and receive automated calls which provide scripted dialogs. This got me thinking...what if I could call my ZXTM and get a status update? You can with the following piece of jiggery-pokery :-)

In this article I'm going to use ZXTM to host my application, you don't have to, in fact you can use any Java servlet runner but I'm using it for convenience. In addition to ZXTM I'm going to be using the language Scala. Hopefully it'll nicely follow-up my previous article on Knowledgehub with a bit more code to show how elegant the language is. The last thing you'll need is Apache Axis which we'll use to talk over SOAP to our ZXTM; more information about this can be found here and here.

First thing you'll need a trial Twilio account, you can sign-up at www.twilio.com

Now you need to set up a virtual server on your ZXTM to host the application. The 'Manage a new service' wizard is your quickest route here; pick an unused port like 9000 and use any node you like. The node does not matter as our application will be handling all requests and none will be forwarded to a backend node.

Log into your Twilio account and go to your Dashboard. On your Dashboard will be a section called 'Your Trial Sandbox'; here you have four pieces of information namely the public phone number you'll be talking to your ZXTM on, the access pin code, the URL where your application is going to be hosted and your remaining free testing credit. To let Twilio access your application update the 'USES URL' to point to your ZXTM and the Virtual Server you have created; something like "http://my.zxtm.cloud.server:9090/" where you use the publicly accessible hostname or IP address of your ZXTM.

We are not ready to call that number yet, we need to sort out our app first. Ok so let's take a very simple example, we want to phone up and ZXTM say "Hello most excellent Zeus user", because using Zeus makes you pretty excellent :-) To do this we need to respond to the HTTP POST calls the Twilio service sends to us with the script we want it to enact. So to reply with our simple greeting we need to reply with the XML message,

<Response>
   <Say>Hello most excellent Zeus user</Say>
   <Hangup/>
</Response>

A simple little Scala Extension would look like this,

class Twilio extends HttpServlet
{
   val xmldec = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
   val message =
<Response>
   <Say>Hello most excellent Zeus user</Say>
   <Hangup/>
</Response>
 
   override def doPost(req: HttpServletRequest, res: HttpServletResponse) {
      res.setContentType("text/xml")
      val out = res.getWriter
      out.println(xmldec)
      out.println(message)
   }
}

This I think showcases Scala's inline XML declaration quite well. Escaping and concatenation is a problem that just disappears. To help testing you may wish to add a doGet method to your servlet with the same calls as your doPost method, that way you can test the output of your app in isolation and in your browser. In fact the next thing you should do is compile, package and upload your app to ZXTM and test whether you get the correct XML back. You should compile your Scala in the normal way,

> scalac Twilio.scala

and package up your class files into a Jar for easy deployment.

> jar cf Twilio.jar *.class

For more information on deploying Extensions to ZXTM please have a look here.

Once your very simple example is working it is time to start extending our dialog to do something more useful but still just as flattering. The next trick is to gather some input from the user. We do this with the 'Gather' verb in Twilio speak. Let's give the caller two options to choose from in our dialog.

<Response>
   <Say>Hello most excellent Zeus user</Say>
   <Gather action="react" numDigits="1">
      <Say>Press one for node error summary</Say>
      <Say>Press two to set Z X T M throttling</Say>
   </Gather>
   <Hangup/>
</Response>

What we are trying to achieve with this is to collect 1 digit of input from the caller while saying the two 'Press X' statements then enact the action which is to post the data to '/react' in our application. Input from the caller stops the call and it is over to our app to decide what to do next.

class Twilio extends HttpServlet
{
   val xmldec = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
   val firstmessage =
<Response>
   <Say>Hello most excellent Zeus user</Say>
   <Gather action="react" numDigits="1">
      <Say>Press one for node error summary</Say>
      <Say>Press two to set Z X T M throttling</Say>
   </Gather>
   <Hangup/>
</Response>
 
   val hangupmessage =
<Response>
   <Hangup/>
</Response>
 
   override def doGet(req: HttpServletRequest, res: HttpServletResponse)
   { dispatch(req,res) }
   override def doPost(req: HttpServletRequest, res: HttpServletResponse)
   { dispatch(req,res) }
 
   override def dispatch(req: HttpServletRequest, res: HttpServletResponse) {
      val out = prep(res)
      req.getRequestURI match {
         case "/" => initial_request(out)
         case "/react" => react(req,out)
         case _ => hangup(out)
      }
   }
 
   def initial_request(out: PrintWriter) {
       out.println(xmldec);
       out.println(firstmessage);
   }
 
   def react(req: HttpServletRequest, out: PrintWriter) {
      // Handle the input from user
   }
 
   def hangup(out: PrintWriter) {
       out.println(xmldec);
       out.println(hangupmessage);
   }
 
   def prep(res: HttpServletResponse) = {
      res.setContentType("text/xml")
      res.getWriter
   }
}

Our dispatch function above uses Scala's pattern matching to select the function to call used to handle a particular URL on which the Twilio service contacts us. In the catch all case we choose to hangup the call. Using a little more pattern matching we can flesh-out our 'react' function.

def react(req: HttpServletRequest, out: PrintWriter) {
   // Handle the input from user
   val Digit = req.getParameter("Digits")
   Digit match {
      case "1" => play_errors(out)
      case "2" => apply_throttle(out)
      case _ => hangup(out)
   }
}

The contents of our 'play_errors' function needs to contact ZXTM over SOAP to get the current node errors. I'm going to be using Apace Axis for this example, for fuller details on using this with Scala check here. The first thing is to setup a simple class that accesses the Diagnosis SOAP API.

object DiagSOAP {
   val username = "admin"
   val pass = "admin"
   val host = "localhost"
   val port = 9090
   lazy val soap_port = init
 
   def init = {
      // Boilerplate to silence errors about ZXTM's default self-signed cert
      Security.addProvider( new MyProvider )
      Security.setProperty( "ssl.TrustManagerFactory.algorithm",
                            "TrustAllCertificates" )
      val dl = new DiagnoseLocator
      dl.setDiagnosePortEndpointAddress(
		"https://"+username+":"+pass+"@"+host+":"+port+"/soap")
      dl.getDiagnosePort
   }
 
   def getNodeErrors = {
      val FullErrors = soap_port.diagnoseSystem( Diagnose.ErrLevel.ERR_SERIOUS )
      FullErrors.getFailedNodes
   }
}

We can now put this to good use.

def play_errors(out: PrintWriter) {
   val nerrs = DiagSOAP.getNodeErrors
   var str_errs = List("Currently there are no node errors")
   if( nerrs.length > 0 ){
      str_errs = List.fromArray( nerrs.map(s => format_node_error(s)) )
   }
   val payload = str_errs.map(s => say(s)).mkString("\n")
   val response =
<Response>
   {payload}
   <Hangup/>
</Response>
   out.println(response)
}
 
def format_node_error(err: DiagnoseFailedNode) = {
   "Node "+err.getIpAddress+" port "+err.getPort+
	" failed with the message "+err.getErrorMessage
}
 
def say(s: String) = {
<Say>
{s}
</Say>
}

So that illustrates getting and formatting any node errors that there may be raised on your ZXTM. The best thing now is to compile this up and get dialing :-) I have omitted the implementation of setting up throttling, my full implementation of this example can be found here. There are also a great many considerations I have omitted from this article, error handling and securing the service with a PIN are the first two that come to mind.

We have setup ZXTM to receive calls and act on them, I look forward to playing with Twilio's outbound call API when it is available here in the UK so I can show you how to get ZXTM to call you when events happen, using ZXTM's powerful Alerting infrastructure ;-)

Dec [Zeus Dev Team] 19 August 2009