An HTTP based Bulk SMS API for Mobicents

Recently, I have been working on a Bulk SMS Service implemented within Mobicents that allows external systems to communicate with it via HTTP. The service, in fact, is two services in one. The first service is a network-hosted address book that allows users to manage their own contact lists. For this, the service makes use of the Mobicents XDMS which comes with native XCAP resource list  support. The second service is the actual SMS service that receives requests to send SMSes. Each request must specify a list of recipients that can be specified individually or as a group that contains several members. This post describes the version 1.0 of the API that I have created and how it behaves. In a subsequent post, I will be providing details of the actual implementation and how extensions will be factored in for version 1.1.

Basic Structure and Parameters
All requests are HTTP GET requests. The basic structure of the request that is sent to Mobicents is as follows:

http://hostname:port/mobicents?username=foo&password=bar&type=[document|group|contact|sms] &op=[add|edit|del|send] [&parameters]

In the above request format, the hostname and port number are those of the Mobicents instance that is running the service. The “mobicents” subpath maps onto the Mobicents HTTP servlet connector that is associated with the service.
The mandatory parameters are:

• username - The username of the user.
• password - The password of the user.
• type - The type of data that is being managed. Legal values are “document”, “group” and “contact” for managing contact list documents, contact groups and individual contacts respectively, and “sms” for generating functions.
• op - The type of operation that is being attempted. Legal values are “add”, “edit” and “del” for managing contact information, and “send” for sending SMSes.

Contact List Management
A contact list refers to a document that is hosted on a document management server that contains user contact details. An HTTP request from an external system can be made to manage such documents. The structure of the request must accord with the following:

http://hostname:port/mobicents?username=foo&password=bar&type=document&op=[add|del]

A contact list document can either be created or deleted. When a new contact list is created, a single contact group named “Ungrouped” is automatically created in the user’s contact list. The add operation is idempotent, meaning multiple executions do not change the state of the document from how it is when it is initially created. The delete operation can be executed on non-empty documents, that is documents that contain contacts in the Ungrouped group or other groups.

Group Management
An HTTP request from an external system can be made to modify a contact group that a user has defined. The structure of the request must accord with the following:

http://hostname:port/mobicents?username=foo&password=bar&type=group&op=[add|edit|del] &group=group [&newgroup=newgroup]

An group management request is indicated by assigning the value “group” to the type parameter. Contact groups can be added, edited and deleted. It is assumed that each contact group has a name and consists of zero or more contacts. There is an additional parameter that can be specified when the name of an existing group is being edited:

• newgroup - The new name being allocated to an existing group.

Next, some examples are given of how these requests should be structured for given operations.


To create a new contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=group&op=add&group=Friends

To change the name of the contact group called Friends to Close Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=group&op=edit&group=Friends&newgroup=Close%20Friends

To delete the contact group named Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=group&op=del&group=Friends

Contact Management
An HTTP request from an external system can be made to modify the details pertaining to a given contact. The structure of the request must accord with the following:

http://hostname:port/mobicents?username=foo&password=bar&type=contact&op=[add|edit|del]&name=name&number=number [&parameters]

Contacts can be added, edited, deleted and removed from a group or multiple groups. In addition to the general mandatory parameters listed previously, contact management requests must specify a name and a contact number since these parameters identify a contact uniquely. There are other parameters that can be specified depending on the type of operation that is being attempted.

• group - The group name that a contact currently belongs to, is to be inserted into or is to be removed from. 
• newname - The new name to be allocated to an existing contact.
• newnumber - The new contact number to be allocated to an existing contact.

Next, some examples are given of how these requests should be structured for given operations.


To add a new contact named John Doe with mobile number 0786346927, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=add&name=John%20Doenumber=0786346927

In this case a group is not specified, so the contact is allocated to the Ungrouped group in the contact list. To change John Doe’s name to Peter Doe, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=edit&name=John%20Doe&number=0786346927&newname=Peter%Doe

To change John Doe’s mobile number to 0786346920, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=edit&name=John%20Doe&number=0786346927&newnumber=0786346920

To delete John Doe entirely from the contact list, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=del&name=John%20Doe&number=0786346927

To add a new contact named Alice Wonderland with mobile number 0786346928 to a contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=add&name=Alice%20Wonderland&number=0786346928&group=Friends

To remove Alice Wonderland from a contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=del&name=Alice%20Wonderland&number=0786346928&group=Friends


User Profile Management
This document does not define any user profile management methods. It is anticipated that version 1.1 of the API document will define and support them.

SMS Generation
An HTTP request from an external system can be made to send an SMS through Mobicents. The structure of the request must accord with the following:

http://hostname:port/mobicents?username=foo&password=bar&type=sms&op=sendto=nums&group=group&text=text [&report=bool]
The SMS service has the same mandatory parameters defined is Section previously. It also defines the following parameters:

• to - The number or list of numbers to send the SMS to.
• group - The contact group of list of groups to send the SMS to.
• text - The body of the SMS message.
• report - A boolean flag for SMS delivery reports.

When sending an SMS, either the to parameter or the group parameter must be specified, or both. If the SMS is intended for multiple recipients, the contact numbers must be separated by the ’+’ character in the to parameter. Likewise, if the SMS is intended for multiple groups, the group names must be separated by the ’+’ parameter in the group parameter. Only the values “true” and “false” are valid for the report parameter. Assigning the value “false” to the report  parameter is the same as not setting this parameter in the request at all. Next, some examples are given of how these requests should be structured for given operations.

To send an SMS to a user with the mobile number 0786346927, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&to=0786346927&text=This+is+the+text

To send an SMS to the numbers 0786346927, 0786346928 and 0786346929, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&to=0786346927+0786346928+0786346929&text=This+is+the+text

To send an SMS to the numbers 0786346927, 0786346928 and 0786346929 and request a delivery report, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&to=0786346927+0786346928+0786346929&text=This+is+the+text&report=true

To send an SMS to a contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send




To send an SMS to the mobile numbers 0786346927, 0786346928 and 0786346929 in addition to a contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&to=0786346927+0786346928+0786346929&group=Friends&text=This+is+the+text


In such cases, Mobicents is responsible for ensuring that an SMS is not sent more than once to a group contact that is already explicitly listed in the to parameter.

To send an SMS to the groups Friends, Close Friends and Family, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&groups=Friends+Close%20Friends+Family&text=This+is+the+text


Error Conditions
There are a number of operations that can lead to error conditions. They are gracefully handled by Mobicents. Mobicents defines exceptions that are thrown when the processing of a request can lead to an error condition.


Too Few Parameters - This error condition arises when the request that is received is missing one or more of the mandatory parameters that have been defined previously. In response to this, Mobicents will send an HTTP response back to the requesting system with the following message: “HTTP Error 432: Missing Mandatory Parameter in the request - Check API manual”. For example, the following request will generate such a response:

http://hostname:port/mobicents?password=bar&type=contact&op=add&name=name&number=number

Parameter missing a value - This error condition arises when the request that is received is missing a value for any parameter that is specified in the request. In response to this, Mobicents will send an HTTP response back to the requesting system with the following message: “HTTP Error 433: Malformed URL - Missing Parameter Value - Check API manual”. For example,
the following request will generate such a response:

http://hostname:port/mobicents?username=foo&password=bar&type=&op=add &name=name&number=number&group=Friends

Unknown Parameter - This error condition arises when the request specifies a value that is not part of the pre-defined values for the service. In response to this, Mobicents will send an HTTP response back to the requesting system with the following message: “HTTP Error 434: Unknown Parameter in the request - Check API manual”. For example, the following request will generate such a response:

http://hostname:port/mobicents?username=foo&password=bar&type=sms&op=send&group=Friends&text=This+is+the+text&ussd=true


Invalid Request - This error condition arises in a number of different cases where the request is not formatted correctly for the type of operation that is being attempted. A request that violates any of the following rules fits into this category:

• When creating a document, the only legal operations are add, edit and delete. 
• When adding a new group, the group name must be specified.
• When editing a group, both an existing group name and new group name must be specified.
• When deleting a group, the group name must be specified.
• When adding a new contact, both the name and the contact number must be specified.
• When editing a contact’s name, both the existing name and new name must be specified.
• When editing a contact’s number, both the existing number and the new number must be specified.
• When deleting a contact, both the name and the contact number must be specified.

In response to any of these conditions, Mobicents will send an HTTP response back to the requesting system with the following message: “HTTP Error 435: Illegal operation - Check API manual regarding: [error message]”.

Creating a Hello World SLEE application (Ubuntu version)

The development of a SLEE application, though not extremely complex, can be a bit tedious when it comes to creating the directory structure and XML file descriptors. To assist SLEE developers, the Mobicents core team has created tools for the development of SLEE applications in the Eclipse Java IDE. Tutorials do exist already on the Internet and there are a few blog posts that describe the process. This tutorial is essentially a copy of those, but specifically customised for the Ubuntu environment and the Helios version of Eclipse. [download]

Thesis Abstract - Take One

Normally, you don't write the Abstract until you have actually done the thesis. Go figure. But I have decided to give it a jab and put something down for the time-being. Obviously, I will be returning every now and again to shape it up, but this is what I have in mind for now:

Abstract -- The next generation network (NGN), as specified by the International Telecommunication Union (ITU), seeks to guarantee that the network of the future will provide users of telecommunication systems with seamless access across disparate networks, to the applications and services they need and use in everyday life. The IP Multimedia Subsystem (IMS) as defined by standards bodies such as the 3GPP (3rd Generation Partnership Project), ETSI (European Telecommunication Standards Institute) and others, is an important part of the NGN, particularly from the perspective of providing the services architecture that executes and delivers services based on user requests. The decomposition of these services into their constituent parts provides IMS engineers with the advantage of code re-usability and a more flexible platform upon which to develop complex services. Work in this area has led to the definition (outside of the standards) of a service capability interaction manager (SCIM) and a service broker which are responsible for handling the interactions between service components and managing access and third party exposure to these components respectively. The aim of the work related in this thesis has been to investigate in detail the service architecture of the IMS and to identify and validate the shortcomings, if any, of the current architecture for the delivery of complex services through service orchestration. The work applies only to the composition of services that are hosted on SIP (Session Initiation Protocol) application servers which is one of the three target environments specified by IMS. In agreement with related work, this thesis finds that the current architecture is not fully supportive of these functions without some extra interventions. A novel architecture that extends the currently proposed model is subsequently presented using the Mobicents platform which is based on the JAIN SLEE standard that, unlike related work, re-uses existing IMS standards and mechanisms and is compared and contrasted with contemporary designs such as Parlay X, GSMA One API and OMA NGSI.

Innovation Awards - IntelliDesk CRM System based on Open Source Software

Summary-- The Technology Innovation Agency (TIA) in South Africa is an agency of the Department of Science and Technology that seeks to support young innovators in scarce-skills disciplines such as natural sciences, engineering and information technology. A bi-annual competition is held at all the tertiary institutions where independent panels choose three of the best proposals in each institution. Successful competitors are then sent to a two-day crash course where they are taught the basics of how to write a business proposal and are mentored by experts in business administration. In the last stage of the competition, the national stage, the innovators must compete against others for the chance to win ZAR 300,000 (USD 41,000) as the winners of the National Innovation Competition.

Two of my colleagues and I entered the competition late in 2009 with two hopeful business proposals. One proposal was for a "Mobile Trainer" that combines an application that interfaces with a mobile phone's GPS and accelerometer to track the training progress of an athlete. The information that is generated would also be posted onto a website and help create an online community that provides support and comparative statistics to help novice or recreational athletes.

The second proposal that we came up with was "IntelliDesk" which is the proposal that would end up earning us second position in the first round of the competition. IntelliDesk is a telephony-enabled, web-integrated customer relationship management software that is based on open source software that generalises to many business cases. The basic idea is to create an online master database that stores customer profiles. The main way this database is created is through a person interacting with a website that allows them to store information about themselves and also to determine which business entities are allowed to have access to their information.

A local installation of IntelliDesk is setup at the premises of our customers that allows them to download and store user profile information and match these details against the callerid (or sms) of a calling user. The information is put up on a web interface so that the agent at the business side can briefly scan through the information before answering the call. This information is important in dealing better with the user and helps the agent offer a customised service to their clients.

In South Africa, and indeed in other parts of the world, such systems already exist. However, more often than not, these are in-house systems that are installed at call centres or restaurants that serve the interests of that business only. What IntelliDesk offers is a general purpose interface to user profiles that can be utilised by several businesses so that the user does not need to create a 'presence' at each conceivable call centre or restaurant, but one set of information can be shared across many businesses and the power is in the hand of the user who dictates who can access and who cannot access their information.


The System

Poster depicting IntelliDesk architecture for the national competition

IntelliDesk is built from open source software. The telephony portion is handled by Asterisk, an open source PBX. The website is hosted on an Apache web server and PHP files are used as a scripting language for both Apache and Asterisk (through Asterisk AGI support).

Photos of national trials

The venue for the national competition taken from the taxi (Moses Mabidha stadium, one of the World Cup stadiums)

The IntelliDesk setup: Asterisk interface on laptop, two wifi phones, a wifi AP and an analogue phone connected to the Asterisk server (behind the white box) with a Digum card installed

I was basically the eye-candy for our demo stall

Fred and Z showing someone how the system works

Fred (right) showing the Director General of Science and Technology (left) and the chairperson of the Technology Innovation Agency (middle) how the system works

Our consolation prize for not winning the competition

Mobicents Based IM Service with outsourced Billing Using Ericsson Charging SDK

Abstract - Mobicents is a Java based platform that implements the JAIN SLEE standard that delivers a wide range of multimedia services for various application domains. It is an umbrella name for a set of enablers that includes presence, media services, sip servlets and diameter, besides a JAIN SLEE server which provides the application execution environment. The power of the platform comes from its focus on enablers that can then be utilised to develop complex services. This is enhanced by its emphasis on open standards such as those that are being standardised by bodies such as the IETF, 3GPP, ETSI TISPAN and ITU. In this example, the Mobicents SIP function will be used along with a diameter stack to implement a relatively simple billing system for billing SIP based instant messages. Mobicents will be used here as a diameter client which communicates with a diameter server in the form of the Ericsson diameter emulator.

Design

SIP Portion

JAIN SLEE is an event based architecture that allows for service development to be based on an hierarchical and priority based model that defines a root service building block (SBB) which is linked to one or more child nodes (child SBBs). When a root SBB registers for certain events, such as SIP events, the SLEE event router delivers those events, either those from external resources such as SIP softphone running on s user's computer, or those that are generated by itself, to that root SBB. The root SBB can then dispatch that event or a new event to one of its children for further processing. The hierarchical design of the SIP based portion of the service is illustrated below:

Figure 1. Service Design showing root node and children

Diameter Portion

The diameter support in Mobicents is composed of a Diameter stack, a mulitplexer and message validator. The stack is the most important aspect of the diameter infrastructure as the stack provides the mechanisms necessary for message sending and receiving, peer management and session management. The multiplexer allows multiple applications to share a single diameter instance. Lastly, the message validator validates the messages that are sent or received to ensure that they are formatted appropriately. The Mobicents Diameter environment is summarised in the figure below:

Figure 2. Mobicents Diameter environment. Source: [1]

Ericsson Diameter Emulator

The third piece of the puzzle consists of the Ericsson emulator which is a java based implemenation of the diameter protocol.  The emulator is designed to behave in a similar manner to Ericsson's PPS 3.6 system which is a prepaid commercial system developed by Ericsson. Any system which interacts with the emulator properly is guaranteed to work with the commercial version. Ericsson also released an SDK which exposes an API for programmers to use in order to develop Diameter clients or servers of their own quickly.

Outline of the system

With our root SBB and children it is possible to locate user's locations and use the SIP proxy to send messages to SIP endpoints. The Diameter function can be used to implement a Diameter client for sending Accounting requests and receiving accouting answers. The figure below gives an outline of the desired system:

Figure 3. Outline of the system showing main entities.

The system in action

Step 1: We register two SIP clients to the Mobicents SIP Registrar.

Step 2: Using one SIP client, we send a SIP instant message (MESSAGE) to the second SIP client, indicating the caller's URI

Step 3: The SIP MESSAGE is intercepted by the root SBB as configured. The root SBB extracts the callee's SIP URI from the FromHeader in the SIP message and sends a Diameter Accounting Request (ACR) to the Diameter server, inducating the user's MISDN and the service details which will be matched against a tarriff database on the Diameter server.

Step 4: The Diameter server receives the ACA and examines the request. If all is well, the server will respond with an Accounting Answer (ACA) with a 2001 response code (DIAMETER_SUCCESS) to the root SBB. Otherwise, the server may send an error message or a negative 4241 response code (INSUFFICIENT_BALANCE).

Step 5: At the root SBB, the Diameter response is examined. If the result is positive, the root SBB attaches the SIP proxy so that the message can be sent to the callee. If a negative response is received, a SIP message is routed back to the caller indicating the nature of the error.

Conclusion

Mobicents, as a heterogeneous services platform, allows developers to build services based on technology enablers that can be deployed independently or in concert with each other to provide complex services. The emphasis on open source and open standards allows for ease of use and interoperability with other implementations, which makes it easy to tie into existing solutions a customer may already have. The example described here is not complex, but shows what can be done when enablers are pooled together to build intersting services.

Enablers and SCIMs for IMS

Services architecture in NGNs

With the advent of realtime Internet applications especially in the mobile domain and the proliferation of social networking platforms like Facebook, MySpace and Skype, operators are finding themselves in difficult terrain. Not only have revenues decreased from voice calls and text messages due to VOIP and chat services, but now their networks are being degraded to the status of "bit pipes" for access third party services. These services are normally free or are being offered for a nominal prices, and thus their popularity. Thus operators have to come up with advanced services to entice customers to stay within their "walled gardens".

Next generation networks that are now be rolled out by the majority of operators in Europe and America such as the IMS are three tiered architectures separating the access, control and application layers (ASs), with services being deployed through application servers located in the upper layer. Criteria known as initial filter criteria (iFC) are used by the Service Call Session Control Function (S-CSCF) in conjunction with user profile information obtained from the Home Subscriber Server (HSS) to direct user requests to the targeted AS. This type of interaction is summarised in the diagram below:

Sh is the Diameter protocol

ISC is SIP

Cx is Diameter protocol

Ut is XCAP

Towards enablers for NGNs 

This monolithic way of service provisioning in the IMS works for some cases, but is based on predictable rules and does not cater for dynamic conditions such as date and time or some result that can only be determined at runtime, that may be interesting to incorporate in the service model.

Organisations such as the Open Mobile Alliance (OMA) and the 3rd Generation Partnership Project (3GPP) are also radically changing the way in which services are being developed in such networks. These organisations are defining and standardising basic technologies that exist in the network and can be re-used among several different applications. These are called service enablers by the OMA and service capabilities by the 3GPP. We will call them enablers here for simplicity. Examples of enablers include presence, conferencing and instant messaging.

This move will eliminate redundancy in the application domain and will make the development of services quicker and easier. Developers will no longer need to have intimate understanding for example of the SIP Presence specification, but will simply need to use easy APIs exposed by the presence enabler to manipulate presence information. Not only this, but the use of enablers can also help operators provide complex and interesting services such as multi-player gaming and multi-party multimedia conferencing by pooling the enablers together to provide such services.

In order to provide complex service, some node in the network is required which is able to handle the interaction between and dynamic interleaving of these enablers. A special group in the 3GPP was setup that would investigate the architecture of such a node. The name service broker (SB) or service capability interaction manager (SCIM) was given to this node. It was suggested that the SCIM would sit between the ASs and the S-CSCF. The figure below shows the modified services architecture of the IMS, with the SCIM included.

1. ISC interface (SIP) is used between the SCIM and the S-CSCF

2. ISC interface is used between the SCIM and the ASs

3. The ISC interface is used between different SCIMs in the network

In general, the SCIM must be able to perform service interaction management through interaction logic that tells it how to coordinate between different enablers and which enablers to invoke and at what time. As yet, there is no technical specification that details the exact operation of this node, and so there is a need for experimentation in this area.

Demo at the DTI Awards in Cape Town - Part 2

We have returned two weeks ago from the DTI (Department of Trade and Industry) awards. As I alluded to earlier, Rhodes University was nominated by the THRIP (Technology and Human Resources for Industry) programme under the Research Collaboration category. Fortunately, we won!.
Preview
We are now releasing the code that we demonstrated at the DTI Technology awards. As you may recall from part 1, we modified the Mobicents Converged Demo that currently allows users to purchase furniture off a SEAM-powered website, to allow users to browse for and purchase videos instead. We put in an added feature that allows users to view the trailers of the movies on their RTSP-enabled SIP phones. As a client, we used a version of the JAIN SIP Applet phone  and added Gstreamer-Java libraries to it, to support RTSP streaming from a Darwin streaming server.

You can grab the code from my site, which includes the JBOSS server with pre-built binaries, Mobicents Media Server (MMS) sources for the Converged Demo, the modified JAIN SIP Applet phone and some videos to try out.

In addition to the screenshots we showed last time, we have also put up a video of the program in action. Note that this is work in progress, and we will be updating the service in the coming weeks and months - we have huge plans for it! Firstly, we want to remove Darwin and replace it with MMS RTSP stack [nudge to Jean ;-)]. We also want to add buddy lists and IM abilities. We would also incorporate policies and XCAP support. From there, the sky is the limit.

Hope folks enjoy it. Cheers!

Setting up at the hotel before the throw down :-)

The demo is coming together nicely ...

 The demo and the boys behind it, minus the guy with the cam :-)

The award for Research collboration awarded to the COE (Center of Excellence) at Rhodes