IBM MQSeries SupportPac WA82

Web Credit Request Example for IBM MQSeries Workflow 3.3.x
Version 1 Release 4

This example demonstrates how a credit request can be processed by a bank using MQSeries Workflow's web and MQSeries interfaces.

IBM MQSeries Logo

Introduction

This example illustrates how to use MQSeries Workflow and the MQSeries Workflow Web Client. It uses a DB2 database to permanently store customer and credit information. This information is displayed and updated while working on the credit request.

All database updates are performed using a user-defined Program Execution Server, whereas Java Server pages are used to retrieve the data from the database, based on key information in MQSeries Workflow.

Prerequisites


What's new

Version 1 Release 0 (07/02/2000)

Version 1 Release 1 (10/21/2000)

Version 1 Release 2 (05/15/2001)

Version 1 Release 3 (10/15/2001)

Version 1 Release 4 (05/14/2002)

Conventions used in this document

Subsequently '<MQWFDir>' should be replaced with the actual MQSeries Workflow root directory (e.g. 'D:\fmcwinnt') and '<CFGID>' with the configuration ID (e.g. 'WEB') under which the WebClient has been configured. '<WSDIR>' should be replace with the WebSphere Application Server's root directory (e.g. 'D:\WebSphere\AppServer').

Migration from a previous release

If you have an older version of the SupportPac installed, replace the contents of  the <MQWFDir>\scenario\WebCredit directory with the new files. The existing customer database and the MQSeries setup can be left untouched (don't create the database, queue or channels if migrating).

Then follow the installation instructions below to copy the JSPs to the right location.

For the Java UPES, the default queue name has been changed from 'WEBCREDIT' to 'WebCreditInput' (mixed case) and the default queue manager has been changed to 'FMCQM'. If you want to import the WebCredit-UPES FDL again (not necessary since nothing has changed in the UPES definitions from Version 1.2 of the SupportPac), you will need to rename the queue. You should however import the new WebCredit FDL.

Also make sure to install the updated prerequisites (like the latest MQSeries Java API SupportPac) - see the about requirements list for details.

Installation

In the installation instructions it is assumed that you use a Microsoft Windows NT/2000 Installation with default settings for database and queue manager. If you don't have a default installation, you must modify the UPES FDL (<MQWFDir>\scenario\WebCredit\WebCredit-UPES.fdl) to direct the user-defined Program Execution Server to the queue manager and queue you selected and update the CustomerUPES.properties file to reflect your environment.

Make sure your Web Server (or the user ID that the Web Server uses) has connect authorization to DB2 - otherwise the JSPs cannot read data from DB2 (this includes adding the file 'db2java.zip' to the Web Server's CLASSPATH so that the Web Server has access to the JDBC classes).

Create the customer database

  1. Open the DB2 Command Center.
  2. Copy the contents of the file <MQWFDir>\scenario\WebCredit\CreateDB.sql into the command center
  3. Press Ctrl+Enter in the command center. This executes all the commands in the SQL file and creates the database as well as the two tables in the database (if you are getting errors using an older Service Pack for DB2 V6 you'll have to add a semicolon after each line).
  4. Close the DB2 Command Center.

Installation of web pages for WebSphere 3.5.x or Jakarta Tomcat

This section explains the installation of the web pages WebSphere 3.5.x or Jakarta Tomcat. If you are installing the Web Client on WebSphere 4.x please follow the instructions below.

From the scenario\WebCredit directory, copy the contents of the starter directory to the configured Web Client's webpages\starter directory and the contents of the program's directory to the configured Web Client's webpages\programs directory.

On Windows NT/2000, you can use the following commands to copy the files into the correct directories:

xcopy <MQWFDir>\scenario\WebCredit\programs\*.* <MQWFDir>\cfgs\<CFGID>\WebClient\webpages\programs\ /s
xcopy <MQWFDir>\scenario\WebCredit\starter\*.* <MQWFDir>\cfgs\<CFGID>\WebClient\webpages\starter\ /s

Installation of web pages for WebSphere V4

This section explains the installation of the web pages for WebSphere V4.x. If you are installing the Web Client on another application server please follow the instructions above.

WebSphere V4 is configured by deploying an Enterprise Archive (.EAR File) which holds a Web Application Archive File (.WAR File) that has been created by the MQSeries Workflow configuration utility (fmczutil).

During deployment of the enterprise archive all the contents of the .EAR and .WAR files are being unzipped into WebSphere's installedApps directory into a directory '<WSDIR>\installedApps\MQWFWebClient_<CFGID>.ear\fmcohcli.war'. This directory is equivalent to the directory <MQWFDir>\cfgs\<CFGID>\WebClient\webpages for all other application servers.

From the scenario\WebCredit directory, copy the contents of the starter directory to the configured Web Application Server's fmcohcli.war\programs directory and the contents of the program's directory to the configured Web Application Server's fmcohcli.war\programs directory.

On Windows NT/2000, you can use the following commands to copy the files into the correct directories:

xcopy <MQWFDir>\scenario\WebCredit\programs\*.* <WSDir>\installedApps\MQWFWebClient_<CFGID>.ear\fmcohcli.war\programs\ /s
xcopy <MQWFDir>\scenario\WebCredit\starter\*.* <WSDir>\installedApps\MQWFWebClient_<CFGID>.ear\fmcohcli.war\starter\ /s

Modify the external process start pages

If using a workflow configuration ID different from 'FMC' for the Web Client, the pages that start the process have to be modified to reflect the configuration ID.
The WebClient in MQSeries Workflow 3.3 is usually configured to include the workflow configuration ID in its URL (e.g. '/MQWFClient-WEB'). This means that all occurrences of '/MQWFClient-WEB/' have to be replaced to '/MQWFClient-<CFGID>/' where '<CFGID>' is the ID under which the WebClient has been configured.

The following files in the starter directory have to be adapted (search for 'MQWFClient-WEB'):

Setup for the Java-based UPES

If you want to use the Java-based UPES you'll have to follow the following steps. If you want to use the MQSeries Integrator V2 message flow you'll have to follow the steps in the message flow installation section.

In the following steps <FMCQM> is used for the name of Workflow's queue manager. Please substitute your actual name whenever you see this placeholder.

Create the queue for the user-defined PES

  1. Open the MQSeries Explorer.
  2. Make sure your queue manager is running (default: <FMCQM>).
  3. Select: 'Console Root\IBM MQSeries\Queue Managers\<FMCQM>\Queues'.
  4. In the tree on the left, right-click 'Queues' and select 'New/Local Queue'.
  5. For Queue Name enter 'WebCreditInput' (exactly as shown, this is case sensitive) and click OK.
  6. In the dialog box that appears click 'Share in Cluster'.
  7. In the dialog box that appears select 'FMCGRP' in the Cluster combo box and click OK.
  8. Optionally set-up triggering for the UPES (starts the UPES automatically when a new message arrives). See Triggering.
  9. Close the MQSeries Explorer.

Update the batch files for the CustomerUPES

Now follow this link to import the FDL.

Setup for the MQSeries Integrator V2 message flow

Setting up MQSeries

For MQSeries Workflow to be able to talk to MQSeries Integrator it is necessary to setup connectivity between the two MQSeries queue managers. You'll need to create Channels that connect MQSeries Workflow's queue manager with Integrator's queue manager. This SupportPac contains three script files for MQSeries to create the required resources. The file extension is: mqs and they are located in <MQWFDir>\scenario\WebCredit\MessageFlow. Before you run them, check the contents and change them, if necessary for your environment. For details on how to create channels and transmission queues, refer to the MQSeries System Administration. See the chapter on Remote Administration.

Alternatively, you can create all the definitions manually. Follow this link to see instructions on how to do this. If for whatever reason you don't get messages into the WebCreditInput queue on the MQSI Queue Manager, try to delete the definitions that were created automatically and recreate them manually.

Setting up MQSeries Integrator

  1. Make sure that your Configuration Manager, Broker and (if applicable) User Manager are running.
  2. Open the MQSeries Integrator Control Center.
  3. Select File/Import
  4. Enter the filename for the message flows (<MQWFDir>\scenario\WebCredit\MessageFlow\WebCreditUPES.xml
  5. Press the 'Import' button
  6. Make sure that the queue manager and queue names in the nodes 'WebCreditInput' and 'Reply To MQWF' match your environment (Right-click and select 'Properties').
  7. Check-in the 3 message flows (e.g. Right-click 'WebCredit UPES' in the left tree and select 'Check In')
  8. Switch to the 'Assignments' tab.
  9. Check out both the broker and the default execution group.
  10. From the middle tree, drag the 'WebCredit UPES' messageflow onto the default execution group in the right panel.
  11. Check in both the broker and the default execution group.
  12. Select 'File/Deploy/Delta Configuration (all types)'.
  13. Switch to the Log tab and make sure that the operation completed successfully (you'll need to press the refresh button a couple of times to see the actual results of the operation).
  14. Make sure the CUSTOMER database is registered in ODBC so that MQSeries Integrator can access it.

Import the process model into MQSeries Workflow

The Process definitions have been split up into two FDLs - one holds the UPES definition (WebCredit_UPES.fdl), the other holds the rest of the definitions (WebCredit.fdl). It is mandatory that the UPES FDL is imported before the general FDL - otherwise import will generate errors because it will not find the UPES definition in the workflow database. If you are migrating from a previous version of the WebCredit example you can omit importing the UPES definition since it hasn't changed. You should however import the process definitions.

The only difference between using the Java UPES and the MQSeries Integrator message flow is that the queue manager definition for the UPES definition is different. If you are using the Java UPES and you have installed MQSeries Workflow using the default queue manager name (FMCQM) and you created a a local queue 'WebCreditInput' no changes of this FDL are necessary.
If you are using the MQSeries Integrator message flow you will have to modify the WebCredit_UPES.fdl and change the queue manager name to your MQSeries Integrator queue manager name. Also make sure that the queue definition matches the name of the queue that you created.

Now import the FDL files from the scenario directory into MQSeries Workflow. You can use the following commands to import the FDL files:

fmcibie -uADMIN -ppassword -o -i <MQWFDir>\scenario\WebCredit\WebCredit_UPES.fdl

fmcibie -uADMIN -ppassword -o -t -i <MQWFDir>\scenario\WebCredit\WebCredit.fdl
Make sure that you have already imported the FDL file that contains the 'STARTER' user ID (<MQWFDir>\scenario\credit\starter\starter.fdl), which is contained in the MQSeries Workflow Credit Scenario.
Finally verify that you have configured the Web Client (<MQWFDir>\cfgs\<CFGID>\WebClient\WebClient.properties) to allow anonymous process starts, using this 'STARTER' user ID.

That's it. You can go on to running the scenario.

Running the scenario

Start the user-defined PES

This step is only necessary if you use the Java-based UPES. If you running MQSeries Integrator, you can skip this step and continue.

Locate the file CustomerUPES.bat in the the directory <MQWFDir>\scenario\WebCredit\CustomerUPES.

Start the UPES using the CustomerUPES.bat batch file. To demonstrate how MQSeries holds on to a message it's possible to defer starting the UPES until a message has arrived in the queue (e.g. after the first activity in the process has been executed).

If you want to shutdown the Customer UPES you can use the shutdown script that's provided in <MQWFDir>\scenario\WebCredit. Since this version of the UPES is implemented with Synchpoint control it is also possible to just kill the UPES (it may take a short while for MQSeries to clean up its resources however).

Use the Web browser to start a new process

Note: Note that the very first access to each Web page may be slow since the Web Server needs to compile the Java Server pages. Any subsequent access will be much faster.

Use the Web browser to execute the process

There are two user IDs, WEBBANK_CLERK and WEBBANK_LOANMANAGER, that are used in the business process. All steps are done by the WEBBANK_CLERK, except for an optional approval step. This has to be done by the WEBBANK_LOANMANAGER (only if the credit risk is not considered 'Low'). Log on to the MQSeries Workflow Web Client using the user ID WEBBANK_CLERK and start the activities assigned to this user ID.

Appendix

A remark about the code

Note that this is demonstration code. For an implementation of production quality, you would have to implement certain parts in a different way.

Currently all JSPs open or close their own database connection for each request. While this works fine for the purposes of this demonstration, a robust implementation would use database connection pools - for example, DataSources within the IBM WebSphere Application Server.