Samples for the IBM WebSphere MQ Workflow Web client

The samples for the Web client are installed automatically, but they are not part of the Web client configuration, therefore, they are not configured automatically. When you have installed the Web client, you must configure the samples according to the information provided in the following sections.

Before using the samples

It is assumed that you have installed and configured the Web client, and created a process template list, a process instance list, and a work list before configuring the samples. You can create these lists after having logged on to the Web client for the first time, or by using the standard MQ Workflow Client.

Contents

The following samples are provided with the Web client:
Core Viewers The core viewers provide the source code for the DefaultViewer and JSPViewer classes.
InternetConnectionViewer With this sample, you can change the look and feel of the worklist to mimic the IBM FlowMark V2 Internet Connection.
CommandHandlerAdapter With this sample, you can register more than one command handler and dispatch commands.
HTMLDocHandler With this sample, you can access the process documentation from the template list of the Web client.
AuditTrailHandler This sample uses JDBC and XML to display audit trail information for processes and activities.
EmailHandler This sample uses SMTP to send notification e-mails when an item has been transferred.
Credit Request This sample contains Web client additions for the credit request sample that is delivered with MQ Workflow.
StarterPEAHandler This sample uses the onLogon hook to start a batch Program Execution Agent (PEA) for the 'Web user'.
BasicAuthenticationHandler This sample demonstrates third-party authentication using HTTP/1.1 Basic Authentication.
Application Data Integration This sample demonstrates how to integrate non-MQ Workflow data in activity implementation JSPs.
Group Work List The group work list is a 'tutorial' where you learn how to create your own group worklist, according to the design given by the Web client. It shows how you can you can customize the worklist and how to add new commands.
Web Credit Request (web) This sample is a complementary support pack that illustrates the 'Web user' feature and the usage of a User-defined Program Execution Server (UPES).

Core Viewers

If you want to work with MQ Workflow directly ('out of the box'), you can use the core viewers which offer the full functionality of the MQ Workflow APIs. The files are called <MQWFDir>/smp/WebClient/DefaultViewer.java and <MQWFDir>/smp/WebClient/JSPViewer.java. You can also use the sample code for developing your own viewers.

InternetConnectionViewer

This viewer offers minimal worklist functionality, such as checkin, checkout, or refresh. This sample changes the look and feel of the worklist of the Web client to mimic the IBM FlowMark V2 Internet Connection. To do this, you can register a custom Viewer, or replace the JSP that is responsible for rendering the lists when using the JSPViewer. You can switch your browser to German to see localized texts. German is the only available translated language for the viewer. Also refer to the API documentation for InternetConnectionViewer.java.

To run this sample using a custom Viewer:

  1. Make sure that MQ 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>/cfgs/<cfgID>/WebClient/webpages/images directory.
  3. Edit the WebClient.properties file and set
     DefaultViewer=com.ibm.workflow.servlet.sample.InternetConnectionViewer
    You can find the source code for this viewer in the <MQWFDir>/smp/WebClient directory. You must restart the Web client to activate the changes you made.
    Note: You need not change the CLASSPATH because this sample viewer is already contained in the fmcohcli.jar file.
  4. Log on to MQ Workflow using the Web client to display the new layout.

To run this sample using a custom JSP:

  1. Make sure that MQ 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>/cfgs/<cfgID>/WebClient/webpages/images directory.
  3. Make a backup copy of the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/forms/ListViewer.jsp file, then copy <MQWFDir>/smp/WebClient/forms/InternetConnectionListViewer.jsp to <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/forms/ListViewer.jsp. Make sure that the new ListViewer.jsp has its modification time updated. Otherwise, the JSP might not be recompiled.
  4. Edit the WebClient.properties file and set
     DefaultViewer=com.ibm.workflow.servlet.client.JSPViewer
    You must restart the Web client to activate the changes you made.
  5. Log on to MQ Workflow using the Web client to display the new layout.
  6. To restore the original work list, 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, so that you can use more than one custom handler. It also shows how to read settings from the WebClient.properties file. Also refer to the API documentation for CommandHandlerAdapter.java.

To use this sample:

  1. Make sure that MQ Workflow and the Web client are running.
  2. Edit the WebClient.properties file and set
     CommandHandler=com.ibm.workflow.servlet.sample.CommandHandlerAdapter
  3. In the [CommandHandlerAdapter] section of the WebClient.properties file, register all command handlers that you want to use by adding lines of the form
     <CommandHandlerClassName>=<index>
    The indexes 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 registered handler are ignored.
  4. You must restart the Web client to activate the changes.
    Note: You need not change the CLASSPATH because this sample CommandHandler is already contained in the fmcohcli.jar file.

HTMLDocHandler

With this sample, you can access HTML documentation that is exported from MQ Workflow Buildtime from the template list of the Web client. See also the API documentation for HTMLDocHandler.java.

To prepare the HTML documentation for a process:

  1. Create a ProcessDocs subdirectory in <MQWFDir>/cfgs/<cfgID>/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 must copy the exported HTML files to that subdirectory on your Web server.
  2. Start the MQ Workflow Buildtime component.
  3. Select the 'Buildtime' - 'Export...' menu option.
  4. Select the 'Export single objects' radio button.
  5. Select the process for which you want to create HTML documentation from the tree view. Do not select multiple processes. Instead, repeat these 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 'OK'.
  9. In the 'Save As' dialog, enter the file name: <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/ProcessDocs/<ProcessName>.htm. Use the process name as file name, and 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 'Save'.

To run this sample:

  1. Make sure that MQ Workflow and the Web client are running.
  2. Copy the htmldoc.gif file from the <MQWFDir>/smp/WebClient/images/action directory to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/images/action directory.
  3. Edit the WebClient.properties file and set
     CommandHandler=com.ibm.workflow.servlet.sample.HTMLDocHandler

    Alternatively, you can use the CommandHandlerAdapter. You must restart the Web client to activate the changes.
    Note: You need not change the CLASSPATH because this sample CommandHandler is already contained in the fmcohcli.jar file.

  4. Go to the template list of the Web client. There must be an icon on the right of the 'properties' icon for all the processes for which you have created HTML documentation. The HTMLDocHandler does not show an icon for processes for which no HTML documentation is available in the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/ProcessDocs directory. 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. You can query the audit trail data from the process list where a table with all events is displayed, or from the worklist, on which activity statistics are displayed. Both lists use the Bean Scripting Framework to exploit JavaScript within the XSL style sheet. See also the API documentation for AuditTrailHandler.java.

  1. Make sure MQ Workflow and the Web client are running.
  2. Download Xalan-Java V2, which includes the XML parser, the XSLT processor and the Bean Scripting Framework from the Web at http://xml.apache.org/xalan-j. Then, add the xerces.jar file, the xalan.jar file, and the bsf.jar file to the CLASSPATH of your application server. As a rule, this is the location where you registered the fmcohcli.jar file. In WebSphere, for example, the location is the 'Command line arguments' field on the 'Application Server Properties' - 'General' page. If you are using Xalan-Java V2.2-D13 or later, you must also add the xml-apis.jar file to the CLASSPATH.
    Note: Certain application servers already include XML parsers. This can cause problems if you use incompatible versions on the CLASSPATH.
  3. Download the JavaScript plugin (also known as Rhino) for the Bean Scripting Framework from the Web at http://www.mozilla.org/rhino. (Apache's Xalan V2.0 requires Version 1.5 of Rhino). Then, add the js.jar file to the CLASSPATH of your application server.
  4. Copy the audittrail.gif file from the <MQWFDir>/smp/WebClient/images/action directory to the <MQWFDir>/cfgs/<cfgID>/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>/cfgs/<cfgID>/WebClient/webpages/xml/xsl directory.
  6. Edit the WebClient.properties file 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 the WebClient.properties file and make sure they are correctly set for your environment.
  8. Enable the StyleSheetPI and the StyleSheetWI lines to get formatted HTML pages instead of the XML output data. You must restart your application server to activate the changes you made.
  9. Go to the instance list of the Web client. There must be an icon on the right of the 'properties' icon for all the processes that have the audit trail enabled.

EmailHandler

This sample handler intercepts the transferItem command in the ListViewer.jsp file. With this sample, you can specify an e-mail address that determines where to send the notification of the item transfer. See also the API documentation for EmailHandler.java.

  1. Make sure MQ Workflow and the Web client are running.
  2. Download and install the JavaMail file and the Java Activation Framework file. Then, add the mail.jar file and the activation.jar file to the CLASSPATH of your application server. As a rule, this is the location where you registered the fmcohcli.jar file. For example, in WebSphere the location 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>/cfgs/<cfgID>/WebClient/webpages/forms directory. If your mail client natively supports HTML, you can also copy the <MQWFDir>/smp/WebClient/forms/EmailViewer_html.jsp file to <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/forms/EmailViewer.jsp. This also contains some additional documentation.
  4. Edit the WebClient.properties file 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 that are not supported by the DefaultViewer class.
  5. Check the Host and the Address settings in the [SMTP] section of the WebClient.properties file, and make sure that they are set correctly for your environment. You must restart your application server to activate the changes you made.
  6. Go to the worklist of the Web client and click on the 'transfer' icon of one of the items. This opens a new form where you can enter an e-mail address in addition to the user ID that determines where to transfer the item.

Credit Request

This sample contains HTML and JSP forms that you can use with the Credit Request sample that is delivered with MQ Workflow. It shows how to customize the look and feel of the forms that are displayed when processes and work items are started from the Web client. For further details, refer to the corresponding section in How to execute activities. This sample also shows how to use the 'Web user' feature of the Web client that allows you to start processes without logging on to MQ Workflow.

To run this sample using the Web client:

  1. Make sure that MQ Workflow and the Web client are running.
  2. Import the Credit Request process <MQWFDir>/scenario/credit/fmccred.fdl into the Runtime database and translate it. For details on how to use the Runtime import utility, refer to the MQ Workflow Getting Started with Buildtime book.
  3. Copy all files in the <MQWFDir>/scenario/credit/processes directory to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/processes directory.
  4. Copy all files in the <MQWFDir>/scenario/credit/programs to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/programs directory.
  5. Copy all files in the <MQWFDir>/scenario/credit/images to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/images directory.
  6. Copy the creditsample.css from the <MQWFDir>/scenario/credit directory to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages directory.
  7. Edit the WebClient.properties file and set
     DefaultViewer=com.ibm.workflow.servlet.client.JSPViewer
    You must restart the Web client to activate this change.
  8. Open (or refresh) the templates list in the Web client.
  9. Click on the 'Create and start Instance' button for the CreditRequest process. This launches the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/processes/CreditRequest.jsp.
    Note: The name of the JSP or HTML form to be launched is derived from the process template name. If you develop your own applications you should use JSPs instead of the proprietary HTML templates. The HTML files are only supported because of backward compatibility with application servers that do not yet support JSPs.
  10. Go to the worklist of the Web client and start the CollectCreditInformation work item. This launches the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/programs/NCollectCreditData.jsp.
    Note: The name of the JSP or HTML form to be launched is derived from the name of the program that is assigned to the activity.

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

  1. Make sure that MQ Workflow and the Web client are running.
  2. Import the Credit Request process <MQWFDir>/scenario/credit/fmccred.fdl into the Runtime database and translate it. For details on how to use the Runtime import utility, refer to the MQ Workflow Getting Started with Buildtime book.
  3. Copy all HTML and JSP files in the <MQWFDir>/scenario/credit/starter directory to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/starter directory.
  4. Choose the MQ Workflow user ID that you want to use for the 'Web user' feature. You can import the provided <MQWFDir>/scenario/credit/starter/starter.fdl file to create a user ID STARTER with the password password.
  5. Edit the WebClient.properties file and set
     DefaultViewer=com.ibm.workflow.servlet.client.JSPViewer
    You must restart the Web client to activate this change.
  6. Configure the user ID you have chosen in the WebClient.properties file by setting the StarterUserID and StarterPassword properties. You must restart the Web client to activate these changes. The StarterUserID cannot be used to log on to MQ Workflow with the Web client.
  7. Point your browser to http://localhost/MQWFClient-<cfgID>/starter/StartCreditRequest.jsp
    Note: If you use a root URI other than /MQWFClient, which is the default when the Web client is configured in the default configuration FMC, you must enter the new root URI in this file. For configurations other than FMC this is MQWFClient-<cfgID>.
  8. Enter the data needed to start the CreditRequest process and click the 'Apply for Credit' button. Because the 'Web user' feature only allows to start processes, you must log on to MQ Workflow 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: This Program Execution Agent (PEA) is not suited for activities that require user interaction, because it runs on the application server machine. If you expect a rather high workload for the Web user ID, use 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 the WebClient.properties file 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.
  3. Enable the PEA in WebClient.properties by adding the following line:
     StarterPEA=true
    You must restart the Web client to activate this change.
  4. Run the Credit Request sample as described in the previous section. The PEA is started automatically for the Web user ID. Note: This PEA is not actually used by the Credit Request sample, because 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 that are later used to authenticate with MQ Workflow without having to specify a userID and password for the BuiltinHandler.logon() command. See also the API documentation for BasicAuthenticationHandler.java.

To run this sample:
  1. Set up HTTP/1.1 Basic Authentication in your Web server for the Web client Web application . The setup of the HTTP/1.1 Basic Authentication depends on the Web Server you are using.
  2. Edit the WebClient.properties file and set
     CommandHandler=com.ibm.workflow.servlet.sample.BasicAuthenticationHandler
    Alternatively, you can use the CommandHandlerAdapter.
  3. Shut down the MQ Workflow Administration Server.
  4. Enable the Java authentication exit by invoking the following command:
     fmczchk -c inst:m,RTAuthenticationExitTypeServer,JAVA -y <cfgID>
    See also the MQ Workflow V3.3 Programming Guide, Chapter 7, "Using an authentication exit".
  5. Make sure that the CLASSPATH of the MQ Workflow Administration server contains the following .jar files:
     CLASSPATH=<MQWFDir>\bin\fmcoutil.jar;<MQWFDir>\bin\fmcohcli.jar
    The Java authentication exit for this sample (com.ibm.workflow.java.exit.Authentication) is already contained in the fmcohcli.jar file. Therefore, if you do not use this sample, you must not put this .jar file on the CLASSPATH of the MQ Workflow Administration server.
  6. Make sure that the PATH for the MQ Workflow Administration Server includes Java. On Windows installations, it is not sufficient to have the java.exe file in the <WinDir>\system32 directory because the MQ Workflow Java bridge must be able to find the JVM DLL.
  7. Restart the MQ Workflow Administration Server. On Windows, you can use the following batch file for all this:
     @setlocal
     @fmczchk -bc inst:m,RTAuthenticationExitTypeServer,JAVA -y <cfgID>
     @set path=<JDKDir>\bin;%path%
     set CLASSPATH=<MQWFDir>\bin\fmcoutil.jar;<MQWFDir>\bin\fmcohcli.jar
     start fmcamain -c -y <cfgID>
     @endlocal
  8. Point your browser to http://localhost/MQWFClient-<cfgID>/servlet/Main?command=logon. There are no additional parameters required for the logon command, like userID or password.

Application Data Integration

This sample shows 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 the MQ Workflow Buildtime component. If you want these icons to be displayed in the process monitor of the Web client, they must be converted to the JPG format and placed in the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/images/icons directory. On Unix platforms, make sure that the file names have lowercase characters only.

To run this sample:

  1. Make sure that MQ Workflow and the Web client are running.
  2. Import the Application Data Integration process, <MQWFDir>/smp/WebCredit/appdata.fdl into the Runtime database and translate it. For details on how to use the Runtime import utility, refer to the MQ Workflow Getting Started with Buildtime book.
  3. Copy the ACreateCustomer.jsp, ASaveCustomer.jsp, and AShowCustomer.jsp files from the <MQWFDir>/smp/WebClient/programs directory to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/programs directory.
  4. Copy the letter.jpg and the diskette.jpg files from the <MQWFDir>/smp/WebClient/images/icons directory to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/images/icons directory.
  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 name of the instance and click 'OK'.
  7. Go to the worklist and start the 'Create New Customer' work item. This invokes the 'ACreateCustomer' JSP. Refresh your worklist to see the new work item.
  8. Enter the customer data and click 'Create Customer'. This invokes 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 invokes the 'AShowCustomer' JSP, which uses the customer ID stored in MQ Workflow to search the file for the remaining customer data.
  10. For more details, check the source code of the JSP files.