Contents
This document includes the following topics:
- Introduction
- Prerequisites
- Installing the Portal Client
- Known restrictions
- How to use the Portal Client
- Converting your existing Web Client JSPs for use with the Portal Client
- 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:
The List Portlet instances are used to display all Workflow information related to lists. They allow users to work with activities that are assigned to them, and to create and start Workflow processes. Users can also create, modify, and delete lists. You can select from four predefined list views:
- Process Template List
- Process Instance List
- Work Item List
- List of Lists
The ActionPortlet instances are used to process the actions that are triggered by mouse clicks in the ListPortlet. When an action is triggered in a list portlet, a free action portlet capable of handling the action is located using the Workflow Portal Client's interportlet communication mechanism, and a message is sent to that portlet to trigger the appropriate interaction with the Workflow system. If no suitable action portlet is available, the user gets a warning that she must first complete a previous action to free-up a portlet. When successful, the responses from the Workflow system are displayed in the action portlet, when the portal page is aggregated in response to the user request. When a user finishes an action in an action portlet, the portlet becomes 'free', and is available for further actions. You can use the 'edit' mode of the action portlets to specify which types of command each portlet instance can and cannot handle. If you wish, you can assign certain actions to a particular portlet.
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:
- The environment supported by IBM MQSeries Workflow Version 3.3.2.
- IBM MQSeries Workflow Version 3.3.2 - with a configuration that includes a Java Agent that is accessible from the application server running WepSphere Portal Server.
- WebSphere Portal Server 4.1.2 or higher, and all prerequisites for WPS.
- If you are using the Portal Server, Workflow servers, and database on the
same machine it is recommended to have at least have 1 GB of memory installed.
This SupportPac has been tested in the following environments:
- Windows 2000 Professional with SP2
- IBM MQSeries Workflow 3.3.2 SP2
- IBM MQSeries 5.2
- IBM Universal Database 7.2
- IBM WebSphere Application Server 4.02
- IBM WebSphere Portal Server 4.1.2
- Microsoft Internet Explorer 5.5 and 6.0
- Netscape Communicator 4.79, 6.2, and 7.0
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:
- Download the file WA85.zip from the MQSeries Workflow SupportPac Web site.
- Unzip the file to the installation directory of IBM MQSeries Workflow 3.3.2. For example, C:\Program Files\MQSeries Workflow.
- A directory named PortalClient will be created, which contains the file MQWFPortalClient.war.
- 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.
- If the 'IBM WS AdminServer 4.0' Service is not running, start it from the Windows 'Services' window.
- Open the WebSphere Administrative Console.
- Open the 'Properties Tab' of your server instance under Nodes/Your_Node_Name/Application Servers by clicking the server instance 'WebSphere Portal'.
- Select the 'JVM Settings' tab.
- 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.
- Click 'Apply'.
- Stop the server by right-clicking on the 'WebSphere Portal' Server instance and selecting 'stop'.
- Restart the server by right-clicking on the 'WebSphere Portal' Server instance and selecting 'start'.
- Install the MQWFPortalClient.war in WebSphere Portal Server as described in the Portal Server documentation.
- Log on to the Portal as the Portal Administrator.
- Select the page group 'Portal Administration'.
- Select the 'Security' page.
- Select 'Credential Vault'.
- Add a vault segment.
- Provide a vault segment name and click 'OK'.
- Add a vault slot.
- 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.
- Click 'OK'.
- Adapt the file WebClient.properties in WASInstallationDirectory\installedApps\MQWFPortlet****.ear\MQWFPortlet.war\WEB-INF:
- Set SlotName to the name you provided earlier.
- Either adapt the line Logfile=D:\Portal\logs\servlet.log, or make sure that the directory D:\Portal\logs exists.
- Make sure that the AgentLocator specified matches the one used by your Java Agent configuration, for example, AgentLocator=LOC_LOCATOR for local bindings.
- 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.
- As the portal administrator, you must assign the appropriate access rights to the two installed Portlets MQWFListPortlet and MQWFActionPortlet.
- 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:
- The Portal Client log on page does not allow the user to specify which system or system group to log on to. The Portal client can only connect to the system or system group specified in the MQ Workflow Java Agent configuration.
- Using more than one list portlet on a portal page can lead to two known problems:
- The list portlets might exhibit refresh problems. For example, not all list portlets will be refreshed, or a list portlet might display a different MQ Workflow list than the one it displayed before the refresh.
- Using multiple list portlets to log on to MQ Workflow using multiple Workflow user IDs can result in unpredictable behavior.
It is therefore recommended for each portlet page to have only one list portlet instance, but many action portlet instances.
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:
-
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.
-
In addition to importing the Java and Workflow packages you also need to include
<%@ page import="java.text.*, org.apache.jetspeed.portlet.*" %>
- To get access to the Portal API functions:
- Include the Portlet tag library:
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
- Initialize the default objects with: <portletAPI:init />
- 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 |
cancel | This 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. |
free | This 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. |
list | If an action of this type is triggered in a List Portlet, the command is executed and only the list view is updated. |
select | This 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. |
cancelRequest | This 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.
- 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.
- 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.