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.

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

MQSeries Workflow 3.3 Service Pack 1 or higher
MQSeries Workflow Web Client
JSP Support has to be enabled
Java 2 Standard Edition 1.3
MQSeries Java Support must be installed (SupportPac MA88, Version from April 5th 2002 or later)
Xerces-J XML Parser Version 2.x (available from http://xml.apache.org)
MQSeries Integrator 2.1 or higher (if the message flow is used to implement the UPES)
Internet Explorer 5.5 or higher (Netscape is not supported)

What's new

Version 1 Release 0 (07/02/2000)

Initial public release

Version 1 Release 1 (10/21/2000)

Renamed SupportPac from MAW6 to WA82 and updated all files.
Changed process model to include only Customer_ID and Loan_ID from second step on (removed Credit Amount and Credit Reason from Data Structure).
Changed the ReviewCustomerData JSP to only display the Customer_ID - for a new customer (i.e. no Customer_ID assigned) the JSP displays 'Not yet assigned.'
Changed the ReviewCustomerData JSP to only display Credit Amount and Credit Reason. These fields can no longer be changed.
Changed all JSPs (except ReviewCustomerData) to read Credit Amount and Credit Reason from the database based on the Loan_ID.
Added Trigger support.
Added a common script to setup the environment (env.bat) for the UPES.

Version 1 Release 2 (05/15/2001)

Rewrote the UPES code to create a generic base class that can be used to implement other UPESs.
Added MQSeries Syncpoint support to the UPES (shutdown script is no longer necessary - it's still provided however).
Added an MQSeries Integrator V2.02 message flow to - optionally - replace the UPES.
Added documentation and scripts to hook up MQSeries Workflow and Integrator queue managers.
Fixed bug when null values in the database would be displayed as 'null' instead of empty fields in the JSPs.
Changed the image used in the web pages.
Added support to run the UPES on UNIX.

Version 1 Release 3 (10/15/2001)

Raised prerequisite level to MQSeries Workflow 3.3 ServicePack 1.
Added installation instructions for WebSphere V4.
MQSeries Workflow 3.3 Service Pack 2 or higher is required for WebSphere V4 support.
Fixed bug in DisplayCreditHistory.jsp. Used hardcoded name of root URL instead of WebClient convenience function - JSP didn't work on root URLs other then '/MQWFClient'.
Fixed queue manager configuration scripts - the old scripts didn't add triggering for the channels.
Fixed database creation script - the old script had errors on newer DB2 V6 Service Packs. Consolidated DB2 V6 and V7 scripts into one script.
Split the FDL into one generic FDL and one FDLs for the UPES definition.
Fixed bugs in FDL that User IDs didn't have correct authorizations.

Version 1 Release 4 (05/14/2002)

Fixed eSQL bugs that appeared due to more stringent syntax/sematic checking by WebSphere MQIntegrator 2.1
Fixed bug in WebCredit_DisplayCreditHistory.jsp - this page didn't work because the Java Bean was not available in the context for this page.
Clarified the queue name in Java UPES installation instructions.
Changed default queue manager in the Java UPES' properties file to point to FMCQM instead of MQSIQM.
Fixed bug in queue manager configuration scripts - yet again.
Fixed environment scripts to reflect new prerequisite jar files in the MQSeries Java APIs (SupportPac MA88).
Updated to user Xerces-J 2.x instead of Xerces-J 1.x.

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

Open the DB2 Command Center.
Copy the contents of the file <MQWFDir>\scenario\WebCredit\CreateDB.sql into the command center
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).
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'):

WebCreditRequest.html
WebCreditRequest_NewCustomer.html
WebCreditRequest_IDDoesNotExist.html
WebCreditRequest_ExistingCustomer.jsp

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

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

Update the batch files for the CustomerUPES

Find the batch files in <MQWFDir>\scenario\WebCredit\CustomerUPES
Update the file env.bat to reflect your environment
JAVA_HOME: the top-level directory of the JDK
XERCES_HOME: the directory where xerces.jar (XML Parser for Java) is stored
DB2_HOME: the top-level directory of the DB2 installation
MQ_HOME: the top-level directory of the MQSeries installation
JAMES_HOME: the top-level directory of the Java Apache Mail Enterprise Server (this is optional)

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.

fmcqmcl.mqs
This file is used to define the required queue for 'send' and 'receive' from the queue manager FMCQM to MQSIQM. If you use other queue manager names than the proposed ones, change the queue manager name in this file as well. In addition, you must adapt the host name. Change the localhost to your host name and replace 1414 with the port as defined in the MQSI configuration. (1414 is the default port used by MQSeries.)
After having adapted this file to your environment, create the channel using the following MQ command from a command prompt:
```
runmqsc FMCQM < fmcqmcl.mqs
```
mqsiqmcl.mqs
This file is used to define the required queue for 'send' and 'receive' from the queue manager MQSIQM to FMCQM. If you use other queue manager names than the proposed ones, change the queue manager name in this file as well. In addition, you must adapt the host name. Change the localhost to your host name and replace 5010 with the port defined in the MQSeries Workflow configuration on the Queue Manager page. (5010 is the default port used by MQSeries Workflow.)
After having adapted this file to your environment, create the channel using the following MQ command from a command prompt:
```
runmqsc MQSIQM < mqsiqmcl.mqs
```
mqsiqmq.mqs
An additional queue is needed as input for MQSI, where MQSeries Workflow puts the XML message. This queue must be created in the MQSI queue manager, using this command:
```
runmqsc MQSIQM < mqsiqmq.mqs
```

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

Make sure that your Configuration Manager, Broker and (if applicable) User Manager are running.
Open the MQSeries Integrator Control Center.
Select File/Import
Enter the filename for the message flows (<MQWFDir>\scenario\WebCredit\MessageFlow\WebCreditUPES.xml
Press the 'Import' button
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').
Check-in the 3 message flows (e.g. Right-click 'WebCredit UPES' in the left tree and select 'Check In')
Switch to the 'Assignments' tab.
Check out both the broker and the default execution group.
From the middle tree, drag the 'WebCredit UPES' messageflow onto the default execution group in the right panel.
Check in both the broker and the default execution group.
Select 'File/Deploy/Delta Configuration (all types)'.
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).
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

Point your Web browser to http://localhost/MQWFClient-<CFGID>/starter/WebCreditRequest.html.
If you have previously entered data, you can enter a customer ID and click on the Logon button. Note that the page already contains data from the DB2 database, based on the customer ID that you entered.
If you have not previously entered data, click the 'New Customer' button and fill in the necessary information (marked with an asterisk '*').
After having entered or updated all necessary data, click the 'Apply for Credit' button.

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.