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.2-compliant 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 Description WF_INSTALL_FOLDER Folder in which MQ Workflow is installed. WF_CONFIGURATION Configuration profile name for MQ Workflow.

Default value is FMC. WF_USER_ID User ID of the System administrator for MQ

Workflow. Default value is ADMIN. WF_PASSWORD Password of the system administrator for MQ

Workflow. Default value is “password”. WF_SYS_GROUP System group configured for MQ Workflow. Default

value is “FMCGRP”. WF_SYS System name configured for MQ Workflow. Default

value is “FMCSYS”. WF_RT_DB 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> -p<WF_PASSWORD> -t -o -i “<PATH OF FDL FILE>”

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 Replace with @agentName@ AgentName=MQWFAGENT @agentLocator@ AgentLocator=LOC_LOCATOR @agentConfiguration@

AgentConfiguration={WF_CONFIGURATION}

4. Give the following values for the parameters shown below after removing the # symbol before the parameters:

Parameter Value (For the meanings of the

values, see Definitions) StarterUserID {WF_USER_ID} StarterPassword {WF_PASSWORD} StarterSystemGroup {WF_SYS_GROUP} StarterSystem {WF_SYS} Database {WF_RT_DB} DB2User {WF_RT_DB_USER_ID} DB2Password {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) Built the Workflow components.

(a) Created the FDL file for the Sample Scenario. (b) Exported the FDL file to the runtime of MQ Workflow.

(2) 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.

(3) 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://www-106.ibm.com/developerworks/websphere/zones/studio/.

• For access to MQ Workflow information, see the WebSphere Business Integration zone at http://www-106.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:mohan.jadhav@in.ibm.com.

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