IBM WebSphere MQ SupportPac WA82

Web Credit Request Example for IBM WebSphere MQWorkflow 3.4.x
Version 1 Release 5

This example demonstrates how a credit request can be processed by a bank using WebSphere MQWorkflow's web and WebSphere MQ interfaces.

Introduction

This example illustrates how to use WebSphere MQWorkflow and the WebSphere MQWorkflow 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 WebSphere MQWorkflow.

Prerequisites

WebSphere MQWorkflow 3.4 or higher with a configured Web Client
Java 2 Standard Edition 1.3
WebSphere MQ Java Support must be installed
Xerces-J XML Parser Version 2.x (available from http://xml.apache.org)
WebSphere MQIntegrator Broker 2.1 or higher (if the message flow is used to implement the UPES)
Internet Explorer 6.0 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.

Version 1 Release 5 (05/21/2003)

Updated the SupportPac for rebranding of base products
Fixed a number of bugs in the various web pages for WebSphere Application Server 5.0
Added a batch file to create the customer database
Added a WebSphere Business Integration Workbench Model for the business process as well as support for the WebSphere Business Integration Monitor

Conventions used in this document

Subsequently '<MQWFDir>' should be replaced with the actual WebSphere MQWorkflow root directory (e.g. 'C:\MQWF') and '<CFGID>' with the configuration ID (e.g. 'FMC') under which the WebClient has been configured. '<WASDIR>' should be replace with the WebSphere Application Server's root directory (e.g. 'C:\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 WebSphere MQ 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'. You should import the new WebCredit FDL.

Installation

In the installation instructions it is assumed that you use a Microsoft Windows NT/2000/XP Installation with default settings for database and queue manager. If you don't have a default installation, you must modify the FDL (<MQWFDir>\scenario\WebCredit\Model\WebCredit\WebCredit.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

If your DB2 is not installed in C:\IBM\SQLLIB you need to modify the batch file WebCredit\DB2\setupDB2.bat.
Then run the batch file. It will create the database. Make sure to check the file WebCredit\DB2\setupDB.log for errors (the first time it is OK that the database could not be dropped)

Installation of web pages for WebSphere V5

This section explains the installation of the web pages for WebSphere V5.x.

WebSphere V5 is configured by deploying an Enterprise Archive (.EAR File) which holds a Web Application Archive File (.WAR File) that has been created by the WebSphere MQWorkflow 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 '<WASDIR>\installedApps\<hostname&rt;MQWFWebClient_<CFGID>.ear\fmcohcli.war'.

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.

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 WebSphere MQWorkflow is usually configured to include the workflow configuration ID in its URL (e.g. '/MQWFClient-WEB') except when the WebClient has been created for the default configuration. In this case the URL is just '/MQWFClient'. This means that all occurrences of '/MQWFClient/' have to be replaced to '/MQWFClient-<CFGID>/' where '<CFGID>' is the ID under which the WebClient has been configured if the WebClient is configured under anything but the default configuration ID.

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

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 WebSphere MQIntegrator Broker 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 WebSphere MQ Explorer.
Make sure your queue manager is running (default: <FMCQM>).
Select: 'Console Root\WebSphere MQ\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.
Close the WebSphere MQ 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 WebSphere MQ installation
JAMES_HOME: the top-level directory of the Java Apache Mail Enterprise Server (this is optional because it is not needed by the Customer UPES)

WebSphere Business Integration Modeler & Monitor Support

A WebSphere Business Integration Modeler process model has been supplied. It can be found in the directory <MQWFDir>\scenario\WebCredit\Model\WebCredit. The WebSphere Business Integration Workbench (version 4.2.3 or higher) can be used to examine/simulate the process model. The same directory holds a file (WebCredit_4_Monitor.xml) which can be used into the WebSphere Business Integration Monitor to monitor the process.

Now follow this link to import the FDL.

Setup for the WebSphere MQIntegrator Broker V2 message flow

Setting up WebSphere MQ

For WebSphere MQWorkflow to be able to talk to WebSphere MQIntegrator Broker it is necessary to setup connectivity between the two WebSphere MQ queue managers. You'll need to create Channels that connect WebSphere MQWorkflow's queue manager with WebSphere MQIntegrator's queue manager. This SupportPac contains three script files for WebSphere MQ 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 WebSphere MQ 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 WebSphere MQ.)
After having adapted this file to your environment, create the channel using the following WebSphere 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 WebSphere MQWorkflow configuration on the Queue Manager page. (5010 is the default port used by WebSphere MQWorkflow.)
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 WebSphere MQIntegrator Broker, where WebSphere MQWorkflow puts the XML message. This queue must be created in the WebSphere MQIntegrator Broker 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 WebSphere MQIntegrator Broker Queue Manager, try to delete the definitions that were created automatically and recreate them manually.

Setting up WebSphere MQIntegrator Broker

Make sure that your Configuration Manager, Broker and (if applicable) User Manager are running.
Open the WebSphere MQIntegrator Broker 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 WebSphere MQIntegrator can access it.

Import the process model into WebSphere MQWorkflow

The only difference between using the Java UPES and the WebSphere MQIntegrator Broker 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 WebSphere MQWorkflow using the default queue manager name (FMCQM) and you created a a local queue 'WebCreditInput' no changes of the FDL are necessary.
If you are using the WebSphere MQIntegrator Broker message flow you will have to modify the WebCredit.fdl and change the queue manager name to your WebSphere MQIntegrator Broker 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 WebSphere MQWorkflow. You can use the following commands to import the FDL files:

fmcibie -uADMIN -ppassword -o -i -t <MQWFDir>\scenario\WebCredit\Model\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 WebSphere MQWorkflow 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 WebSphere MQIntegrator Broker, 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 WebSphere MQ 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 WebSphere MQ to clean up its resources however).

Use the Web browser to start a new process

Point your Web browser to http://localhost/MQWFClient/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 WebSphere MQWorkflow 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.