Contents

This document includes the following topics:

  1. Introduction
  2. Prerequisites
  3. Installing the Portal Client
  4. Known restrictions
  5. How to use the Portal Client
  6. Converting your existing Web Client JSPs for use with the Portal Client
  7. API documentation

Introduction

IBM MQSeries Workflow - Portal Client V1.0 allows you to access your MQSeries Workflow system from within a Portal Server running on Windows 2000 Professional. The functionality is based on the IBM MQSeries Workflow Web client. Using these functions, you can execute your business processes modelled in the workflow system. Like with the MQSeries Workflow Web Client, you can customize the look and feel of the Portal Client, and can extend it's functionality.

If you have already customized JSPs for the Workflow Web Client, you can also use them in the Portal Client. How to reuse your existing JSPs is described in Converting your existing Web Client JSPs for use with the Portal Client.

The following figure illustrates the structure of the MQSeries Workflow Portal Client.


Two types of Workflow portlets run in the WebSphere Portal Server:

To make full use of the portal's capabilities, you can and should include several action portlet instances on a portal page. Due to known restrictions, it is currently recommended to have only one list portlet instance per portlet page. These portlets use the Web Client BuiltinHandler to interact with the Workflow system using the Java API and MQ messages.

The architecture of the Workflow Portal Client allows CommandHandlers and viewers that were originally written for the Workflow Web Client to be reused in a portal context. You can use a new viewer interface, JSPPortletViewer, to generate portal specific views of the data in the Workflow system.

Prerequisites

IBM MQSeries Workflow - Portal Client V1.0 requires the following prerequisites:

This SupportPac has been tested in the following environments:


Installing the Portal Client

To install and setup IBM MQSeries Workflow - Portal Client V1.0 in your IBM WebSphere Portal Server environment, perform the following:

  1. Download the file WA85.zip from the MQSeries Workflow SupportPac Web site.
  2. Unzip the file to the installation directory of IBM MQSeries Workflow 3.3.2. For example, C:\Program Files\MQSeries Workflow.
  3. A directory named PortalClient will be created, which contains the file MQWFPortalClient.war.
  4. Using a file explorer, verify that the file fmcojagt.jar is located in the directory MQ Workflow directory\BIN\JAVA3322. Note: In a default installation the MQ Workflow directory is C:\Program Files\MQSeries Workflow.
  5. If the 'IBM WS AdminServer 4.0' Service is not running, start it from the Windows 'Services' window.
  6. Open the WebSphere Administrative Console.
  7. Open the 'Properties Tab' of your server instance under Nodes/Your_Node_Name/Application Servers by clicking the server instance 'WebSphere Portal'.
  8. Select the 'JVM Settings' tab.
  9. Click the 'Add' button, and specify the full path to fmcojagt.jar. For example, on a default installation, C:\Program Files\MQSeries Workflow\BIN\JAVA3322\fmcojagt.jar.
  10. Click 'Apply'.
  11. Stop the server by right-clicking on the 'WebSphere Portal' Server instance and selecting 'stop'.
  12. Restart the server by right-clicking on the 'WebSphere Portal' Server instance and selecting 'start'.
  13. Install the MQWFPortalClient.war in WebSphere Portal Server as described in the Portal Server documentation.
  14. Log on to the Portal as the Portal Administrator.
  15. Select the page group 'Portal Administration'.
  16. Select the 'Security' page.
  17. Select 'Credential Vault'.
  18. Add a vault segment.
  19. Provide a vault segment name and click 'OK'.
  20. Add a vault slot.
  21. Provide a name for your slot and leave all other fields as they are. Later, you must add this slot name to the WebClient.properties file.
  22. Click 'OK'.
  23. Adapt the file WebClient.properties in WASInstallationDirectory\installedApps\MQWFPortlet****.ear\MQWFPortlet.war\WEB-INF:
    1. Set SlotName to the name you provided earlier.
    2. Either adapt the line Logfile=D:\Portal\logs\servlet.log, or make sure that the directory D:\Portal\logs exists.
    3. Make sure that the AgentLocator specified matches the one used by your Java Agent configuration, for example, AgentLocator=LOC_LOCATOR for local bindings.
    4. If you have more than one Java Agent configuration, make sure that the line AgentConfiguration=ConfigID specifies the configuration (and therefore the Workflow system) that you want the Portal Client to use.
    Note: The asterisks '****' represent a unique ID assigned by the Portal Server when the portal application is deployed.
  24. As the portal administrator, you must assign the appropriate access rights to the two installed Portlets MQWFListPortlet and MQWFActionPortlet.
  25. Depending on the settings, the portal users or the administrator can now place instances of the Portlets on portal pages.
    NOTE: It is important to have at least one instance of each kind on a portal page (list and action), otherwise the Portal Client can't offer its full functionality.

 

Known restrictions

For version 1.0 of the MQ Workflow Portal Client, the following restrictions apply:


How to use the Portal Client

How to use IBM MQSeries Workflow - Portal Client V1.0 is described here.

 

Converting your existing Web Client JSPs for use with the Portal Client

If you have already created Activity Implementation and Process Start JSPs for the MQSeries Workflow Web Client, you must perform the following steps before you can use them in the Portal Client:

  1. To allow the JavaBean access to the portal specific functions, change the included class from com.ibm.workflow.servlet.client.RequestContext to com.ibm.workflow.portlet.client.RequestContext.
  2. In addition to importing the Java and Workflow packages you also need to include
    <%@ page import="java.text.*, org.apache.jetspeed.portlet.*" %>
  3. To get access to the Portal API functions:
    1. Include the Portlet tag library:
      <%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
    2. Initialize the default objects with: <portletAPI:init />
  4. You must modify all commands used in your JSPs to include a Portlet Action together with the Workflow command. The following Portlet Actions are available:
    Name of DefaultPortletAction Implied actions
    cancelThis action type is used for commands that only require the default view to be displayed again, and do not need to inform other instances about any changes. For a List Portlet, the default view is the most recently displayed list. For an Action Portlet, the default view is generated by ActionPortletNotUsed.jsp.
    freeThis action marks an Action Portlet as free, resets the Action Portlet view to the default view generated by ActionPortletNotUsed.jsp, and refreshes all List Portlet instances on the page.
    listIf an action of this type is triggered in a List Portlet, the command is executed and only the list view is updated.
    selectThis action type causes an MQWFPortletMessage to be sent to a free Action Portlet. When it receives the message, the target Action Portlet sets its status to 'used', it executes the command contained in the message, generates a new view showing the results of the command, and refreshes all List Portlet instances on the page.
    cancelRequestThis action type is used by commands that require the views of used Action Portlets to be updated, for example, terminate/delete ProcessInstance or cancelCheckout triggered from a worklist. A message is sent to the Action Portlets to display either the canceled work item or other information related to a terminated process instance, and all List Portlet instances on the page are refreshed.
    A typical activity implementation or process start JSP will therefore only use the "free" action with its commands. As soon as the button is clicked, and the corresponding command has been executed, the portlet will be made available again for following activities.
  5. If you are using the openForm() convenience method to generate the input form's start tag, the portlet.client.RequestContext class will generate an appropriate form with a "free" action appended to the command. The only extra thing you have to do is to set the PortletResponse in the RequestContext prior to the openForm() call. You can do this by calling setPortletResponse(PortletResponse response) on the RequestContext object.
  6. To make the JSPs portal compatible, remove the <head>, </head>, <body> and </body> tags.

 

API documentation

Each method in the IBM MQSeries Workflow Portal Client V1.0. API is described here.


© Copyright IBM Corporation 2002. All Rights Reserved.