Building RSS feeds for Lotus Domino Document Manager

Set up an RSS feed for your binders in Lotus Domino Document manager, so users are notified when content is added or modified. Using a new view and modifying existing design elements in the database, you can easily create an RSS feed.

Share:

Tim Parsons, Software Engineer, IBM, Software Group

Tim Parsons is a Software Engineer who has been with IBM/Lotus since 2000. He has worked on Domino Document Manager the entire time. He enjoys playing golf and street hockey, and spending time with his daughter Julia.



04 April 2006

Also available in Russian

RSS is quickly gaining in popularity as a way in which to be notified when new content is added to a Web site or application. By adding a few new design elements and tweaking some existing ones, you can provide RSS feeds for binders in Lotus Domino Document Manager. Your Lotus Domino Document Manager users may find that this is a simple way to keep track of their favorite binders.

This article gives a quick overview of RSS, so you have an idea of what it is created in this article. There are far better RSS resources on the Web that you may want to refer to if you are new to RSS. The rest of the article guides you through the steps needed to set up an RSS feed for Lotus Domino Document Manager. This article assumes that you are an experienced Lotus Notes/Domino application developer and that you are familiar with Lotus Domino Document Manager.

RSS overview

A basic RSS feed consists of formatted XML. The first few lines of a feed describe it. These lines contain the title of the feed, a URL for the source, and a description of the feed.

<rss version="2.0">
	<channel>
	<title>Another binder</title>
	<link>http://server.hostname.com/database/view/document</link>
	<description>Another binder</description>

The next set of lines can be thought of as the actual content of the feed. Details about each item in the feed are enclosed in an <item> tag. To keep it simple in this article, you add only necessary information in each <item> tag. Each item contains a title, link, description, published date, and a unique identifier. After all the items are listed, there are just a few more lines that end the XML feed.

	<item>
		<title>Bold red.doc</title>
		<link>http://server.hostname.com/database/view/document</link>
		<description>
		<html><table><tr><td><b>Description:</b></td></tr>
		<tr><td>imported</td></tr><tr><td>&nbsp;</td></tr>
		<tr><td><b>Comments:</b></td></tr>
		<tr><td></td></tr></table></html>
		</description>
		<pubDate>02/08/2006 03:10:25 PM</pubDate>
		<guid>68446C2B10B8DEB58525710F006EBDFC</guid>
	</item>

Because you want to provide a feed of documents in a binder, the best method is to create the XML using a view. You can have the view create the <item> objects for each document, and then place the rest of the XML in a view template. Because most RSS readers request feed updates every few hours, you want to ensure the method you use to create the XML doesn't hinder server performance. A view has its index already created when a feed update is requested, so there should not be much impact.

A view also provides document-level security, so you can be sure that users see only documents to which they have access. Other methods, such as an agent or Java servlet can be used, but they may not perform as well or may not provide the document-level security that is required. The design elements described in this article are provided in a Domino database for download, so you do not need to recreate them.


Creating the view

First, you start by creating a blank view in your File Cabinet template database (filecab.ntf is the default). Name the view (rssBinderView) and give it an alias of rssBinderView. On the Advanced tab of the View property box, select the option "Treat view contents as HTML," if not already selected (see figure 1). This option prevents Lotus Domino from creating HTML for you, which breaks the XML that you create.

Figure 1. View property box
View property box

The view's selection formula is:

SELECT ObjectType = "Document" & IsLatest = "1" & ISWIPVer != "1" & ShouldBeDeleted != "1" & BinderID != ""

This formula selects all current documents in the database.

Hide the first column in the view, sort it ascending, and categorize it. The view should not have a title because titles break the XML. The column's value displays the BinderID field to ensure that the feed displays only the documents of one binder. More will be said about this first column later in the article.

The second column in the view should also be hidden, but sorted descending. Again, the view should not have a title. The column's value should be the Last Modified date. This column ensures the most recently edited document is first in the feed.

The third and final column should be visible and unsorted with no titles. This column creates the RSS XML for an individual document. The following code snippet generates the XML:

Click to see code listing

url := "http://servername.domain.com/";

"<item>" + @Char(10) +
"<title>" + @ReplaceSubstring(Title; "&"; "&") + "</title>" + @Char(10) +
"<link>" + url + @Left(@ReplicaID; 8) + @Right(@ReplicaID; 8) + "/(DDMAutoLaunch)?OpenAgent&DocID=" + DocID 
+ "&LaunchType=0</link>" + @Char(10) + "<description><html><table>
<tr><td><b>Description:</b>
</td></tr><tr><td>" + DescriptionOfDocument +
"</td></tr><tr><td>&nbsp;</td>
</tr><tr><td><b>Comments:</b></td>
</tr><tr><td>" + VerComment + "</td></tr>
</table></html></description>" + @Char(10) +
"<pubDate>" + @Text(@Modified) + "</pubDate>" + @Char(10) +
"<guid>" + @Text(@DocumentUniqueID) + "</guid>" + @Char(10) +
"</item>" +  @Char(10)

On the first line, the basic URL is hard-coded to generate the URL to the document. You hard code the URL because you cannot perform an @DbLookup in a view column. Normally, you can pull this information from the HTTP header, but the HTTP header isn't available because the view is built on the server. If you don't want to hard code this URL, you can create a setting in your server's Notes.ini file to look up that value. Using the Notes.ini method, you can deploy on multiple servers without hard-coding the information.

The next few lines create the item in the feed. Use an @ReplaceSubstring for the Title field because if any documents have an ampersand character in the title, the XML will break. By replacing the ampersand with the entity &, you solve this problem. Also, in the <description> tag, many characters have been escaped (for instance, < is now <). This is also done so you can provide HTML in the description tag and not break the XML. You can modify the <description> tag to contain anything you like. The code above creates a table with the document's description and the comment entered when the document was checked in.

That's it for the view. Save and close it, and let's move on.


Creating a view template

You need to create a view template for the view you just created. This template is used to filter the view to one binder and to provide the XML that wraps around the <item> values the view creates. To create the template, create a new form and name it $$ViewTemplate for rssBinderView. On the Defaults tab of the Form property box, set the Content type to Other and in the field beside the option, type text/xml (see figure 2). This prevents Lotus Domino from adding any of its own HTML to the form when it renders it for HTTP users. It also tells the RSS reader that you are providing XML.

Figure 2. Form property box
Form property box

Some hidden fields are added at the top of the form. These fields contain the query string and the values of the HTTP headers as well as parse the query string. The BinderID is contained in the query string of the feed's URL to allow you to use one view for all binders. If you have large File Cabinets, you may want to create a view for each binder. Using one view for a large File Cabinet impacts performance negatively because the view takes a long time to build, to update, and to filter.

The next few lines after the hidden fields start the XML for the feed. Notice in this sample, we use the binder's title for the feed's title. You may want to customize this. For example, you can add the library and the File Cabinet's name to make the title more descriptive (for example, Library::File Cabinet::Binder). The next line provides a URL that goes straight to the binder. The last line before the embedded view contains a description for the feed. This could be anything you like. In this example, we use the binder's title.

The following code snippet gets the binder's title. The variable qsBinderID is a field at the top of the form that parses the binder's ID from the URL's query string.

BinderRepID := @DbLookup(""; ""; "Maintenance"; 
_"GlobalProfile"; "BinderDBReplicaID");
@If(
	@IsError(BinderRepID);
		"Error getting BinderRepID - " + @Text(BinderRepID);
	@Text(
		@DbLookup(""; @Left(BinderRepID; 8) + ":" + 
		_@Right(BinderRepID; 8); "(BinderLookup)"; qsBinderID; "Title")
	)
)

Next, you embed the view you created in the previous step. You need to change a few properties to display this view correctly. On the Embedded View property box, you must display the view using HTML as opposed to a Java applet. Using the Java applet breaks the XML. It is also necessary to set the value for Show single category to qsBinderID to display only the documents for the requested binder.

After the embedded view, there are two lines to end the RSS feed: </channel> and </rss>. Save and close the form. With the combination of the view and the template, you have successfully built your feed.


Modifying existing design elements

Now that the view is done, you can add an icon so users can access the RSS feed, and you can modify a few other design elements, so your links in the feed work correctly. First, modify the agent (DDMAutoLaunch), which launches a document profile given its ID and version number. The modifications made to this agent enable it to launch the document's file as well as its profile. The code has also been changed to use Option Explicit, so all variables are declared before being used. It is probably easiest to remove the existing agent, and then to copy and paste it from the supplied database to your template. Be sure to open and save the agent after pasting it to make sure it compiles correctly.

Second, change the existing File Cabinet HTML form. The changes made to the form enable it to launch a binder view given its ID in the query string. A new field is added to the form (htmlBinderUNID) to parse the binder's UNID from the URL query string, if it exists. The other change is made to the HTMLTags field. The field is changed so that if htmlBinderUNID contains a value, it creates a URL to launch that binder. Here is the new code for the HTMLTags field:

titleTemp := "Document Manager";
DbName:= @ReplaceSubstring(@Subset(@DbName;-1);"\\";"/");
LibReplicaID:= @DbLookup("";"";"(InternalAdmin)";"GlobalProfile";"LibraryReplicaID");
varPath:=@If( htmlDocUNID!="";
	"/AllByUnid/" + htmlDocUNID + "?OpenDocument\">";
	htmlBinderUNID != "";
	"/(WebFindTOCUNID)?OpenAgent&BinderID=" + htmlBinderID + 
	_"&BinderUNID=" + htmlBinderUNID + "\">";
	"/Web+All+Binders?OpenView\">");

"<Title>" + titleTemp + "</Title>
<FRAMESET FRAMEBORDER=1 BORDER=1 bordercolor = \"white\" FRAMESPACING=3 COLS=\"175,*\">
<frameset frameborder=0 border=1 framespacing=0 rows=\"134,*\">
<FRAME NAME=\"Left\" SRC=\"/" + LibReplicaID + "/WebNavigationPanel?OpenForm\" 
MARGINWIDTH=0 MARGINHEIGHT=0 SCROLLING=\"NO\"><FRAME NAME=\"Tree\" SRC=\"/" + 
LibReplicaID + "/BlankForm?ReadForm\" MARGINWIDTH=0 MARGINHEIGHT=0 ></frameset>
<FRAMESET FRAMEBORDER=0 BORDER=0 FRAMESPACING=0 ROWS=\"53,*\"><FRAME NAME=\"Header\" 
SRC=\"/" + LibReplicaID + "/WebHeaderPanel?OpenForm\"  MARGINWIDTH=0 MARGINHEIGHT=0 
SCROLLING=\"NO\"><FRAME NAME=\"Bottom\"  MARGINWIDTH=0 MARGINHEIGHT=0 SRC=\"/" + 
DbName + varPath + "</FRAMESET></FRAMESET>"

Again, the easiest way to incorporate these changes is to copy and paste the form. Be sure to either remove or rename the existing HTML form first.

Lastly, you need to display a link to the feed. Add a standard feed icon, such as RSS feed icon available from Feed Icons Web site, in the binder's view. To do this, modify the WebTaskBarBinder subform. Towards the bottom of the subform, you see a table. This table contains the breadcrumb trail that is displayed in the binder view. Add a column to this table and add a field that generates the URL for the feed. You want to align the new column to the right, so the icon is displayed on the right-hand side of the browser window. To do this, make sure the cursor is in the new cell and open the Table property box.

On the Table Programming tab, set the Other field in the Cell HTML Tags section to Align=right (see figure 3).

Figure 3. Table property box
Table property box

You must modify the BinderTitleDisplay field as well. The change sets the BinderID in the parent frame. This is necessary because if a user navigates across multiple pages of the view, the BinderID will become lost. If the BinderID is lost, you can no longer generate the correct URL for the feed. The new field, rssIcon, generates the link to the feed. It uses JavaScript to create the link because you need to reference the BinderID variable in the parent frame, which is set by the BinderTitleDisplay field. The image is actually placed on the Domino server in the icon directory (typically, data\domino\icons).

Here is the value for the rssIcon field, which uses Javascript to create the link to the feed:

DbFilename:= @ReplaceSubstring(@Subset(@DbName;-1);"\\";"/");

"<script>document.write(\"<a href='/" + DbFilename + "/(rssBinderView)?OpenView&binderid=\" 
+ parent._BinderID + \"'><img src='/icons/xmlrss2.jpg' border=0></a>\")</script>"

At this point, you have made all the design changes required. Now, make sure the design elements are signed with the correct ID, and then load design from the server's console. Figure 4 displays an image of what the new icon looks like in a binder view.

Figure 4. Binder view
Binder view

Figure 5 displays an image of what the feed looks like in an RSS reader.

Figure 5. RSS reader
RSS reader

Accessing the feed

Accessing the feed is quite simple. In your Web browser, navigate to a binder to view its contents. To the far right, there is the feed icon that you supplied. Click it to load the RSS data. To make this more user friendly, you may want to add a page that describes what a feed is. For example, you can add a link next to the icon that says, "About this icon." The linked to page can describe what a feed is and how it helps the user keep track of binders and possibly suggest an RSS reader for the user to try. This is a good approach because users may get confused when they click the icon, and then see raw XML.

To add the URL to your RSS reader, simple copy and paste it. Depending upon your Domino authentication scheme, you may either see the contents of the binder or be prompted for a password.

A note about authentication

Most RSS readers can handle basic authentication. However, many people use some form of single sign-on (SSO). Typically, RSS readers don't understand SSO, so they don't load the feed correctly, if at all. One way around this is to paste the feed's URL into the reader's browser window (if it has one). That should display the SSO login page. After authenticating, the feed should now load correctly. You can also disable SSO.

Yet another alternative is to set up a replica Lotus Domino Document Manager server and to configure it with basic authentication. Then, modify the URL that the rssIcon field on the WebTaskbarBinder generates to point to the other server.


Conclusion

By adding two design elements and modifying three others, you can provide a simple RSS feed for binders in Lotus Domino Document Manager. This feed provides users an easy way to be notified when new content is added or modified. You can extend this simple approach to provide File Cabinet-level feeds or even feeds for other non-Lotus Domino Document Manager databases.


Download

DescriptionNameSize
Sample Notes databaserss.nsf448KB

Resources

Learn

Get products and technologies

Discuss

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=106468
ArticleTitle=Building RSS feeds for Lotus Domino Document Manager
publish-date=04042006