• IBM® WebSphere® Portal for Multiplatforms Version 5.0
• IBM DB2® Content Manager for Multiplatforms Version 8.2
• IBM WebSphere Application Server Enterprise Version 5.0.1 (Build PTF M0314.O4)
• IBM WebSphere Application Server Version 5
• IBM DB2 Information Integrator for Content Version 8.2
• IBM DB2® Universal Database™ Text Information Extender Version 7.2
• IBM WebSphere Studio Application Developer Version 5
• Portal wizards plug-in
• IBM DB2 Universal Database Enterprise Edition Version 7.2 (dbelevel is SQL07025, fixpack level WR21313-5933)
• Microsoft Visual Studio Version 6.0 including Visual C++ Version 6.0

Overview

Part 1 of this series describes the solution overview and architecture. The sample application uses DB2 Content Manager as its repository, and the user interface is developed using WebSphere Portal. To integrate the portal application with the Content Manager repository, the rich DB2 Information Integrator for Content API was used for behind the scenes transactions. See Resources for an overview of the API.

This article details the authoring part of the research report, including report creation, assignment to an author, and editing. A separate article will detail the tasks for processing this solution, such as submitting the report for comments, review, and different levels of approvals.

Back to top

Sample application design

The research report application design has three types of documents: A_Report, A_Comment, and A_Published. These document types are explained below and shown in Figure 1.

A_Report

The document representing the actual report object. Every report has a different instance of this document. The document is a root part, with exactly one subpart and three user-defined attributes. The user-defined attributes are:

A_Author	The Content Manager user ID of the document's author. It is used to handle all task processes involving the author. This ID should match the portal user ID.
A_Area	The area of research this document belongs to. This value is set by the supervisor and cannot be modified later.
A_Title	Title of the report. This value is set by the supervisor, but can be modified later by the researcher.

All three are required attributes. The subpart consists of a document of the predefined type ICMBasePart, which is where the body of the report is saved.

A_Comment

The document type that handles a comment attached to a specific report. Comments can be generated by the workflow process and by peers during the report review process. To enable easy access to comments without affecting the report document version, comments are placed in a folder that is linked to all comments related to a report. The comments folder is created when the A_Report document is created and is linked to the report document.

When a comment is added to the report document, the folder is accessed through the link from the report document, and the new comment document is added to the comment folder. In our scenario, both the comment folder and the comment document are A_Comment document types; the folder has a semantic type of folder, while the individual comment has a semantic type of document.

A_Published

A document type used as a folder semantic type. It helps hold in one place all the documents published. The document does not have any user-defined attributes. There is only one instance of this document for the whole scenario, and it is created separately by the Content Manager administrator. When documents get published by the publisher, this one instance of this document is queried, and a new link is created from this instance to the ready-to-publish document. When the published documents are displayed on the employee Web site, this instance is queried again, and all links from this instance are followed in order to access and display the published documents. This design allows easy publishing, and later archiving, without changes to the reports or complex queries.

Back to top

Document management application

The research report application has a number of portlets organized on several portal pages. The portlets and portal pages have different access permissions based on a predefined set of groups. In this article we'll only discuss the ones that directly create or modify the research reports.

Assign Report portlet

This portlet is where the research report is created, and it is only available to members of the Supervisors group. It allows a supervisor to create a new report with a topic and title, and to assign it to a specific researcher, as shown in Figure 2. The portlet is placed alone in a portal page restricted to members of the Supervisors group.

To create and assign a report to a researcher, a supervisor fills out the required fields and clicks Assign. A new report document is created, with a new comments folder associated with the report instance. The author field in the A_Report item is set to the author's user ID selected by the supervisor. The list of author IDs is populated from the members of the Researchers group. The title and topic fields are also set as defined by the supervisor.

In addition to creating the document, a workflow process is started at this time. The document is in the A_New state. A new task is also created and assigned to the specified author. For details on the workflow and tasks handling, see Part 3 of this series.

The following is a snippet of the code for processing the assignment of a new report.

try{
  //create a new report
  String itemID =  ReportUtil.createReport(researcherName,title,topic) ;
  // get the supervisor s user id
	String userId = request.getUser().getUserID() ;
  //get the supervisor s password
 String password = PortletCredential4ICMUtil.getPassword4CMFromCredential(
	request, PortletCredential4ICMUtil.getVault
	   (getPortletConfig().getContext()), userId);
 //assign the newly created report to the researcher as set in the  
    author's ID of the report.
 DocRoutingProcessing.researcherAssigned(itemID, userId, password);
}catch(Exception e) { e.printStackTrace() ;}

After the report has been assigned to the author, it is shown in the author's documents management page.

Document management portal page

A researcher acknowledges a report assignment by accepting the research assignment task. (You can expect more details about task processing in the next article in the series.) After accepting the assignment, the author needs to perform numerous operations on the document. These operations are all available on one page as shown in Figure 3. This page is only accessible to members of the Researchers group.

My Documents View portlet

The My Documents View portlet lists all the documents for the user who is currently logged in, as shown in Figure 4. The document's title is also a link, and clicking this link shows the document details in the both the Document Details and Versioning portlets. Also displayed in the Documents View portlet are the document's status and the topic. The document status is not a stored attribute in the Report Item type; it is determined based on the document status in the workflow process.

The list of reports is queried by the portlet by executing the following query on the IBM DB2Content Manager data store object.

public  void getUserDocs(String userID) {
		
dkResultSetCursor cursor =null ;
...

// prepare the query s string
String query = "/" + BSDConstants.ITEMTYPE_REPORT + " [@VERSIONID = 
   latest-version(.) AND @" 
  + BSDConstants.ATTRTYPE_AUTHOR + " = \"" + userID + "\"] ";
        
// Specify Search / Query Options
DKNVPair options[] = new DKNVPair[3];
options[0] = new DKNVPair(DKConstant.DK_CM_PARM_MAX_RESULTS, "0"); // 
   No Maximum (Default)
// Specify any Retrieval Options desired.  Default is ATTRONLY.
options[1] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE, new 
   Integer(DKConstant.DK_CM_CONTENT_ATTRONLY)); 
// Must mark the end of the NVPair
options[2] = new DKNVPair(DKConstant.DK_CM_PARM_END, null);
//connect to the ICM data store 
DKDatastoreICM dsICM = ICMConnectDisconnect.connect();
//execute the query and get the result
cursor =  dsICM.execute(query, DKConstantICM.DK_CM_XQPE_QL_TYPE, options);
setResultSet(cursor) ;	
cursor.destroy() ;
ICMConnectDisconnect.disconnect(dsICM);	
..
}

After retrieving the list of reports from the repository, the list is stored in the portlet's session bean. This list is used by the portlet's JavaServer Pages (JSP) servlets. The HTML code below shows how the JSP servlets retrieve the result set from the portlet's session bean and create an action associated with every title of a report.

<%java.util.Vector vector = sessionBean.getResultSet() ;

%>

<table cellpadding="10" name="myTable">
	<th>Title</th>
	<th>Topic</th>	
	<th>Status</th>	
	
<it:iterate collection='<%=vector%>'   >
<% 
   short topicDataId = item.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,
      BSDConstants.ATTRTYPE_TOPIC) ;
   short titleDataId = item.dataId(DKConstant.DK_CM_NAMESPACE_ATTR,
      BSDConstants.ATTRTYPE_TITLE) ;
   String itemId = ((DKPidICM)item.getPidObject()).pidString() ;
   String formName = "Row" + itemId ; 
   String uri = viewBean.getRowFormAction(itemId) ;
  
%>

<FORM  id="<%=formName%>" method="POST" action="<%=uri%>">
<tr >
<td><a  href="#" onclick="document.getElementById('<%=formName%>').submit();
		return false;" ><%=item.getData(titleDataId) %>
  </a>
</td>
<td><%= item.getData(topicDataId) %> </td>
<td><%= ReportUtil.getStatus(item) %></td>
</tr>
</FORM>
</it:iterate>

</table><BR/>

When the title link is clicked, the corresponding action in the Documents View portlet is invoked, and this action broadcasts a message to the portlets on the same portal page. The message contains the item ID of the report whose title was clicked. The message also has the document's item ID in it, which is used by the listening portlets to update their contents, as described below, in each portlet.

Document Details portlet

This portlet lists the document details, as shown in Figure 5. The version of the document can be selected from the list box, and displays the corresponding document version. By default, the latest version is selected. The comments are shown in a separate text area. The comments include those generated by the workflow process due to changes in status, as well as comments entered by peers during the review process.

The portlet has a message listener interface that listens to all messages of type PortletMessage. When the Documents View portlet broadcasts a message with the item ID of the selected report, this portlet is one of the portlets intercepting the message and using the item ID to query the DB2 Content Manager data store to retrieve the actual report object. The report object is then passed to the DocumentDetails.jsp through the session bean to display its attributes in the portlet.

The contribution of comments is not discussed in this article because it is part of a workflow process discussed in Part 2 of this series.

In Figure 5:

• Next Comment and Previous Comment lets the researcher view those comments.
• Change lets the researcher change the title originally set by the supervisor.
• Save allows the researcher to save the document body of the report.

To display the different versions of the item in the Document Details portlet, a query is made (using DB2 Content Manager flexible query language) to the DB2 Content Manager repository to query all documents with the same item ID. All the versions are stored in the drop-down list in the portlet. Selecting a version from the drop-down list updates the portlet to show the content of the specific version of the report.

 String query = "" ;
 // Using Item ID.
         
 query = "/" + BSDConstants.ITEMTYPE_REPORT + " [@ITEMID=\""+itemId+"\"]";
// Specify Search / Query Options
DKNVPair options[] = options    = new DKNVPair[3];
// Specify max using a string value.
options[0] = new DKNVPair(DKConstant.DK_CM_PARM_MAX_RESULTS, "0");
// Specify any Retrieval Options desired.  Default is ATTRONLY.
options[1] = new DKNVPair(DKConstant.DK_CM_PARM_RETRIEVE,
	new Integer(DKConstant.DK_CM_CONTENT_ATTRONLY));
// Must mark the end of the NVPair
options[2] = new DKNVPair(DKConstant.DK_CM_PARM_END,null);

DKResults results = (DKResults)dsICM.evaluate(query,
		DKConstantICM.DK_CM_XQPE_QL_TYPE, options);
                
dkIterator iter = results.createIterator();
// While there are still items to iterate through, continue.
while(iter.more()){
	// Move pointer to next element and obtain that object.
		DKDDO ddo = (DKDDO) iter.next();
	docs.add(ddo.getPidObject().pidString()) ;
	             
}

After the list of documents is available, the version numbers are stored in the combo box. A listener is implemented on the combo box to detect a change in the selection and change the content of the JSP servlet, as required.

Version Control portlet

The Version Control portlet is linked to the selected document in the Documents View portlet. The latest version should be shown by default, as well as the item ID (not the item PID, which is unique to each report version). The user can select the version they want to check out, allowing them to modify the selected version. After a report is checked out, a researcher can make multiple changes in the Document Details portlets. The report version is increased for every change. When all the changes are complete, the researcher should check the report in.

The author is required to check out a report before modifying it, to ensure that the report is not modified by any other source. When the researcher has finished making the modifications to the report, the report should be checked in. The check in, check out, and version selection are executed by calling the following function.

//Checkout:
if( VERSION_ACTION.equals(actionString) ) {
	// Set form text in the session bean
	sessionBean.setSelectedVersion(request.getParameter("versions")) ;
}
else if (CHECKIN_ACTION.equals(actionString) ) {
	String pid = sessionBean.getDocPidWithVersion
	   (sessionBean.getSelectedVersion()) ;
	try{		
		//sessionBean.checkinFromFile(pid) ;
		dsICM = sessionBean.getDataStore() ;
		DKDDO doc = dsICM.createDDO(pid) ;
		dsICM.checkIn(doc) ;
	}catch(Exception e) { e.printStackTrace() ;}
	
}
else if (CHECKOUT_ACTION.equals(actionString) ) {
	String pid = sessionBean.getDocPidWithVersion
	   (sessionBean.getSelectedVersion()) ;
	try{
		//sessionBean.checkOutFromFile(pid) ;
		dsICM = sessionBean.getDataStore() ;
		DKDDO doc = dsICM.createDDO(pid) ;
		dsICM.checkOut(doc) ;
	}catch(Exception e) { e.printStackTrace() ;}
} 

Back to top

Summary

The DB2 Information Integrator for Content API offers a rich set of APIs that are able to interact with WebSphere Portal to accomplish a seamless integration. The integration shown in this article is totally customized to the "Analyst research reporting" scenario, and requires programming skills to implement. The decision to implement such a solution, rather than using a document management system, should take into consideration the desired features in the solution.

Resources

• For more about the DB2 Information Integrator for Content API, see the IBM DB2 Content Manager for Multiplatforms Workstation Application Programming Guide.
  
  
• Visit the series overview page to see the current list of articles in this series.
  
  
• Read the first article in this series, Handle increasing volumes of content (developerWorks, April 2004), for an overview of a content management solution in an employee workplace.
  
  
• Read the second article in this series, Define a document-centric workflow (developerWorks, April 2004), for an introductory background of DB2 Content Manager Document Routing.
  
  
• Read the third article in this series, Design the workflow management component (developerWorks, April 2004), for details of how the workflow management is designed.
  
  
• The fourth article in this series, Control access in workflow management (developerWorks, May 2004), discusses the design of the workflow management component using their solution scenario described in Part 1.
  
  
• Visit IBM On Demand Workplace at IBM Business Consulting Services for more details about the On Demand Workplace.
  
  
• Visit the DB2 Content Management zone on developerWorks DB2 for comprehensive information on how to manage various content from all sources -- document, image, Web, and rich media.
  
  
• Visit the WebSphere Portal and WebSphere Studio zones on developerWorks WebSphere for comprehensive information on how to acquire and use IBM's suite of tools for application development.
  
  
• Browse for books on these and other technical topics.
  
  

About the author

Therese Sroujian is a Business Scenario Designer for the IBM Software Group System House. She joined the IBM Toronto Lab in 1997 and has worked on a variety of assignments. Within the System House Scenario team, Therese's main responsibilities include designing and prototyping solutions focused on customer integration challenges. Therese can be contacted at sroujian@ca.ibm.com.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Overview
• Sample application design
• Document management application
• Summary
• Resources
• About the author
• 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