Samples for the MQSeries Workflow Web Client

The samples for the Web Client are not part of the initial installation. After having installed the Web Client, configure the samples as described in the following sections.

It is assumed that the Web Client is already installed and configured. You should also have created a process template list, a process instance list, and a work list. You can do this either by configuring the JSPViewer before starting the Web Client or by using the standard Runtime Client.

Contents

Core Viewers Source code for the DefaultViewer and JSPViewer classes
InternetConnectionViewer Changes the look and feel of the worklist to mimic the IBM FlowMark V2 Internet Connection
CommandHandlerAdapter Allows to register more than one command handler and dispatches commands
HTMLDocHandler Accesses process documentation from the Web Client's template list
AuditTrailHandler Uses JDBC and XML to display audit trail information for processes and activites
EmailHandler Uses SMTP to send notification emails when an item has been transferred
Credit Request Web Client additions for the credit request sample that comes with MQSeries Workflow
StarterPEAHandler Uses the onLogon hook to start a batch PEA for the 'Web user'
BasicAuthenticationHandler Demonstrates third-party authentication using HTTP/1.1 Basic Authentication
Application Data Integration Demonstrates how to integrate non-Workflow data in activity implementation JSPs
Group Work List A tutorial that shows how to customize the work list and how to add new commands
Web Credit Request A complementary support pac that illustrates the 'Web user' feature and the usage of a UPES

Core Viewers

This is not actually a sample, but the source code for two Viewers shipped with the Web Client. You can find the files at <MQWFDir>/smp/WebClient/DefaultViewer.java and <MQWFDir>/smp/WebClient/JSPViewer.java. You may want to have a look at this code when developing your own Viewers.

InternetConnectionViewer

This sample changes the look and feel of the Web Client's work list to mimic the IBM FlowMark V2 Internet Connection. This can be done by either registering a custom Viewer or - when using JSPViewer - by replacing the JSP responsible for rendering the lists. Switch your browser's language to German in order to see localized texts. See also the API documentation for InternetConnectionViewer.java.

To run this sample using a custom Viewer:

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Copy the point.gif, workflow.gif, and restart.gif files from the <MQWFDir>/smp/WebClient/images directory to the <MQWFDir>/WebClient/webpages/images directory.
  3. Edit <MQWFDir>/WebClient/WebClient.properties and set
     DefaultViewer=com.ibm.workflow.servlet.sample.InternetConnectionViewer
    Note that you find the source code for this Viewer in the <MQWFDir>/smp/WebClient directory. You must restart the Web Client for this change to become effective. There is no change to the CLASSPATH necessary since this sample Viewer is already contained in fmcohcli.jar.
  4. Log on to Workflow using the Web Client in order to see the new layout.

To run this sample using a custom JSP:

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Copy the point.gif, workflow.gif, and restart.gif files from the <MQWFDir>/smp/WebClient/images directory to the <MQWFDir>/WebClient/webpages/images directory.
  3. Make a backup copy of <MQWFDir>/WebClient/webpages/forms/ListViewer.jsp, then copy <MQWFDir>/smp/WebClient/forms/InternetConnectionListViewer.jsp to <MQWFDir>/WebClient/webpages/forms/ListViewer.jsp. Make sure the new ListViewer.jsp has its modification time updated or the JSP might not be recompiled.
  4. Edit <MQWFDir>/WebClient/WebClient.properties and set
     DefaultViewer=com.ibm.workflow.servlet.client.JSPViewer
    You must restart the Web Client for this change to become effective.
  5. Log on to Workflow using the Web Client in order to see the new layout.
  6. To restore the original work list, simply use the ListViewer.jsp from your backup.

CommandHandlerAdapter

This sample CommandHandler loads up to 16 other command handlers and dispatches user-defined commands to them, thus allowing for more than one custom handler. It also shows how to read settings from the WebClient.properties file. See also the API documentation for CommandHandlerAdapter.java.

To use this sample:

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Edit <MQWFDir>/WebClient/WebClient.properties and set
     CommandHandler=com.ibm.workflow.servlet.sample.CommandHandlerAdapter
  3. In the [CommandHandlerAdapter] section of WebClient.properties register all command handlers that you would like to use by adding lines of the form
     <CommandHandlerClassName>=<index>
    The indices are zero-based and must be consecutive. They denote the order in which user-defined commands are to be dispatched. Commands that are not recognized by any registerd handler are ignored.
  4. You must restart the Web Client for this change to become effective. There is no change to the CLASSPATH necessary since this sample CommandHandler is already contained in fmcohcli.jar.

HTMLDocHandler

This sample allows HTML documentation exported from MQSeries Workflow Buildtime to be accessed from the Web Client's template list. See also the API documentation for HTMLDocHandler.java.

To prepare the HTML documentation for a process:

  1. Create a ProcessDocs subdirectory in <MQWFDir>/WebClient/webpages. The process documentation files will be created in this directory. If the Buildtime component is installed on a different machine than the Web Client, you will have to copy the exported HTML files to that subdirectory on your Web server.
  2. Start the MQSeries Workflow Buildtime.
  3. Select the 'Buildtime' - 'Export...' menu option.
  4. Select the 'Export single objects' radio button.
  5. In the tree view, select the process you want to create HTML documentation for. Do not select multiple processes, but rather repeat theses steps for each process you want to export.
  6. In the 'Export format' group box, select the 'HTML' option.
  7. In the 'Export flags' group box, select the 'Export deep' option.
  8. Click the 'OK' button.
  9. In the 'Save As' dialog, enter the File name: <MQWFDir>/WebClient/webpages/ProcessDocs/<ProcessName>.htm. Make sure to use the process name as file name and to use .htm (not .html) as file extension. This is necessary because the HTMLDocHandler uses the Process Template name to find the corresponding HTML file (for the same reason you must export each process individually).
  10. Click the 'Save' button.

To run this sample:

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Copy the htmldoc.gif file from the <MQWFDir>/smp/WebClient/images/action directory to the <MQWFDir>/WebClient/webpages/images/action directory.
  3. Edit <MQWFDir>/WebClient/WebClient.properties and set
     CommandHandler=com.ibm.workflow.servlet.sample.HTMLDocHandler
    Alternatively, you can use the CommandHandlerAdapter. You must restart the Web Client for this change to become effective. There is no change to the CLASSPATH necessary since this sample CommandHandler is already contained in fmcohcli.jar.
  4. Go to the Web Client's template list. You should see an additional icon to the right of the 'properties' icon for those processes you have created HTML documentation for. HTMLDocHandler does not show the icon for processes where no HTML documentation is available in <MQWFDir>/WebClient/webpages/ProcessDocs. Note that you can find the source code for this CommandHandler in the <MQWFDir>/smp/WebClient directory.

AuditTrailHandler

This sample accesses the audit trail using JDBC and returns the event data in XML format. This data is then formatted using XSL style sheets. Audit trail data can be queried from the process list where a table with all events will be shown as well as from the work list where activity statistics will be shown. Both use the Bean Scripting Framework to exploit JavaScript within the XSL style sheet. See also the API documentation for AuditTrailHandler.java.

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Download the XML parser, XSLT processor and Bean Scripting Framework from http://xml.apache.org/xalan. Then add xerces.jar, xalan.jar, bsf.jar, and bsfengines.jar to your application server's CLASSPATH. Usually this is the same place where you registered fmcohcli.jar, for example, in WebSphere it is the 'Command line arguments' field on the 'Application Server Properties' - 'General' page.
  3. Download the JavaScript plugin (aka Rhino) for the Bean Scripting Framework from http://www.mozilla.org/rhino. Note that Apache's Xalan V2.0 requires Version 1.5 of Rhino. Then add js.jar to your application server's CLASSPATH. Note that WebSphere Application Server V3.5 already ships all those .jar files, but they might not work because they are incompatible.
  4. Copy the audittrail.gif file from the <MQWFDir>/smp/WebClient/images/action directory to the <MQWFDir>/WebClient/webpages/images/action directory.
  5. Copy the files AuditTrail.xsl and Statistics.xsl from the <MQWFDir>/smp/WebClient/xml/xsl directory to the <MQWFDir>/WebClient/webpages/xml/xsl directory.
  6. Edit <MQWFDir>/WebClient/WebClient.properties and set
     CommandHandler=com.ibm.workflow.servlet.sample.AuditTrailHandler
    Alternatively, you can use the CommandHandlerAdapter.
  7. Check the DB2Server, Database, DB2User, and DB2Password settings in the [AuditTrail] section of WebClient.properties and make sure they are correctly set for your environment.
  8. Enable the StyleSheetPI and StyleSheetWI lines in order to get formatted HTML pages instead of raw XML output. You must restart your application server for all these changes to become effective.
  9. Go to the Web Client's instance list. You should see an additional icon to the right of the 'properties' icon for those processes which have the audit trail enabled.

EmailHandler

This sample handler intercepts the transferItem command in ListViewer.jsp. It allows to specify an email address where to send a notification of the item transfer. See also the API documentation for EmailHandler.java.

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Download and install JavaMail and the Java Activation Framework. Then add mail.jar and activation.jar your application server's CLASSPATH. Usually this is the same place where you registered fmcohcli.jar, for example, in WebSphere it is the 'Command line arguments' field on the 'Application Server Properties' - 'General' page.
  3. Copy the EmailViewer.jsp file from the <MQWFDir>/smp/WebClient/forms directory to the <MQWFDir>/WebClient/webpages/forms directory. Alternatively, you can copy <MQWFDir>/smp/WebClient/forms/EmailViewer_html.jsp to <MQWFDir>/WebClient/webpages/forms/EmailViewer.jsp if your mail client natively supports HTML. The latter form also contains some additional documentation.
  4. Edit <MQWFDir>/WebClient/WebClient.properties and set
     CommandHandler=com.ibm.workflow.servlet.sample.EmailHandler
    Alternatively, you can use the CommandHandlerAdapter. Then set
     DefaultViewer=com.ibm.workflow.servlet.client.JSPViewer
    This is necessary because the EmailHandler is based on JSPs which are not supported by the DefaultViewer class.
  5. Check the Host and Address settings in the [SMTP] section of WebClient.properties and make sure they are correctly set for your environment. You must restart your application server for all these changes to become effective.
  6. Go to the Web Client's work list and click on the 'transfer' icon of an item. This will open a new form where you can enter an email address in addition to the user ID where to transfer the item.

Credit Request

This sample contains HTML and JSP forms to be used with the Credit Request sample that comes with MQSeries Workflow. It shows how to customize the look and feel of the forms being displayed when processes and work items are started from the Web Client. See also the corresponding section in Activity Execution for more details. Furthermore, this sample shows how to use the 'Web user' feature of the Web Client that allows you to start processes without logging on to workflow.

To run this sample using the Web Client:

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Import the Credit Request process, <MQWFDir>/scenario/credit/fmccred.fdl into Runtime and translate it. For details on how to use the Runtime import utility, see the MQSeries Workflow Getting Started with Buildtime book.
  3. Copy all files in <MQWFDir>/scenario/credit/processes to <MQWFDir>/WebClient/webpages/processes.
  4. Copy all files in <MQWFDir>/scenario/credit/programs to <MQWFDir>/WebClient/webpages/programs.
  5. Copy all files in <MQWFDir>/scenario/credit/images to <MQWFDir>/WebClient/webpages/images.
  6. Copy creditsample.css from <MQWFDir>/scenario/credit to <MQWFDir>/WebClient/webpages.
  7. Open (or refresh) the templates list in the Web Client.
  8. Click on the 'Create and start Instance' button for the CreditRequest process. This will launch either <MQWFDir>/WebClient/webpages/processes/CreditRequest.html (when using DefaultViewer) or <MQWFDir>/WebClient/webpages/processes/CreditRequest.jsp (when using JSPViewer). Note that the name of the JSP or HTML form to be launched is derived from the process template name. When developing your own applications you should use JSPs rather than the propriatary HTML templates. The latter are only supported for backward compatibility with application servers that do not yet support JSPs.
  9. Go to the Web Client's work list and start the CollectCreditInformation work item. This will launch either <MQWFDir>/WebClient/webpages/programs/NCollectCreditData.html or <MQWFDir>/WebClient/webpages/programs/NCollectCreditData.jsp. Note that the name of the JSP or HTML form to be launched is derived from the name of the program assigned to the activity.

To run this sample using the 'Web user' feature:

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Import the Credit Request process, <MQWFDir>/scenario/credit/fmccred.fdl into Runtime and translate it. For details on how to use the Runtime import utility, see the MQSeries Workflow Getting Started with Buildtime book.
  3. Copy all HTML and JSP files in <MQWFDir>/scenario/credit/starter to <MQWFDir>/WebClient/webpages/starter.
  4. Decide which Workflow user ID is to be used for the 'Web user' feature. You can import the provided <MQWFDir>/scenario/credit/starter/starter.fdl file to create a user ID STARTER with password password.
  5. Configure this user ID in WebClient.properties by setting the StarterUserID and StarterPassword properties. Note that you have to restart the Web Client for these changes to become effective. Also note that the StarterUserID cannot be used to log on to Workflow with the Web Client.
  6. Point your browser to http://localhost/MQWFClient/starter/StartCreditRequest.html or to http://localhost/MQWFClient/starter/StartCreditRequest.jsp Note that you might have to edit these files since they are not served by the Web Client and thus cannot dynamically query the servlet configuration. That is, if you are using a root URI other than /MQWFClient, you must enter the new root URI in these files.
  7. Enter the data needed to start the CreditRequest process and click the 'Apply for Credit' button. Since the 'Web user' feature only allows to start processes, you must now logon to Workflow in order to complete the process.

StarterPEAHandler

This sample shows how to use the CommandHandler.onLogon() and CommandHandler.onLogoff() hooks to automatically start a Program Execution Agent for the 'Web user'. See also the API documentation for StarterPEAHandler.java.

Note that since this PEA runs on the Application server machine it is not suited for activities that require user interaction. If you expect more than small workload for the Web user ID, you should consider using a User-defined PES (UPES) instead of this PEA. For a completely different use of the onLogon hook see the Group Work List tutorial.

  1. Edit <MQWFDir>/WebClient/WebClient.properties and set
     CommandHandler=com.ibm.workflow.servlet.sample.StarterPEAHandler
    Alternatively, you can use the CommandHandlerAdapter.
  2. Set up the 'Web user' feature as described in the Credit Request sample above.
  3. Enable the PEA in WebClient.properties by adding the following line:
     StarterPEA=true
    Note that you have to restart the Web Client for this change to become effective.
  4. Run the Credit Request sample as described above. The PEA will be automatically started for the Web user ID. Note that this PEA is not actually used by the Credit Request sample since it contains no automatic activities assigned to that user ID.

BasicAuthenticationHandler

This sample shows how to use the CommandHandler.getCredentials() hook to extract credentials from an HTTP request which are later used to authenticate with MQSeries Workflow without having to specify userID and password for the BuilinHandler.logon() command. See also the API documentation for BasicAuthenticationHandler.java.

  1. Set up up HTTP/1.1 Basic Authentication in your Web server for the Web Client's Web application.
  2. Edit <MQWFDir>/WebClient/WebClient.properties and set
     CommandHandler=com.ibm.workflow.servlet.sample.BasicAuthenticationHandler
    Alternatively, you can use the CommandHandlerAdapter.
  3. Only when using MQSeries Workflow V3.3 or later release levels:
    1. Shut down the Workflow Administration server.
    2. Enable the Java Authentication Exit by invoking the following command:
       fmczchk -c inst:m,RTAuthenticationExitTypeServer,JAVA -y <cfgID>
      See also the MQSeries Workflow V3.3 Programming Guide, Chapter 7, "Using an authentication exit".
    3. Make sure the Workflow Administration server's CLASSPATH contains the following two jar files:
       CLASSPATH=<MQWFDir>\bin\fmcoutil.jar;<MQWFDir>\WebClient\fmcohcli.jar
      Note that the Java authentication exit for this sample, com.ibm.workflow.java.exit.Authentication, is already contained in fmcohcli.jar. That is, you must not put this jar file on the Workflow Administration server's CLASSPATH if you do not use this example.
    4. Make sure the PATH for the Workflow Administration server includes Java. On Windows, it is not sufficient to have java.exe in the <WinDir>\system32 directory since the Workflow Java bridge must be able to find the JVM DLL.
    5. Restart the Workflow Administration server.
  4. Point your browser to http://localhost/MQWFClient/servlet/Main?command=logon. Note that there are no additional parameters like userID or password needed for the logon command.

Application Data Integration

This example demonstrates how to display non-Workflow data in activity implementation JSPs, how to store non-Workflow data entered in theses JSPs, and how to use custom icons in the process monitor.

Custom icons are assigned to activities when modeling the process in Buildtime. If these icons are to be shown in the Web Client's process monitor, they must be converted to the JPG format and placed in the <MQWFDir>/WebClient/webpages/images/icons directory. On Unix platforms, make sure the file names consist of lowercase characters only.

  1. Make sure MQSeries Workflow and the Web Client are running.
  2. Import the Application Data Integration process, <MQWFDir>/smp/WebCredit/appdata.fdl into Runtime and translate it. For details on how to use the Runtime import utility, see the MQSeries Workflow Getting Started with Buildtime book.
  3. Copy the ACreateCustomer.jsp, ASaveCustomer.jsp, and AShowCustomer.jsp files from <MQWFDir>/smp/WebClient/programs to <MQWFDir>/WebClient/webpages/programs.
  4. Copy the letter.jpg and diskette.jpg files from <MQWFDir>/smp/WebClient/images/icons to <MQWFDir>/WebClient/webpages/images/icons.
  5. Open (or refresh) the templates list in the Web Client.
  6. Click on the 'Create and start Instance' button for the Application Data Integration process. Enter the instance' name and click 'OK'.
  7. Go to the worklist and start the 'Create New Customer' work item. This will invoke the 'ACreateCustomer' JSP. You may need to refresh your worklist to see this new work item.
  8. Enter the customer data and click 'Create Customer'. This will invoke the 'ASaveCustomer' JSP which stores all data in a file and only passes the customer ID on to Workflow.
  9. Start the 'Show Customer Data' work item. This will invoke the 'AShowCustomer' JSP which uses the customer ID stored in Workflow to search the file for the rest of the customer data.
  10. For more details, look at the source code of the JSP files.


© Copyright IBM Corporation 1999, 2001. All Rights Reserved.