This article demonstrates how to build up your own solution using Lotus Quickr content services; it includes an example of a customized search center.

Prerequisites

To get the most from this article, you should already have an understanding of:

• IBM Lotus Quickr
• Representational State Transfer (REST) services
• Web services based on SOAP
• Atom syndication format
• IBM WebSphere® Portal
• Javaâ„¢ programming

Back to top

Introduction to IBM Lotus Quickr and Lotus Quickr services

IBM Lotus Quickr is team collaboration software that helps you share content, collaborate, and work faster online with your teams. It also provides a set of public APIs (services) for you to access content to build up your own solution.

Lotus Quickr content services make it possible to create, manage, update, search, query, and delete Lotus Quickr content. The services enable users to access and manipulate content in Lotus Quickr, using a diverse set of clients and programming models such as REST- or SOAP-based protocols.

In Lotus Quickr 8.1 services for IBM WebSphere Portal, searching content is performed using search scopes to target results to specific domains. REST-style services are available to get the list of defined scopes and to perform a search operation on the content defined in a scope.

Back to top

The scenario

Lotus Quickr provides a search center that offers the ability to search documents and other collaborative content, such as blogs and wikis. In addition, Lotus Quickr provides a set of powerful content services that can be used to build customized solutions.

Figure 1 shows the high-level architecture of the search center for this scenario, which is made up of four main components for search, sorting, categorizing, and filtering. Using the search center, users first perform a search operation, which is implemented by the Search Service; the target search systems are configurable to one or more Lotus Quickr services for IBM WebSphere Portal servers. Then, based on the retrieved search results, users perform specific sorting, categorizing, and filtering operations based on the document properties retrieved using Lotus Quickr document services. When sorting, the documents are ordered by user-selected criteria and then shown as a top-ten list. When categorizing, the documents in the search results are classified into several categories by a specific document property with a summary of each category provided. When filtering, the documents in search results can be subselected based on document properties.

We use a scenario about the Olympic Games to demonstrate the story. Suppose there are documents about Olympic Games stored in different libraries in different Lotus Quickr servers. Each document can be for a specific Olympic Games, such as the 2008 Beijing Olympics or the 2004 Athens Olympics. Also, each document can be for different activities, including the opening ceremony, the torch lighting ceremony, details of the matches, and so on. This information is stored in a user-defined property sheet that is applied to each document.

Back to top

Deployment and data preparation

To explain the scenario, we provide a complete example in the form of a portlet that you can download from the links shown later in this article. You can deploy the portlet into Lotus Quickr services for WebSphere Portal so that you can try out the example with your own document content.

Follow these steps to complete the deployment and preparation of the example portlet.

Portlet deployment

To deploy the portlet, do the following:

1. Download the WAR file available in the Downloads section of this article. Review the readme.txt file, and update your related properties file according to your environment. You need to specify access information for the target servers, including server URL, port number, username, and password.
2. Log in to the Lotus Quickr server as someone with administration privileges (for example, as wpsadmin), click Site Administration - Advanced Administration - Portlet Management - Web Modules. A window like the one shown in figure 2 opens.
   
   
   Figure 2. Web modules
   
   
   
3. Click Install as shown in figure 3. Then click Browse and select CustomizedSearchCenter.war, and then click Next and Finish. Then, click Back to Home.
   
   
   Figure 3. Install Web module for CustomizedSearchCenter
   
   
   
4. Select Create a Place - Custom. Enter the name of your place and click Create. Enter the newly created place, click Customize - Pages - Advanced layout, and then create a new page. Search for the portlet titled CustomizedSearchCenterPortlet; see figure 4. Click OK to deploy the portlet.
   
   
   Figure 4. Search Center user interface
   
   
   

Data preparation

To demonstrate the functions of the search center, prepare some documents with specified properties. You need to prepare documents in the target servers that you indicated in step 1 of the preceding process. The detailed requirements are listed here.

To prepare the documents, follow these steps:

1. From the upper right of the library portlet, select Manage Library Elements as shown in figure 5, and then select Property Sheets. Create a property sheet named Olympics that has city and activity fields as shown in figure 6. Search results are categorized and filtered according to the value of these properties.
   
   
   Figure 5. The Manage Library Elements window
   
   
   
   
   Figure 6. The Create Property Sheet window
   
   
   
2. Create a document type named OlympicsDocType and its property sheet named Olympics as shown in figure 7.
   
   
   Figure 7. The Create Document Type window
   
   
   
3. Create some documents in the OlympicsDocType document type, and set the value for the city and activity fields to different values (such as Beijing, Sydney, Athens for the city property and Opening Ceremony, Closing Ceremony, Match Detail for the activity property). Create the documents at different times so that you can also try out sorting using the property last update date. See figure 8.
   
   
   Figure 8. The View Document Properties window
   
   
   
4. Add different comments to the documents because the comment number is one of the sort criteria of the search results.

Back to top

Solution

This section focuses on the implementation details of the features provided in this customized search center: search, sort, categorize, and filter. In the following sections, we introduce you to how to use these Lotus Quickr services in a Java program, and we provide sample code and demonstration screen captures.

Search

The Lotus Quickr search service is based on the REST architecture style, which accepts standard HTTP requests using parameters in the URL to express search conditions. It then provides responses of search results in the Atom feed format. The search request is a standard HTTP GET command:

http:// <hostname>:<port>/searchfeed/myserver/search?
Scope=&query=Quickr&queryLang=en&results=100

This request includes the following parameters:

• <hostname>: The hostname of the Lotus Quickr server.
• <port>: The port used by the Lotus Quickr server.
• scope: The scope to search; an empty string means search all available indexes.
• query: The search keywords.
• queryLang: The language of the query string; this value must comply with ISO 639 and ISO 3166 standards. (This parameter is optional; the default value is the server locale.)
• results: The number of results to return for a single request.

For a detailed explanation of all of the parameters supported in the Lotus Quickr search service, refer to the Lotus Quickr wiki on developerWorks® Lotus.

The Lotus Quickr search service processes the search request and returns the matched results in Atom feed format. Listing 1 shows a sample response.

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom" >
<atom:title>Search results for query Quickr on all sources</atom:title>
<atom:updated>2008-03-18T17:36:21.344+08:00</atom:updated>
<atom:entry>
	<atom:title>Quickr FVT team Introduction.ppt</atom:title>
	<atom:author>
	   <atom:name>wpsadmin g wpsadmin sn</atom:name>
	</atom:author>
	<atom:updated>2008-03-07T14:40:30.000+08:00</atom:updated>
	<atom:id>/lotus/poc/?uri=dm%3a3c4973804909a2a5b2e6b383f770467c&
	pageHint=6_BUJUQL5108G0702330VJI712G6</atom:id>
……
</atom:entry>
......
<atom:entry>
	......
</atom:entry>
</atom:feed>

In the response, each entry represents a matched document. In the example portlet, Apache Abdera is used to parse the response. The search results are saved into a hash map for sorting, categorizing, and filtering. Figure 9 shows the structure of this hash map.

Listing 2 shows the process of retrieving and handling search results. You can find the project source in the attached WAR file, CustomizedSearchCenter_multiServer.war. The following code snippet is part of \WEB-INF\classes\com\ibm\clb\cmsearch\SearchAndFilter.java.

public Map getSearchResult(String keyword) throws Exception {
	Map searchResultMap = new Hashtable();
	List list = new ArrayList();
	String key = urlencode(keyword);
	String searchUrl = SEARCH_BASE_URL
        + "search?locale=en_US&results=100&scope=&queryLang=en&query=" + key;
	response = client.get(searchUrl);
	Document doc = response.getDocument();
	Feed feed = (Feed) doc.getRoot();
	releaseResponse();
	Iterator iter = feed.getEntries().iterator();

while (iter.hasNext()) {
	Entry entry = (Entry) iter.next();
	String id = getDocumentID(entry.getId().toASCIIString());
	String title = entry.getTitle();
	String type = 
	entry.getAlternateLink().getAttributeValue("type");			
	String link = SEARCH_BASE_URL.substring(0, (SEARCH_BASE_URL
		.indexOf("searchfeed") - 1))
		+ entry.getId().toASCIIString();
	Date ludate = entry.getUpdated();
	String author = entry.getAuthor().getName();
	SearchItem searchItem = new SearchItem(id, title, type, summary,
		ludate, link, author);
	searchResultMap.put(id, searchItem);
}
	return searchResultMap;
} 
	

Figure 10 is an example of the list of matched results using Olympics as the keyword.

Sorting

Different criteria can be used to sort the documents in the search results that you retrieved. Two sorting criteria are introduced in this section: sorting by comment number of documents and sorting by last updated date of documents. Together, these two properties define a hot document, one that displays in the top-ten list.

We made the following assumptions to define hot documents:

• Hot documents should have more comments than other documents.
• Hot documents should be updated more recently than other documents.

The last updated date property of the documents has been retrieved from the Lotus Quickr search service and saved into the SearchItem bean. Although the comment numbers of the documents couldn’t be retrieved from the Lotus Quickr Search service, it can be calculated according to the feeds of the documents, which are produced by the Lotus Quickr Document REST service.

The Lotus Quickr document REST service is a REST-style interface that provides various operations on Lotus Quickr documents. The service defines a URL for getting document libraries, folders, and documents, based on UUIDs. Thus, for the documents in the search results, you need to assemble and access their document feed URLs, and the information that you need is included in the returned Atom feed. The document UUIDs have been saved in the SearchItem bean, and the format of the URL is as follows:

http://<hostname>:<port>/dm/atom/library//document/<documentUUID>/feed?pagesize=100

For a detailed introduction to the parameters supported in Lotus Quickr Document REST service, refer to the Lotus Quickr wiki on developerWorks Lotus.

The Lotus Quick Document REST service processes the HTTP request and returns the document feed in Atom feed format. Listing 3 shows a sample response.

<?xml version="1.0" encoding="UTF-8"?>
<feed xml:base="http://lwpcn05.cn.ibm.com:10038/dm/atom/library//" >
  <id>urn:lsid:ibm.com:td:7f45d70049099f85b2c9b383f770467c</id>
  <title type="text">Quickr 8.0 introduction.doc</title>
  <updated>2008-03-18T08:25:09.844Z</updated>
  
  <entry>
    <id>urn:lsid:ibm.com:td:91b262004909c20db4ffb583f770467c</id>
    <link href="document/7f45d70049099f85b2c9b383f770467c/comment/
    91b262004909c20db4ffb583f770467c/entry" rel="self"></link>
    <author>
    		<name>wpsadmin g wpsadmin sn</name>
    </author>
    <updated td:displaydate="Yesterday at 4:25 PM CST">
    2008-03-18T08:25:09.875Z</updated>
<content type="html">this is one of the comment content</content>
  </entry>
  <entry>
  ......
  </entry>
  ......
</feed>

In the response, each entry represents a comment of the document. Apache Abdera is used to parse the response in this example. The comment number of the document can be calculated by counting the entry number in the feed, and the result can be saved into the SearchItem bean.

Now both the comment number properties and the last updated date properties of the documents in the search results are prepared for sorting. You use them to produce the list of the top-ten documents.

The implementation of sorting functionality is shown in listing 4. Look at CustomizedSearchCenter_multiServer.war\WEB-INF\classes\com\ibm\clb\cmsearch\SearchAndFilter.java to learn more about the details.

public static Map topTenMapByCommentsNumber = new Hashtable();
public static Map topTenMapByLastUpdatedDate = new Hashtable();
public void makeTopTenHotDocument(Map searchResultMap) throws Exception {
		Set set = searchResultMap.keySet();
		Iterator iter = set.iterator();
		while (iter.hasNext()) {
			String id = (String) iter.next();
			SearchItem si = (SearchItem)searchResultMap.get(id);
			String documentUrl = BASE_URL + "library//document/" + id
					+ "/feed?pagesize=100";
			response.release();
			response = client.get(documentUrl);
			Document doc = response.getDocument();
			Feed feed = (Feed) doc.getRoot();
			int commentsNumber = feed.getEntries().size();
			si.setCommentNumber(commentsNumber);
			searchResultMap.put(documentID, si);
		}
……
//select the top ten hot document from search results and save it to 
topTenMapByCommentsNumber map object.
topTenMapByCommentsNumber = makeTopTenDocumentByCommentsNumber(searchResultMap);
……
//select the top ten hot document from search results and save it to 
topTenMapByLastUpdatedDate map object.
topTenMapByLastUpdatedDate = makeTopTenDocumentByUpdatedDate(searchResultMap);
……
	}

Figure 11 illustrates the top ten hot documents, sorted by number of comments.

Figure 12 illustrates the top ten hot documents sorted by lasted updated date.

Back to top

Categorizing and filtering

The search result that you get from Lotus Quickr Search service can be categorized and filtered according to document properties. These properties can be the standard predefined properties that come with Lotus Quickr (that is, title, author, and so on) or customer-defined properties (that is, those defined in custom property sheets). In this example, we choose the city property from the Olympics property sheet that was defined during document preparation to demonstrate the categorizing and filter feature in the example. You can retrieve the property by using the SOAP bindings to the Lotus Quickr document service. We describe the categorizing functionality and filtering feature separately in the following sections.

Categorizing

The SOAP binding to the Lotus Quickr document service provides a SOAP-style interface to access documents in Lotus Quickr libraries. You can get detailed information about this service by inspecting the WSDL file that you can generate from your Lotus Quickr server using this URL:

http://<hostname>:<port>/dm/services/ContentService?wsdl

For example, the URL can look like this one:

https://greenhouse.lotus.com/dm/services/ContentService?wsdl

From this WSDL file you can generate a client stub out of the WSDL file using the wsdl2java tool.

In Lotus Quickr, a ClbDocument object represents one document, which can contain multiple property sheets represented by the ClbPropertySheet object. Figure 13 shows the structure model of Lotus Quickr Library documents. The properties that we use in this example are stored in the property sheet. Each ClbPropertySheet object is an instance of the ClbPropertySheetType object. To get the property value, the work we need to do includes these steps:

• Get the ClbPropertySheet object from the current ClbDocument object.
• Get the property ID from the property name in the corresponding ClbPropertySheetType object.
• Get the property value from the property ID in the corresponding ClbPropertySheet

It is not hard to categorize the documents after you retrieve the property value of each document.

Listing 5 shows a snippet of the code sample used to get the value for a custom property sheet from a document. You can find more details about the implication here:

CustomizedSearchCenter_mutiServer.war\WEB-INF\classes\com\ibm\clb\cmsearch\WsUtil.java

public String retrievePropertyValue(String documentUUID, 
String peopertySheetTypeName, String propertyLabel) throws Exception
  {
	  ……
	  ClbDocumentResponse docResponse = 
	  documentService.getDocument(documentUUID, null, 
	  null,INCLUDE_PROPERTYSHEETS );
	  ClbDocument doc = docResponse.getDocument();
	  
	  //Retrieve propertySheetType.
	  ClbPropertySheetType propertySheetType = 
	  getPropertySheetType(doc, peopertySheetTypeName );
	  
	  String propertySheetTypeUUID = propertySheetType.getId();
	  
	  //Retrieve propertyName from propertySheetType by propertyLabel;
	  String  propertyName = 
	  getPropertyNameFromLabel(propertySheetType, propertyLabel);
	  
	  //Retrieve propertySheet
	  ClbPropertySheet propertySheet = 
	  getPropertySheet(doc,propertySheetTypeUUID);
	  
	  //Retrieve dynamicValue from propertySheet by propertyName
	  String dynamicValue = 
	  getDynamicValueFromPropertySheet(propertySheet, propertyName);
	  ……
	  return dynamicValue;
	  
  }

Having the categorized results now allows you to depict the results in a simple pie chart, as illustrated in figure 14. This figure illustrates the categorizing result of all searched documents that have different values for the city property.

Filtering

Following a similar process, documents from the search results can be filtered by a user-specified property. In figures 15 and 16, the filtered results are illustrated for the documents that have Beijing as the value of the city property, and for the documents that have Opening Ceremony as the value of the activity property.

\

Back to top

Conclusion

Lotus Quickr content services provide a way to develop customized solutions. This article introduces a scenario of a customized search center to demonstrate how these services can be used. With this example, you can develop your own solution with search-related features to handle user-defined properties to fit your production environment.

Back to top

Download

Information about download methods

Resources

Learn

• Read the developerWorks Lotus article, "Introducing IBM Lotus Quickr REST services."
  
  
• Read the developerWorks Lotus article, "Introducing IBM Lotus Quickr Web services."
  
  
• Read the developerWorks Lotus article, "Getting to know the Atom Publishing Protocol, Part 3: Introducing the Apache Abdera project."
  
  
• Read the developerWorks Lotus wiki describing the IBM Lotus Quickr Content Services.
  
  
• Read the IBM Lotus Quickr Information Center.
  
  

Get products and technologies

• Download Apache Abdera.
  
  

Discuss

• Participate in the discussion forum.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Prerequisites
• Introduction to IBM Lotus Quickr and Lotus Quickr services
• The scenario
• Deployment and data preparation
• Solution
• Categorizing and filtering
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Lotus Quickr
• Demo: Lotus Quickr
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Quickr

My developerWorks community

Dig deeper into Lotus on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers