O'Reilly    
 Published on O'Reilly (http://oreilly.com/)
 See this if you're having trouble printing code examples


Plugging iotum into PhoneGnome
A PhoneGnome Application Partner Case Study: iotum

by Mark Petrovic
05/22/2006

Introduction

The internet is at its best when an innovator is free to create loose couplings between open systems that reside in different domains of control. An instant classic in this regard is the mashup; developers increase the value of publicly available geographic data by superimposing recreational or economic features of interest. In doing so, map providers do what they do best (aggregate geographical data), while developers do what they do best (manifest ideas in running code based on that data).

The mashup is the result of a data owner making a confident declaration that she cannot conceive of all of that data's possible uses. In a departure from legacy thinking, the owner adds value to her map data by providing access to it, but she permits third-party developers to deliver that added value to the end user. Making data available at bearable prices encourages the creation of these loose couplings, and is known in some circles as Web 2.0: opening data, which was once handled and served exclusively by its owners, for mass movement and consumption.

We are proud to introduce PhoneGnome FieldSig with the same enthusiasm. The combined voice telephony and data needs of the modern user are vastly richer and more nuanced than we can conceive. PhoneGnome FieldSig consists of two expressive interplatform signalling mechanisms, which occur in real time between the PhoneGnome platform and the platforms of our business partners, DeepSig and LiteSig.

PhoneGnome DeepSig is SIP-based and allows not only for simple interplatform informational exchanges, but for partners hooking into deep call flows. Using PhoneGnome DeepSig, partners can place themselves in the SIP signalling and media path of their customer's calls, enabling any number of novel and compelling value-added voice services.

PhoneGnome LiteSig, by contrast, is XML-RPC based and shines in the area of simple query-response interplatform messaging. PhoneGnome LiteSig is ideal when partners don't need access to the call media, but simply to the real-time fact that the call is occurring, with an option for simple call disposition instructions.

By publishing the PhoneGnome FieldSig protocol, we invite third-party developers to add value to PhoneGnome telephony data on behalf of their customers--customers who demand a mixing and matching of their IP voice data and metadata with their contemporary business rules and data.

The focus of this article will be LiteSig, which is extremely lightweight, expressive, and fully capable of rapidly creating couplings between the PhoneGnome platform and the platforms of our developer partners. Under LiteSig, the PhoneGnome platform functions as an XML-RPC client to our partner's XML-RPC server, calling out to the server when telephony events of interest occur. In turn, the server looks inward toward its user base and delivers interpreted value to the called user in question. This value is rich, varied, and best understood and articulated by our partners. LiteSig is simple, easy to deploy, and extends the PhoneGnome developer franchise to any competent generalist developer, independent of her SIP experience.

In the next sections, I'll showcase how PhoneGnome business partner iotum exploits the new PhoneGnome LiteSig to deliver compelling and novel voice-derived services to its user base, and most importantly, without becoming a telephony provider itself. FieldSig allows iotum to focus on its core competency, rather than on the protocol and operational details of modern IP voice services.

PhoneGnome LiteSig in Action: iotum

iotum is a PhoneGnome business partner whose iotum Relevance Engine is at the center of a new Voice 2.0 call processing service. It is the winner of both the 2005 Internet Telephony Product of the Year and the 2006 DemoGod Awards. The iotum service routes voice calls based on customer business rules. iotum describes its Relevance Engine as:

the world's first platform to intelligently filter, rank, and prioritize calls based on their relevance to you. Using your contextual information and preferences, iotum knows who's calling, whether you want to take the call, and which phone you want to use. You get the calls you want, where you want.

In the course of using their iotum service, users generate state and availability information that determines subsequent inbound call routing. Some of that information is configured declaratively in the form of the user's web-based iotum account setup. This information includes a distinction between work time and personal time, and the set of terminal destinations for inbound calls, such as desktop phone number, mobile phone number, voice mail address, and email address. Other state and availability information is developed from the user's calendar entries and IM state.

The iotum service leverages Windows developer techniques to programmatically ascertain a user's Outlook calendar entries and MSN Messenger state. This information is relayed, as needed, in real time to iotum servers, which are connected to the user's desktop with a software plugin provided by iotum as part of their service. All of this current state information is used in the call-routing decision process for inbound calls to that iotum user.

iotum Call Disposition Basics

Figure 1 shows a simple block diagram of call dynamics and disposition. As a result of the iotum-PhoneGnome provisioning process, the PhoneGnome platform knows when an inbound call is addressed to an iotum user. When a call comes in, the PhoneGnome platform--functioning as XML-RPC client--makes a remote procedure call to the iotum XML-RPC server. The server examines, in real time, the connected state of the iotum user, applies the user's routing rules, and sends an XML-RPC response to the PhoneGnome platform with instructions on the call's disposition. Depending on the user's state of availability, time of the call, caller identity, and user-configured iotum call routing rules, the call is routed to the user's devices. These devices may include a desktop, mobile phone, voice mail, or more.

figure

Figure 1. Call dynamics and disposition.

Specifically, the PhoneGnome platform forms an XML-RPC method call, Services.CallProcessingService.process, with a single struct argument. The argument is a dictionary of SIP headers and values.


<?xml version="1.0"?> 
<methodCall> 
<methodName>Services.CallProcessingService.process</methodN 
ame> 
  <params> 
    <param> 
      <value> 
        <struct> 
          <member> 
            <name>From</name> 
            <value> 
             
<string>"8165551212"<sip:8165551212@televolution.net> 
</string> 
            </value> 
          </member> 
          <member> 
            <name>Contact</name> 
            <value> 
              <string>PHONEGNOME TEST</string> 
            </value> 
          </member> 
          <member> 
            <name>To</name> 
            <value> 
              <string>9185551212</string> 
            </value> 
          </member> 
        </struct> 
      </value> 
    </param> 
  </params> 
</methodCall>

The response from the iotum XML-RPC server tells the PhoneGnome platform how to dispose of the call. The response is also an XML-RPC struct, where the iotum server response action is ACCEPT, REDIRECT, or DECLINE. REDIRECT specifically includes appropriate redirect-to parameters, typically a tel: or SIP URI, and can also direct the call to voicemail.


<?xml version="1.0"?> 
<methodResponse> 
  <params> 
    <param> 



      <value> 
        <struct> 
          <member> 
            <name>action</name> 
            <value> 
              <string>ACCEPT</string> 
            </value> 
          </member> 
        </struct> 
      </value> 
    </param> 
  </params> 
</methodResponse>

Partner Provisioning

Prior to the new XML-RPC signalling, the iotum user must be provisioned in both the PhoneGnome and iotum customer databases. This mutual provisioning is also network XML-RPC-based, and the semantic details depend on both the PhoneGnome and partner's back-office business rules. For more information on acquiring customers and provisioning them on your service, see the PhoneGnome Partner Page or please contact us at developer@televolution.com.

PhoneGnome DeepSig in Brief

We have concentrated on a real-world use case of PhoneGnome LiteSig using lightweight XML-RPC, but let's take a quick look at PhoneGnome DeepSig. This is an overview, and will give you a sense of DeepSig's deeper addressing level. For more information on DeepSig, please contact us at developer@televolution.com.

LiteSig method calls have familiar XML-RPC characteristics--method names followed by method parameters in appropriate markup. DeepSig, conversely, uses extended SIP URIs to convey protocol information:

sip:*action*acct*id*params@partnerhost

where action is the account number of the user/endpoint, id is an opaque value identifying the transaction, and params are action-specific parameters, if any. DeepSig actions may be initiated on inbound or outbound calls.

For example, consider this inbound SIP INVITE with a DeepSig encoded URI:

INVITE sip:*3*46001820*1911003180*@67.96.221.66 SIP/2.0 
Via: SIP/2.0/UDP 198.211.140.7:5060;branch=z9hG4bK75262cb3 
From: "JOAN SMYTH" 
<sip:9255558775@198.211.140.7>;tag=as541a0b6a 
To: <sip:*3*46001820*1911003180*@67.96.221.66> 
Contact: <sip:9255558775@198.211.140.7> 
Call-ID: 288d4e6b0de370345751d60f365b7b17@198.211.140.7 
CSeq: 102 INVITE 
User-Agent: TelEvolution Server 
Date: Wed, 14 Dec 2005 19:36:21 GMT 
Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER 
Content-Type: application/sdp 
Content-Length: 263 
 
v=0 
o=root 7113 7113 IN IP4 198.211.140.7 
s=session 
c=IN IP4 198.211.140.7 
t=0 0 
m=audio 15754 RTP/AVP 0 3 8 101 
a=rtpmap:0 PCMU/8000 
a=rtpmap:3 GSM/8000 
a=rtpmap:8 PCMA/8000 
a=rtpmap:101 telephone-event/8000 
a=fmtp:101 0-16 
a=silenceSupp:off - - - -

Such inbound calls are subject to busy and unavailable event handlers, as well as thru handling. Possible values of action are 1 for Dial/pass pattern through outbound dial handling, 2 for Busy/pass to subscriber busy event, 3 for Unavailable/pass to subscriber unavailable handler, and 4 for Thru/pass call through to next inbound dial handler.

Partner handlers, which for DeepSig are inherently SIP-based, may return the call to the PhoneGnome platform via SIP INVITE to specific URIs as:

sip:*action*acct*id*params@API-host

The partner essentially owns the SIP message body, including any SDP, and can pass it back to the platform DeepSig handler as is, or modify it based on whatever other services the partner may offer.

Conclusion

From the PhoneGnome Mission Statement:

We remove obstacles for application service providers by providing an efficient application development and distribution platform. Our partners can deliver branded advanced services to any landline subscriber in the world, in a neutral environment, without the need to engage the local telephone company. We provide transparent and simple commercial terms, streamlined business processes, and light-weight certification requirements. Additionally, the platform helps deliver a secure, convenient, and consistent experience to users in a way that individual service providers are unable to achieve.

PhoneGnome continues to remove barriers to developers by publishing PhoneGnome FieldSig interplatform signalling protocols. The iotum case shows how easily value can be added to what were once locked-down telephony data and events. With deep or lightweight message schemes, PhoneGnome business partners can create powerful loose couplings between their respective platforms, and deliver value to their customers without building out full-featured IP voice platforms themselves.

For more information on how you can take advantage of PhoneGnome platform APIs, please contact us at developer@televolution.com.

Mark Petrovic is a technologist and software developer.


Return to the O'Reilly Emerging Telephony

Copyright © 2009 O'Reilly Media, Inc.