Using the WebSphere MQ Workflow Web Client with WebSphere Studio

Using the WebSphere MQ Workflow Web Client with
WebSphere Studio
Mohan K. Jadhav
Software Engineer, IBM Software Group
IBM India, Bangalore
October 27, 2004
© Copyright International Business Machines Corporation 2004. All rights reserved.
This tutorial is for Java™ developers who work on IBM WebSphere MQ Workflow’s
Web client development using WebSphere Studio Application Developer 5.x (hereafter
called WebSphere Studio). It demonstrates how to:
•
•
•
Work with WebSphere MQ Workflow using Flow Definition Language (FDL).
Configure a Web project in WebSphere Studio for the WebSphere MQ Workflow
Web client.
Create JavaServer Pages (JSP) using the JSP plug-in for WebSphere MQ
Workflow. A sample scenario illustrates each of these steps.
Introduction......................................................................................................................... 2
Interpreting placeholder definitions................................................................................ 2
Sample scenario .................................................................................................................. 3
Building the workflow components.................................................................................... 4
Creating the FDL file ...................................................................................................... 4
Exporting the FDL to the Runtime of MQ Workflow .................................................... 4
Configuring WebSphere Studio for MQ Workflow Web Client ........................................ 4
Creating the Web client in WebSphere Studio ............................................................... 5
Adding the resources to the Web project........................................................................ 5
Editing the Web configuration file ................................................................................. 7
Editing the properties file................................................................................................ 8
Creating JSPs ...................................................................................................................... 9
Downloading the WebSphere Studio Plug-in for JSPs................................................... 9
Creating and modifying the JSPs.................................................................................... 9
Deploying Web pages to the server .............................................................................. 15
Running the application ................................................................................................ 16
Conclusion ........................................................................................................................ 18
Resources .......................................................................................................................... 19
About the author ............................................................................................................... 19
Trademarks ............................................................................................................... 19
Introduction
WebSphere MQ Workflow is a powerful business integration tool used for enterprise
business process modeling. WebSphere MQ Workflow Web client is a J2EE 1.2compliant Web application, consisting of a servlet, some JSPs, and HTML pages. With
the Web interfacing abilities of the WebSphere MQ Workflow Web client, your Web
applications can now:
•
•
Access MQ Workflow process template lists, process instance lists, worklists,
user settings, list settings, and object properties.
Start workflow processes from a Web page, and submit data into processes
without having to log on to MQ Workflow. This is convenient, for example,
when you have to start workflow processes from the Internet.
The tutorial contains the following sections:
•
•
•
•
Sample scenario explains the application we are using for illustration purposes.
Building the workflow components describes the creation of the build time model
for the sample application and how to export the model to the workflow's runtime.
Configuring WebSphere Studio for WebSphere MQ Workflow Web Client
discusses how to configure a Web project in WebSphere Studio for running the
Workflow's Web client.
Creating JSPs explains how to create the JSPs in WebSphere Studio for the
sample application.
Interpreting placeholder definitions
This tutorial uses the following field “placeholders”. You can interpret the values for
these placeholders in the context of your environment.
Place Holder
WF_INSTALL_FOLDER
WF_CONFIGURATION
WF_USER_ID
WF_PASSWORD
WF_SYS_GROUP
WF_SYS
WF_RT_DB
Description
Folder in which MQ Workflow is installed.
Configuration profile name for MQ Workflow.
Default value is FMC.
User ID of the System administrator for MQ
Workflow. Default value is ADMIN.
Password of the system administrator for MQ
Workflow. Default value is “password”.
System group configured for MQ Workflow. Default
value is “FMCGRP”.
System name configured for MQ Workflow. Default
value is “FMCSYS”.
Name of the runtime database configured for the MQ
Workflow.
WF_RT_DB_USER_ID
User ID for the runtime database configured for the
MQ Workflow.
WF_RT_DB_PASSWORD Password for the runtime database configured for the
MQ Workflow.
HOST
Machine name on which WebSphere Studio is
installed.
PORT
Port at which WebSphere Studio listens for the
requests.
WEB_PROJECT_NAME
Name of the Web project created in WebSphere
Studio for deployment of the Web client.
Sample scenario
The sample scenario is a basic user authentication application, as shown in Figure 1. The
user enters a name, ValidateUser,and depending on the value entered, the system
decides whether the user is authorized to continue with the application (ShowHome) or
not (ShowErrorPage). For simplicity, this tutorial does not include database
operations in the example.
Figure 1. Workflow process model
From a development perspective, this example is a Web-based workflow application in
which the Web content is served by the WebSphere MQ Workflow Web client’s JSPs.
Building the workflow components
We begin by working with the Flow Definition Language (FDL) file in the MQ
Workflow.
Creating the FDL file
Information about business processes, the infrastructure, and participating people (staff)
is made known to the execution server by populating the Runtime database with the
corresponding information. This is done by importing a flow definition language (FDL)
file using a tool that translates the FDL definitions into the entities of the Runtime
database. Normally, MQ Workflow Build time is used to generate FDL files.
To use the FDL file for the sample shown in Figure 1, do one of the following two
options:
Option 1: Refer to MQSeries Workflow for Windows NT for Beginners (Redbook) for
creating the build time model as shown in Figure 1.
Option 2: You can also download the FDL. This download contains the final FDL that
you can use in this tutorial provided on the summary page.
Exporting the FDL to the Runtime of MQ Workflow
After creating the build time model, the FDL file is exported to the Workflow’s runtime
context. The steps are:
1. Open a command window.
2. Go to the <WF_INSTALL_FOLDER>\BIN directory, where
WF_INSTALL_FOLDER is the folder where the MQ Workflow is installed.
3. Type the following command and press Enter.
> fmcibie –u<WF_USER_ID>
FDL FILE>”
-p<WF_PASSWORD>
-t
-o
-i “<PATH OF
Configuring WebSphere Studio for MQ Workflow Web
Client
You have created the FDL for the sample and exported it to the runtime of the MQ
Workflow.
The next step is to create the Web Project in WebSphere Studio and configure it with the
resources for MQ Workflow Web client.
Creating the Web client in WebSphere Studio
For steps on how to create a Web project in WebSphere Studio, refer to WebSphere
Studio Application Developer Version 5 Programming (Redbook).
The created Web Project looks like as follows:
Figure 2. Web Project
Adding the resources to the Web project
1. Right click on the Web Content folder of the Web Project and select Import
from the context menu. The “Import” wizard is displayed.
2. Select the File System in the list. Click Next.
3. In the File System screen, see Figure 3, browse for the following directory:
{WF_INSTALL_FOLDER}\skeleton\WebClient\webpages
4. Select the following folders in the left pane by checking the boxes next to
them:
a. forms
b. help
c. images
d. WEB-INF
Select all the files in the right pane by checking the boxes beside them.
5. Ensure that the Web Content folder is selected in the Select the destination
for the imported resources drop-down and select the Create Selected
folders only radio button. Click Finish.
Figure 3. File system
6. Right click on the WEB-INF folder and select Import from the context
menu. The “Import” wizard is displayed.
7. Select the File System in the list. Click Next.
8. In the “File System” screen, browse for the following directory:
{WF_INSTALL_FOLDER}\skeleton\WebClient
9. Expand the WebClient folder in the left pane. The contents of the WebClient
folder are displayed in the right pane.
10. Select the WebClient.properties file in the right pane.
11. Ensure that the Web Content/WEB-INF folder is selected in the Select the
destination for the imported resources drop-down and select the Create
Selected folders only radio button. Click Finish.
12. Now the Web Project looks Figure 4.
Figure 4. Web Project
Editing the Web configuration file
The following steps help in editing the Web configuration file for the Web project:
1. Expand the WEB-INF folder in the Web Content folder of the Web Project.
2. Double click on the web.xml file. The settings for the file are opened in the right
frame of WebSphere Studio.
3. Select the Source tab in the right frame. The XML source of the file is opened for
editing.
4. Find the @configurationFile@ string in the file and delete it.
5. Select the Servlets tab. Ensure that the Main servlet is added in the list of servlets
as shown in Figure 5.
6. Save the file.
Figure 5. Servlets and JSPs
Editing the properties file
1. Expand the WEB-INF folder in the Web Content folder of the Web Project.
2. Double click on the WebClient.properties file. The file opens for editing
in the right frame.
3. Find the strings and replace them appropriately as shown in the table below:
Find
@agentName@
@agentLocator@
@agentConfiguration
@
Replace with
AgentName=MQWFAGENT
AgentLocator=LOC_LOCATOR
AgentConfiguration={WF_CONFIGURATI
ON}
4. Give the following values for the parameters shown below after removing the
# symbol before the parameters:
Parameter
StarterUserID
StarterPassword
StarterSystemGroup
StarterSystem
Database
DB2User
DB2Password
Value (For the meanings of the
values, see Definitions)
{WF_USER_ID}
{WF_PASSWORD}
{WF_SYS_GROUP}
{WF_SYS}
{WF_RT_DB}
{WF_RT_DB_USER_ID}
{WF_RT_DB_PASSWORD}
5. Comment any other placeholders in the file that starts with @ and ends with
@.
6. Save the file.
Creating JSPs
You have now configured the Web project to work with the MQ Workflow’s Web client.
In this section, create the JSPs in WebSphere Studio for the sample using a JSP plug-in
for the MQ Workflow’s Web client.
Downloading the WebSphere Studio Plug-in for JSPs
1. Use the Web link provided in the References section to download the plug-in for
WebSphere Studio that helps to create the JSPs. Follow the instructions given in
the Web page for the download and use of the plug-in.
2. Extract the plug in folder from the downloaded ZIP file into
<WSAD_INSTALL_FOLDER>\WebSphere Studio\eclipse\plugins, where
WSAD_INSTALL_FOLDER is the folder where WebSphere Studio is installed.
Creating and modifying the JSPs
Now, you will create the JSPs for the workflow model that was built for the sample
application.
The workflow model consists primarily of two main parts, process and activities.
Referring to Figure 1 for the sample application, the blocks named “ValidateUser”,
“ShowHome” and “ShowErrorPage” are activities in the model, while the process
encompasses all the activities and it spans from the source to sink through all the
activities in Figure 1.
Create JSPs for both the process and activities of the model:
1. Open WebSphere Studio.
2. Right click on Web Content of the “Sample” project.
3. Select New -> Folder from the context menu.
4. Enter processes as the folder name in the Folder Name field. Click on Finish.
5. Repeat steps 2 through 4 to create the “programs” folder under the Sample\Web
Content folder.
6. Right click on project and select New -> Other… from the context menu. See
Figure 6 below.
Figure 6. Selecting a JSP
7. Select the JSP for MQWF Web Client in the right pane. Click Next.
8. In the “FDL and Project Selection” screen, browse to the path of the FDL file in the
Enter or Select a source FDL field. Select Sample Web project in the list of
projects. Click Next. The screen looks like Figure 7.
Figure 7. New JSP file
9. Select the ValidateUser activity and click Next.
10. Figure 8 shows the “JSP and Template Selection” screen.
Figure 8. JSP and template selection
11. Browse to the Web Content\programs folder of the Sample project. Check the
Force to create the JSP file option. Click Next.
12. Figure 8a shows the Form Properties screen. In the Output tab under the Container
Member section, select Name and check the Output this field option in the Field
Properties. Click Next.
Figure 8a. Form Properties
13. Click Finish.
14. Repeat the steps 6 through 12 for the other two activities, ShowHome and
ShowErrorPage. For both activities, repeat step 12 with the Input tab instead of the
Output tab.
15. Click Finish.
Now, create the JSP for the process:
1. Follow steps 6 through 8 above.
2. Uncheck Generate JSP for the activity option as shown in Figure 9.
Figure 9. Generate JSP for the activity
3. Repeat the steps 11 through 15 above. While executing the steps this time, select
Web Content\processes instead of Web Content\programs folder of the Sample
project in step 12 and step 13. Select Input tab instead of Output tab. Click
Finish.
You have created a JSP for the process and three JSPs each for an activity in the
model. Figure 10 shows the contents of the Web project.
Figure 10. Contents of the Web project
Deploying Web pages to the server
To start the Web client for the MQ Workflow:
1. Create and configure a server in WebSphere Studio for the Web Project.
2. Open the Server Perspective.
3. Select the Server and select Open from the context menu. The settings for the server
are displayed in the right frame.
4. Select the Paths tab.
5. In the Class Path section, click on the Add External JARs button and select the
following JAR files from the file system:
fmcojapi.jar
fmcohcli.jar
You can find the above JAR files in the {WF_INSTALL_FOLDER}\BIN directory.
6. Save the settings.
7. Double click on Logon.html in the Web Content folder of the Web Project.
8. Replace the @rootURI@ string with the Web Project name. Save the file.
9. Start the MQ Workflow runtime client.
10. Start the server in WebSphere Studio after publishing the Web Project in it.
11. Access the Web client through the following URL:
http://{HOST}:{PORT}/{WEB_PROJECT_NAME}/Logon.html
For the meanings of the placeholders in the above link, see Definitions.
Running the application
To run the sample application:
1. Access the URL, http://{HOST}:{PORT}/{WEB_PROJECT_NAME}/Logon.html
2. Login through a valid user ID and password to the Workflow’s Web client. By
default, the user ID and password combination is ADMIN/password. Because the
ADMIN user ID is also used for other administrative tasks for the Workflow, the
client is not allowed to use that ID. Create an user ID in the Workflow’s build
time. For this tutorial, you can use TESTUSER as the User ID and password as the
password because this user ID is part of the FDL file for the tutorial.
3. After a successful login, the screen shows all the available templates in the
Workflow’s run time as shown in Figure 11.
Figure 11. Available templates
You can also access the above page by selecting the My Template option from the
drop-down.
Note: If you cannot see the above page listing all the templates, create the new
template and the work list to proceed. See MQSeries Workflow for Windows NT
for Beginners for more information on creating your template and work list.
4. After logging into the Workflow system, create the instance for the process. Start
the process instance by clicking on the button
for the “Authenticate User”
template. Figure 12 shows the template.
Figure 12. Authenticate user template
5. Since you have specified the “Name” output field during the creation of the JSP
for the process, you can see the text field for “Name” in the screen. You can
remove this option while creating the JSP itself. Now, click on Apply for
Instance button on the screen.
6. In the next screen, select My Worklist from the drop-down as shown in Figure
13.
Figure 13. Drop-down list
7. This is the activity pending for you in your work list. You can start this activity by
clicking the
button and Figure 14 is displayed.
Figure 14. Activity pending list
8. Enter the valid user name. Because you defined the transit condition for the
“ValidateUser” activity as User Name == “Mr Valid”, the home page is
displayed when you enter “Mr Valid” in the name field in the above screen. Enter
Mr Valid for the name and click on the Complete work item button. Figure 15
shows the next work item.
Figure 15. Next work item
9. Because you entered a valid user name, the “ShowHome” activity is shown. Start
the activity and the screen looks similar to Figure 16.
Figure 16. Valid user name
10. Clicking on Complete work item button in this screen ends the process.
11. Repeat the steps 8 through 10 by entering other invalid user names. The activity
for “ShowErrorPage” is shown if the name is not “Mr Valid”.
You have now thus successfully completed this tutorial.
In summary, you have:
(1)
(2)
(3)
Built the Workflow components.
(a) Created the FDL file for the Sample Scenario.
(b) Exported the FDL file to the runtime of MQ Workflow.
Configured WebSphere Studio for MQ Workflow Web Client.
(a) Created the Web Project in WebSphere Studio.
(b) Added the Workflow-related resources to the Web Project.
(c) Edited the Web configuration file for MQ Workflow.
Created JSPs for the MQ Workflow Web client.
Conclusion
This tutorial showed you how to work with JSPs in the MQ Workflow’s Web client and
their subsequent deployment in WebSphere Studio. You can modify the created JSPs for
the Workflow through the plug-in so that they can communicate to the database through
any middleware layers.
Resources
•
•
•
•
•
•
To download the JSP Rapid Deployment tool, see
www-.ibm.com/software/integration/support/supportpacs/individual/wa83.html
For working with the MQ Workflow’s build time, see MQSeries Workflow for
Windows NT for Beginners, SG24-5848-00.
For managing resources in WebSphere Studio, see WebSphere Studio Application
Developer Version 5 Programming Guide, SG24-6957-00.
For more information on the MQ Workflow Web Client, see the documentation at
{WF_INSTALL_FOLDER}\DOC\WebClient\index.html.
For access to WebSphere Studio how-to articles, downloads, tutorials, education
and product information, see the WebSphere Studio zone at http://www106.ibm.com/developerworks/websphere/zones/studio/.
For access to MQ Workflow information, see the WebSphere Business
Integration zone at http://www106.ibm.com/developerworks/websphere/zones/businessintegration/.
About the author
Mohan K Jadhav is a Staff Software Engineer in IBM India, Software Group, Bangalore.
He is currently working on J2EE technologies developing web-based applications using
the web application frameworks. You can reach Mohan at
mailto:[email protected].
Trademarks
• DB2, IBM, and WebSphere are trademarks or registered trademarks of IBM
Corporation in the United States, other countries, or both.
• Windows and Windows NT are registered trademarks of Microsoft Corporation in the
United States, other countries, or both.
• Java and all Java-based trademarks and logos are trademarks or registered trademarks
of Sun Microsystems, Inc. in the United States, other countries, or both.
• Other company, product, and service names may be trademarks or service marks of
others.
IBM copyright and trademark information:
http://www.ibm.com/legal/copytrade.phtml