A tour of Sametime toolkits

by
Firas
Yasin

Level: Beginner
Works with: Sametime
Updated: 02-Jan-2003

Sametime is well-known for its superior collaboration technology, providing users with instant messaging and meeting services. Developers familiar with the product are also aware of its customization features, which include Sametime toolkits.

In this article, we take a tour through all the toolkits available to the Sametime developer. We start by identifying the available toolkits. Then we explore the capabilities of each toolkit and how it can be applied in real-life applications. But first, let’s find out why you may want to use these Sametime toolkits.

Why Sametime-enable applications?
As users rely on Sametime’s functionality more and more, they expect to find it (or at least its functionality) in other applications. For instance, a word processor user accustomed to using Sametime may want to collaborate on a certain document from within the word processor application. To do so, the user must switch to the Sametime Connect client, and then start a chat or meeting. But it would be easier for the user to have Sametime available from within the application to start the collaboration.

In addition to native applications, you can also Sametime-enable a Web site. Suppose you have a site with multiple contributors, and you want to enable your users to contact a contributor for more information about something that was published on the site. Using one of the Sametime toolkits, you can Sametime-enable the Web site. When you do this, users can quickly see who is and isn't online. For example, if a contributor is online, her name can be highlighted with an identifying color so other users can click it and start collaborating with her.

Multiple environments, multiple toolkits
As you can see from the previously mentioned examples, you can Sametime-enable applications for many different environments. There is the HTML environment, the native environment, and the Java environment to name a few. Sametime provides developers with toolkits to create solutions for these platforms and environments.

We can divide the Sametime toolkits into two groups: client-side toolkits and server-side toolkits. The client-side toolkits interact directly with the end user, while the server-side toolkits run on the server and provide services to the user indirectly. The client-side toolkits include the following:

Java Toolkit
C++ Toolkit
Sametime Links Toolkit
COM Toolkit

The server-side toolkits include:

Community Server Toolkit
Directory and Database Access Toolkit

For each of these toolkits, we'll look at the platforms for which it was designed, the language you can use with it, and the features of each. Before we examine the toolkits in detail, let's briefly review the Sametime architecture to help you better understand the function of each toolkit.

Sametime architecture overview
Sametime provides users with core services including awareness, chat, shared whiteboard, and application sharing. With the Sametime Multimedia Services package, users also have access to audio and video within meetings. Applications can be Sametime-enabled using the Community and Meeting Services. When a user logs into Sametime, he can access all the services provided by Sametime, regardless of whether the client he uses is the standard Sametime Connect client or a customized client using any of the toolkits.

Sametime is based on client/server architecture, where a client communicates with the server to achieve its purpose. A Sametime Connect client initiates a chat with another user through the Sametime server. The client sends instant messages to the Sametime server, which then forwards messages to the intended client. The Sametime server consists of three servers, each providing different services as described in the following table:

Server	Description
Community Server	Provides Community services, such as awareness, chat, and logins.
Meeting Services Server	Provides Meeting services, such as white boarding and application sharing, and an Audio/Video service which is available through the Multimedia Services package.
Domino Server	Provides many services, including authentication, HTTP, and directory access.

Client-side toolkits
Now let's discuss each of the client side toolkits, beginning with the Sametime Java Toolkit.

Sametime Java Toolkit
The Sametime Java Toolkit provides you with access to core Sametime services, such as awareness, chat, and white boarding. The toolkit also provides you with access to the Sametime Abstract Windowing Toolkit (AWT). You can embed the AWT components inside any AWT container, which reduces time required to develop a user interface to your Sametime application. An example of an application that uses the AWT is the Java-based Sametime Connect client that you can launch from your home Sametime server as shown in the following screen:

Sametime AWT container example

The toolkit has a layered architecture composed of three main layers: the Transport Layer, the Services Layer, and the UI Layer. The Transport Layer provides the communication link between the application and the Sametime server, while the Services Layer provides the application with the Sametime Community and Meeting services. The UI Layer provides the Sametime-enabled AWT component and the UI for the application.

The Java Toolkit is modular, thread-safe, and extendable. It provides access to the entire feature set in Sametime via an object-oriented API model. With this toolkit, you can expose the new functionality offered with Sametime 3.0, such as file transfer, selective alerts, and announcements.

You can also create applets and applications, such as a customized Sametime Connect client (the standard Connect client comes with a Java-based version), Sametime automatic response bots, and customized applications in which only a few features of Sametime are included. You can also create customized applets for your Web site using this toolkit. However, if you need to create a simple awareness application on your Web site, then you want to use the Sametime Links Toolkit.

Sametime Links Toolkit
The Sametime Links (ST Links) is a toolkit that lets you Sametime-enable a Web site by indicating whether or not a user is logged in to the Sametime server. The toolkit uses simple HTML and JavaScript APIs to provide this functionality. The Web page creator adds simple lines of code to a Web page with names to turn them into Sametime-enabled names (a.k.a. Sametime Links).

The HTML/JavaScript API is easy to use. The toolkit is lightweight with just a 20 KB embedded applet that requires no special installation on the client machine. The toolkit is also rich in features offering awareness with status icons, instant messages, and N-way chat. Users can also launch instant meetings. The toolkit provides an authentication mechanism in which users do not need to login if they have already authenticated on the Web site. One other attractive feature is the ability of the toolkit to work over the extranet through firewalls because it uses HTTP to communicate with the Sametime server.

The Sametime Links Toolkit is supported on Windows platforms (95, 98, NT, and 2000) with Microsoft Internet Explorer 5 and later. It also supported on Netscape Navigator 4.7x.

To access the ST Links on your Sametime server type in the following in your Web browser:

http://<sametimeserver>/sametime/toolkits/st30linkstk/index.html

The following screen shows a Sametime Link-enabled Web page:

Sametime Links-enabled Web page

To enable a Web page with ST Links, follow these steps:

In your Web page editor, open an HTML file with Sametime user names listed.
In the header of the page, add the following code:

<LINK REL=STYLESHEET HREF="http://<sametimeserver>/sametime/stlinks /stlinks.css" TYPE="text/css">
<SCRIPT src="(http://<sametimeserver>/sametime/stlinks/stlinks.js"></SCRIPT>
<SCRIPT>setSTLinksURL("http://<sametimeserver>/sametime/stlinks ");</SCRIPT>

(This assumes that the ST Links Toolkit is installed on your Sametime server in the default directory and the URL for it is http://<sametimeserver>/sametime/stlinks/stlinks.js.)
Add the following code to place the hidden Sametime Links Java applet on the page. You can insert this code anywhere in your Web page because the applet is placed on a hidden HTML layer.

<SCRIPT>writeSTLinksApplet (loginName, key, isByToken);</SCRIPT>

In the code, loginName is the user name and key is either the password or token. The isByToken is a Boolean variable which indicates whether or not you are logging the users using tokens. (Users can log in using a user name and password, a token, or anonymously.) For more information about this function, see the Sametime Links Toolkit guide.
Add a Sametime link anywhere in the body of the HTML file by typing the following:

<SCRIPT>writeSametimeLink(userName, displayName, bResolve, options)</SCRIPT>

Where userName is the unique user name, the displayName is how you want the user's name to appear (e.g. Last Name, First Name), and the bResolve variable is a Boolean variable indicating whether or not the name needs to be resolved by Sametime. False indicates that the name is already resolved. Options is a semicolon delimited list of options. For a complete list of options, see the Sametime Links Toolkit guide.
Save the HTML file.

Sametime C++ Toolkit
The Sametime C++ Toolkit runs within the Microsoft Visual C++ development environment. It targets Windows platforms (95, 98, ME, NT, and 2000) to create Win32 applications. You can run many of the applications created with this toolkit on a Sametime 2.0 or 2.5 server. However, if the application uses new features of the Sametime 3.0 environment (such as file transfer), then the application will not run on earlier Sametime releases (2.0 or 2.5).

The C++ Toolkit provides access to the following Community services:

Awareness service
BuddyList service
Community service
Directory service
File Transfer service
Instant Messaging service
Lookup service
Places service
Post service
Storage service
Token service

Notice that this toolkit, unlike the Java Toolkit, does not have a user interface (UI) component. If you create an application in which a user interface is expected, then you will have to develop your own interface. You can use this toolkit if you want to develop applications native to the Windows environment. Some of the applications that have been developed using this toolkit include NotesBuddy, which is available from alphaWorks. The following screen shows a NotesBuddy example:

NotesBuddy from IBM Alphaworks

The next screen shows the NotesBuddy List:

NotesBuddy List from IBM Alphaworks

Sametime COM Toolkit
The Sametime COM Toolkit is relatively limited in its functionality compared to the Java Toolkit. However, it provides you with access to any environment that supports COM objects. For example, if you want to develop Sametime awareness for Microsoft Office products, then the Sametime COM Toolkit is the answer. The toolkit also supports the OLE Automation technology by providing a TLB file as well as a DLL to support importing all interface names. By using your own development tools, you can create your own user interface on top of the Sametime services.

The Sametime COM Toolkit provides access to the Community service, Awareness service, Lookup service, and Instant Messaging service in Sametime. It provides logging in and out and changing one's status (active, away, do not disturb) through the Community service. It resolves names using the Lookup service and provides information about other users through the Awareness service. To send text and binary messages, it uses the Instant Messaging service.

You can run the sample code from your Sametime server, but before you do so, you must download the Microsoft Visual Basic runtime environment, which you can obtain from the Developer Resources page of Microsoft's Download Center Web site. The following screen shows an awareness sample from the COM Toolkit.

Awareness example for the COM toolkit

Server-side toolkits
In this section, we discuss the remaining two toolkits for Sametime: Community Server Toolkit and the Directory and Database Access Toolkit.

The Community Server Toolkit
The Community Server Toolkit is a Java-based toolkit. It lets you develop application services that run on the server, much like those that have already been developed and run on the Sametime server, for example Sametime Logger, Sametime Directory, and so on. This toolkit provides the mechanism for your applications to log in to the Sametime server as a server application and thus, to have access to services that a typical Sametime user may not have access to. So in a way, your server application can behave much like a super user on the server with access to server resources. The toolkit offers you an array of services much like the Java Toolkit does. The toolkit also provides you with the ability to create channels which are used for all communications in Sametime. These channels are virtual connection between two Sametime entities. The Community Server Toolkit provides developers the ability to create Sametime channels to communicate with other Sametime entities using a proprietary protocol.

You can use the Community Server Toolkit to create applications that monitor the Sametime server or to create a new service that uses it own channel. Users can connect to that channel to subscribe to the new service, for instance, a stock quote application.

The Directory and Database Access Toolkit
The Directory and Database Access Toolkit has two parts:

Chat Logging Service Provider Interface (SPI)
Token Authentication SPI

You can use the Chat Logging SPI to develop applications that log chat transcripts to a database of your choosing. The scripts can be later reviewed by administrators and supervisors even if they did not participate in the actual chats. It's your responsibility to determine the best methods to store these chats. In other words, the SPI doesn’t provide an off-the-shelf mechanism to store the transcripts, so it's up to you to choose which data store to use. For example, you may choose to store the transcripts in a DB2 or a Domino database.

The second part of the toolkit is the Token Authentication SPI. When a user authenticates using his user name and password, Sametime uses token authentication to authenticate the user's connection. In general, authentication by tokens allows users to authenticate without having to re-type their user names and passwords. Sametime out-of-the-box supports two types of token authentication:

Sametime proprietary tokens, which are only supported by Sametime
Light Weight Third Party Authentication (LTPA) tokens, which are supported by Domino and WebSphere

The Token Authentication SPI lets you implement a mechanism to support other types of tokens specific to your organization.

The full Directory and Database Access SPI is delivered as a DLL for the Windows environment and as a shared library for the AIX and Solaris environments. However, the SPI is currently implemented specifically for the Windows operating system using the Microsoft C development environment. AIX and Solaris developers can use the same source files to implement the SPI on their own platforms.

Which toolkit should I use?
Given all the available toolkits, you may be unsure which one to use. As with any development project, your best choice depends on several factors. These include:

Platform
Size/performance
Developer skills
Time
Features
Target user

Consider these factors in combination. For example, if you want to develop an application for a Win32 environment, and you are primarily concerned with the speed of your application’s performance, then the Sametime C++ Toolkit could be your best option. But if your developers are only trained in the Java development environment and you're considering deploying your application on other platforms someday, the Sametime Java Toolkit may be your choice. Also, consider whether or not your users will resist having to download another client (that is, your custom application), but still need access to Sametime awareness. If so, use the Sametime Links Toolkit. And if your users are concerned about using Sametime through their Microsoft Office products, consider the Sametime COM Toolkit.

How do I find the toolkits on my Sametime server?
To locate a Sametime toolkit, go to your Sametime home page and click the SDK link at the bottom of the home page as shown in the following screen:

If you click the link, but the toolkits appear in plain text, then you must install the toolkits on your Sametime server from CD 2 that ships with Sametime.

For more information about each toolkit, start by reading the Sametime product documentation, which you can download from the Documentation Library. You can also consult the IBM Redbooks Working with the Sametime Client Toolkits and Working with the Sametime Community Server Toolkit.

Conclusion
To sum up the Sametime toolkits, here is a table showing the toolkits and the platforms and programming languages that they support.

Toolkit	Platform	Language
Java	Any JDK 1.1 or higher	Java
Links	Web	JavaScript/HTML
C++	Windows	C++
COM	Windows	VB, JavaScript, LotusScript
Community Server	JDK 1.1	Java
Directory and Database Access	Windows, AIX, Solaris	C

Sametime's versatility extends to its toolkits and can be applied in many different flavors to achieve multiple objectives.

ABOUT THE AUTHOR
Firas Yasin is a Software Engineer for IBM, providing pre-sales support for several Lotus products. He currently concentrates on QuickPlace and Sametime development and customization. He is also one of the authors of the IBM Redbook Working with the Sametime Community Server Toolkit. A University of Kentucky graduate, Firas lives in Lexington, Kentucky and enjoys tennis when he's not working.