Create the task processing portlet

 

+

Search Tips   |   Advanced Search

 

This topics describes the APIs used to develop the task processing portlet.

You should read Setting up the development environment for process applications before proceeding with this topic.

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.

  • Task API

    Human task manager of WebSphere Process Choreographer

  • TaskUI Manager API

    Portlet service for the task user interface

  • Property broker API

    Exchange properties with other portlets

Javadocs for the TaskUI Manager and Property Broker APIs are located in the portal_server_root/doc/Javadoc/api_docs directory. Javadocs for the Task API are located in the app_server_root/web/apidocs/ directory.

The Task API Javadoc is available only if the option to install the API documentation was selected during installation of WebSphere Application Server.

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

  1. Retrieving properties from My Tasks portlet

  2. Processing the task

  3. Closing the task page

  4. Import required class libraries

 

Retrieving properties from My Tasks portlet

As the properties that are sent 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. For standard portlets, add the following preference value to the portlet.xml file. Figure 1. Standard portlet preference example 

        <portlet_preferences>

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

   ...
    </portlet_preferences>

For IBM portlets, add the following configuration parameter for the concrete portlet to the portlet.xml file. Figure 2. IBM configuration parameter example: 

  ...
   <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>

You must also modify the web.xml file to refer to the property broker classes. The servlet class entry should specify the com.ibm.wps.pb.wrapper.PortletWrapper class in the property broker. See Receiving property values for an example.

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

Standard portlet example:

Standard 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.

  1. Obtain the HumanTaskManagerDelegate using the HumanTaskManagerDelegateFactory.

    Standard portlet example 

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

     ...

      Context ctx = new InitialContext();

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

       HumanTaskManagerDelegateFactoryService humanTaskManagerDelegateFactoryService = 
                (HumanTaskManagerDelegateFactoryService)
             humanTaskManagerDelegateFactoryServiceHome.getPortletService(HumanTaskManagerDelegateFactoryService.class);

       humanTaskManager = humanTaskManagerDelegateFactoryService.getHumanTaskManagerDelegate();
     ...
   }

    IBM portlet example 

       humanTaskManagerDelegateFactory = (HumanTaskManagerDelegateFactoryService) 
      portletConfig.getContext().getService(HumanTaskManagerDelegateFactoryService.class);

     ...
      
      HumanTaskManagerDelegate humanTaskManager = 
      humanTaskManagerDelegateFactory.getHumanTaskManagerDelegate();

  2. 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: 

       DataObject message = (DataObject) 
   (((com.ibm.task.api.ClientObjectWrapper) taskManager.getInputMessage(taskID)).getObject());

  3. 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.

  4. 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: 

       Task task = taskManager.getTask(taskID);
   ClientObjectWrapper cow = (com.ibm.task.api.ClientObjectWrapper) 
   taskManager.createMessage(taskID, task.getOutputMessageTypeName());

        DataObject message = (DataObject) cow.getObject();
               
        message.setBoolean("managerApproved",true);
               
        taskManager.setOutputMessage(taskID, cow);

  5. 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 standard and IBM portlets.

Obtaining the TaskUIManager

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

Standard portlet 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 portlet 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 (standard portlet API) or an ActionEvent (IBM portlet API).

Standard portlet 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 portlet 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);

   ...
}

 

Import required class libraries

The task processing portlet must include the WSDL and XSD message files for tasks that are generated by WebSphere Integration Developer 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. Before you start these steps, make sure you have a copy of this JAR on the machine used to develop the task processing portlet.

If we use Rational Application Developer for portlet development, perform these steps:

  1. Open the task processing portlet project.

  2. Open the /Web-Content/WEB-INF/lib folder of the portlet project.

  3. Right click on the /lib folder to open the context menu.

  4. Select Import from the context menu. The Import wizard opens.

  5. Select Select From File and click Next.

  6. In the next window click Browse to select the folder in which the JAR is located and click OK.

  7. Select the JAR and click Finish.

The JAR is imported into the portlet project.

 

Parent topic:

Developing business process applications

 

Related concepts

Setting up the development environment for process applications
Initiating a process instance

 

Related information

Enabling the business process for portal
Migrating business process applications