For this article, the team used the following products:

• IBM® WebSphere® Portal for Multiplatforms Version 5.0
• IBM 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
• Enterprise Information Portal Version 8.2
• IBM DB2® Universal Database™ Text Information Extender Version 7.2
• IBM WebSphere Studio Application Developer Version 5
• Portal wizards plugin
• IBM DB2 Universal Database Enterprise Edition Version 7.2 (db2level is SQL07025, fixpack level WR21313-5933)
• Microsoft Visual Studio 6.0, including Visual C++ 6.0

Overview

Part 5 of this series, "Create an authoring process using portlets and IBM DB2 Content Manager", discusses a sample developed to prototype the Analyst research reporting scenario in Part 1. Part 5 focused on the authoring tasks of the sample.

This article explores the details of task handling by the Web portal. I'll describe the portlets used to handle the tasks and show an entire integration between the employee portal and the tasks required to go through a complete life cycle of a research report. The implementation used in the sample separates the portlets from the specifics of the workflow, showing the value of the portlet design.

The Web portal application will use IBM DB2 Content Manager as its repository. To integrate the portal application with the IBM DB2 Content Manager repository, we used the rich Information Integrator for Content API for behind-the-scenes transactions. For an overview of the API see Resources.

This article discusses the task-processing portion of the application, which was implemented with a portal page that is only accessible to members of the research team. The page is composed of two portlets:

Task list

Lists all the tasks assigned to a particular researcher.

Task process

Starts with a blank content and is always populated with the JavaServer Pages (JSP) component corresponding to the task selected in the task list portlet.

The selected task is communicated between the task list portlet and the task process portlet by using a PortletMessage, which is a common way of sending information between portlets residing on the same page.

Back to top

Task page

The task page is one of the three portal pages in the sample Analyst Research Report portal application. The first page handles the authoring tasks of the scenario, and the third page displays all the published reports. The task page focuses on the portlets needed to handle the tasks, from accepting a report assignment until the report is published. The specific tasks involved in the scenario depend on the design of the workflow. The workflow can have as little as one stage involving publishing the report, or it could have a complex flow involving approval and rejection branches. The workflow-specific stages will not affect the design of the portlets shown in this page, nor will they affect their implementation. For details on the workflow implemented in the sample, see Part 3 of this series, "Design the workflow management component."

The task page is a portal page accessible to all members of the research team. The page is made of two portlets:

• Task list portlet, which will always show the tasks owned by the authenticated portal user
• Task process portlet, which will always start blank

The task list portlet is refreshed whenever a task is processed; we refresh the task list portlet whenever the task process portlet has finished processing any given task.

Back to top

Task list portlet

The task list portlet shows all the tasks assigned to the authenticated user. The portlet lists the task priority, the task description, and the document's title and status. Clicking on the task description link shows task details in the task process portlet.

The task list portlet is very useful to the Web portal application because it provides a one-stop location, where users are informed about all the tasks waiting for their actions. The portal user does not have to query all his or her reports to find out their state or if they are waiting on any action. The portal user does not have to know about the specific workflow or stages involved in the processing of the report. The workflow details are simply hidden from users so they can focus on the details of the task being handled. As shown in Figure 2 below, users cannot see any tasks or reports that they did not author, or were not assigned to author. The portlet itself has no knowledge of the tasks being displayed; it simply displays all the tasks assigned to the authenticated user.

We used IBM DB2 Content Manager Document Routing as the workflow engine to create the tasks and change the report status. The sample application has a framework to create those tasks and query them by user. For complete details about the workflow framework, see Part 3 of this series.

The portlet queries the list of tasks and dynamically creates portlet actions and associates one to each task. When the user selects the task, the corresponding portlet action is invoked. The portlet extracts the task ID (also known as workpackage ID for document routing) from the selected task. The only data sent to the task process portlet is the task ID. This data is sent by a PortletMessage object in the form of a string.

Details of the processing of the task are discussed in the task process portlet section. After processing a task, the task list portlet is refreshed and the task is no longer shown in the task list view.

The following code fragment shows how the list of tasks is retrieved and processed.

dkCollection result = DocRoutingProcessing.listWorkPackagesByUser
   (userId.toUpperCase()) ;
dkIterator iterator = result.createIterator() ;
while(iterator.more()){
	DKWorkPackageICM workPack = (DKWorkPackageICM) iterator.next() ;
	String itemId = workPack.getItemPidString() ;
	if(ReportUtil.isValidDocument(itemId))
	{
		PortletURI rowActionURI = response.createURI();
		String workPackID = workPack.getPidString() ;
     		rowActionURI.addAction("Row"+ workPackID) ;
     		viewBean.setRowForm(workPackID,rowActionURI.toString()) ;
		resultV.add(workPack) ;
	}
}
sessionBean.setWorkPackages(resultV) ;

listworkPackagesByUser() is the method where all the workpackages (tasks) are collected from the Document Routing component of IBM DB2 Content Manager. In the actionPeformed method below, the task ID (workpackage ID) is embedded in the action. When the action is invoked, the action handler receives the action string from the action event and extracts the task ID from the action string.

public void actionPerformed(ActionEvent event) throws PortletException {
.
.
String actionString = event.getActionString();
.
.
if(actionString.startsWith("Row"))
	getPortletConfig().getContext().send(null, new 
	   DefaultPortletMessage(actionString.substring(3)));

Back to top

Task process portlet

This portlet is where the selected task in the task list portlet is processed. The JSP component shown in the portlet is populated dynamically, depending on the task being processed. Figure 3 below shows just one of the JSP components that could be displayed. This particular one corresponds to the task "Acknowledge the Assignment" shown in the task list portlet. To achieve a separation between the portlet implementation and the specific workflow used in the scenario, the portlet uses a special design discussed below. The design ensures that any task can be handled in an independent manner, from the JSP component being displayed, to the number of ways a task can be processed, to the actual processing of the task.

The processing of a task starts with the task process portlet receiving a PortletMessage from the task list portlet. This is possible because the task process portlet implements a message listener in its controller. When the portlet receives the PortletMessage, the workpackage ID of the selected task is embedded in the message. The message listener implemented in the task process portlet will extract the workpackage ID from the message. The workpackage ID is used to query the workpackage object (task) and find out the state of the report. The code used to retrieve the workpackage ID and the state of the document is shown below.

public void messageReceived(MessageEvent event) throws PortletException {
.
.
    PortletMessage msg = event.getMessage();
	.	
	.
		
    try{

	DKDatastoreICM dsICM = ICMConnectDisconnect.connect();
	if( msg instanceof DefaultPortletMessage ) 
	{
	  String msgContent = ((DefaultPortletMessage )msg).getMessage() ;
	  DKDocRoutingServiceICM routingService = new 
	     DKDocRoutingServiceICM(dsICM);
	  DKWorkPackageICM workPack =routingService.retrieveWorkPackage
	     (msgContent,false) ; 

	       String workNodeName = workPack.getWorkNodeName() ;//Also 
	          represents the state of the Report.
	  String itemId 	= workPack.getItemPidString() ;   
			
	  DKDDO ddoDocument = dsICM.createDDO(itemId);
	  ddoDocument.retrieve();
	  sessionBean.setItem(ddoDocument) ;
	  FlowNode node = (FlowNode) allNodes.get(workNodeName) ;
	  sessionBean.setNode(node) ;
	  sessionBean.setIncomplete() ;	
	}
	ICMConnectDisconnect.disconnect(dsICM);
	   			
   }catch(Exception e){e.printStackTrace() ;
}

The code above shows how the message content is interpreted as the workpackage ID. IBM DB2 Content Manager Document Routing then retrieves the workpackage. The report identification stays in the workpackage object, and can therefore be retrieved and stored in the portlet session bean. The workpackage name was set in our sample to the state of the report. This will be used to retrieve the corresponding JSP component and handlers from the supplied XML file.

The state of the report is important because it is used as an indicator of the corresponding JSP component to display in the task process portlet. In addition to the JSP component name, the state of the report will indicate the ways that a particular state can be processed. In the example shown in the portlet above, a researcher is only allowed one way to process the task "Acknowledge the Assignment," and that is accepting the assignment. In other cases, there will be more then one way to process a task. For example, for an approval task, there would be task approval or rejection. In the case of a task involving contributing comments, a researcher can contribute comments or abstain from contributing comments. The processing of the task can also be done completely outside the portal; the portlet will simply be used to mark the completion of the task with a task complete action.

The dynamic nature of this portlet requires a way to handle displaying different JSP components depending on the report state and a way to handle the actions associated with those different JSP components. To implement this processing, an XML file is provided. The XML file has the required details to handle the prototype-specific states and action handlers for every task's possible outcomes. The XML file associates every state with one JSP file, and a number of branches, where each branch represents one way a task can be processed. It also includes a class name and method name for every branch indicating the Java method for processing the task.

<?xml version="1.0" encoding="UTF-8"?>
< allNodes>
  < node>
	<name>A_New</name>
	<jspPath>AcceptAssignment.jsp</jspPath>
	<branch>
	   <name>Accept</name>
	   <className>myportletproject5.ProcessAcceptAssignment</className>
	   <methodName>accept</methodName>
	</branch>
  </node>	
</allNodes>

The example above shows the processing of "Accept" when the report is in the A_New State. The task process portlet will use the information in this node when a task is selected whose report is in the A_New State. The node indicates the name of the JSP component to display in the portlet. The node also indicates the name of the only action available to handle this task, which in this case is called Accept. Finally, the last piece of information supplied in the node is the name of the class and method to handle the Accept action, myprtletproject5.ProcessAcceptAssignment.accept().

Linking the dynamic JSP component to the correct action in the portlet is done in three steps:

1. In sessionBean.setNode(), you assign the corresponding section of the XML file to the portlet session bean.
2. In the portlet's doView method, the portlet queries the node set in the first step and creates all necessary actions to handle the processing of the task.
3. When an action is invoked, the portlet invokes the corresponding action handler as specified in the XML file.

Below are the code fragments for the steps.

public void doView(PortletRequest request, PortletResponse response) throws 
   PortletException, IOException {
...
	Hashtable actionsURI = new Hashtable() ;		
	// Make a view mode bean
	TaskProcessViewBean viewBean = new TaskProcessViewBean();
 	request.setAttribute(VIEW_BEAN, viewBean);
 	String jspPath = VIEW_JSP + "blank.jsp" ;
 		
 	FlowNode node = sessionBean.getNode() ;
 	if((node != null)&&(!sessionBean.getComplete()))
 	{
 		System.out.println("node is not null") ;
		Vector branches = node.getBranches() ;
		
		for(int i=0;i<branches.size();i++)
	{
              // Set actionURI in the view mode bean
              PortletURI dynamicActionURI = response.createURI();
              Branch branch = (Branch) branches.elementAt(i) ;
              dynamicActionURI.addAction(branch.getName());
              actionsURI.put(branch.getName(),dynamicActionURI) ;
	}
	    	viewBean.setActionsURI(actionsURI);
...

public void actionPerformed(ActionEvent event) throws PortletException {

if( getPortletLog().isDebugEnabled() )
	getPortletLog().debug("ActionListener - actionPerformed called");

// Action string contains the name of the action that invoked the handler.
String actionString = event.getActionString();
		
PortletRequest request = event.getRequest();
        
TaskProcessSessionBean sessionBean = getSessionBean(request);
FlowNode node = sessionBean.getNode() ;
		
try{
    	Branch branch = getBranch(node,actionString) ;
    	if(branch != null)
  {
	Class c = Class.forName(branch.getClassName()) ;
	Class[] parameters = new Class[3] ;
	parameters[0] = Class.forName("java.lang.String") ;
	parameters[1] = Class.forName("org.apache.jetspeed.portlet.
	   PortletRequest") ;
	parameters[2] = Class.forName("org.apache.jetspeed.portlet.
	   PortletContext");
				
	Method m = c.getMethod(branch.getMethodName(),parameters) ;
	Object[] args = new Object[3] ;
	args[0] = sessionBean.getItem().getPidObject().pidString() ;
	args[1] = request ;
	args[2] = getPortletConfig().getContext();
	m.invoke(null,args) ;//method has to be static with one argument of 
	   type DKDDO	
	sessionBean.setComplete() ;
  }
		
	}catch(Exception e)
	{
		e.printStackTrace() ;
	}
		
}
}

By adopting this design we successfully separate the task process portlet from the workflow details of the scenario. This ensures that any future changes of the workflow or additions of other workflows will not affect the portlet code. Instead, there would be changes to the supplied XML file, necessary JSP files, and corresponding classes handling the actions presented in the JSP components. Figure 4 shows the interaction of the task processing portlets with the user-defined options.xml file, and the supplied JSP components and handlers.

Back to top

Summary

This article outlined an effective way to integrate workflow tasks using a portal user interface. The effectiveness of the solution lies in the separation of the portlets from the workflow-specific tasks. The simple user interface makes it easy for portal users to locate their tasks. Users do not have to know what state a report is in, or who has last processed the report, to find their tasks.

Our implementation provides the user with details on the current report state and the task being performed. This is beneficial to the portal user, because all the information needed to make a decision about the task is in one place. The dynamic loading of the JSP components ensures that the task processing portlet can be customized to include as much detail as the specific task requires. This solution has been implemented with the Document Routing engine of IBM DB2 Content Manager, but it could be used with any other workflow engine allowing the management of its tasks with an API. The changes required to alter the workflow engine are hidden under the workflow framework of the sample. For more information about the workflow implementation of the sample, see Part 3 of this series.

Resources

• Visit the series overview page to see the current list of articles in this series.
  
  
• Read IBM DB2 Content Manager for Multiplatforms Version 8.2 Application Programming Reference for a full understanding of how the Content Manager APIs work.
  
  
• For more about the Information Integrator for Content API, see the IBM Content Manager for Multiplatform/IBM Information Integrator for Content Workstation Application Programming Guide Version 8 Release 2 (SC27-1347-01).
  
  
• Visit IBM On Demand Workplace at IBM 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
• Task page
• Task list portlet
• Task process portlet
• 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