Installing and setting up the IBM WebSphere MQ Workflow Web Client

The following sections provide installation hints for unsupported environments. They can help you getting started, but they are not guaranteed to work. Note that most of these setups have only been tested on Windows NT or Windows 2000. Additional or different settings may be necessary for other platforms.

Note: In the following <MQWFDir> denotes the MQSeries Workflow installation directory, for example, d:\fmcwin2k. MQWFClient-<cfgID> denotes the root URI of the Web Client's Web application and includes the MQSeries Workflow configuration ID. If the configuration ID is the default 'FMC', then the root URI is /MQWFClient. If the configuration ID is different from the default, the configuration utility will add it as a suffix to the root URI, for example, /MQWFClient-WEBC. Newer versions of the configuration utility allow you to specify a different root URI.

If you want to create a .war file (Web archive) or a .ear file (Enterprise Application archive) to deploy in your environment, you now can do so using the configuration utility. Simply select j (Other (Servlet 2.2 / J2EE 1.2)) when prompted for the application server. This will create fmcohcli.war and fmcohcli.ear files in the <MQWFDir>/cfgs/<cfgID>/WebClient directory. The only external reference that still must be resolved is to point the application server's CLASSPATH to <MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar. Note that this file cannot be packaged in the WEB-INF/lib directory like fmochcli.jar as it loads native libraries and therefore is not reloadable.

Note: If you create a .war file by selecting either the f (WebSphere 4.0 (EAR)) option or the j (Other (Servlet 2.2 / J2EE 1.2)) option when being prompted for the application server, then the ConfigurationFile servlet initialization parameter must no longer be set. In these cases, the configuration utility copies the WebClient.properties and fmcohcli.jar files to the WEB-INF directory. This is their default location where they will be found without having to specify their path using the ConfigurationFile servlet initialization parameter or the CLASSPATH, respectively. The old behaviour is still supported for Servlet V2.1 environments.

Setup for IBM VisualAge for Java V3.5 WebSphere Test Environment

  1. Create a Web Client configuration and either specify w (WebSphere 3.x) or o (Other) when being prompted for the application server by fmczutil.
  2. Make sure you have VisualAge for Java installed and you have added the 'WebSphere Test Environment' Feature. If the 'WebSphere Test Environment' is not installed:
    1. Open the VA for Java Workbench
    2. Press 'F2' or select 'File' - 'Quick Start'
    3. Select 'Features' and 'Add Feature' and press 'Ok'.
    4. Select 'IBM WebSphere Test Environment' and press 'OK'.
    In the following, <WTEDir> denotes the WebSphere Test Environment directory, <VAJDir>/ide/project_resources/IBM WebSphere Test Environment.
  3. Edit the <WTEDir>/properties/default.servlet_engine file and add the following lines to the <websphere-servlet-host name="default_host"> section:
     <websphere-webgroup name="MQWFClient">
      <description>MQSeries Workflow Web Client</description>
      <document-root><MQWFDir>/cfgs/<cfgID>/WebClient/webpages</document-root>
      <classpath><MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF</classpath>
      <root-uri>/MQWFClient-<cfgID></root-uri>
      <auto-reload enabled="true" polling-interval="3000"/>
      <shared-context>false</shared-context>
     </websphere-webgroup>
    (note the leading forward slash for the document-root element).
  4. Copy the <WTEDir>/hosts/default_host/default_app/servlets/default_app.webapp file to <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF/MQWFClient.webapp. Note that this file must be in the Web application's classpath (see above) and that its basename must match the websphere-webgroup's name.
  5. Edit the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF/MQWFClient.webapp file and add the following lines:
     <servlet>
      <name>Main</name>
      <code>com.ibm.workflow.servlet.client.Main</code>
      <servlet-path>/servlet/Main</servlet-path>
      <init-parameter>
       <name>ConfigurationFile</name>
       <value><MQWFDir>/cfgs/<cfgID>/WebClient/WebClient.properties</value>
      </init-parameter>
     </servlet>
  6. Import the MQSeries Workflow Java API into VA for Java:
    1. Open the VA for Java Workbench
    2. Select 'File' - 'Import'
    3. Enter <MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar as the Filename
    4. Enter 'IBM MQSeries Workflow Java APIs' as the project name
    5. Check 'Create new/scratch editions of versioned projects/packages'
    6. Check 'Version imported classes and new editions of packages/projects'
    7. Select 'Version name' and enter your version number, for example '3.3.0.0'. Then click 'Finish'
    All Problems in the packages com.ibm.workflow.corba and com.ibm.workflow.corba.jni can be safely ignored.
  7. Import the MQSeries Workflow Web Client into VA for Java:
    1. Open the VA for Java Workbench
    2. Select 'File' - 'Import'
    3. Enter <MQWFDir>/bin/fmcohcli.jar as the Filename
    4. Enter 'IBM MQSeries Workflow Web Client' as the project name
    5. Check 'Create new/scratch editions of versioned projects/packages'
    6. Check 'Version imported classes and new editions of packages/projects'
    7. Select 'Version name' and enter your version number, for example '2.3'. Then click 'Finish'
    All problems in the packages com.ibm.workflow.servlet.client, com.ibm.workflow.servlet.sample, and com.ibm.workflow.util.cfg can be safely ignored.
  8. Configure the WebSphere Test Environment:
    1. Open the VA for Java Workbench and start the WTE using 'Workspace' - 'Tools' - 'WebSphere Test Environment...'
    2. Select 'Servlet Engine' in the tree on the left
    3. Click 'Edit Class Path...' and make sure that 'IBM MQSeries Workflow Java APIs' and 'IBM MQSeries Workflow WebClient' are checked.
    4. To debug JSPs, make sure all 3 checkboxes in the 'JSP Settings' area are checked ('Load servlets externally', 'Halt at the beginning of the service method' and 'Enable JSP Source debugging').
    5. Select 'JSP Execution Monitor Options' in the tree on the left make sure that both checkboxes are checked ('Enable monitoring JSP execution' and 'Retrieve syntax error information').
  9. The default port used by the WTE is 8080, so start your Web browser and point it to http://localhost:8080/MQWFClient-<cfgID>/RTC.html to run the Web Client within the WebSphere Test Environment.

Setup for IBM WebSphere V4 Single Server Edition

  1. Create a Web Client configuration and specify f (WebSphere 4.0) when being prompted for the application server by fmczutil.
  2. Start the WebSphere Application Server.
  3. In a Web browser start the Administrator's Console, by accessing http://localhost:9090/admin.
  4. When presented with a log-in dialog box, enter your user ID.
  5. In the tree view on the left side of the console, expand 'Nodes', expand your node, and expand 'Enterprise Applications', to display a list of applications.
  6. Click the 'Install' button in the right pane.
  7. In the section 'Specify the Application or Module located on this machine to upload and install' specify <MQWFDir>/cfgs/<cfgID>/WebClient/fmcohcli.ear.
  8. The fields 'Application Name' and 'Context Root' need not to be filled in because you specified a .ear file in the step before (instead of a .war file).
  9. Click on the 'Next' button.
  10. Select 'Virtual Host Name': 'default_host' and 'Precompile JSPs': 'No'. Click on the button 'Next'.
  11. Click the 'Finish' button to confirm the information that you entered for installing the application.
  12. When deploying the application was successful and the Browser shows again the section 'Enterprise Applications', click on the link 'Plug-in configuration needs to be regenerated'.
  13. Click on 'Generate'.
  14. Back on section 'Enterprise Applications' click on the link 'Configuration needs to be saved'.
  15. Select Radiobutton 'Save Configuration File: <InstallDir>\config\server-cfg.xml' and click 'OK'.
  16. Click on the link 'Exit' located in the top menu bar.
  17. In the tree view on the left side of the console, expand 'Nodes', expand your node, expand 'Application Server', expand your Server and expand 'Process Definition'. Click on the link 'JVM Settings'.
  18. Enter <MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar in the 'Classpath:' field on the right pane.
  19. Click on the 'OK' button.
  20. Safe the configuration (see above).
  21. To run the Web Client:
    1. Restart your Server and restart the IBM HTTP Server.
    2. Start your Web browser and point it to http://localhost:8080/MQWFClient-<cfgID>/RTC.html.
      Note: You can find the context root in the Administrator's Console under 'Nodes' - '<Your Node>' - 'Enterprise Applications' - '<Your Application>' - 'View Deployment Descriptor (application.xml)'.

Setup for IBM WebSphere Studio Application Developer V4

  1. Create the MQWF Web Client project in WebSphere Studio Application Developer (WSAD):
    1. Using fmczutil, create a Web Client configuration and specify the j (Other (Servlet 2.2 / J2EE 1.2)) option when being prompted for the application server.
    2. Start WebSphere Application Developer.
    3. Select 'File' - 'Import'.
    4. Select 'EAR-File' and click the 'Next' button.
    5. Enter <MQWFDir>/cfgs/<cfgID>/WebClient/fmcohcli.ear in the 'EAR file' field.
    6. Enter 'MQWF Web Client EAR' in the 'Enterprise Application project name' field.
    7. Click the 'Next' button twice.
    8. Enter 'MQWF Web Client WAR' as the 'New Project Name' for the fmcohcli.war module.
      Note: If you want to run the Web Client in the WSAD Tomcat test environment, you must select a project name that does not contain blanks because the Web project's name will be used as context root URI.
    9. Click the 'Finish' button.
    10. Click 'Yes' when being prompted whether to fix links that have changed due to a renaming operation.
    Note: In the 'Tasks' view you will get a lot of messages about broken links and undefined attributes. They can be safely ignored. WSAD seems to have problems with certain browser-specific HTML attributes, with servlet links, and it cannot analyze the control flow in JSPs. The latter will cause some 'invalid location of tag' and 'no start tag <form>' messages.
  2. Add the MQWF Java API library to the MQWF Web Client project:
    1. Open the 'J2EE' perspective and select the 'Navigator' view.
    2. Within the Navigator view right click on the 'MQWF Web Client WAR' folder and choose 'Properties' from the context menu.
    3. Choose 'Java Build Path' in the properties panel.
    4. Choose the 'Libraries' tab.
    5. Click 'Add External JARs'.
    6. Enter <MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar in the 'File name' field then click the 'Open' button.
    7. Click the 'OK' button to close the properties panel.
  3. Create a new Server Configuration:
    1. Change to the Server perspective by selecting 'Perspective' - 'Open' - 'Server'.
    2. Right click on the 'Server Configurations' folder and choose 'New' - 'Server Instance and Configuration' from the context menu.
    3. Enter 'MQWF Web Client Server' in the 'Server name' field.
    4. Enter 'MQWF Web Client Server' in the 'Folder' field.
    5. Select 'WebSphere Servers' - 'WebSphere v4.0 Test Environment' in the 'Server instance type' box.
    6. Click the 'Finish' button.
    7. Select 'Yes' when being prompted whether to create a new server project.
    8. In the 'Server Configuration' view right click on the 'MQWF Web Client Server' server configuration.
    9. Select 'Add Project' - 'MQWF Web Client EAR'.
    10. Double click on the 'MQWF Web Client Server' server instance.
    11. Select the 'Paths' tab in the properties view.
    12. Add <MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar to the 'Class Path:' list by clicking 'Add External JARs'. When using WSAD V4.0.2 or later be sure to use the lower list - the upper list sets the 'ws.ext.dirs' property!
    13. Make sure this configuration is saved by pressing 'Ctrl-S'.
  4. Optional: To monitor the TCP/IP traffic create a monitoring server configuration:
    1. Right click on the 'Server Configurations' folder and choose 'New' - 'Server Instance and Configuration' from the context menu.
    2. Enter 'MQWF Web Client Monitor' in the 'Server name' field.
    3. Keep the 'MQWF Web Client Server' folder name.
    4. Select 'TCP/IP Monitoring Server' in the 'Server instance type' box.
    5. Click the 'Finish' button.
    6. In the 'Server Configuration' view double click on the 'MQWF Web Client Monitor' configuration and make sure the 'Remote port' matches the one used by the 'MQWF Web Client Server' configuration.
    Note: To use the TCP monitor, you must enable the 'port' hidden request parameter in Logon.jsp. Otherwise, the TCP monitor will be bypassed after the first HTTP redirect (status code 302).
  5. Start the test server:
    1. Switch to the 'J2EE' perspective.
    2. Open the 'MQWF Web Client WAR' - 'webApplication' tree.
    3. Right click on RTC.html and choose 'Run on Server'. The WebSphere Test Environment should start up. If you created the monitoring server, the 'Select a Server Client' dialog box will pop up. Select 'Launch "Open Web browser" using the TCP/IP monitoring server' to use the TCP/IP monitor or select 'Open Web browser' to run without the TCP/IP monitor.
    4. If the server cannot be started because it is invalid, you may have to republish it. In the 'Servers' view, right click on a server instance and select 'Publish' on the context menu. If this menu item is disabled, you must first close WebSphere Studio Application Developer and then re-open it.

Setup for Apache Tomcat V3.2

Apache Tomcat V3.2 is an open source project that can be found at http://jakarta.apache.org. It is the reference implementation for the Servlet 2.2 and JSP 1.1 specifications from Sun. Sun JavaServer Web Development Kit V1.0.1 and Apache Tomcat V3.1 are no longer supported, please upgrade to Apache Tomcat V3.2.

  1. Create a Web Client configuration and specify the o (Other) option when being prompted for the application server by fmczutil.
  2. In <TCDir>\bin\tomcat.bat:
  3. In <TCDir>\conf\server.xml add
     <Context path="/MQWFClient-<cfgID>"
              docBase="<MQWFDir>/cfgs/<cfgID>/WebClient/webpages"
              reloadable="false" />
    before the closing </ContextManager> tag at the end of the file, for example,
     <Context path="/MQWFClient-WEBC"
              docBase="/d:/Program Files/MQSeries Workflow/cfgs/WEBC/WebClient/webpages"
              reloadable="false"/>
    (note the leading forward slash and that the long names containing blanks have to be used).
  4. To run the Web Client:
    1. Start <TCDir>\bin\startup.bat
    2. Start your Web browser and point it to http://localhost:8080/MQWFClient-<cfgID>/RTC.html
  5. If the com.ibm.workflow.api package cannot be found when compiling the JSPs and you are using directories with blanks in their names on the CLASSPATH, try using the short names instead. For example, use
     set CP=%CP%;c:\Progra~1\MQSeri~1\bin\java3300\fmcojagt.jar;c:\Progra~1\MQSeri~1\bin\fmcohcli.jar
    instead of
     set CP="%CP%;c:\Program Files\MQSeries Workflow\bin\java3300\fmcojagt.jar;c:\Program Files\MQSeries Workflow\bin\fmcohcli.jar"

Setup for Apache Tomcat V3.3

Apache Tomcat V3.3 is an open source project that can be found at http://jakarta.apache.org. It is the reference implementation for the Servlet 2.2 and JSP 1.1 specifications from Sun.

Note that Tomcat V3.3 is not supported. Use either Tomcat V3.2 or Tomcat V4 instead.

Setup for Apache Tomcat V4

Apache Tomcat V4 is an open source project that can be found at http://jakarta.apache.org. It is the reference implementation for the Servlet 2.3 and JSP 1.2 specifications from Sun.

Other (WAR / EAR)
  1. Create a Web Client configuration and specify the o (Other (Servlet API 2.1)) option when being prompted for the application server by fmczutil. Tomcat V4 would support .war files (option j - Other (WAR / EAR)) as well, but the Servlet V2.1 open directory structure is easier to manage.
  2. Copy <MQWFDir>\bin\fmcohcli.jar to <MQWFDir>\cfgs\<cfgID>\WebClient\WEB-INF\lib\fmcohcli.jar.
  3. In <TCDir>\bin\catalina.bat:
  4. To run the Web Client:
    1. Start <TCDir>\bin\startup.bat
    2. Start your Web browser and point it to http://localhost:8080/MQWFClient-<cfgID>/RTC.html
  5. If you get an exception like javax.servlet.ServletException: org.xml.sax.Attributes: method getQName(I)Ljava/lang/String; not found when accessing the Web Client's servlet, you most likely have an incompatible XML parser on the CLASSPATH. For example, the full installation of IBM JDK 1.3 includes Xerces V1.0.3 in <JDKDir>/jre/lib/ext/xerces.jar. You must either delete this file or rename its extension to deactivate it.

Setup for Apache Tomcat V5 using MQWF native Java API

Apache Tomcat V5 is an open source project that can be found at http://jakarta.apache.org. It is the reference implementation for the Servlet 2.3 and JSP 1.2 specifications from Sun.

Other (WAR / EAR)
  1. Create a Web Client configuration and specify the (option j - Other (WAR / EAR)).
  2. Copy <MQWFDir>\cfgs\<cfgID>\WebClient\fmcohcli.war to <TCDir>\webapps\. Rename the .war file to a name of your choice, for example <Your name>.war, as the file name will later be part of the URL used to access the configurated WebClient.
  3. In <TCDir>\bin\catalina.bat:
  4. To run the Web Client:
    1. Start <TCDir>\bin\startup.bat
    2. Start your Web browser and point it to http://localhost:8080/<Your name>/RTC.html

Setup for BEA WebLogic V5.1

  1. Create a Web Client configuration and specify the o (Other) option when being prompted for the application server by fmczutil.
  2. In <WLDir>\startWebLogic.cmd add
     <MQWFDir>\bin\java<VRMS>\fmcojagt.jar;<MQWFDir>\bin\fmcohcli.jar
    to the PRE_CLASSPATH setting.
  3. In <WLDir>\weblogic.properties add the following line:
     weblogic.httpd.webApp.MQWFClient-<cfgID>=<MQWFDir>/cfgs/<cfgID>/WebClient/webpages
    Make sure to use forward slashes ('/') as directory separators.
  4. To run the Web Client:
    1. Start <WLDir>\startWebLogic.cmd
    2. Start your Web browser and point it to http://localhost:7001/MQWFClient-<cfgID>/RTC.html

Setup for BEA WebLogic V6

In the following, <WLServerDir> denotes the WebLogic server directory (for example, d:\bea\wlserver6.0), <domain> denotes the name of your domain and <server> denotes the name of the server where to deploy the Web Client.

  1. Create a Web Client configuration and specify the o (Other) option when being prompted for the application server by fmczutil.
  2. Make sure the WebLogic server is not running while you are updating its configuration.
  3. In the <WLServerDir>\config\<domain>\startWebLogic.cmd file, add
     <MQWFDir>\bin\java<VRMS>\fmcojagt.jar;<MQWFDir>\bin\fmcohcli.jar
    to the CLASSPATH setting.
  4. In <WLServerDir>\config\<domain>\config.xml add the element describing the Web Client Web application to the Domain element.
    With WebLogic 6.0, use:
     <Application Deployed="true" Name="MQSeries Workflow Web Client" Path="<MQWFDir>\cfgs\<cfgID>\WebClient\webpages">
      <WebAppComponent Name="MQWFClient-<cfgID>" Targets="<server>" URI="."/>
     </Application>
    With WebLogic 6.1, use:
     <Application Deployed="true" Name="MQSeries Workflow Web Client" Path="<MQWFDir>\cfgs\<cfgID>\WebClient\webpages">
      <WebAppComponent Name="/MQWFClient-<cfgID>" Targets="<server>" URI="."/>
     </Application>
    Note that the only difference is the leading slash in the WebAppComponent name which must match the root URI.
  5. To run the Web Client:
    1. Start the WebLogic server. If you get a warning about a missing fmcohcli.war file on the console, you can safely ignore that.
    2. Start your Web browser and point it to http://localhost:7001/MQWFClient-<cfgID>/RTC.html

Setup for Allaire JRun V3.0

  1. Create a Web Client configuration and specify the o (Other) option when being prompted for the application server by fmczutil.
  2. Make a backup copy of the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF/web.xml file. There have been instances where this file was overwritten during configuration of the Web application.
  3. Create a new Server for MQSeries Workflow:
    1. Copy the directory <JRDir>/servers/default to <JRDir>/servers/fmc.
    2. Edit the <JRDir>/lib/jvms.properties file and add the following line:
       fmc=<JRDir>/servers/fmc
    3. Edit the <JRDir>/servers/fmc/local.properties file and change the following property to read:
       jrun.server.displayname=JRun MQWF Server
    Read the chapter 'Server Creation' in the JRun online documentation for more details.
  4. Make sure the JRun Admin Server is running.
  5. Start the JRun Management Console (JMC).
  6. Expand the 'JRun MQWF Server' node in the tree on the left.
  7. In the 'Java Settings' branch, edit the 'JRun Control Port' setting and assign to it an unused port number (it still has the same port as the default server it was copied from).
  8. On the same panel, add <MQWFDir>/bin/java<VRMS>/fmcojagt.jar and <MQWFDir>/bin/fmcohcli.jar to the 'Classpath' setting.
  9. If you are using the built-in JRun Web server instead of an external Web server, open the 'JRun Web Server' branch and assign an unused port number to the 'Web Server Port' setting, for example, 8080.
  10. Select the 'Web Applications' branch and delete the two Web applications from the default server, 'Default User Application' and 'JRun Demo'.
  11. Click on 'Create an Application'.
  12. Select 'JRun MQWF Server' in the 'JRun Server Name' list box.
  13. Enter 'MQSeries Workflow' in the 'Application Name' field.
  14. Enter '/MQWFClient-<cfgID>' in the 'Application URL' field.
  15. Enter '<MQWFDir>/cfgs/<cfgID>/WebClient/webpages' in the 'Application Root Dir' field.
  16. Click on 'create'.
  17. To run the Web Client:
    1. Select 'JRun Web Server' in the tree on left.
    2. Click the 'start server' button.
    3. Start your Web browser and point it to http://localhost:8080/MQWFClient-<cfgID>/RTC.html
    4. If you see the logon page, but get an error when trying to log on, check if the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF/web.xml file has been overwritten and restore it from your backup, if necessary.

Setup for Inprise Application Server V4.1

  1. Create a Web Client configuration and specify the o (Other) option when being prompted for the application server by fmczutil.
  2. In WebClient.properties, set the following:
     DocumentRoot=<MQWFDir>/cfgs/<cfgID>/WebClient/webpages
  3. Edit the file <IASDir>/properties/server/<ServerName>/java.options and add the following line:
     -classpath <MQWFDir>\bin\fmcohcli.jar;<MQWFDir>\bin\JAVA<VRMS>\fmcojagt.jar
  4. Start the Inprise Application Server and go to http://localhost:9090. If the Inprise AS is running, you should be connected to the Administration Console.
  5. Log on, select the HTTP Web Engine, and press 'Manage'.
  6. Under 'Setup', select 'File Aliases'.
  7. Add a new entry with Alias Pathname "/MQWFClient-<cfgID>" and Full Pathname "<MQWFDir>/cfgs/<cfgID>/WebClient/webpages".
  8. Under 'Servlet Aliases', add the alias "/MQWFClient-<cfgID>/servlet" and under Servlet Invoked, specify "invoker".
  9. Select the 'Servlets' button and select 'Add' to add the servlet: Specify 'Main' for the servlet name and 'com.ibm.workflow.servlet.client.Main' as the Servlet.
  10. Under 'Properties', specify 'ConfigurationFile' as Name, and <MQWFDir>\cfgs\<cfgID>\WebClient\WebClient.properties for the servlet's properties file.
  11. To run the Web Client:
    1. Shutdown and restart the Inprise Application server.
    2. Start your Web browser and point it to http://localhost:8080/MQWFClient-<cfgID>/RTC.html

Setup for Borland Application Server V4.5

Borland AppServer's Web container is based on Tomcat V3.2, so the setup is very similiar to the one of Tomcat V3.2.
  1. Create a Web Client configuration and specify the o (Other) option when being prompted for the application server by fmczutil.
  2. In the Borland AppServer's Console open the 'Web Containers' tree of your AppServer (denoted by <server> in the following).
  3. Right-click on the 'tomcat3' item and select 'Edit Properties' from the context menu.
  4. On the 'General' page, select 'Additional Options...'.
  5. Add the following two lines
     /<MQWFDir>/bin/fmcohcli.jar
     /<MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar
    at the end of the list box labeled 'Additional CLASSPATH entries:'. (Note the leading forward slash - this is the same as for the docBase in the next step.)
  6. Edit the <BASDir>\var\servers\<server>\adm\tomcat3\conf\server.xml file and add the following line:
     <Context path="/MQWFClient-<cfgID>"
              docBase="<MQWFDir>/cfgs/<cfgID>/WebClient/webpages"
              reloadable="false"/>
    before the closing </ContextManager> tag at the end of the file, for example,
     <Context path="/MQWFClient-WEBC"
              docBase="/d:/Program Files/MQSeries Workflow/WebClient/webpages"
              reloadable="false"/>
    (Note the leading forward slash and that the long names containing blanks have to be used).
  7. To run the Web Client:
    1. Start the Web container tomcat3 from the Borland AppServer's Console.
    2. Start your Web browser and point it to http://localhost:8080/MQWFClient-<cfgID>/RTC.html

Setup for Sun/Netscape iPlanet Web Server V4.1

  1. Create a Web Client configuration and specify the o (Other) option when being prompted for the application server by fmczutil.
  2. Go to the <iPDir>/<server>/config directory where <iPDir> denotes the iPlanet installation directory and <server> denotes the ID of the server where you want to configure the Web Client.
  3. Edit the jvm12.conf file and add the following to the jvm.classpath setting:
     jvm.classpath=...<MQWFDir>/bin/fmcohcli.jar;<MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar
    Be sure to use the correct path separator character for your platform. Note that it is not sufficient to add these .jar files to the servlet's classpath, this will result in java.lang.MissingResourceExceptions.
  4. Edit the obj.conf file and add the following line to the <Object name="default"> section:
     NameTrans fn="pfx2dir" from="/MQWFClient-<cfgID>" dir="<MQWFDir>/cfgs/<cfgID>/WebClient/webpages"
  5. Edit the rules.properties file and add the following line:
     /servlet/Main=MQWFClient
  6. Edit the servlets.properties file and add the following lines:
     servlet.MQWFClient.code=com.ibm.workflow.servlet.client.Main
     servlet.MQWFClient.initArgs=ConfigurationFile=<MQWFDir>/cfgs/<cfgID>/WebClient/WebClient.properties
     servlet.MQWFClient.context=MQWFClient
  7. Edit the contexts.properties file and add the following lines:
     context.MQWFClient.uri=/MQWFClient-<cfgID>
     context.MQWFClient.docRoot=<MQWFDir>/cfgs/<cfgID>/WebClient/webpages
  8. To run the Web Client:
    1. Run the iPlanet server administration and make sure the manual changes are picked up (you can click the 'Apply' button in the upper left corner to do so).
    2. Start the server for which you configured the Web Client.
    3. Start your Web browser and point it to http://localhost/MQWFClient-<cfgID>/RTC.html

Setup for Sun/Netscape iPlanet Web Server V6.0

  1. Create a Web Client configuration and specify the o (Other) option when being prompted for the application server by fmczutil.
  2. Go to the <iPDir>/<server>/config directory where <iPDir> denotes the iPlanet installation directory and <server> denotes the virtual server where you want to configure the Web Client.
  3. Edit the jvm12.conf file and add the following to the jvm.classpath setting:
     jvm.classpath=...<MQWFDir>/bin/fmcohcli.jar;<MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar
    Be sure to use forward slashes as directory separators.
  4. Edit the web-apps.xml file and add the following line before the ending </vs> tag:
     <web-app uri="/MQWFClient-<cfgID>" dir="<MQWFDir>/cfgs/<cfgID>/WebClient/webpages"/>
    Again, be sure to use forward slashes as directory separators. For other JSP tuning parameters, see the iPlanet online documentation.
  5. Edit the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF/web.xml file and change the string reading
     "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"
    to
     "file:/<iPDir>/bin/https/dtds/web-app_2_2.dtd"
    Be sure to use forward slashes as directory separators and do not forget the leading slash right after the file: protocol specification.
  6. To run the Web Client:
    1. Run the iPlanet server administration and make sure the manual changes are picked up (you can click the 'Apply' button in the upper left corner to do so).
    2. Start the server for which you configured the Web Client.
    3. Start your Web browser and point it to http://localhost/MQWFClient-<cfgID>/RTC.html

Setup for HTTPS with Apache Tomcat V3.2

Starting with version 3.2, Tomcat has been enabled to support SSL. Setup is pretty simple:

  1. Make sure Apache Tomcat V3.2 is configured and working.
  2. Download and install JSSE (Java secure sockets extension). When using IBM JDK 1.2, you may already have this extension. Check the <JDKDir>/jre/lib/ext directory for the jsse.jar file. Note that the current Tomcat implementation specifically requires Sun's JSSE, for instance, it does not work with IBM's JSSE that comes with IBM JDK 1.3.
  3. Then open the <TCDir>/doc/tomcat-ssl-howto.html file and follow the instructions in the section titled SSL direct.
  4. If using the JDK's keytool, note that the default location for the keystore file is the System.getProperty("user.home") directory (for example, c:\winnnt\profiles\<userID> on Windows NT). Use the -keystore parameter of keytool if you want to specify an alternate location.
  5. Start your Web browser and point it to https://localhost:8443/MQWFClient-<cfgID>/RTC.html. If you copied the Connector parameters from the Tomcat instructions and have troubles accessing the Web Client over this connection, try to set
     <Parameter name="clientAuth" value="false"/>
    in Tomcat's server.xml configuration file.

Setup for HTTP/1.1 Basic Authentication with Apache Tomcat

  1. Make sure Apache Tomcat V3.2 or Apache Tomcat V4 is configured and working.
  2. Edit the <TCDir>/conf/tomcat-users.xml file and add the Workflow user IDs you want to authorize to your Workflow role, for example, mqwf:
     <tomcat-users>
      <user name="admin" password="password" roles="mqwf"/>
      <user name="user1" password="changeit" roles="mqwf"/>
     </tomcat-users>
    Note that this .xml-file based authentication requires the org.apache.tomcat.request.SimpleRealm request interceptor to be enabled in <TCDir>/conf/server.xml (this is the default, there is another interceptor available which is JDBC-based). See also the BasicAuthenticationHandler sample.
  3. Enable authentication for the Web Client's Web application by adding the following lines before the closing </web-app> tag in <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF/web.xml:
     <security-constraint>
      <web-resource-collection>
       <web-resource-name>Web Client</web-resource-name>
       <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <auth-constraint>
       <role-name>mqwf</role-name>
      </auth-constraint>
     </security-constraint>
     <login-config>
      <auth-method>BASIC</auth-method>
      <realm-name>IBM WebSphere MQ Workflow Web Client</realm-name>
     </login-config>
    Note that the role-name entered here must match the entry in the roles attribute above.

Setup for HTTP/1.1 Basic Authentication with WebSphere V3.5

  1. Make sure the WebSphere server is running and start the WebSphere Adminstrative Console.
  2. Open the 'Configure Global Security Settings' wizard and check the 'Enable Security' checkbox on the 'General' page. On the 'User Registry' page, check what Server ID you are using.
  3. Click 'Finish'. You now must restart the WebSphere server and enter the Server user ID and password when re-opening the Administrative Console.
  4. Open the 'Create Enterprise Application' wizard and enter 'MQSeries Workflow' as application name, then click 'Next'.
  5. Open the 'Web Applications' node, select 'MQWFClient-<cfgID>', click 'Add', click 'Next', then click 'Finish' (there is nothing to enter on the last page).
  6. Open the 'Configure Application Security' wizard to select the authentication mechanism to be used and select the 'MQSeries Workflow' leaf of the 'Enterprise Applications' node. Then click 'Next'.
  7. Enter 'MQSeries Workflow Web Client' as the Realm name. This is the text the user will see on the browser's password prompt.
  8. Select the 'Basic' challenge type and optionally check the 'Use SSL' box if you configured HTTPS.
  9. Click 'Finish' (again, there is nothing to enter on the last page).
  10. Open the 'Configure Security Permissions' wizard to configure authorizations and select the 'MQSeries Workflow' leaf of the 'Enterprise Applications' node. Then click 'Next'.
  11. On the 'Permissions' page, select all permissions by pressing Ctrl-A, then click 'Next'.
  12. On the 'Grant Permissions' page select the 'Selection' radio button. In the 'Search For' box select 'User' and in the 'Search Filter' box enter '*' (asterisk). Then click 'Search'. (EF: What is 'All authenticated'? Never got a password prompt with this one...)
  13. In the 'Search Results' list select the user ID you want to authorize. Note that this user ID must be a Workflow user ID and its password must match the Workflow password if you want to use the BasicAuthenticationHandler sample.
  14. Click 'Next'. On this page, you can check that the permissions have been granted by opening the trees. Click 'Finish'.
  15. Open the 'Configure Resource Security' wizard to configure access restrictions and expand the 'Virtual Hosts' node. Open the 'default_host' node, select the '/MQWFClient-<cfgID>/' leaf. Make sure you select the URL with the trailing slash. Then click 'Finish' (there is nothing to enter on the last page).
  16. To test Basic Authentication start the 'MQSeries Workflow' Enterprise Application instead of the 'MQWF Web Client' Application Server. Then point your browser to http://localhost/MQWFClient-<cfgID>/servlet/Main?command=logon. You must have an authentication handler like the BasicAuthenticationHandler sample installed for this to work.

Setup for HTTPS with IBM HTTP Server and Apache Tomcat V3.2

This setup uses IBM HTTP Server as Web server and Apache Tomcat as Servlet container. This is different from the Tomcat standalone configuration where Apache Tomcat is used as both Web server and Servlet container.

  1. Shutdown the IBM HTTP server if it is running.
  2. Create a self-signed certificate (sufficient for demonstration purposes):
    1. Start the Key Management utility that comes with IBM HTTP Server.
    2. Select the 'Key Database File' - 'New...' menu option.
    3. Select 'CMS key database file' from the list of key database types and type in the name and location for the file: <MQWFDir>/WebClient/ihs.kdb. Then click OK.
    4. In the password dialog box, enter a password for this database. Leave the expiration time for the key database unspecified. Click the 'Stash the password to a file?' checkbox. If the password is not stashed into a file, the Web server will not be able to start automatically. Then click OK.
    5. Select the 'Create' - 'New Self-Signed Certificate...' menu option.
    6. Enter 'WebClient' as the 'Key Label' and fill in all information about your organization. Then click OK to create and save the certificate.
    7. Close the Key Management utility.
  3. Make sure Apache Tomcat is configured and start it at least once.
  4. EF tbd: What about ApacheModuleJServ.dll?
  5. Edit the <IHSDir>/conf/httpd.conf file and add the following line at the end:
     Include "<TCDir>/conf/tomcat-apache.conf"
  6. To run the Web Client using HTTPS:
    1. Start Apache Tomcat (this must be done before starting IBM HTTP Server so that the tomcat-apache.conf file is up to date).
    2. Start IBM HTTP Server.
    3. Start your Web browser and point it to https://localhost/MQWFClient-<cfgID>/RTC.html

Setup for HTTPS with IBM HTTP Server and WebSphere V3.5

These instructions describe how to enable SSL in WebSphere Application Server. In the following, <IHSDir> denotes the IBM HTTP Server installation directory and <WASDir> denotes the WebSphere Application Server installation directory.

  1. Open the WebSphere Administrative console and locate the virtual host, that you want to enable SSL support, for example, default_host. Go to the 'Advanced' page of the virtual host and add <virtual_host>:443 and its variations to the alias list.
  2. You must restart all application servers using the virtual host for the changes to become effective.
  3. Create a self-signed certificate as described above.
  4. Go to the <IHSDir>/conf directory and make a backup copy of httpd.conf.
  5. Edit the httpd.conf file and make sure the ServerAdmin directive points to a valid e-mail address and the ServerName directive is enabled and matches the fully qualified hostname. SSL configuration requires that the ServerName directive matches the fully qualified host name of your server, such as www.acme.com.
  6. Locate the line where the WebSphere server module is loaded and add the IBM HTTP Server SSL module you have installed, for example:
     LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll
     LoadModule ibm_app_server_module <WASDir>/bin/mod_ibm_app_server.dll
  7. Add the port number for the virtual server just below the Listen 80 statement. The default port number for SSL is 443. If you don't have the Listen 80 item, just add the following line after the sample #Listen lines:
     Listen 443
  8. Add following lines at the end of the httpd.conf:
     <VirtualHost :443>
     SSLEnable
     SSLClientAuth none
     DocumentRoot "<IHSDir>/htdocs"
     ErrorLog logs/error.log
     TransferLog logs/access.log
     </VirtualHost>
     SSLDisable
     Keyfile "<MQWFDir>/WebClient/ihs.kdb"
     SSLV2Timeout 100
     SSLV3Timeout 1000
    Be sure to use replace <IHSDir> and <MQWFDir> with the values appropriate for your environment.
  9. To run the Web Client using HTTPS:
    1. Start IBM HTTP Server.
    2. In the WebSphere Administrative Console, select the 'MQSeries Workflow WebClient' server from the Topology Tree and click the start button.
    3. Start your Web browser and point it to https://localhost/MQWFClient-<cfgID>/RTC.html

Setup for Apache mail server and Microsoft Outlook Express

This setup can be used to demonstrate the EmailHandler sample without being connected to a network. It assumes that you have Microsoft Outlook Express installed (usually comes with Microsoft Internet Explorer). Then download and install the Apache mail server, JAMES, which is an open source project that can be found at http://java.apache.org.

  1. Go to the <JamesDir>/bin directory and start the run.bat script.
  2. Open a new console window and edit the newly created <JamesDir>/conf/JAMES.conf.xml file. Search for the line reading
     <account login="root" password=""/>
    (it is marked with a 'FILL ME' tag; do not confuse it with the comment line near the top of the file) and fill in the adminstrator's password. You need not fill in the other fields marked with the 'FILL ME' tag.
  3. Save your changes and go back to the console where you started the run.bat script. Press the enter key to start the mail server.
  4. Open a telnet session on 'localhost', port '4555'. Select the 'Connect' - 'Remote system...' menu option of the Windows NT telnet program to do so. You might want to turn on 'local echo' for the telnet session (on Windows 2000, enter set LOCAL_ECHO on the telnet command line). Log on to JAMES with user ID 'root' and the password you specified above.
  5. Create mail accounts for the Workflow users you want to send mail to, for example, type adduser admin password to create a mail account for the Workflow administrator. Type quit when done.
  6. The mail server is now running and operable. In the future, just invoke the <JamesDir>/bin/run.bat script to start the mail server. This concludes the server-side configuration.
  7. Start Outlook Express and select the 'Tools' - 'Accounts...' menu option.
  8. Click the 'Add' button and select the 'Mail...' option.
  9. Enter the descriptive name of the mail user, for example, 'Workflow Admin'. Then click 'Next'.
  10. Select the 'I already have an e-mail address ...' option and enter 'admin@localhost' in the 'E-mail address' field. The user ID specified here must match the one used with the adduser command above. The click 'Next'.
  11. Select 'POP3' as incoming mail server type. Enter 'localhost' in both the 'Incoming mail server' and 'Outgoing mail server' fields, then click 'Next'.
  12. Enter the account name and password as specified with the adduser command above. Select the 'Remember password' option so that you do not have to enter the password every time you receive your mail (this should be OK for demonstration purposes). Click 'Next'.
  13. Click 'Finish' to create the new account.
  14. Select the newly created account (named 'localhost') on the 'Mail' page of the dialog box and click the 'Properties' button.
  15. Enter a more meaningfull name for this account, for example, 'Workflow Admin'. Deselect the 'Include this account' box so this account is not automatically synchronized and does not interfere with your other uses of the mail client. Then press the 'OK' button.
  16. Close the 'Internet Accounts' dialog box. This concludes the client-side configuration.
  17. When e-mail has been sent to this account, simply select the 'Workflow Admin' option of the 'Send/Recv' button on the toolbar.