Accessing IBM Lotus Quickr REST services using IBM WebSphere Portlet Factory

This article presents a sample application that demonstrates how to use IBM® WebSphere® Portlet Factory builders to easily interact with IBM Lotus® Quickr™ REST services with minimal coding.

Share:

Sam Alexander (sam_alexander@us.ibm.com), Software Developer, Lotus

Sam Alexander is a software developer for the IBM WebSphere Portlet Factory team in Massachusetts, focusing on content integration.  A seven-year veteran of IBM, his previous roles include developer on the WebSphere Portal 6 and Lotus Workplace search teams, tools developer and performance engineer for the Lotus Center of Competency, and software tester for Lotus Domino on the iSeries platform.



Thomas Beauvais (tbeauvai@us.ibm.com), Software Architect, IBM

Tom Beauvais is a Software Architect for IBM WebSphere Portlet Factory. Tom joined IBM in 2006 as part of the IBM acquisition of Bowstreet, and he brings more than 22 years of software development experience to his role at IBM. Prior to Bowstreet, he was a Development Manager in the Directory Management Group for Computer Associates.



24 June 2008

One of the significant strengths of IBM WebSphere Portlet Factory is its ability to rapidly create dynamic Web applications that interact with back-end data, without programming to an API.

Demonstrating this strength, this article shows how you can use IBM WebSphere Portlet Factory to easily build an application that interacts with IBM Lotus Quickr data over Representational State Transfer (REST).

To get the most out of this article, you should have a basic familiarity with WebSphere Portlet Factory as well as its provider and consumer architecture. Finally, you should be familiar with REST services for Lotus Quickr and the Atom APIs.

We begin by briefly describing WebSphere Portlet Factory. Then, after describing the sample application, we describe the architecture and the models used in the application.

WebSphere Portlet Factory

WebSphere Portlet Factory is a rapid application development tool for creating dynamic Javaâ„¢ Platform, enterprise Edition applications. At design time, you construct your applications using software components called builders. Each builder is configured using a wizard-like user interface (UI) and automatically generates the code of the application.


The sample application

As shown in figure 1, the sample application is a simple explorer application that allows you to explore and manipulate data stored in Lotus Quickr document libraries. By clicking the folder icons, you can navigate into the structure of the library. By clicking the pencil icon, you can edit folder and document metadata. At any level in the library, you can upload new documents, create folders, and delete folders and documents.

Figure 1. The running Sample Quickr Explorer page
The running Sample Quickr Explorer page

Architecture

As shown in the high-level diagram in figure 2, the application is designed in a WebSphere Portlet Factory provider and consumer pattern. In this pattern, the provider model exposes a set of service operations to consumer models. Consumer models call these operations, unaware of the underlying implementation.

In the provider model, the service operations make REST-style service calls to Lotus Quickr using WebSphere Portlet Factory’s REST Service Call builder. The REST Service Call builder, introduced in WebSphere Portlet Factory version 6.0.2, is used to generate the runtime code to make requests and publish to the server. It also provides the design-time generation of input and results in XSD schema information for each operation in this provider model. The consumer model, in addition to calling the provider model operations, is responsible generating a user interface.

Figure 2. The Lotus Quickr consumer and provider models
The Lotus Quickr consumer and provider models

Sample models

The following sections describe the WebSphere Portlet Factory models in this sample. We first describe SetupConnection, a model imported by the other models in the sample.

SetupConnection model

In addition to the Lotus Quickr host name, all Lotus Quickr REST service calls require authentication with a username and password. SetupConnection is a common model, imported by the other models using the Imported Model builder, which is responsible for managing authentication.

The model contains a variable to hold the Lotus Quickr server host name, username, and password. The configureConnection method is responsible for setting their values.

The configureConnection method first tries to set the variables based on their profiled values. If there are no profiled values, then configureConnection initializes them from the values in the connectionInfo variable.

The connectionInfo variable is created by the Import to XML builder. This builder, when provided with a properties file, creates an XML structure and variable that represents each of the key value pairs. In this example, the Import to XML builder is set to read in:

/WEB-INF/samples/quickr/server_info.properties

The consumer model’s Action List builder, named main calls configureConnection to initialize these variables before making any REST calls. With the connection information taken care of, we can now look at the provider model responsible for making the REST calls to Lotus Quickr.

QuickrFeedProvider model

QuickrFeedProvider is the service provider model that exposes service operations for interacting with Lotus Quickr data. The following sections describe each service operation.

The service operations incude getFeed, addFolder, deleteEntry, uploadDoc, and getLibraries.

getFeed

Given the URL to a valid document library or folder feed, this operation uses the REST Service Call builder that performs an HTTP GET to fetch the Atom feed and creates an XML variable representing the library.

Figure 3 shows that the builder is configured to perform an HTTP GET operation to the URL stored in the feedURL variable. The User Name and Password input fields are configured to get their values from variables.

Parameters to Lotus Quickr REST services can also be passed using key value pairs passed on the query string portion of the URL. In this example, we set the pagesize variable to 200, which limits the number of entries returned in the feed.

Figure 3. The REST Service Call builder responsible for retrieving the Atom feed
The REST Service Call builder responsible for retrieving the Atom feed

To simplify and reduce the amount of data, the operation passes the Atom feed data to the getEntries() method. Using the WebSphere Portlet Factory lightweight IXml interface, getEntries() parses the feed and creates a new, simplified XML structure containing just the <entries> section of the feed. In addition, getEntries() sets two attributes that are used in UI: title and baseURL. The title attribute is used in the UI to display the title of the library. Because all URLs in a Lotus Quickr Atom feed are relative, the consumer model uses both, the baseURL and relative URL, to build up the URLs to Lotus Quickr. This code is shown in listing 1.

Listing 1. The getEntries() method
{
   IXml entries = feed.findElement("entries");
  
   String base = feed.getAttribute("xml:base");
   String title = feed.getText("title");
 
   entries.setAttribute("baseURL", base);
   entries.setAttribute("title", title);

   return entries;
}

In the example return value, shown in listing 2, each <entry> element within <entries> element represents either a document or a folder. This new structure can be more easily consumed by the WebSphere Portlet Factory page automation.

Listing 2. Example of getEntries() return value
<entries baseURL=
"http://<host>/dm/atom/library/20450d004832346bb299bb8c8f51c94e/" 
title="ACME Company Annual Open Enrollment">
  <entry xmlns:td="urn:ibm.com/td" xml:lang="en">
    <id>urn:lsid:ibm.com:td:c72e808048323d6a8fdfdf54a97ad0e3</id>
    <link href="document/c72e808048323d6a8fdfdf54a97ad0e3/entry" 
    rel="edit"></link>
    <title type="text">Welcome.pdf</title>
    ....
  </entry>
  ....
</entries>

updateEntry

The Lotus Quickr REST services allow you to update document and folder metadata through an HTTP PUT to the edit URL of the document or folder, sending a new <entry> element as part of the body. As defined by the REST service, the element must be in the form shown in listing 3.

Listing 3. An example of an <entry> element
<entry xmlns="http://www.w3.org/2005/Atom">   
<id>urn:lsid:ibm.com:td:c72e808048323d6a8fdfdf54a97ad0e3</id>      
<title type="text">Welcome.pdf Changed</title>
<summary type="text">Description of Welcome.pdf</summary>
</entry>

The REST Service Call builder easily allows you to perform an HTTP PUT and send data in the body.

As shown in figure 4, the REST Service Call builder is configured for an HTTP PUT. When PUT is selected as the HTTP Request Type, the builder automatically creates a variable in the application called xxxRestInputs, where xxx is the name entered in the Name field. In this example, the created variable is named editEntryRestInputs.

At runtime when the PUT is performed, the builder sends the contents of editEntryRestInputs in the body and sets the body content type to the value of the Body Content-Type field.

Figure 4. REST Service Call builder responsible for updating document or folder metadata
REST Service Call builder responsible for updating document or folder metadata

The functionality of this REST builder is wrapped by the updateEntry service operation. This operation takes the following parameters:

  • editURL. The edit URL from the original entry being modified.
  • ID. The Lotus Quickr unique ID of the entry being modified.
  • Title. The updated title of the documents or folders entry.
  • Summary. The updated summary for the documents or folders entry.

Given these four fields, the operation calls the updateEntryData() method, which creates a new <entry> XML structure (defined by Lotus Quickr) and sets the editEntryRestInputs variable to this structure.

addFolder

The addFolder operation creates a new document folder as a child of the current folder. After building up a new <entry> element representing the folder, the REST service calls to perform a POST operation to create the new entry. The service call for this request takes the following parameters, which are passed to the server request:

  • editURL. The edit URL for the parent folder.
  • Title. The title of the new folder entry.
  • Summary. The summary information for the new folder entry.

deleteEntry

The deleteEntry operation deletes an existing folder or document using its edit URL. This operation uses the REST service call to perform a DELETE operation to remove the existing entry. The service call for this request takes the following parameter:

  • editURL. The edit URL from the original entry that is being deleted.

uploadDoc

The uploadDoc operation uploads a new document to a library or folder. A REST Service Call builder is used to perform a POST operation to create the new document.

When the REST Service Call builder is configured to perform an HTTP POST, and when the Body Content Data Type input is set to InputStream, the builder automatically creates a variable, named PostNewDocInputStream in this example, of type java.io.InputStream, to hold the contents of the data. At runtime, the builder takes care of sending the contents of the InputStream in the body.

The service call for this request takes the following parameters:

  • uploadURL. The URL of the document library or folder where the new document is placed.
  • fileName. The name of the file on the application server that is uploaded to Lotus Quickr.

Before calling the REST service, the service operation for this functionality calls the uploadDoc Action List, which sets the PostNewDocInputStream variable to the file uploaded to the application server by the File Upload builder.

getLibraries

The getLibraries service operation fetches a list of the document libraries and their feed URLs available to the authenticated user. The REST Service Call builder performs an HTTP GET using the Lotus Quickr introspection URL to fetch the Atom feed containing the libraries.

Rather than returning the entire Atom feed, the operation calls QuickrUtil.getLibraries(), a utility method that modifies the data to be more suitable for use with the Lookup Table builder and WebSphere Portlet Factory page generation. As shown in listing 4, the method uses the WebSphere Portlet Factory lightweight IXml interface to parse only the library title and feed URL from the Atom feed and creates and returns a new XML structure.

Listing 4. The code for QuickrUtil.getLibraries method
public IXml getLibraries(WebAppAccess webAppAccess)
{
  IXml retVal = XmlUtil.create("Libraries");

  // Fetch the service doc over REST
  webAppAccess.processAction("ServiceDoc.invoke");
  IXml svcDocFeed =  webAppAccess.getVariables().getXml("ServiceDoc_reply");

  // Skip down to the <collections> elements
  IXml collectionsXml = svcDocFeed.findElement("service/workspace");

  // For each lib, parse the title & feed url.  Add to our XML structure
  Iterator collections = collectionsXml.getChildren().iterator();
  while(collections.hasNext())
  {
    IXml collection = (IXml) collections.next();
    String colFeedUrl = collection.getAttribute("href");
    String colTitle = collection.findElement("atom:title").getText();

    IXml lib = XmlUtil.create("Library");
    lib.addChildWithText("label", colTitle);
    lib.addChildWithText("value", colFeedUrl);
    retVal.addChildElement(lib);
  }
  return retVal;
}

QuickrFeedConsumer model

QuickrFeedConsumer is a service consumer model used to navigate a library and display and update folder and document data from a Lotus Quickr server. The QuickrFeedProvider model, described previously, is used to interface to the Lotus Quickr server and bring the data into the context of this model. The following are the high-level pieces of functionality that this model provides.

The user interface

The View & Form builder is responsible for calling the provider model’s getFeed() service operation and generating pages to display the results. It also creates update pages for editing document and folder metadata, and it calls the provider model’s updateEntry() operation.

The feed data returned from getFeed() is rich with metadata about the entries in the library. By minimally parsing the feed data and by using an Image Button builder, the application dynamically places an appropriate icon of either a folder or a document next to each entry in the document library. As shown in figure 5, the builder’s Image input field is configured to get its value from a call to QuickrUtil.getimage().

Figure 5. The Image input field of the Image Button builder
The Image input field of the Image Button builder

Given an Atom feed’s <entry> element, QuickrUtil.getImage()parses the term attribute from the entry’s <category> element. If the value is document, the location of a document icon is returned; otherwise, the location of a folder icon is returned. QuickUtil.getImage() is shown in listing 6.

Listing 6. Code for QuickrUtil.getImage()
public String getImage(IXml entryElement)
{

  IXml category = entryElement.findElement("category");		   

  return category.getAttribute("term").equals("document") ? 
    "/samples/quickr/images/document.gif" : "/samples/quickr/images/folder.gif"; 
}

You can click each entry’s icon. When you click the folder icon, the UI refreshes and displays the contents of the folder. When you click a document icon, the browser is redirected to Lotus Quickr, which streams the document back to the browser.

This functionality is achieved by configuring the Image Button builder’s Action input to call QuickrUtil.openItem(). This method parses the <category> element of the selected entry. If the category is folder, the method updates the input variables to the provider model’s getFeed service operation with the URL to the folder, fetches the feed for the folder, and renders the view page.

Other page automation builders are used to format or hide certain data. For example, a Data Field Modifier builder is used to transform UTC dates to mm/dd/yyyy format.

The Breadcrumbs builder is used to track the context of the folders as you navigate through the document folders. You can use the breadcrumb trail to navigate back up the tree.

Uploading documents

The File Upload builder is used to place a file upload control on the page.

At runtime, when you click the Upload Doc button, the builder streams the file from the browser to the application server. The uploadFile Action List calls the provider model's uploadDoc service, passing the filename of the uploaded file.

Delete entry

This section adds support for deleting a document or folder from the server. A Delete button is added to the details page created by the View & Form builder. The delete operation calls the provider model's deleteEntry operation, passing it the editURL for the current entry.

Create folder

To create a new folder at the current location, use an Input Form builder to create the UI for entering the new folder information. Then use the provider model's addFolder operation to create the folder.

Profiling

Use profiling in this model to expose user personalization settings in the portal. The actual profiled inputs are in the SetupConnection model, which is imported into this model.

The profile set quickr.connectionInfo.Edit is used to control the document feed URL and the user's credentials.


QuickrFeedCustomizer model

When you run this sample as a portlet on Websphere Portal, the QuickrFeedCustomizer model allows users to set and save their Lotus Quickr server, credentials, and the document library they want to explore. This functionality, shown in figure 6, is exposed by selecting Personalize from the Portlet Menu of the QuickrFeedConsumer portlet.

Figure 6. The running Customizer Page
The running Customizer Page

The majority of this functionality is achieved using the Portlet Customizer builder, which automatically generates the configure page for our portlet, based on the profiled inputs in our models.

As shown in figure 7, we selected the profile set quickr.connectionInfo.Edit. When this profile set is chosen, the Input Values field is automatically populated with the values we have profiled: the Quickr server host name, username, password, and library.

Figure 7. The Portlet Customizer builder
The Portlet Customizer builder

A unique feature of this model is its ability to fetch a list of Lotus Quickr document libraries from which users can choose. We used a Button builder and Select builder to place a Populate button and a drop-down list on the configure page. When the Populate button is clicked, the QuickrFeedProvider’s getLibraries() service operation is called to retrieve the list. The list is then used to populate the drop-down list.

For better performance, after fetching the list of document libraries from Lotus Quickr, the model calls a method that uses the portlet API to cache the library names in the user's WebSphere Portal preferences. Doing this cachiing operation avoids the need to re-fetch a list from the Lotus Quickr server, which can be time consuming when the number of libraries is large. If the list of libraries on the Lotus Quickr server has changed, then you need to refresh the local copy by clicking the Populate button.


Conclusion

This sample demonstrated how you can use WebSphere Portlet Factory builders to easily interact with the Lotus Quickr REST services with minimal coding. Most notably, the REST Service Call builder conveniently handles the HTTP communication and sends binary files in the body.

The sample is also a good example of the WebSphere Portlet Factory strengths in general: page generation, code generation, profiling, data integration, and WebSphere Portal integration. Taken together, these strengths allow you to create data driven applications more rapidly.


Appendix: Instructions for running the sample

Follow these steps to run the sample:

  1. Ensure that you are using WebSphere Portlet Factory version 6.0.2 or higher.
  2. Version 8.0 or later of Lotus Quickr services for WebSphere Portal (also called the Java Platform, enterprise Edition version of Lotus Quickr) is required. (Lotus Quickr services for Lotus Domino® supports a limited set of REST services and will not work with this sample.)
  3. Download the quickr_rest_sample.zip ZIP file and import it into a project. Choose File - Import - WebSphere Portlet Factory Archive.
  4. Optional: If you know your document library’s Atom feed URL, you can specify it in WebContent\WEB-INF\samples\quickr\server_info.properties. An example is shown in listing A1. Otherwise, you can choose a document library by title at runtime by selecting Personalize from the portlet menu.

    Listing A1. Example of server_info.properties
    Example:
       # Quickr Server Information
       quickr_default_docLibFeedURL=
       http://<your host>/dm/atom/library/< library ID>/feed
       quickr_user_name=
       quickr_user_password=

    NOTE: If you use a secure connection (using SSL) to access your server, then you must install a certificate from the Lotus Quickr server onto the application server that is running the model. In many cases, the Lotus Quickr server redirects a non-SSL HTTP request to a secure one.
  5. File upload support must be enabled to upload a file. Set bowstreet.upload.enabled to true in WEB-INF\config\override.properties. Also, update the bowstreet.upload.maxFileSizeK to the maximum file size that can be uploaded.
  6. Redeploy the project to your portal or application server.
  7. Deployment:
    • If you deploy to WebSphere Portal, then you must add the portlet to a page. The sample portlet is named:
      » Sample: Lotus Quickr Explorer
      After the portlet is on a page, you can set your credentials and choose the document library using the portlet's Personalize menu option.
    • If you deploy only to WebSphere Application Server, then you can run the sample portlet model:
      samples\quickr\QuickrFeedConsumer.model

Additional considerations

You can use the same techniques shown in the samples to build other types on Lotus Quickr portlets.

The following are some of the next steps you might want to consider:

  • Integrate into your existing application.
  • Customize the page's look to match your specifications.
  • Integrate with a credential vault to supply user credentials.

Download

DescriptionNameSize
code samplequickr_rest_sample.zip.zip28.7KB

Resources

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, WebSphere
ArticleID=315813
ArticleTitle=Accessing IBM Lotus Quickr REST services using IBM WebSphere Portlet Factory
publish-date=06242008