Create the task processing portlet

After the user claims a task and selects the task for processing, the task page is launched with the task processing portlet. My Tasks and the task processing portlet build a dynamically assembled page application that spans multiple pages. To develop a task processing portlet, be familiar with the following APIs.

The internal flow of control of the task processing portlet can be separated into three phases.

API	Description
Task	Human task manager of WebSphere Process Choreographer
TaskUI Manager	Portlet service for the task user interface
Property broker	Exchange properties with other portlets

Retrieve properties from My Tasks portlet

As the properties that are send by the My Tasks portlet are only delivered once, the task processing portlet is responsible to keep them as long as they are required. The following properties are delivered:

Name	Value	Description
TaskID	String	Unique identifier of the task
ReturnPageID	com.ibm.portal.ObjectID	The object ID of the page to which the user should be navigated when the task is completed.
TaskUIHandle	com.ibm.portal.taskui.TaskUiHandle	A handle that identifies the current task page. Used to close the task page.

The task processing portlet must indicate that it can retrieve task properties using the following setting in the portlet.xml

JSR 168 example:

Add the following preference value to the portlet.xml file.

    
   <preference>
      <name>com.ibm.portal.pagecontext.enable</name>
      <value>true</value>
   </preference>

IBM example:

Add the following config-parameter for the concrete portlet to the portlet.xml file.

   ...
   <concrete-portlet-app uid="ApprovePortlet.1">
      <portlet-app-name>Travel Request Application</portlet-app-name>
      ...
      <concrete-portlet href="#Portlet_1">
         <portlet-name>Approve Portlet</portlet-name>
         ...
         <config-param>
            <param-name>com.ibm.portal.pagecontext.enable</param-name>
            <param-value>true</param-value>
         </config-param>
         ... 
      </concrete-portlet>
   </concrete-portlet-app>

The portlet obtains the properties using the following code. For more information about how cooperative portlets exchange properties, see Registering portlet properties.

JSR 168 example:

JSR 168 compliant portlets receive page context parameters on the processAction() method using the com.ibm.portal.action.name request attribute. The value of this attribute is a Map storing the context entries. Each property value is obtained by name.

   public void processAction (ActionRequest request, ActionResponse response) 
                throws PortletException, java.io.IOException
   {
       
      // perform application specific action handling
      ...
          
      // perform page context processing
   
      String specialAction = request.getParameter("com.ibm.portal.action");
 
      if (specialAction != null &&
         specialAction.equals("com.ibm.portal.pagecontext.receive")) 
      {
         //this indicates context was passed to the launched page
         java.util.Map contextMap = (java.util.Map)
                       request.getAttribute("com.ibm.portal.pagecontext.context");

         TaskUIHandle taskUIHandle =  (TaskUIHandle) contextMap.get("TaskUIHandle");
   
         ObjectID returnPageID = (ObjectID) contextMap.get("ReturnPageID");

         String taskID = (String) contextMap.get("TaskID");

         portletSession.setAttribute("TaskUIHandle", taskUIHandle);
         portletSession.setAttribute("ReturnPageID", returnPageID);
         portletSession.setAttribute("TaskID", taskID);

      }

   }

IBM example:

IBM portlets must implement the PropertyListener interface that provides the setProperties() method, which provides the page context parameters as an array of PropertyValue objects. In this sample, a loop is used to scan the array for the task properties.

   public void setProperties PortletRequest(request, PropertyValue contextArray[])
   {
        
      String taskID = null; 
      TaskUIHandle taskUIHandle = null;
      ObjectID returnPageID = null;

      for (int i = 0; i < contextArray.length; i++) 
      {
          String propertyName = contextArray[i].getProperty().getName();

         if(propertyName.equals("TaskUIHandle"))
         {
            taskUIHandle = (TaskUIHandle)contextArray[i].getValue();
         }
            else if(propertyName.equals("ReturnPageID"))
         {
            returnPageID = (ObjectID) contextArray[i].getValue();
         }
         else if(propertyName.equals("TaskID"))
         {
            taskID = (String) contextArray[i].getValue();
         }
      }

      request.getSession().setAttribute("TaskUIHandle", taskUIHandle);
      request.getSession().setAttribute("ReturnPageID", returnPageID);
      request.getSession().setAttribute("TaskID", taskID);

   }

Processing the task

To process the task, the following steps need to be performed.

Obtain the TaskManagerDelegate using the TaskManagerDelegateFactory.

JSR 168 example


   public void init PortletConfig(portletConfig) throws PortletException, UnavailableException
   {
      super.init(portletConfig);

      ...

      Context ctx = new InitialContext();

      PortletServiceHome taskManagerDelegateFactoryServiceHome = 
         (PortletServiceHome)
      ctx.lookup("portletservice/com.ibm.portal.portlet.service.taskmanager.TaskManagerDelegateFactoryService"); 

      TaskManagerDelegateFactoryService taskManagerDelegateFactoryService = (TaskManagerDelegateFactoryService)
      taskManagerDelegateFactoryServiceHome.getPortletService(TaskManagerDelegateFactoryService.class);

      taskManager = taskManagerDelegateFactoryService.getTaskManagerDelegate();
      ...
   }

IBM example


   taskManagerDelegateFactory = (TaskManagerDelegateFactoryService) 
      portletConfig.getContext().getService(TaskManagerDelegateFactoryService.class);

      ...
      
      TaskManagerDelegate taskManager = taskManagerDelegateFactory.getTaskManagerDelegate();

Retrieve the input message from the human task manager and display it.
The portlet uses the getInputMessage() method of the TaskManagerService interface to obtain the input message from the human task manager.
Example:
```
   WSIFMessage message = 
      (WSIFMessage)( (ClientObjectWrapper)taskManager.getInputMessage(taskID)).getObject() );
        
```
When the input or output messages of a task contain complex types, verify you add the Java classes that were created by the WebSphere Studio process tooling for these messages to the classpath of the portlet. This would be in the portlet's /WEB-INF/classes directory or, if packaged as a JAR, in the /WEB-INF/lib directory.
Display the input message and provide a user interface to obtain the required data from the user for output. As part of this step, the portlet could exchange properties with other supporting portlets on the page through the property broker.
Send the output message to the human task manager.
After the user has entered information into the portlet and submits the changes, the portlet uses the setOutputMessage() of the TaskManagerService interface to send the information to the human task manager.
Example:
```
   ClientObjectWrapper cow = (ClientObjectWrapper)taskManager.getOutputMessage(taskID);
   WSIFMessage message = cow.getObject();                           
   message.setObjectPart("approval", true);
   taskManager.setOutputMessage(taskID, cow);
   
```
When the input or output messages of a task contain complex types, verify you add the Java classes that were created by the WebSphere Studio process tooling for these messages to the classpath of the portlet. This would be in the portlet's /WEB-INF/classes directory or, if packaged as a JAR, in the /WEB-INF/lib directory.
Complete the task.
The portlet uses the complete() method of the TaskManagerService interface.
Example:
```
   taskManager.complete(taskID);
```

Closing the task page

The portlet retrieves the TaskUIManager portlet service to close the task page and return the user to the task list page. The following samples show how this can be done for JSR 168 compliant and IBM portlets.

Obtaining the TaskUIManager

JSR 168 compliant and IBM portlets retrieve the TaskUIManager using different methods. See Portlet services for more information.

JSR 168 example


   public void init PortletConfig(portletConfig) 
               throws PortletException, UnavailableException
   {
      super.init(portletConfig);

      ...

      Context ctx = new InitialContext();

      PortletServiceHome serviceHome = (PortletServiceHome)
      ctx.lookup("portletservice/com.ibm.portal.portlet.service.taskui.TaskUIManager"); 
 
      taskUIManager = (TaskUIManager)
      serviceHome.getPortletService(TaskUIManager.class);

      ...

   }

IBM example


   taskUIManager = (TaskUIManager)
   portletConfig.getContext().getService(TaskUIManager.class);

Closing the page and setting the new page

The closeTaskUI() method closes the task page specified by the TaskUIHandle. The setPage() method indicates the new page (ReturnPageID) that will be opened. In addition, both methods accept either the ActionRequest and ActionResponse arguments (JSR 168) or an ActionEvent (IBM).

JSR example

public void processAction (ActionRequest request, ActionResponse response) 
       throws PortletException, java.io.IOException
{
   ...

   TaskUIHandle taskUIHandle = (TaskUIHandle)
   portletSession.getAttribute("TaskUIHandle");
    
   ObjectID returnPageID = (ObjectID)
   portletSession.getAttribute("ReturnPageID");


   taskUIManager.closeDynamicUI(request, response, taskUIHandle);
   taskUIManager.setPage(request, response , returnPageID);

   ...
}

IBM example


public void actionPerformed(ActionEvent event)
        throws PortletException
{
    ...

    TaskUIHandle taskUIHandle = (TaskUIHandle)
    portletSession.getAttribute("TaskUIHandle");

    ObjectID returnPageID = (ObjectID)
    portletSession.getAttribute("ReturnPageID");

    taskUIManager.closeDynamicUI(event, taskUIHandle);
    taskUIManager.setPage(event, returnPageID);

    ...
}

Importing required class libraries

The task processing portlet must include the message classes generated by WebSphere Studio Application Developer Integration Edition as well as special classes for property broker support (see Classes required for the task processing portlet). These classes are packaged in a JAR and must be added to the /WEB-INF/lib directory of the portlet.

If you use Rational Application Developer for portlet developing perform these steps:

Open your task processing portlet project.
Open the /Web-Content/WEB-INF/lib folder of the portlet project.
Right click on the /lib folder to get the context menu.
Select Import from the context menu. The Import wizard opens.
Select Select From File and click Next.
In the next window click Browse to select the folder in which the JAR is located and click OK.
Select the JAR and click Finish.

The JAR will is imported into the portlet project.