How does it work

A new approach for the development of telecom services


Let’s consider in a more detailed way the model for the development of telecommunication services. Its global framework is shown below.

As seen the AGI-proxy component is at the heart of the model. The AGI-proxy is a Java-based application implemented on the basis of FastAGI, an open source library. The AGI-proxy is installed directly on the PBX Asterisk side.

In fact, the Asterisk represents the same thing for the AGI-proxy, as the J2EE container does for a Java-servlet. All calling messages produced by the Asterisk come to the proxy within the method service with two parameters: interfaces AgiRequest and AgiChannel. Through the first parameter one can get the information about the calls (caller name / number, called number, context of the call, feed settings, etc.) and through the second one the interaction with the Asterisk is carried out (call termination, transfer mode and etc.).

Subscriber’s name (CallerIdName), caller’s number (CallerIdNumber) and called number (Extension) are wrapped within a string-parameter by the AGI-proxy. Then the AGI-proxy executes an HTTP request on its behalf to an external web service, whose URL is set in the configuration. The response from the invoked service is seen as an indication to what to do with the call. The call may be terminated or redirected to a specified number; a media file may be played. The instructions returned by an external service must be presented in an xml-format. It has a very simple scheme:

An example of the typical response of a web service is shown below:

On receiving this xml-response, the proxy will play the media file "demo-nogo" (playMadiaFile).

Under this architecture the sequence of calls is reduced to a very simple diagram.



A few words about external web services and provide you with one simplified example. Web services within this model may have many different purposes - from the statistics (to record a call and terminate it - in voting systems) to the Asterisk dialplan control (auto- answering and call forwarding in communication systems).

To demonstrate the functionality the proxy we need two files agiproxy.jar, AgiProxyScript.java and two configuration files - agiproxy.conf, fastagi-mapping.properties. The files should be copied to the directory /var/lib/asterisk/agi-bin/. Let’s make the following steps to configure the proxy:

1. Set the extensions (calls), to which the proxy will “react”. In the file /etc/asterisk/extensions.conf one may write, for example, the following instruction:
exten => _1XXX,1,Agi(agi://localhost/proxy.agi)
(To run the proxy when a four-digit number beginning with "1" is dialing up)

2. Set the URL of an external service (see below), with which the proxy will interact. For example:
urltunnel=http://localhost:8080/agiweb/agi.jsp
(to perform an HTTP-request to the agi.jsp at the localhost)

3. Set parameters for the interaction of the proxy with the Asterisk:
hostname=localhost (Asterisk server name)
username=manager (user name indicated in manager.conf)
password=pa55w0rd (password from manager.conf)

4. Compile AgiProxyScript.java for your operating system as follows: to run the instruction written below from /var/lib/asterisk/agi-bin/-directory (for Java version 1.6):

javac -cp .:asterisk-java-0.3.1.jar:agiproxy.jar AgiProxyScript.java

5. Run the Asterisk, using, for example, the following instruction:
asterisk -vvvvvcd

6. Launch the AgiServer by invoking the instruction below from /var/lib/asterisk/agi-bin/ - directory:
java -cp agiproxy.jar:asterisk-java-0.3.1.jar:. org.asteriskjava.fastagi.DefaultAgiServer

As the example of external services a trivial java server page (agi.jsp) has been written. It parses the string of parameters received from the AGI-proxy and determines a called number (Extension). Then it creates instructions for Asterisk depending of the called number: for the number “1200” a media file will be played, a call having the number “1300” will be redirected to the number “500”, any other numbers will be terminated.
In conclusion, let me remind you the advantages of using this model to develop telecommunication services as opposed to the traditional "programming" dialplan in configuration files:

1. The entry barrier for programmers of new telecommunication services becomes lower.
2. The possibility to develop services using various technologies, such as CGI, JSP, ASP.NET.
3. The possibility of integration of new external services without any changes on the PBX side.

Source code and files necessary to install the demonstration examples are available here.


Summary