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.

Back to top

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.

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.

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

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)iterator.next();
}

Back to top

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.

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.

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.

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.

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.

Back to top

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.

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.

Back to top

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

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.)

javascript:
var h='https://paxos.lotus.com/dogear';
var d=document;
var b=d.body;
var e=encodeURIComponent;
var t=setTimeout;
var dw;
(function() {
 if(b){
  var p=d.createElement('script');
  p.charset='UTF-8';
  p.src=h+'/tools/blet.js';
  b.appendChild(p);
  }

 t("var u=d.getElementById('dogear_postUrl');
    if(u){u=u.href;}
    else{u=h+'/post?url='+e(location.href)+'&title='+e(d.title);}
    dw=open(u+'&ver=0.9','dogear','toolbars=no,width=670,height=650');
    if(!(dw==null||typeof(dw)=='undefined')){dw.focus()}",250)}
 )()

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.

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.

Lotus Connections toolbar

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

Back to top

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.

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.

<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
	<!-- 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" 
	src="http://connections.company.com/ibm_semanticTagServlet/
	javascript/semanticTagService.js"></script>
	<link rel="stylesheet" href="http:// connections.company.com/profiles/css/
	styles.css" type="text/css" />
</head>
<body>
	<script>
		var appName = "communities";	
		var microfmtTagScope = "div,h2";
	</script>
	<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;">fjania@us.ibm.com</span>
	</div>
	<h1>Person tag (popup)</h1>
	<h2 class="vcard">
		<a href="http:// connections.company.com/profiles/html/
		profileView.do?uid=6A1212897&lang=en" 
		class="fn url person">Frank Jania</a>
		<span class="email" style="display:none;">fjania@us.ibm.com</span>
	</h2>
</body>
</html>

Back to top

Conclusion

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.

Acknowledgments

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.

Resources

Learn

• Read the developerWorks article, "Deploying IBM Lotus Connections: Planning and architecture considerations."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Post-installation tuning."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Maintenance."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Troubleshooting."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Branding and customization."
  
  
• Read the developerWorks article, "Deploying IBM Lotus Connections: Application programming interface."
  
  
• Read the developerWorks article, "IBM Lotus Connections: Enhancing productivity with social computing."
  
  
• Read the developerWorks article, " An overview of the Atom 1.0 Syndication Format."
  
  
• Visit the developerWorks Lotus Connections page.
  
  
• Read the Lotus Connections V1.0 Reviewer's Guide.
  
  
• Consult the Lotus Connections documentation page for details on the installation, configuration, and administration of Lotus Connections.
  
  
• Learn more about the Atom Syndication Format.
  
  
• Learn more about AtomEnabled.
  
  
• Get more Firefox extensions development information.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Participate in the developerWorks Lotus team blog.
  
  

About the authors

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introducing the Atom API
• Integration with IBM Lotus Notes
• Integration with IBM WebSphere Portal
• Integration with Microsoft Windows Explorer and Microsoft Office
• Integration with Web browsers
• Using Javlin – Person Tag
• Conclusion
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Lotus on developerWorks

Lotusphere knows the secret to a successful collaboration event: You.

Lotusphere 2010. Register now! January 17-21, 2010 in Orlando, FL

Special offers