….::: VOX POPULI :::….

Open311 Goes Big Time

Posted by Mark Headd under Open Government, Open Source, Standards

This was a big week for the Open311 initiative. Federal CIO Vivek Kundra joined Gov 2.0 rock star Mayor Gavin Newsom from the City of San Francisco to announce a national initiative to adopt a common standard for a 311 API.

The number of supporters for the initiative is growing, and I think it’s high time that developers started getting in on the act.

There isn’t a publicly available sandbox (that I am aware of) for developers to use to develop Open311 applications. The Open311 website, however, has some detailed information on the API standard as well as some sample XML responses that the API will provide.

Based on this information, I’ve started working on a set of PHP classes for interacting with the Open311 API. It’s still rough, and it will obviously undergo many changes as more information on the API is developed, and public test infrastructure is set up.

Still, its a start (and it was fun to write!) - I’m hopeful that others will help develop this set of classes. Hit me up at mheadd [at] voiceingov.org if interested.

Cloudvox: Cloud Telephony Applications Made Easy

Posted by Mark Headd under Development Tools, Open Source, Tutorials

A couple of months ago, I did a quick write up on a new cloud telephony company named Cloudvox. In the interim, I’ve been doing some playing around with their HTTP/JSON API for creating telephone applications, and I’ve been blown away by how simple and powerful a tool it is for building sophisticated cloud telephony applications.

This post will provide a quick overview of how the Cloudvox JSON API can be paired with PHP and the delightfully awesome Limonade Framework. If you’re not a PHP developer don’t despair - this example can easily be ported to other languages like Ruby (using Sinatra) or C# (using Kayak).

Cloudvox API Helper Classes

When writing apps for the Cloudvox JSON API, there are two things that we need to manage - the JSON that we will send to Cloudvox (using plain old HTTP) and the response Cloudvox sends back to our app (this will include any user input collected from the caller, and also things like a unique identifier for the call, caller ID and other information about the call).

To make managing both sides of our exchange with Cloudvox easier, I’ve created a set of PHP classes that can be used with any standard PHP IDE to make writing Cloudvox JSON and parsing Cloudvox responses simple and easy. You can download this class library from GitHub.

Using these classes is pretty straightforward:


< ?php
include('cloudvox-json-http-classes.php');
$speak = new Speak("Hello world!");
$hangup = new Hangup();
Output::renderJSON($speak, $hangup);
?>


Will render:

[{"name":"Speak","phrase":"Hello world!"},{"name":"Hangup"}]

Required properties are included in the constructor for each class - in most IDE’s this means that you can simply use Shift + Control + Space Bar when you create a new instance of the object to see what properties are required.

Optional properties on all classes are handled by using the PHP __set() method in the base class. This effectively let’s you overload the object and set properties which are not declared in the class definition. So for example, if we wanted to collect input from the caller (e.g., their zip code) we would use the GetDigits class, and overload it to add a URL to post the results to:


< ?php

// First argument passed into the constructor sets # of digits to collect.
// Second argument sets the timeout.
$getDigits = new GetDigits(1,5);

// Now we overload the object to add a URL to post the results to.
$getDigits->url = “http://somehost.com/myscript.php”;

?>


The problem with overloading in PHP is that you don’t get the benefit of having your IDE display overload options (it can’t because the properties that we wish to set are not declared in the class definition). There also isn’t any way to control what overloaded properties get set, so its possible to add things the Cloudvox won’t understand.

I’m not sure there is any way around this given the way that PHP has implemented overloading. I do plan to work on a set of Cloudvox classes using another language that handles overloading a bit better, like C#, but for now you should only overload to set the url and method properites for classes that can use them (see the Cloudvox docs for more details).

Sipping on some Limonade

If you know of the excellent Ruby Framework Sinatra but you want to code your project in PHP, fear not - check out the equally excellent PHP framework called Limonade. It’s the functional equivalent of Sinatra for PHP.

Using Limonade with our set of Cloudvox JSON classes makes building cloud telephony applications very simple. The biggest benefit is that you don’t have to split up the different steps in your application (i.e., collecting input, validating input, re prompting, etc.) into different PHP files (which can be kind of a pain) - all of your steps can be contained within a single file.

Limonade lets you set a URL “route” that Cloudvox can send HTTP requests to with results, and to get rendered JSON for another application step. For example:


< ?php

dispatch_get('/start', 'cloudvox_start');
function cloudvox_start() {

$speak = new Speak("Hello world!");
$hangup = new Hangup();
Output::renderJSON($speak, $hangup);

}

?>


This “Hello World” example - defined in a script named sample.php - could be accessed by hitting http://somehost.com/index.php?/start. To make things easier, we’ll use a little Apache magic to allow URL rewriting:

This will let us access the above URL by hitting http://somehost.com/index.php/start.

A simple demo app using the Cloudvox JSON helper classes and the Limonade Framework can be seen below. You can use this sample application with a new Cloudvox account to get started building cloud telephony applications.

This simple app demonstrates how powerful the Cloudvox JSON API is for creating cloud telephony apps. When coupled with an elegant framework like Limonade, sophisticated, cloud-based telephony applications are readily available to any developer that wants to build one.

The helper classes for the Cloudvox API are obviously a work in progress, so if anyone reading this has comments or suggestions feel free to let me know - mheadd [at] voiceingov.org.

XHP for VoiceXML

Posted by Mark Headd under Development Tools, Open Source

Facebook has been busy lately doing all sorts of interesting things to the PHP scripting language. Although most of the recent PR hype was centered around HipHop for PHP (a name that, quite frankly, makes me want to use it less), Facebook also released another very interesting and potentially useful extension for PHP - XHP. From the XHP wiki on Github:

XHP is a PHP extension which augments the syntax of the language such that XML document fragments become valid PHP expressions. This allows you to use PHP as a stricter templating engine and offers much more straightforward implementation of reusable components.

Not sure where I read it, but one commenter compared XHP to E4X in JavaScript. It’s a neat idea, and its actually not all that hard to start playing around with XHP (if you’re comfortable installing PHP extensions).

After thinking about XHP and playing around with it a bit, I started to think it might be useful as a way of generating not just HTML, but also other XML-based languages like VoiceXML.

The core XHP classes that are used for generating HTML are fairly easy to understand, once you get use to the syntax - extending these core classes to generate VoiceXML (or any other XML-based language) is not all that hard. But before we do that, let’s install XHP as a PHP extension and kick the tires a bit.

Installing XHP on Ubuntu

I’ve tried the following instructions on both Ubuntu 8.04 and 8.10, and I’m pretty sure they’ll work with just about any recent Ubuntu version.

Make sure you’ve got the basics for building PHP extensions:

$ sudo apt-get install build-essential
$ sudo apt-get install php5-dev

Get the XHP source code:

$ mkdir xhp
$ cd xhp
$ git clone git://github.com/facebook/xhp.git

Get the PHP source code

$ sudo apt-get source php5

Make a directory in the PHP source code for the XHP extension

$ mkdir php-5.X.X/ext/xhp
$ cp -r xhp/xhp/* php-5.X.X/ext/xhp/

Depending on your system, you may need to add some of the prerequisites for building this extension:

$ sudo apt-get install flex bison

I tried this approach on both Ubuntu 8.04 and 8.10 and in both cases only version 0.13.5 of re2c worked (earlier version obtained via apt-get did not cut the mustard). If you’re running a later version, you may be able to get this version of re2c from the standard repos.

For this example, I’ll just build it from source:

$ wget http://sourceforge.net/projects/re2c/files/re2c/0.13.5/re2c-0.13.5.tar.gz/download
$ tar -zxvf re2c-0.13.5.tar.gz
$ cd re2c-0.13.5/
$ ./configure
$ sudo make
$ sudo make install

Move to new XHP extension directory and get ‘er done.

$ cd php-5.X.X/ext/xhp
$ phpize
$ ./configure
$ sudo make
$ sudo make install

When you run make install, the new extension file is placed in a directory where Apache can load it - however, we need to modify the php.ini file so that Apache is aware of the extension. Open php.ini and add the following:

extension=xhp.so
extension_dir=directory_where_xhp.so_is_located

When setting this last option, use the directory where xhp.so was placed by make install. Now we just restart Apache:

$ sudo /etc/init.d/apache2 restart

Easy right? Unfortunately, things get a little less clear at this point. It turns out that to make XHP work properly, some PHP libraries need to be included in any of the XHP scripts we write. These files are located in the php-lib directory of the XHP source code.

To make things easier (especially when we start to write our own extension to XHP for VoiceXML, lets move these files to a convenient local directory that we can include in our scripts:

$ cp php-5.X.X/ext/xhp/php-lib/* my/local/directory/php-lib/

So now we can do some interesting stuff like this:

What’s especially interesting about XHP is that it enforces proper syntax at compile time, so if your markup isn’t syntactically correct an exception gets tossed.

Generating VoiceXML with XHP

The XHP libraries we just discussed implement the HTML spec out of the box. However, if you try and render tags that are not part of the HTML spec an exception will occur. I wanted to find out how hard it would be to extend the concepts behind XHP for other markup languages, like VoiceXML. Turns out, its not hard at all.

If you look at the init.php file that is included in the example above, you’ll see its in turn including a file called html.php, which defines all of the HTML elements that can be rendered by XHP, the attributes that each can have and also the parent-child relationship between elements.

Using this is a guide (the syntax is new but fairly easy to follow), I knocked out a quick class file for some basic VoiceXML elements - just to illustrate the concept:

This is admittedly rough, and it only covers a few basic VoiceXML elements, but it demonstrates that extending XHP to render VoiceXML is actually quite easy. To use this file, simple edit the init.php file mentioned previously and add an include statement:

< ?php
require_once 'core.php';
require_once 'html.php';
require_once 'vxml.php';
?>

Now we’re ready to use XHP to generate VoiceXML:

How cool is that?

I’m still toying around with XHP, but this little experiment clearly shows that it has use beyond just simply rendering HTML. I’d be interested in hearing from other developers - is this worth a full blown project to flush out a complete VoiceXML class library for XHP? What other markup languages would make good candidates for this same type of approach?

Post a comment here, a tweet to @mheadd or shoot a quick e-mail to mheadd [at] voiceingov.org with your thoughts or comments.

A Governor Tweets: Propaganda or Engagement?

Posted by Mark Headd under Open Government, Twitter

According to the one and only tweet in his account, Delaware Governor Jack Markell will “officially” join the Twitterverse at an upcoming event on February 3rd.

Although I imagine the public relations potential of Governor Markell joining the scores of other federal, state and local officials on Twitter is not lost on his staff, if the Governor is serious about embracing Twitter it could open up a new way for citizens to engage and communicate with him.

So, as the Governor prepares to “activate” his Twitter account, it makes sense for the citizens and taxpayers he serves in Delaware (particularity those of us that tweet) to ask whether this will mean propaganda or engagement.

WonderTwit powers, activate!

The Governor’s first tweet doesn’t bode well (in my mind anyway) for those of us eager to see his new account used to engage citizens and encourage communication with taxpayers.

I find the notion of “launching” a Twitter account that has already been created a bit odd. There is no way that I am aware of to create an “inactive” Twitter account – inactive accounts are those that Twitter considers abandoned.

By virtue of having a Twitter profile, the Governor’s account is indeed active. He could send tweets from it now, and could have sent tweets from it starting on the date it was first activated - June 19th, 2009 - a full 228 days prior to the date of this post.

However, even if the Governor has chosen not to tweet since last June, because his account is active anyone that uses Twitter can send a message directly to him by formatting a Tweet as a @reply (technically referred to as a “@mention” by Twitter).

I did this very thing not too long ago, sending a link I hoped the Governor would read before “officially” joining the Twitterverse.

Still waiting on a response…

Twitter engagement and communication

The @mention feature of Twitter is not one that can be turned off. Everyone has the ability to view tweets that @mention them by simply going to the proper tab on their Twitter home page (its worth noting that any one of the many Twitter clients can make checking, organizing and responding to @mentions quite easy).

It is this feature that has attracted people (like myself) interested in leveraging Twitter as a way to send messages directly to elected officials.

In early 2009, I develop a service called Hear Me Say This which uses IVR technology with Twitter to allow people to send recorded messages to members of Congress. Other people have taken this same approach to send messages directly to elected officials on Twitter using @mentions.

The critical issue for any elected official that uses Twitter is how they will handle tweets that @mention them. They are a potentially useful tool for citizens and activists because they can be sent directly to the official who owns the account (unless that official wants to fess up that someone is ghost tweeting for them). They can also be used to develop support for a cause or issue because friends and followers can retweet status messages (including those that @mention others).

Some elected officials may bank on the fact that responding directly to @mentions from their constituents can be portrayed as being unreasonable burdensome. One can certainly understand why the Governors of California or Michigan (both of whom are prolific tweeters) might be able to get away with not reposing to @mentions (for the record, I don’t know that they do).

However, most Delawareans have different expectations about personal interactions with their elected officials.

Only in Delaware…

Delaware’s small size, concentrated population and cordial political environment come together to create an atmosphere where it is not uncommon to bump into an elected official on the street, or at the gym, or in a store and engage them in a conversation.

Its not uncommon to bump into a Governor, a U.S. Senator or a Member of Congress while out for a jog (I once passed Congressman Mike Castle running at a park near my house), at the gym (I had a nice conversation with Senator Tom Carper between reps at the YMCA about the health care bill several weeks back) or at a gas station (I once stood in line with Joe Biden at a Greenville gas station).

Delaware isn’t a place where elected officials can get away with being insulated from citizens by surrounding themselves with an entourage or a group of handlers. People here aren’t surprised when they run into an elected official at the gas station or the corner store, and I think many expect to be able to interact with them.

So its only logical to ask whether this same type of interaction will work when Governor Markell officially “launches” his Twitter account.

It can work if the Governor decides (as many forward thinking politicians on Twitter already have) that using social networking services like Twitter will provide new opportunities for transparency and citizen contact.

Will the Governor respond to the following when he attends the upcoming Delaware Tweetup on February 3rd:

• Does he intend to use his Twitter account personally (even if he isn’t the exclusive user of the account) as a way to make his administration more open, transparent and receptive to citizen communication?
• Will he commit to responding to Twitter @mentions that appear to be from legitimate Twitter users, or from Delawareans that have an actual question, problem or complaint?

Whether or not Delaware’s somewhat unique brand of political interaction will work when our Governor starts tweeting is entirely up to him, and how he decides to use his newly “activated” Twitter account.

Unfortunately, I won’t be able to attend the event on February 3rd, but I sure would appreciate a response to my tweet.

Twitter, Facebook, Geotagging and 311

Posted by Mark Headd under Open Government, Twitter

Several weeks back, I wrote a quick post about the new locational functionality being rolled out in Twitter. Now that this new functionality is being supported by more and more Twitter clients, I think its time for an object lesson in how Twitter’s new locational feature (and soon Facebook’s) can be used to engage citizens to submit 311 service requests.

Consider the following Tweet (sent using TweetDeck for iPhone):

Here is the data behind this Tweet in XML format, courtesy of the Twitter API:

Does this Tweet contain enough information to start a 311 Service request (and by “start” I mean via some application logic that automatically parses 311 tweets and requires no human intervention)?

It has a hashtag describing the nature of the request (#pothole), a URL to a picture of the offending pothole (admittedly a pretty wimpy one) and it also has the lat/long of the location where I took the picture. All together, it took me about 15-20 seconds to take the photo, geotag the Tweet and compose the message.

The Twitter API provides some background information on me, in the event that the government handling this kind of a service request wants or needs it. If there was really a need for more, it wouldn’t be all that hard to build a Twitter BOT to interact with the person Tweeting the service request and get any additional information that was required.

One of the primary benefits for governments from deploying a 311 API, or working with companies like CitySourced or SeeClickFix is that it can help engage (and empower) citizens to report service requests. If it’s quick, easy and convenient to report 311 requests, people will do it and they are more likely to be satisfied with the experience (something that doesn’t always happen when citizens interact with government).

The new locational feature of Twitter (and soon of Facebook) will provide governments with a very effective way of empowering citizens to report 311 service requests.

It will be interesting to see how many of the them leverage this as part of their 311 services.

NoSQL Telephony with Tropo and CouchDB

Posted by Mark Headd under CouchDB, Development Tools, Open Government, Tutorials

In the last two posts, I’ve provided a basic overview of how to create cloud telephony applications using the Tropo platform and CouchDB.

In the first post of this series, I walked through a quick install of CouchDB and provided information on getting a Tropo account set up. In the second post, we created a simple auto attendant Tropo script in PHP that populates a CouchDB database with a call record for each inbound call that is transferred.

I’ll conclude the series with information on how to retrieve information from a CouchDB instance for use in a cloud telephony application, and talk about design documents. This post will also introduce the reader to the concepts of CouchDB Views and Show Functions - powerful tools that can be harnessed to create truly cutting edge cloud phone apps.

First, let’s create a CouchDB database to hold our call settings.

Creating a Call Settings Database

As mentioned in the previous CouchDB posts, you can create a new call settings database using curl from the command line, or using the Futon GUI.

$ curl -X PUT http://your_new_couchdb_ip:5984/call_settings

You should see a response from CouchDB like this:

{”ok”:true}

You can add a record to the call settings database the same way. This time, however, we’ll append the URL for our CouchDB database with a document ID, in this case ‘1000′ - this is the extension that a caller to our cloud telephony app will dial. We’ll use the document ID and and the CouchDB REST API to get all of the settings we’ll need to conduct the transfer - these settings can be seen in the document structure below (feel free to add others to meet your needs or preferences).

$ curl -X PUT http://your_new_couchdb_ip:5984/call_settings/1000 -d ‘{”first_name”:”Joe”,”last_name”:”Blow”,”phone”:”17777777777″,”title”:”Master of Disaster”,”ring_tone”:”audio/ring.wav”}’

You should see a response from CouchDB like this:

{”ok”:true,”id”:”1000″,”rev”:”1-0cf5a7c3a70ac5760f1a5d8dcb8b48d2″}

Let’s add a few more documents to our call settings database (replacing the telephone numbers below with real ones that you want callers to transfer to) and then view all of the documents that we have created.

$ curl -X PUT http://your_new_couchdb_ip:5984/call_settings/2000 -d ‘{”first_name”:”Harry”,”last_name”:”Smith”,”phone”:”18888888888″,”title”:”President of the World”,”ring_tone”:”audio/ring.wav”}’

$ curl -X PUT http://your_new_couchdb_ip:5984/call_settings/3000 -d ‘{”first_name”:”Martin”,”last_name”:”Scorsese”,”phone”:”19999999999″,”title”:”The Departed”,”ring_tone”:”audio/ring.wav”}’

You can view all of the documents in a CouchDB database using the HTTP GET method:

$ curl -X GET http://your_new_couchdb_ip:5984/call_settings/_all_docs

You should see a response from CouchDB like this:

{”total_rows”:3,”offset”:0,”rows”:[
{"id":"1000","key":"1000","value":{"rev":"1-0cf5a7c3a70ac5760f1a5d8dcb8b48d2"}},
{"id":"2000","key":"2000","value":{"rev":"1-ee2f09516df8b191a89791b01828d788"}},
{"id":"3000","key":"3000","value":{"rev":"1-a1399e8218ae75e1efb73ba3f87862ff"}}
]}

Now we need to modify our Tropo PHP script to retrieve the settings we want to use with each transferred call.

Note, for now we’ll keep the logic simple - if a caller enters an extension that does not exist we’ll get a specific HTTP response back from CouchDB - something in the 400 class of responses. If this happens, we’ll just end the call - in the real world you’d want to do something a little more friendly, but you can sort that out when you build your own cloud telephony application.

Modifying the Tropo Script

So, our new Tropo script looks like this:

Note that the getPhoneNumberByExtension() method no longer returns a hard coded phone number - it is using the 4-digit extension entered by the caller to access our CouchDB database using the REST API. The response from CouchDB is a document in JSON format, that we can easily parse using PHP’s handy json_decode() function.

I’ve also modified the value of the $callLog variable to correctly capture some of the variables exposed in the Tropo environment (i.e., the session ID of the call, and the caller ID - see this thread for more information).

So now we have a working cloud telephony application built on Tropo that uses CouchDB to get its call settings, and also to write a call record for billing, reconciliation, etc.

As cool as this is, there is still a lot more we can do with CouchDB in our cloud telephony apps. Note the constants declared at the top of the Tropo script - the last two are blank; one for a design document name, and one for a show function.

define(”COUCH_DB_DESIGN_DOCUMENT_NAME”, “”);
define(”COUCH_DB_SHOW_FUNCTION_NAME”, “”);

Let’s talk about those concepts now, and explore how they could be used in a cloud telephony application.

Getting more out of CouchDB - Design Documents, Map/Reduce and Show Functions

As the title of this post suggests, we’re building cloud-based phone applications without SQL. CouchDB doesn’t use SQL - instead it uses a Map/Recuce framework to index documents in a database.

Map functions can be used to emit a key-value listing of documents in a CouchDB database. Reduce functions are used to aggregate the key-value pairs emitted by a Map function. Map/Reduce functions (or Views) live inside of a special document in a CouchDB database called a “design document“, which has a document ID prefixed with “_design/”.

For example, suppose we have a special design document in our database called “_design/extensions” with a View called “getExtensions” - our View is made up of a Map function and (optionally) a Reduce function. Let’s assume our View has only a Map function to return data on extensions with valid phone numbers to transfer a caller to.

function(doc) {
  if(doc.phone.length == 11 && doc.phone.substr(0,1) == ‘1′) {
    emit(doc._id, doc.phone);
  }
}

Our Map function (which is written in JavaScript, and stored in our design document) has one parameter - doc. This function is called for each document in our database, and the doc parameter represents the document itself. As can be seen, we simply examine each document in the database to see if it has a valid phone number (11 digits, starting with 1).

Views are accessed using a specific URI structure (do note, however, that the REST API for querying Views can change significantly between CouchDB versions), and the response is a set of key-value pairs formatted as JSON.

http://{server_ip_address}:5984/{database_name}/_design/{design_document_id}/_view/{view_name}

$ curl -X GET http://your_new_couchdb_ip:5984/call_settings/_design/extensions/_view/getExtensions

You should see a response from CouchDB like this:

{”total_rows”:3,”offset”:0,”rows”:[
{"id":"1000","key":"1000","value":"17777777777"},
{"id":"2000","key":"2000","value":"18888888888"},
{"id":"3000","key":"3000","value":"19999999999"}
]}

You can check to see if your Map function is working properly by adding a document with an invalid phone number.

$ curl -X PUT http://your_new_couchdb_ip:5984/call_settings/4000 -d ‘{”first_name”:”Richard”,”last_name”:”Kimble”,”phone”:”4444444″,”title”:”The Fugitive”,”ring_tone”:”audio/ring.wav”}’

Accessing the getExtensions view will return the same results as before, as the phone number for the new document does not pass validation. Using design documents and Views, cloud telephony developers can use CouchDB to build grammars for user input which will significantly enhance the usability of the sample application we’ve used during the last few posts.

But there is even more potential with another piece of functionality in CouchDB - show functions. Show function also live in design documents, alongside Views. Show functions allow a developer to return specifically formatted content from a CouchDB instance, not just data in JSON format.

A basic show function that can be used to return information from our CouchDB database in the format of a SRGS grammar might look like this.

function(doc, req) {
 var grammer = ‘<?xml version=\”1.0\”?><grammar xmlns=\”http://www.w3.org/2001/06/grammar\”>’;
 grammar += ‘<rule id=\”R_1\”><one-of>’;
 grammar += ‘<item>’ + doc.phone + ‘<\item>’;
 grammar += ‘</one-of></rule></grammar>’;
 return grammar;
}

Like Views, Show Functions are accessed using a specific URI structure.

http://{server_ip_address}:5984/{database_name}/_design/{design_document_id}/_show/{show_function_name}/{document_id}

Note that the Show function above is different from the Map function discussed earlier in that it takes two parameters - doc and req. As before, the doc parameter represents the document the function is called against. The req parameter represents a parameter that is sent in with the HTTP request, which can be used inside the function to render output. So a Show function canbe accessed using the above URL with an optional parameter as well, like so.

http://{server_ip_address}:5984/{database_name}/_design/{design_document_id}/_show/{show_function_name}/{document_id}?{parameter}={some_value}

Conclusion

I hope this series of posts has provided a helpful overview of CouchDB, with an emphasis on how it can be used to build cloud telephony applications.

Cloud telephony platforms like Tropo, CloudVox, CallFire and others provide enormous flexibility to developers in building and deploying sophisticated cloud telephony applications.

Pair these tools with CouchDB and you’ve got a powerful combination for building full featured, easy to maintain cloud-based phone apps.

Relaxing on the Couch with Tropo and CouchDB

Posted by Mark Headd under CouchDB, Development Tools, Open Source, Tutorials

This is the continuation of a series that will describe how to build voice applications with the Tropo cloud telephony platform and CouchDB.

In the last post, I detailed how to get a CouchDB instance up and running on Ubuntu, and how to get an account started on Tropo so that you can start building cloud telephony applications. In this post, we’ll create our first CouchDB database and create a simple Tropo application that connects to our CouchDB instance. First, however, we need to tweak the default settings for CouchDB so that we can access our CouchDB instance from the an external environment.

Configuring CouchDB

Recall from the last post that the configuration files for CouchDB are located in /usr/local/etc/couchdb/. Open the local configuration file and take a look at the default settings:

$ sudo vim /usr/local/etc/couchdb/local.ini

In the [httpd] section, you’ll notice the setting for the default port that is used to connect to CouchDB - 5984. You’ll also note the bind_address setting. By default, CouchDB listens only on localhost – you can change this by altering the value of bind_address to a publicly resolvable IP address (you may need to uncomment this setting as well).

However, before proceeding please note that CouchDB does not yet have a built in security model, so anyone that can access the IP address in the configuration file can potentially access your CouchDB instance. We’ll need to take some steps to restrict access to our CouchDB instance – there are several ways of doing this.

First, if you know the IP address (or range of addresses) that will be accessing your CouchDB instances, you can simply use IPTables to restrict access to that IP:

$ iptables -A INPUT -p tcp -s 64.57.102.34 –dport 5984 -j ACCEPT

The above command would restrict access to your CouchDB instance to a single IP address.

Another method for securing a publicly exposed CouchDB instance is to use Apache password authentication. A good overview of this approach can be found here.

After you’ve modified the bind_address setting, restart CouchDB and test connectivity to it:

$ sudo /usr/local/etc/init.d/couchdb restart
$ curl http://your_new_couchdb_ip:5984

Creating our CouchDB Database

Once you have your CouchDB instance up and running, you can create a database in one of two ways. The first, and easiest, is simply to use the curl command. You create a database in CouchDB by using the HTTP PUT method:

$curl -X PUT http://your_new_couchdb_ip:5984/call_logs

You can also create a database (and do lots of management functions in CouchDB) by using the GUI (called Futon). Its located at http://your_new_couchdb_ip:5984/_utils

Building a Simple Auto Attendant Application with Tropo

Now that we have an initial database in our CouchDB instance, lets build a simple Tropo application that will populate it with records (or documents in CouchDB parlance):

This simple application is a basic auto attendant. It asks the caller for a 4-digit extension and then transfers them to a 10-digit PSTN number. At the end of the call, we write a very simple call log document to our new call_logs database using the HTTP POST method.

(One small side note – you can use either the POST or PUT methods to insert a document into a CouchDB database. However, using PUT assumes you want to assign a specific document ID to your document. When you use HTTP POST, CouchDB will automatically assign a document ID. For now, we’ll keep things simple and use POST.)

Much of the functionality in this simple app is just stubbed out for now - i.e., the getPhoneNumberByExtension() method - we’ll build more of this out in later posts.

Modify this file by adding your instance-specifc details to the constant declarations at the top. Do also note that the last two constants can remain blank for now.


define("COUCH_DB_DESIGN_DOCUMENT_NAME", "");
define("COUCH_DB_SHOW_FUNCTION_NAME", "");


We’ll talk about how to use design documents in the next post.

When you load this file up on Tropo and make a test call, you will see your call log document is inserted into the call_logs database. The structure of the document is pure JSON, which is supported quite nicely in PHP (and most every other language that can run on Tropo as well).

In the next post, we’ll examine CouchDB design documents in more detail and modify our simple demo application to get a list of extensions from another CouchDB database and parse the JSON data structure in the getPhoneNumberByExtension() method.

Until then, keep on relaxing….

Building Voice Applications with Tropo and CouchDB

Posted by Mark Headd under CouchDB, Development Tools, Open Source, Tutorials

The beginning of a new decade is usually the time when there is a lot of reflection on what has changed for the better (and the worse) over the past 10 years.

The end of 2009 saw its fair share of pundits talking about how far we’ve come since the year 2000, but for me the most dramatic change has been to the way that voice applications are developed and deployed. In the past 10 years (hell, in the past 10 months!) we’ve seen a dramatic shift toward cloud telephony with the launch of a number of new services that have fundamentally altered how voice applications can be built.

There has simply never been a more varied and powerful array of tools available for developers to build phone applications with than exists today. Some of the newest and most innovative platforms around for building cloud-based phone applications are listed below:

• Tropo
• Couldvox
• CallFire
• TringMe
• Twilio
• Ribbit

Over the same period of time there’s also been lots of changes to some of the foundational technologies supporting voice applications (and other kinds of web applications). The NoSQL movement is gaining steam, and there is an interesting collection of new document-oriented databases available for developers to use. One of my favorite is Apache CouchDB.

The thing I find really interesting about CouchDB is that it makes use of an HTTP-based API - pretty much any tool or technology that can communicate via HTTP can be used to interact with a CouchDB instance (hello command line…). In addition, that data structure of the documents stored in a CouchDB instance is JSON. In my mind, this makes CouchDB a very useful choice when building cloud applications, specifically cloud telephony applications.

Who wants to use one of those old relational databases to build a cutting edge cloud phone app? That’s so 2009.

This post and the next several that follow it will detail how to set up a CouchDB instance and to build a cloud telephony application with it using the Voxeo Tropo platform.

For those that don’t know, Tropo is one of the new cloud telephony platforms that lets developers author voice apps quickly and easily using one of several different languages. It’s open source, well documented and supported by Voxeo’s industry leading telephony infrastructure.

So, if you want to start the new decade of right by learning how to build powerful, scalable, full featured voice applications using Tropo and CouchDB, read on.

Getting Started with Tropo

Head on over to Tropo.com and set up a new account (if you don’t have one already). Take a little time to review the documentation for Tropo - I’d recommend running through a few of the sample apps if you have time. They’re fairly self explanatory and provide a solid overview of the different languages that can be used to write a Tropo app - I’ll be using PHP for the example application in this series of blog posts, but you can use any language that Tropo supports.

Deploying and testing an application on Tropo is a snap, and you can even deploy a PSTN number for your application (or you can use the Skype calling number automatically provisioned when you create a Tropo app). More on this in the next post.

Installing CouchDB

The next step in building our cloud telephony application for the new decade is getting CouchDB up and running. The steps listed below detail how to install CouchDB 0.9 on Ubuntu 8.04 (the long-term support version of Ubuntu). A few points before we get started…

This specific combination of Ubuntu and CouchDB is my own preference. I typically run Ubuntu 8.04 when I deploy a new virtual server, but you are free to run whatever version you like, or another Linux distro entirely - its up to you. Depending on the version of Ubuntu you are running, you may be able to get CouchDB 0.9 installed by simply doing sudo apt-get install couchdb.

Keep in mind, though, that the HTTP API for CouchDB can change dramatically between versions - I’ve noticed some significant changes when going from 0.8 to 0.9 - the discussion here will focus on version 0.9 (as does a lot of good documentation on CouchDB available on the web).

If you don’t want to install CouchDB yourself, you may be able to take advantage of one of the growing number of CouchDB hosting services like CloudAnt or Couch.io. Again, its up to you.

To install CouchDB 0.9 on Ubuntu 8.04, using the following steps.

Step 1. Determine what version of Ubuntu is running on your machine:

$ cat /etc/lsb-release

Step 2. Install Erlang - CouchDB 0.9 requires at least Erlang version 5.5.5. If you are running Ubuntu 8.10 or above, you can probably get the required Erlang version by simply doing sudo apt-get install erlang. (Note - The last step in this section may take a while, feel free to go grab a cup of Joe while the source compiles.)

$ sudo apt-get build-dep erlang
$ sudo apt-get install java-gcj-compat java-gcj-compat-dev
$ wget http://www.erlang.org/download/otp_src_R12B-5.tar.gz
$ tar -zxvf otp_src_R12B-5.tar.gz
$ cd otp_src_R12B-5/
$ ./configure && make && sudo make install

Step 3. Install CouchDB dependencies:

$ sudo apt-get install libmozjs-dev libicu-dev libcurl4-openssl-dev

Step 4. Download CouchDB 0.9 Source and install:

$ wget http://apache.mirrors.redwire.net/couchdb/0.9.0/apache-couchdb-0.9.0.tar.gz
$ tar -zxvf apache-couchdb-0.9.0.tar.gz
$ cd apache-couchdb-0.9.0/
$ ./configure && make && sudo make install

Step 5. Create a user for CouchDB (More on this in the CouchDB README.txt file):

$ sudo adduser – –system – –home /usr/local/var/lib/couchdb – –no-create-home – –shell /bin/bash – –group – –gecos “CouchDB Administrator” couchdb
$ sudo chown -R couchdb /usr/local/etc/couchdb
$ sudo chown -R couchdb /usr/local/var/lib/couchdb
$ sudo chown -R couchdb /usr/local/var/log/couchdb

Step 6. Start CouchDB

$ sudo /usr/local/etc/init.d/couchdb start

If you see an error that says:

“Apache CouchDB needs write permission on the PID file: /usr/local/var/run/couchdb.pid”

Do the following, then try starting CouchDB again:

$ sudo touch /usr/local/var/run/couchdb.pid
$ sudo chown couchdb:couchdb /usr/local/var/run/couchdb.pid

When CouchDB starts successfully, you will see a message that says:

* Starting database server couchdb     [ OK ]

Step 7. Test connectivity to CouchDB:

$ curl http://127.0.0.1:5984

You should see:

{”couchdb”:”Welcome”,”version”:”0.9.0″}

The configuration file for CouchDB is located at /usr/local/etc/couchdb/default.ini — in the next post, we’ll modify some of the config settings for our CouchDB instance so that we can access it via HTTP from the Tropo environment.

We’ll also set up our first CouchDB database, add some documents and start coding our new cloud telephony application using Tropo.

Stay tuned…

The Growth of Civic Apps

Posted by Mark Headd under Open Government, Open Source

A pretty good indicator of the growth in the number of “civic applications” can be seen in the creation of some new application directories.

City-Go-Round is a really nice site that pulls together dozens of applications that relate to travel and transit systems. It lets users enter a zip code so they can identify apps created specifically for their area (if any exist). I really like that this site focuses not only on the use of publicly released transit data, but also encourages users to advocate for more public transit data. You can view a list of agencies and sort by those that make their transit data public and those that don’t - it also lists contact information so that users can advocate with transit agency officials that don’t yet make their data public and get them to wise up.

Another site (still in the alpha stage) that lists applications specifically tailored to a particular geographic area is Appify. One of the brains behind this site is John Geraci (of DIYCity.org fame). While this app directory doesn’t look to be focused exclusively on civic applications, there are several prominent ones represented in the alpha release - theNextTrain, SubwayDelay and SeeClickFix among them.

The civic application ecosystem is healthy and growing, and I think we’ll start to see more application directories like these as more and more governments and transit agencies start to make their data public.

Delaware Checkbook a Step Backwards for Transparency

Posted by Mark Headd under Open Government

Earlier this year, the State of Delaware added a new section to its official website - the State of Delaware Online Checkbook.

If you like this website then you can probably hear “I Want it That Way” playing in the background as you vigilantly prepare your desktop PC for the onset of Y2K. But while you’ve been jamming to the Backstreet Boys and getting ready to party like its 1999, the e-Government movement has been chugging right along.

Don’t get me wrong, I think its great that the State of Delaware is making more information public - all things being equal, more public access to information about how state government conducts its business is a good thing. However, I take issue with the way that Delaware is doing it.

To deploy the State of Delaware Online Checkbook, state officials have sanctioned the creation of one of the worst web sites I have seen in a long time. Aside from looking like the work of someone who has only recently discovered AJAX (and wants to add as much hip new AJAXian elements as possible to impress the ladies) it’s a horrible mishmash of inline CSS and nasty table-centric layout. I haven’t tested it formally, but I’d be willing to bet that this website fails every conceivable test for access by the disabled that there is. I doubt very much that this site meets the state’s own standards for accessible web content.

Even for those without impairment, this website presents challenges for anyone who wants to take a critical look at state expenditures. The data is not downloadable - you can’t click on a link and download a CSV file for an agency (at least nowhere that I could find). Instead you have to navigate, page by page, through arcane listings of expenditures - many with highly non-descriptive summaries. If you want to download this information and use it in a spreadsheet to compare spending across agencies you’re out of luck. Because of the cheezy AJAX pagination that litters the site, you can’t link to anything meaningful either, instead users are simply forced back to the summary for a particular agency. This is one of the most unusable site I have seen in a very long time.

Contrast this with what is occurring in the District of Columbia, New York City, San Francisco, Vancouver and even at the federal level courtesy of the Obama Administration. These governments are providing public access to raw data sets, making it easy for anyone (or anything) to consume this information, slice it up, analyze it and create interesting mashups. Delaware’s lame attempt with the Online Checkbook is like a time warp back to the very early days of e-Gov 1.0, when governments hid their data behind an opaque web facade that dictated how citizens would get to access it. It hasn’t been done like this in a long, long time.

Not only are other governments posting data online in highly usable formats, many are also asking citizens what they want to see next. In the last few weeks, the Obama Administration has set a new challenge for federal agencies through the Open Government Directive, which encourages agencies to publish information online in “machine readable” formats and to solicit input from the public on how to enhance the quality of government data.

The State of Delaware’s current attempt at publishing open data is so far away from what is considered standard in the current e-Government environment that it must be viewed as a step backwards. This is almost worse than having no data available, because it lets state leaders claim they are making government more transparent when all they are doing is muddying the waters.

The irony here is that it was the state’s then Treasurer (and current Governor) Jack Markell who took up the cause of e-Gov 1.0 during the early days of the Minner Administration. Apparently, his thinking on e-Government has not changed much since then.

Maybe he just wants to keep spinning those Backstreet Boys records as well…