The Lotus Instant Messaging and Web Conferencing (Sametime) Connect client version 3.1 and later-both the Windows and Java clients-includes a hidden telephony extension. You can enable this extension by running a telephony server application that logs into a Lotus Instant Messaging and Web Conferencing server (which this article refers to as the Lotus Instant Messaging server). The existing telephony extension is a very basic implementation and provides limited ability to communicate call information from Lotus Instant Messaging and Web Conferencing Connect clients (which this article refers to as Connect clients) to a listening telephony server application.

This article introduces you to the telephony extension. It also describes a simple telephony server application capable of activating the extension and accepting and processing call setup requests from Connect clients, but does not set up the call on a voice network. In essence, the telephony extension is the conduit that allows third-parties and customers to build simple telephony into a Lotus Instant Messaging community. Using this article as a starting point, you can implement telephony functionality in a Lotus Instant Messaging community that allows your users to set up calls from Connect clients.

This article assumes that you are an experienced Java programmer and are familiar with the Community Server toolkit. Knowledge of computer-to-telephony interconnection technology is required to fully couple a telephony service provider or technology with Lotus Instant Messaging. This article describes the telephony extension, but does not attempt to provide network connection or physical call setup.

The telephony extension

The telephony extensions implemented by the Connect clients is basically an improved graphical user interface and run-time application enhancement. The user interface enhancement includes new phone call setup menu items and buttons in the Connect client. The run-time application enhancement allows the client to generate and send call setup messages to a Lotus Instant Messaging telephony server application.

This extension is not available by default and must be activated on the Lotus Instant Messaging server and in turn, on the Connect clients. You can activate the telephony extension on all clients logged into a particular Lotus Instant Messaging server by running a telephony server application that also logs into the server supporting the clients. In this article, we use the Community Server toolkit to develop the server application.

A telephony server application is a Java- or C++-based program that logs into the Lotus Instant Messaging server using the Community Server toolkit and provides telephony services to Connect clients. These services are supplementary to those core services provided by the Lotus Instant Messaging server itself.

In the following illustration, the telephony server application logs into the Lotus Instant Messaging server to provide extra services to Connect clients. With some server configuration, it is possible to run server applications on machines other than the Lotus Instant Messaging server itself. This protects the Lotus Instant Messaging server's integrity from third-party code. See the "Server application security" sidebar for additional security information.

When a telephony server application logs into the Lotus Instant Messaging server, it registers a specific channel type and publishes a server attribute containing some important login information. These actions allow the telephony server application to receive call setup requests from Connect clients. Once the telephony server application is connected to a particular Lotus Instant Messaging server, the telephony extension is enabled on all connected version 3.1 or later clients. Those clients can then send call setup requests to the telephony server application.

Enablement and use of the telephony extension does not require Connect client modifications; the telephony extension is already built into the client and only needs to be activated. The following screen details the telephony extensions. An enabled client has a telephone button in the toolbar and also has the option to Start a Phone Call in the main meeting menu, the contact list context menu, and the list context menu.

From a user's point of view, the telephony extension is similar to the chat feature. A user selects a number of buddies in his or her contact list and can either choose the Start a Phone Call menu item or click the Telephone button. When the user takes one of these actions, the client sends a message summarizing the proposed call to the telephony server application where its interpretation and processing is intended to be handled by a third-party telephony service provider or by a proprietary telephony service external to the core Lotus Instant Messaging services.

The actual implementation of the server application can include the setup of a voice over IP call between the parties selected by the user, the setup of a Public Switched Telephone Network (PSTN)-based connection for a telephone call, or perhaps the setup of a conference between the parties using an audiobridge or teleconference service provider.

When a user decides to use the telephony feature from a Connect client, there is no standard method to provide feedback on the state of the call (for instance, if the lines are busy or if some problem has arisen). Some suggestions include opening a chat channel back to the client to provide some textual feedback. This method is primitive, but has the advantage of being simple to implement and allows user input in the form of text commands. It's similar in theory to a Lotus Instant Messaging and Web Conferencing (Sametime) bot. A more sophisticated suggestion is to send back an applet URL to the client in a chat message. This URL could launch a call control application.

Back to top

Implementing the telephony extension

Now that we have introduced the telephony extension and its various possibilities, let's discuss the implementation of a very simple server application that provides the basics required to enable or activate the telephony extension, to accept incoming call requests, and to process call requests short of setting up the call itself.

The sample telephony server application

As previously mentioned, enabling the telephony extension on the Connect client and the processing of call request messages requires implementation of a telephony server application. This article discusses the design and implementation of a reference telephony server application. You can download the source code for this application from the Sandbox. The application outlined in this document is a Java application that logs into and manipulates the Lotus Instant Messaging server using the Community Server toolkit.

First, we discuss some preliminaries and requirements, and then discuss the design and implementation of the telephony server application. The server application is contained in the file TelephonySA.zip available for download. The contents of the archive are:

The telephony server application source code and class files are contained in the TelephonySA.jar file and the package structure is as shown.

Package com.lotus.sametime.telephonysa

The Launcher class provides the application entry point and constructs the TelephonySA class which is the main server application class. An instance of the TelephonyHandler class handles single incoming telephony requests. The CallRequestBuddy class represents a contact that is included in the telephony request. The CallRequestInfoParser is a class implementing a call request info parser (message format used by Connect clients) and de-serializer.

Package com.lotus.sametime.telephonysa.util

The UTIL package contains an STErrorLookup helper class that provides convenient translation of error constants into a human readable form.

Back to top

Requirements

You need the following tools to run and further develop the telephony server application.

Java development and runtime environment

We recommend that you download the latest Java software development kit and install it on your machine. The telephony server application described in this article was developed with Java 2 software development kit standard edition version 1.4.1_01 using the Eclipse integrated development environment version 3.0.0.

If you want to run the telephony server application, you need a Java run-time environment installed on the telephony server application host. Again the Java 2 runtime environment standard edition version 1.4.1_01 and above is recommended to run the telephony server application.

It is recommended, but not necessary, that you download and use a copy of the latest Eclipse integrated development environment to further develop the telephony server application. You can download the Eclipse integrated development environment from the Eclipse Web site. To setup a project using the telephony server application source code and external JAR files, see the Eclipse application help system.

Lotus Instant Messaging and Web Conferencing development

To run the telephony server application, you need Lotus Instant Messaging and Web Conferencing 3.1 or later server. The telephony server application logs into the Lotus Instant Messaging server to provide service. To properly use and test the telephony server application, you need a Lotus Instant Messaging 3.1 or later client.

Before you use or further develop the telephony server application, you need to add the Community Server toolkit (stcommsrvrtk.jar found in the bin/ directory of the Community Server toolkit install) to the telephony server application class path. Download the toolkit from either your Lotus Instant Messaging server (see the sidebar for details) or from the Downloads page. After installing the toolkit onto your machine, set your classpath to point to the stcommsrvrtk.jar file or alternatively copy the stcommsrvrtk.jar file to the directory from which the telephony server application is to be run. If you use Eclipse for development, you need to lookup the application help system to determine how to add the stcommsrvrtk.jar file to the build path.

XML parser

Next, you need an XML parser for Java. You can download the XML Parser for Java from the IBM alphaWorks site. After you download the binary distribution of the XML parser for Java, set your class path to point to the parser JAR files or alternatively copy the parser JAR files to the directory from which the telephony server application is to be run. Again if you are using Eclipse for development, you need to look up the application help system to determine how to add the XML Parser for Java JAR files to the build path. The latest Java runtime environments come pre-packaged with XML APIs.

Configuration

Finally, you need to configure the TelephonySA.ini initialization file to reflect the name of the Lotus Instant Messaging server to which you connect and configure any other setting you deem necessary. The following is a configuration example:

[connection]
sametimeserver      = 127.0.0.1

[debug]
debuglevel               = 1
debugprefix             = [TelephonySA] 
logfile                       = telephonysa.log
timestamplogfile       = 0

In the previous settings, the telephony server application connects to host 127.0.0.1 (localhost); the debug level is set to one, which prints only System.out (the higher the debug level the more verbose the debug output is produced); and debugprefix is the prefix appended to telephony server application output. The logfile key if present is the file to which all System.out and all System.err output is redirected. Finally, the timestamplogfile key indicates if there is a new log file created for each launch of the telephony server application (1) or if the same log file is to be overwritten over and over again (0).

Back to top

Running the telephony server application

Assuming that you have followed the requirements correctly, double-click the TelephonySA.bat file to start the telephony server application. Information similar to the following appears in the Java console or log file if configured:

[TelephonySA] Sametime telephony server application booting on Mon Jan 12 09:17:18 GMT 2004
[TelephonySA] Sametime debug level set to 1
[TelephonySA] Attempting serverApp login to Sametime server host dubxblue02 on port 1516
[TelephonySA] Sametime telephony server application is logged into the Sametime server dubxblue02
[TelephonySA] General Awareness service is available on dubxblue02
[TelephonySA] Putting the telephony attribute on sametime server dubxblue02
[TelephonySA] Telephony server attribute has been put on dubxblue02
[TelephonySA] Telephony service is available on dubxblue02

Start a call using a Connect client that is logged into the Lotus Instant Messaging server against which the telephony server application runs. After you connect to the Lotus Instant Messaging server, you should see the telephone icon and notice the new menu items to Start a Phone Call. Select a number of buddies and click the Telephone button.

On the telephony server application Java console or log file (if configured), you should see output similar to the following:

Received a CallRequest message from CN=Michael Desmond/O=IBM on Mon Jan 12 10:23:41 GMT 2004
<call_request_info>
	<user>
		<user_id> CN=Michael Desmond/O=IBM</user_id>
		<user_on_mobile_device>0</user_on_mobile_device>
		<external_user>0</external_user>
	</user>
	<user>
		<user_id> CN=Mark Wallace/O=IBM</user_id>
		<user_on_mobile_device>1</user_on_mobile_device>
		<external_user>0</external_user>
	</user>
</call_request_info>
Number of invitees 2
com.lotus.sametime.telephonysa.CallRequestBuddy 
	CN=Michael Desmond/O=IBM isExternal = false isOnMobile = false
com.lotus.sametime.telephonysa.CallRequestBuddy 
	CN=Mark Wallace/O=IBM isExternal = false isOnMobile = true

Finally, at the command prompt, press Ctrl+C or close the Java console to shut down the server. The server is also shutdown on logout from the server, for instance, during server shutdown or network failure.

[TelephonySA] Telephony server application shutdown hook is running
[TelephonySA] Sametime telephony server application is terminating
[TelephonySA] Removing the telephony attribute from sametime server dubxblue02
[TelephonySA] Waiting for removal of the telephony attribute from dubxblue02
[TelephonySA] Telephony server attribute has been removed from dubxblue02
[TelephonySA] Telephony service is unavailable on dubxblue02
[TelephonySA] Logged out of sametime host dubxblue02 - reason ST_OK

Back to top

The telephony server application (under the hood)

Let's now discuss the design and implementation of the telephony server application, concentrating on the most important points in the server application startup and run-time behavior. By discussing the telephony server application in this way, you will have a greater understanding of the Lotus Instant Messaging and Web Conferencing telephony extension and of the Community Server toolkit.

Server application start up

On start up, the telephony server application (TelephonySA class) loads and processes debug settings from the TelephonySA.ini file. Settings that cannot be loaded from the initialization file are defaulted. The TelephonySA also loads the name (IP address or DNS machine name) of the Lotus Instant Messaging server that it is to connect to using the initialization file key sametimeserver. To connect the telephony server application to a different Lotus Instant Messaging server, change the value of the Lotus Instant Messaging server key (sametimeserver) in the STTelephony.ini file. If the telephony server application (TelephonySA class) cannot obtain the name of the Lotus Instant Messaging server that it must connect to, it attempts to connect to the default IP address 127.0.0.1. (It assumes that it is running on the Lotus Instant Messaging server.) After the TelephonySA class loads the settings outlined above, it begins its server application boot sequence.

Server application login

The telephony server application uses standard login to the Lotus Instant Messaging server using the Lotus Instant Messaging serverAppService. (Server Application Service is part of the STBase component. See the Community Server toolkit documentation for details.) Login takes place using a direct socket connection on port 1516 with a 10 second timeout.

On login to the Lotus Instant Messaging server, the server application registers its service type. The telephony service provider is not an activity wrapper, so does not provide an activity type. Because of this, there is no service to register, so the telephony server application registers an empty array of service types. As you will see later, the telephony server application publishes its login details as an attribute on the Lotus Instant Messaging server. This is how the server is addressed:

                 
/*
* Login to the Lotus Instant Messaging server
*/
private void login()
{
	/*
	 * Register service type
	 */
	int[] svcTypes = { };
		
	/*
	 * Do not connect via the mux, use a direct socket connection
	 */
	Connection[] connections = { new SocketConnection(DEFAULT_PORT, 
		DEFAULT_CONNECTION_TIMEOUT), };
	serverAppService.setConnectivity(connections);
	serverAppService.loginAsServerApp(stHost, 
		STUserInstance.LT_SERVER_APP, "TelephonySA", svcTypes);

	}

After the server application has logged in (a server application is logged in when it has received the loggedIn() call-back from the serverAppService on the LoginListener interface that it implements), it registers itself as a listener for telephony IM channels.

Telephony IM channel registration

An IM channel as referred to in this article is simply a full-duplex data channel addressed using a login ID or a user ID that is capable of transporting text or binary data between Lotus Instant Messaging and Web Conferencing entities. (See the IBM Redbook Working with the Sametime Community Server Toolkit.) Text carrying IM channels implement chat in the Lotus Instant Messaging community. IM channels have a type that is simply an integer value that identifies the channel type; a telephony IM channel as described in this article is an IM channel of type 9060. Chat channels are of type ImTypes.IM_TYPE_CHAT.

To receive IM channels from other Lotus Instant Messaging and Web Conferencing entities, the entity must register itself as a listener for a particular type of channel. Registration is performed using the InstantMessagingService. (For more information about the InstantMessagingService, see the Community Server toolkit development guide). After a Lotus Instant Messaging and Web Conferencing entity registers itself as a listener for a particular type of IM channel and registers itself as an ImServiceListener on its InstantMessagingService interface, it receives asynchronous ImReceived call-backs from the InstantMessagingService whenever an IM channel of a registered type addressed to it is opened.

The telephony server application detailed here must register itself as a recipient of telephony IM channels as follows:

	
/*
* Register for telephony IM messages
*/
imService.registerImType(IM_TYPE_TELEPHONY);

IM_TYPE_TELEPHONY is a symbolic constant fixed with the value 9060 defined as the telephony IM channel type.

	
/*
*  IM type used by the telephony plug in.
*/
private final int IM_TYPE_TELEPHONY = 9060;

The reason the server application registers for telephony IM channels is that when a client sends call request information, this data is sent in a telephony IM channel to the telephony server application. To receive the information, the server must listen for telephony IM channels by registering for the telephony channel type, and then adding an IM service listener to the instant messaging service.The InstantMessagingService rejects any message that does not have a registered IM type.

		
/*
* Register for telephony channel type
*/
imService.registerImType(IM_TYPE_TELEPHONY);
		
/*
* Add an IM service listener to receive IM received events
*/
imService.addImServiceListener(new ImServiceListener()
{
	public void imReceived(ImEvent event)
	{
		TelephonySA.this.imReceived(event);
	}
});

When an IM channel of type telephony is received, addressed to the telephony server application, the telephony server application receives an imReceived call back, the only method in the ImServiceListener interface which the server application main class TelephonySA implements.

	
/* 
* Service request received, allocate a handler
*/
private void imReceived(ImEvent event)
{
	new TelephonyHandler(event.getIm());
}

Creating an IM channel to another entity in the Lotus Instant Messaging community requires a user ID or login ID. The telephony server application does not have a persistent user ID as such (it does not have an entry in whichever directory the Lotus Instant Messaging server uses for authentication), so to create an IM channel to the server application, a client must somehow get the telephony server application login ID, which it uses to address the telephony IM channel it wants to create to the telephony server application. This problem is solved using the telephony attribute.

Publishing the telephony attribute

The telephony server application publishes its login ID as an attribute on the Lotus Instant Messaging server. This has a two-fold effect: First, the existence of the telephony attribute on a Lotus Instant Messaging server enables the telephony extension on the Connect clients connected to the server; they are listening for this attribute to appear. Second, Connect clients can retrieve the login ID of the telephony server from the value of the attribute and so are capable of correctly addressing and setting up IM channels to the telephony server application. Publishing the server application's login ID/telephony attribute takes place after login to the Lotus Instant Messaging server.

You can set and remove attributes on a Lotus Instant Messaging server using the General Awareness Service (see the Community Server toolkit development guide for details). An attribute is identified by an attribute type and a value. To publish a Lotus Instant Messaging server attribute, create the generalAwareness component in your Sametime session, and then get a reference to the generalAwarenessService interface from the session object. Add a generalAwarenessListener to the component, and then wait for the serviceAvailable() callback.

After the serviceAvailable() callback is received on the generalAwarenessListener interface, a Lotus Instant Messaging and Web Conferencing entity--in our case, the telephony server application--can change or remove attributes on the Lotus Instant Messaging server. Attributes put on the Lotus Instant Messaging server can be derived from the basic primitives, such as String, Integer, Boolean, and so on, or can be put as a serialized object. To publish the telephony server application login ID as the telephony attribute, the login ID must be serialized into a byte stream using the NdrOutputStream utility. NdrOutputStream and NdrIntputStream are network data representation serialization utilities that greatly simplify programming using Lotus Instant Messaging and Web Conferencing.

		
/*
* Prepare the server login bytes to publish 
*/
try
{
	/*
	 * Serialize the login ID using network data representation, 
	 * this format is expected by Connect clients
	 */
	NdrOutputStream out = new NdrOutputStream();
	serverAppLoginId.dump(out); serverAppLoginBytes = out.toByteArray();
			
}
catch (Exception e)
{
	e.printStackTrace();
	print("Error Serializing the telephony 
		server application login bytes");
	System.exit(0);
}

After the telephony server application login ID has been retrieved and serialized into an acceptable format, it is then published to the Lotus Instant Messaging server as the telephony attribute using a call to the generalAwarenessService interface changeAttr() method which accepts a STServer object and the attribute to be changed. The STAttribute object passed as an argument to the changeAttr method is constructed with the telephony attribute ID, AwarenessConstants.STS_ATTR_TELEPHONY_PLUG_IN (9060), and the serialized telephony server login ID.

The telephony attribute is only published when the serviceAvailable callback is received from the generalAwarenessService indicating that the service is available on the connecting Lotus Instant Messaging server.

	
private void putTelephonyAttribute()
{
	/*
	* Publish the login bytes and wait for the attribute changed callback 
	*/
	print("Putting the telephony attribute on the server " + stHost);
		 
	if(generalAwarenessService.isServiceAvailable()) 
		generalAwarenessService.changeAttr(stServer, 
		new STAttribute(AwarenessConstants.STS_ATTR_TELEPHONY_PLUG_IN, 
			serverAppLoginBytes));
}

AwarenessConstants.STS_ATTR_TELEPHONY_PLUG_IN is a symbolic constant fixed with the integer value 9060--the telephony server attribute ID. Connect clients are constantly listening for the status of the AwarenessConstants.STS_ATTR_TELEPHONY_PLUG_IN attribute on their connecting Lotus Instant Messaging server in order to activate their telephony extension.

Because of the design and implementation of the Lotus Instant Messaging and Web Conferencing telephony extension, there can be only one telephony server application per Lotus Instant Messaging server at any particular instance. This is because the Connect clients use the value contained in the telephony attribute to address the telephony server application providing the telephony service. If one telephony server application publishes its login ID as the telephony attribute on a Lotus Instant Messaging server, and then another telephony server application does the same on the same server, the first server ID is overwritten, and in time, it is overwritten on all connected clients. Thus, the last telephony server to publish its login ID gets all the client requests.

After the telephony server application login bytes have been successfully "put" (indicated by a call from the attrChanged callback on the generalAwarenessListener interface), the telephony server application is ready to accept incoming service requests.

When the telephony server application is shut down or is logged out from the Lotus Instant Messaging server, it removes the telephony attribute from its connecting Lotus Instant Messaging server.

	
private void removeTelephonyAttribute()
{
	/*
	 * Remove the login bytes and wait for the attribute removed callback 
	 */
	print("Removing the telephony attribute from the server " + stHost);
		
	if(generalAwarenessService.isServiceAvailable())
		generalAwarenessService.removeAttr(stServer, 
			AwarenessConstants.STS_ATTR_TELEPHONY_PLUG_IN);

}

Service requests

An incoming service request is simply an XML message sent from a Connect client to the telephony server application. The XML message summarizes a telephone call request.

To prepare for incoming service requests, the telephony server application waits for callbacks on the imReceived() method in the ImServiceListener interface. This indicates that an IM channel has been opened to the telephony server application. To handle incoming requests, the telephony server application allocates a TelephonyHandler object to handle each new request.

	
public void imReceived(ImEvent event)
{
	new TelephonyHandler(event.getIm());
}

The TelephonyHandler class implements the ImListener interface. When an imReceived() callback is fired on the ImServiceListener interface implemented by the TelephonySA class, the main telephony server application class, an IM object representing the new IM channel is accessible from the event object. To accept data coming in on the IM channel, an ImListener must be attached to the IM object that represents the channel. To achieve this, the TelephonyHandler adds itself as an ImListener on the IM object with which it is constructed.

In essence, when the telephony server application receives a call request, it allocates a TelephonyHandler object that adds itself as a listener on the instant messaging channel and receives and processes the incoming XML request.

	
public TelephonyHandler(Im im){
	this.im = im;
	this.im.addImListener(this);
}

All interception and processing of this particular client request is managed by the allocated telephony handler. After the telephony handler is allocated to a client service request, it first receives the imOpened() callback on the ImListener interface and then the textReceived() callback when the client sends the text message with the actual call setup request.

Call_request_info

Service requests come from Connect clients over telephony instant messaging channels in the form of XML messages tagged at the top level with <call_request_info>. The Connect (Windows and Java) clients are programmed to send <call_request_info> messages to the telephony server when a call is started from the user interface. The <call_request_info> messages are sent over IM channels of type 9060 (telephony IM channels) to the telephony server application. Here is an example of a <call_request_info> message sent by a Connect (Windows) client to the telephony server application outlined in this article.

<call_request_info>
	<user>
		<user_id> CN=Michael Desmond/O=IBM</user_id>
		<user_on_mobile_device>0</user_on_mobile_device>
		<external_user>0</external_user>
	</user>
	<user>
		<user_id> CN=Mark Wallace/O=IBM</user_id>
		<user_on_mobile_device>1</user_on_mobile_device>
		<external_user>0</external_user>
	</user>
</call_request_info>

The format of the <call_request_info> is very simple. Each user who was selected in the contact list when the call was started from the user interface is represented as a <user> sub element with a user_id, user_on_mobile_device flag, and an external_user flag. The user_on_mobile_device flag is true (1) if the user is logged into Lotus Instant Messaging as a mobile user; the external_user flag is true (1) if the user is logged into Lotus Instant Messaging as an external user.

The getText() method on the IM event object can access the raw XML message sent over the IM channel. After the TelephonyHandler has access to the text message, it can parse it using the CallRequestInfoParser singleton class that accepts <call_request_info> messages and returns an array of CallRequestBuddy objects representing the call request. The CallRequestInfoParser is a very simple SAX parser.

In the following code sample--the textReceived method of the TelephonyHandler class--a summary of the call request is printed. In a production system, the call would be processed here.

		
System.out.println("Received a CallRequest message from " + 
event.getIm().getPartner().getId().getId() + " on " + date);
		
/*
* Print the raw XML
*/
System.out.println(event.getText());
		
/*
* Parse the XML string
*/
CallRequestBuddy[] buddiesToCall = null;
	
try
{
	buddiesToCall = 
	CallRequestInfoParser.getInstance().parseCallRequestInfo(event.getText());
} 
catch (Exception e)
{
	e.printStackTrace();
	event.getIm().close(0);
	return;
}

System.out.println("Number of invitees " + buddiesToCall.length);
		
/*
* Process/Print the call request data
*/
for(int i = 0; i < buddiesToCall.length; i++)
	System.out.println(buddiesToCall[i].toString());

Finally, after the call request information has been obtained, the IM channel back to the client must be closed. If the IM channel is not closed, it becomes a zombie channel and wastes resources:

		
/*
* Close the im channel back to the client,
* the client will not close this channel
* if server does not close it, it will become a zombie
*/
event.getIm().close(0);

When the imClosed callback is received on the ImListener interface, the ImListener needs to be removed, and the service request is then completed.

		
public void imClosed(ImEvent event)
{	
	/*
	 * Remove IM Listener
	 */
	event.getIm().removeImListener(this);
		
	im = null;
}

Back to top

Hints and Tips

There are some hints and tips related to the telephony extension that you should be aware of.

Users' online status in not considered when sending <call_request_info> messages to the telephony server application. For instance, if the user of a telephony enhanced Connect client selects everyone in his contact l list to start a call with, then all users (whether on-line, away, do not disturb, or off-line) are included in the <call_request_info> message. Filtering of on-line buddies can be achieved on the server application-side using the Awareness service and a watch list. (See the Java toolkit documentation.)

Another point to note in the Connect 3.1 Windows client is that, once the telephony extension has been activated on a Lotus Instant Messaging server, it remains activated client-side even when the telephony server application has been shut down and the telephony attribute has been removed from the connecting Lotus Instant Messaging server. To deactivate the telephony extension, restart the Lotus Instant Messaging Windows client. This is a known issue and has been fixed in Lotus Instant Messaging and Web Conferencing 6.5.1. Connect Windows 6.5.1 clients dynamically deactivate the telephony extension when the telephony attribute is removed from the Lotus Instant Messaging server. This does not require client reboot.

Back to top

Extending the example

In the telephony server application provided with this article, the call requests made by clients are parsed and a summary printed to the console. Setting up telephone calls is a more sophisticated matter, but the basic functionality and some simple extension points are provided. Let's consider a hypothetical example, providing teleconference support on a Lotus Instant Messaging and Web Conferencing 3.1 server. First, we need the server and a modified version of the telephony server application as outlined here in this article.

On startup, the telephony server needs to connect to an audiobridge using some proprietary API, or even better, using a standards-based telephony API. After the telephony server application is booted, it receives call setup requests and allocates telephony handlers. Instead of printing the call request details, the telephony handlers need to resolve user IDs to telephone numbers, perhaps using a directory or a database. After the phone numbers have been resolved, the telephony handler allocates resources for the call on the audiobridge and starts the call using the teleconference profile of the user that initiated the call--again using a directory or database to find this data. Policy could even be implemented--who has/does not have authorization to start teleconferences. After the teleconference has been initiated, the telephony handler instructs the bridge to dial all the users specified in the call request message.

As mentioned previously, you can implement user feedback using chat IM channels, perhaps sending an instant message to all the participants giving them a summary of the teleconference or even inviting them to the teleconference and allowing them to accept or reject the invitation. The possibilities with Lotus Instant Messaging technology are endless.

Back to top

Conclusion

Using the knowledge and code provided in this article, you can begin to implement simple telephony in a Lotus Instant Messaging community. The addition of telephony enables your Lotus Instant Messaging users to use the telephone system as easily as they would the Lotus Instant Messaging chat facilities. Telephony integration on Connect clients comes free; the telephony service provider must implement only one or more telephony server applications (as outlined in this article) and run them against the Lotus Instant Messaging community.

With computer telephony integration such a hot topic at the moment, Lotus Instant Messaging provides a very simple and effective means of providing telephony service to a large number of users.

Resources

• Download the sample code for this article from the Sandbox.
  
  
• Download the Community Server toolkit from the Downloads page.
  
  
• For more information about the Lotus Instant Messaging Community Server toolkit, see the IBM Lotus Redbook Working with the Sametime Community Server Toolkit.
  
  
• Download the XML parser used in this article from the IBM alphaWorks Web site
  
  
• Download the Eclipse integrated development environment from the Eclipse Web site.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• The telephony extension
• Implementing the telephony extension
• Requirements
• Running the telephony server application
• The telephony server application (under the hood)
• Hints and Tips
• Extending the example
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Lotus Sametime
• Buy: Lotus Sametime

Dig deeper into Lotus on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers