Deploying IBM Lotus Connections: Integrating with other systems

Part six in our article series focuses on integrating IBM Lotus Connections with other systems using the Atom API. This article is intended for I/T specialists and developers and is helpful when exploring options to integrate Lotus Connections into your applications.


Mac Guidera (, Senior I/T Specialist, IBM

Mac Guidera is a Senior I/T Specialist who has been with IBM Lotus since January 2006. He has been working on the IBM Software Services for Lotus Connections Early Adoption project since January 2007. Enjoy his blog on all things lotus at

Frank Jania, Technical Evangelist, IBM

Frank Jania is currently the Technical Evangelist for IBM's Real Time Collaboration and Social Computing Technologies. He is responsible for building and maintaining relationships with business partners in an effort to enable them to use and extend IBM's collaboration platforms. In his almost eight years at IBM, Frank has developed tooling for the Sydney Olympic Web site, been the project lead for IBM Community Tools, done user interface work for IBM Research, and managed a distributed team of software engineers. A prolific inventor and member of IBM's IP community, Frank currently has 30 patents pending and is leading an effort to revitalize participation in the IP program across all of Software Group's Research Triangle Park site. Frank earned Bachelor and Master degrees in Electrical Engineering from The Cooper Union for the Advancement of Science and Art. Take a look at his social software blog.

FuYi Li (, Senior Software Engineer, IBM Lotus

FuYi Li is a Senior Software Engineer for IBM Lotus Connections working in Westford, MA. FuYi is the Lotus Connections Integration User Experience team lead working on linked values between Lotus Connections and existing applications such as IBM Lotus Sametime, IBM Lotus Notes, and IBM WebSphere Portal. FuYi architected and implemented the Lotus Connections portlet. FuYi holds an M.S. in Computer Science from Boston University and a B.S. in Computer Science from Beijing University of Aeronautics and Astronautics in Beijing, China.

Judy J. Piper (, SDK Developer, IBM

Judy Piper is Staff Software Engineer at IBM and Lotus Connections Activities and Forums API Lead. She has great technical expertise in HTTP and XML and has extensive knowledge in web application development and social software in particular. As a Development Lab Advocate, Judy supports IBM business partners and customers in their product development and deployment. She has been a mentor and a project coach to teams of student co-op programmers and has managed many intern projects. She earned her B.S. in Computer Science from University of Utah and joined IBM in 2004.

11 September 2007 (First published 04 September 2007)

Also available in Russian Japanese

Working with Web applications today requires accessing information dynamically in an open and platform-agnostic manner that allows data and process integration. The Atom Publishing Protocol (AtomPub) is a mechanism that meets this requirement, providing a standardized way to work with components. It is an application-level protocol for publishing and editing Web resources, and it is supported in these IBM Lotus Connections features: Activities, Blogs, Communities, and Dogear (in Profiles, only reading is supported). This article is an introduction to working with Lotus Connections through its Atom API.

Introducing the Atom API

The concept of publishing and syndicating data over the Web using XML is not new. XML-RPC paved the way almost a decade ago as seen in Frontie in April 1998. It is a remote procedure call that uses HTTP as the transport and XML as the media. It was designed to be simple while allowing complex data structures to pass back and forth between client and server; it was an elegant and easy solution that needed only time to improve.

Fortunately and unfortunately, emerging blogging software jumped right into the XML-RPC specification. It became a great way to publish and work with blogs remotely, giving users a choice of editing software and the freedom to be separated from the server. The specification went through an evolution in the LiveJournal Client/Server API, the Blogger API, and the MetaWeblog API to name a few. During this time, it became as complicated as could be and started to resemble a bad implementation of its parts. XML-RPC strayed from its simple and clear beginnings.

Like so many baby steps, this clumsy process was needed to instill confidence in remote syndication. We needed to see a big step forward to facilitate effortless interoperability, easier integration, and smooth compatibility among various applications and components through a secured transaction, and Atom was that necessary step.

Atom is a collective term commonly used to refer both to Atom Syndication Format and to Atom Publishing Protocol. Atom is a data model that specifies Atom Documents, Feed, and Entry. An Atom Document is a well-formed XML-based form of Web content and metadata. AtomPub standardizes communication between a client and a server for publishing and editing Web resources, using Atom Syndication Format and HTTP. Integration with other applications and interoperability among various components are easy with Lotus Connections features because they provide an Atom API that is compliant with Atom specifications.

A typical Atom data transfer operation between a client and a server begins with the client sending one of four HTTP GET, POST, PUT, and DELETE methods on a specified resource URI with an Atom Document as a request body. The server sends an HTTP response header and a response body after the client establishes a credential using the Basic HTTP authentication method. With the Lotus Connections Atom API, you can let the application determine what is best for accessing the service: JavaScript, PHP, J2EE, or LotusScript to name a few.

Integration with IBM Lotus Notes

With the release of the new IBM Lotus Notes V8 client comes the ability to easily extend the workspace environment to deliver access to applications through composite applications and client plug-ins. This capability is demonstrated in the IBM Lotus Sametime sidebar plug-in, which gives you the full functionality of Lotus Sametime within Lotus Notes, and the Activities sidebar plug-in, which allows users to interact with their dashboard on a Lotus Connections Activities server. You are not required to use Lotus Notes V8 to work with Lotus Connections features; this capability is available today through custom development with API calls.

The Lotus Connections plug-in for Notes (available in V1.0.1) demonstrates the ability to access and add to Lotus Connections data. This plug-in lets you add Lotus Notes documents to an Activity, create a Dogear bookmark of a document or database, or search for a person's Profile. Once installed, these options are available as a toolbar in Lotus Notes, allowing users to:

  • Add a Lotus Notes document to an Activity as shown in figure 1.
  • Bookmark a Lotus Notes document, view, or database as shown in figure 2.
  • Bookmark a database view.
  • Search for a person's name to view his or her Profile as shown in figure 4.
Figure 1. Add to Activity
Add to Activity
Figure 2. Add Bookmark
Add Bookmark
Figure 3. Profile search
Profile search

You can work with the Lotus Connections API easily by using the open source Abdera APIs in Java agents in IBM Lotus Domino Designer. The Abdera API project implements the Atom Syndication Format and AtomPub and hooks easily into the Lotus Connections API. Listing 1 shows the use of the Abdera object and Client class to retrieve a feed in a Lotus Notes Java agent.

Listing 1. Retrieving Overview feed from Activities
// Using Abedera ClientResponse object, you can retrieve entries 
// from a feed as follows.               
Abdera _abdera = new Abdera();
Client _client = new CommonClient(_abdera);
client.addCredentials(“http://” + hostname, null, null, 
new UsernamePasswordCredentials(_username, _password)); 
            RequestOptions _options = _client.getDefaultRequestOptions();

ClientResponse clientResponse = 
_client.get(“http://” + hostname + atomFeedPath);             
            InputStream in = clientResponse.getInputStream();                  
            Document doc = (Document)_abdera.getParser().parse(in);
Feed feed = (Feed)doc.getRoot();
List links = feed.getEntries(); 
Iterator iterator = links.iterator();
while( iterator.hasNext()){
   Entry entry = (Entry);

Integration with IBM WebSphere Portal

IBM WebSphere Portal provides a single access point to Web content and applications, personalized to each user's needs. Integration of WebSphere Portal and Lotus Connections features gives business users a complete Web 2.0 collaboration suite. The value of integrating WebSphere Portal and Lotus Connections is much more than the sum of the two. In this section, we show you some of the integration points between WebSphere Portal and Lotus Connections.

Lotus Connections Portlet

Lotus Connections Portlet supports all five Lotus Connections features: Dogear, Profiles, Communities, Activities, and Blogs. Lotus Connections Portlet is a JSR168 standard portlet; it supports View, Personalize, Edit Shared Settings, and Configuration modes.

Lotus Connections Portlet leverages the Atom feeds provided by the Lotus Connections features to supply a Lotus Connections dashboard for portal users. Lotus Connections Portlet supports viewing all five features with different views, displaying tag clouds, supporting search and customized views, and providing a quick launch to the Lotus Connections Web user interface. See figure 4.

The portlet is an Ajax portlet that uses XMLHttpRequest to retrieve the feeds from the Lotus Connections features, processes the feeds using Document Object Model (DOM), and uses DHTML to display the content dynamically without refreshing the whole portal page.

Figure 4. Dogear portlet
Dogear portlet

When the portlet is configured to work with multiple Lotus Connections features, a drop-down menu allows users to view data from selected applications. In each application, the user can select views from a drop-down menu. The views include out-of-the-box views and custom views. Custom views can be defined in the Portlet Edit Shared Settings mode. In the next section, we show you how to define custom views.

The portlet's main content is the list of entries of selected services in a selected view: My Activities, My Blogs, My Bookmarks, and My Communities. Each entry provides a short description when you click the Read More option.

For each of the features, the portlet supports full-text search and filtering by tags. If you want to make the portlet window smaller, you can hide the tag cloud and search box. For some features, there is more than one search scope. For example, you can search All Bookmarks, Tags, People, and My Bookmarks in Dogear.

Installation and configuration

If you prefer to have a single service for each portlet, you can clone the portlet to create multiple portlets. Each portlet can be configured to connect to a single service. Alternatively, you can also configure each portlet instance to work with a single Lotus Connections feature.

The portlet supports single sign-on (SSO), which means that if WebSphere Portal and Lotus Connections are configured for SSO, you do not need to provide user name and password when using the portlet. If Websphere Portal and Lotus Connections do not have SSO set up, you must provide user name and password in the personalization mode as shown in figure 5.

Figure 5. Personalization mode
Personalization mode

You can define custom views in Edit Shared Settings mode. In addition, you can also define which applications should be displayed in the View mode by selecting or deselecting the Show the application option. You can set the default view shown in figure 6.

Figure 6. Shared portlet settings
Shared portlet settings

Lotus Connections Portlet can act as a cooperative portlet. Figure 7 shows an example of using Lotus Connections Portlet as the target portlet to display federated search results across four Lotus Connections features. Each feature is a Lotus Connections Portlet instance. The four features (Communities, Dogear, Activities, and Blogs) along with Google display search results from a source portlet in which marketing was entered as a search string.

Figure 7. Portlet display
Portlet display

Other WebSphere Portal integration points

Because all Lotus Connections features provide Atom/AtomPub and because Websphere Portal is a Web application, developers can easily create situation applications leveraging the supported Lotus Connections Atom API. For example, you can create Firefox extensions to insert a Dogear or Activities icon next to bookmarkable Web content, and you can allow users to click the icon to bookmark the content to Dogear or to send a link to Activities.

Integration with Microsoft Windows Explorer and Microsoft Office

Lotus Connections Plug-ins for Microsoft Windows Explorer and for Microsoft Windows Office uses the Lotus Connections Atom/AtomPub API to publish documents to Activities and Blogs and to search Profiles.

Lotus Connections Plug-in for Microsoft Windows Explorer allows a user to post a document to Activities by right-clicking a document from Microsoft Windows Explorer. The Lotus Connections Microsoft Office Plug-in for Microsoft Word allows Microsoft Windows users to publish a document to Activities, to post content to a Blog, to search Profiles, and to create a to-do list.

With the "Make To Do List" option, you can quickly post a list of to-dos to Activities from a Microsoft Word document by highlighting the lines you want to make as a list of to-dos. When you post a document to Activities as shown in figure 8, you can choose the Activities you want the document to post to. You can add descriptions and tags for this posting.

Figure 8. Add to Activity
Add to Activity

Similarly, Lotus Connections Plug-in for Microsoft PowerPoint and Excel supports Add to Activities and Search Profiles functions. In a document, you can highlight a name and choose Search Profiles from the Lotus Connections menu. The search results are displayed in a dialog box as shown in figure 9. You can then click the name to view this person's profile from the Profiles Web user interface.

Figure 9. Profiles search
Profiles search

Integration with Web browsers

Lotus Connections is a powerful suite of Web applications that allows for easy integration through the Web browser. These are seen quickly in bookmarklets and plug-ins.


Bookmarklets are small JavaScript programs stored as URLs in a browser's bookmark. Bookmarklets look like normal links, but they contain functionality that can modify the content of the page, launch a new page, or follow any other programmatic instructions.

Lotus Connections ships with bookmarklets for three of its services:

  • The Activities bookmarklet allows you to add the URL currently loaded in the browser to an Activity. The window that opens presents you with the list of Activities to which you belong.
  • The Communities bookmarklet allows you to add the URL currently loaded in the browser to the list of bookmarks for a Community.
  • The Dogear bookmarklet allows you to add the URL currently loaded in the browser to your bookmarks.

For these services, you can navigate to the Tools page to drag these bookmarklets to your browser's links bar. Because bookmarklets are simply JavaScript, you can use them as a template for adding functionality to your own page. Listing 2 shows the content bookmarklet that ships with the Dogear feature of Lotus Connections. (The bookmarklet in listing 2 has been formatted for ease of reading. Normally it would not have any line breaks.)

Listing 2. Content bookmarklet of the Dogear feature
var h='';
var d=document;
var b=d.body;
var e=encodeURIComponent;
var t=setTimeout;
var dw;
(function() {
  var p=d.createElement('script');

 t("var u=d.getElementById('dogear_postUrl');

This code constructs a URL that is called to launch the pop-up window with some of the fields populated. If you want to implement a bookmarking function in your Web application, you can generate this URL automatically and embed it in your page. If your application does not run in the browser, you can generate the URL and call to the operating systems to launch the default browser to reuse the dialog box.

Browser extensions

In this section, we provide examples of browser extensions without delving into the mechanics of building extensions for different browsers. For more information on developing Firefox extensions, refer to the Mozilla Web site. These examples have been implemented by IBM developers using the Lotus Connections API, which will be covered in the next article in this series.

The to-do bar in Firefox

The to-do bar in the Firefox browser allows you to quickly and easily manage the to-do's assigned to you in an Activity. See figure 10.

Figure 10. Firefox browser extension
Firefox browser extension

The Dogear plug-in

The Dogear extension can be installed from the Dogear Web application. You can find it on the Tools page of the Dogear application.

The Dogear browser extension shows who else has bookmarked the current page and which tags they have used. It also gives you a quick link to store the bookmark yourself. See figure 11.

Figure 11. Dogear browser extension
Dogear browser extension

Lotus Connections toolbar

The Lotus Connections toolbar allows for easy searching and for adding bookmarks to various services. See figure 12.

Figure 12. Lotus Connections toolbar
Lotus Connections Toolbar

Using Javlin – Person Tag

Lotus Connections contains reusable JavaScript libraries for incorporating rich information about people in the Profiles directory from within your own application. The examples that follow show the two styles of person tags – inline and pop-up – in their open and closed states. Figure 13 through 16 show the states for person tags.

The four images show the two types of available person tags, each in its open and closed states. The first two show the inline person tag, which displays the user's photo and name when closed and more detailed information when opened. The second two show the pop-up person tag. When closed, the pop-up person tag reacts to a user's hover and displays a control that when clicked displays a business card with more information.

Figure 13. Inline person tag - closed
Inline person tag - closed
Figure 14. Inline person tag - open
Inline person tag - open
Figure 15. Pop-up person tag - hover
Pop-up person tag - hover
Figure 16. Pop-up person tag – displayed
Pop-up person tag – displayed

The code that generates these tags is very simple. Listing 3 is all the code you need to generate both these tags on a sample page that works when loaded in any browser with access to the Lotus Connections Profiles server.

Listing 3. Generating person tags
<html lang="en" xml:lang="en" xmlns="">
	<!-- Copyright IBM Corp. 2001, 2006 All Rights Reserved. -->
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<title> Person Tag test page </title>
	<script type="text/javascript" 
	<link rel="stylesheet" href="http://
	styles.css" type="text/css" />
		var appName = "communities";	
		var microfmtTagScope = "div,h2";
	<h1>Person tag (inline)</h1>
	<div class="vcard X-person-display-inline">
		<span class="fn" style="display:none;">Frank Jania</span> 
		<span class="email" style="display:none;"></span>
	<h1>Person tag (popup)</h1>
	<h2 class="vcard">
		<a href="http://" 
		class="fn url person">Frank Jania</a>
		<span class="email" style="display:none;"></span>


As we have demonstrated in this article, the Lotus Connections implementation of the Atom API makes it easy to integrate third-party applications with the social networking suite. The abilities to extend Lotus Connections and to easily create mash-ups, plug-ins, or new interfaces are key features of the product.


The authors of this article want to thank the Lotus Connections Atom API Review team for their efforts and resources that made this article possible. Rob Yates (Chair), Andy Myers (Activities), Judy Piper (Activities), James Snell (Blogs), Alex Kordun (Communities), David Brooks (Dogear), and Colleen Connearney (Profiles). Also, thank you to Dan Gurney from the Plug-in team for his great work and willingness to provide help and support.





developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks

ArticleTitle=Deploying IBM Lotus Connections: Integrating with other systems