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.
- Create a Web Client configuration and either specify w (WebSphere 3.x)
or o (Other) when being prompted for the application server by fmczutil.
- 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:
- Open the VA for Java Workbench
- Press 'F2' or select 'File' - 'Quick Start'
- Select 'Features' and 'Add Feature' and press 'Ok'.
- 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
.
- 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).
- 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.
- 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>
|
- Import the MQSeries Workflow Java API into VA for Java:
- Open the VA for Java Workbench
- Select 'File' - 'Import'
- Enter
<MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar
as the
Filename
- Enter 'IBM MQSeries Workflow Java APIs' as the project name
- Check 'Create new/scratch editions of versioned projects/packages'
- Check 'Version imported classes and new editions of packages/projects'
- 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.
- Import the MQSeries Workflow Web Client into VA for Java:
- Open the VA for Java Workbench
- Select 'File' - 'Import'
- Enter
<MQWFDir>/bin/fmcohcli.jar
as the
Filename
- Enter 'IBM MQSeries Workflow Web Client' as the project name
- Check 'Create new/scratch editions of versioned projects/packages'
- Check 'Version imported classes and new editions of packages/projects'
- 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.
- Configure the WebSphere Test Environment:
- Open the VA for Java Workbench and start the WTE using 'Workspace' - 'Tools' -
'WebSphere Test Environment...'
- Select 'Servlet Engine' in the tree on the left
- Click 'Edit Class Path...' and make sure that 'IBM MQSeries Workflow Java APIs'
and 'IBM MQSeries Workflow WebClient' are checked.
- 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').
- 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').
- 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.
- Create a Web Client configuration and specify f (WebSphere 4.0) when being prompted
for the application server by fmczutil.
- Start the WebSphere Application Server.
- In a Web browser start the Administrator's Console, by accessing
http://localhost:9090/admin.
- When presented with a log-in dialog box, enter your user ID.
- 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.
- Click the 'Install' button in the right pane.
- In the section 'Specify the Application or Module located on this machine to upload and install'
specify
<MQWFDir>/cfgs/<cfgID>/WebClient/fmcohcli.ear
.
- 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).
- Click on the 'Next' button.
- Select 'Virtual Host Name': 'default_host' and 'Precompile JSPs': 'No'.
Click on the button 'Next'.
- Click the 'Finish' button to confirm the information that you entered for installing the
application.
- 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'.
- Click on 'Generate'.
- Back on section 'Enterprise Applications' click on the link 'Configuration needs to be saved'.
- Select Radiobutton 'Save Configuration File: <InstallDir>\config\server-cfg.xml'
and click 'OK'.
- Click on the link 'Exit' located in the top menu bar.
- 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'.
- Enter
<MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar
in the 'Classpath:' field
on the right pane.
- Click on the 'OK' button.
- Safe the configuration (see above).
- To run the Web Client:
- Restart your Server and restart the IBM HTTP Server.
- 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)'.
- Create the MQWF Web Client project in WebSphere Studio Application Developer (WSAD):
- 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.
- Start WebSphere Application Developer.
- Select 'File' - 'Import'.
- Select 'EAR-File' and click the 'Next' button.
- Enter
<MQWFDir>/cfgs/<cfgID>/WebClient/fmcohcli.ear
in the
'EAR file' field.
- Enter 'MQWF Web Client EAR' in the 'Enterprise Application project name' field.
- Click the 'Next' button twice.
- 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.
- Click the 'Finish' button.
- 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.
- Add the MQWF Java API library to the MQWF Web Client project:
- Open the 'J2EE' perspective and select the 'Navigator' view.
- Within the Navigator view right click on the 'MQWF Web Client WAR' folder and choose
'Properties' from the context menu.
- Choose 'Java Build Path' in the properties panel.
- Choose the 'Libraries' tab.
- Click 'Add External JARs'.
- Enter
<MQWFDir>/bin/JAVA<VRMS>/fmcojagt.jar
in the 'File name'
field then click the 'Open' button.
- Click the 'OK' button to close the properties panel.
- Create a new Server Configuration:
- Change to the Server perspective by selecting 'Perspective' - 'Open' - 'Server'.
- Right click on the 'Server Configurations' folder and choose 'New' -
'Server Instance and Configuration' from the context menu.
- Enter 'MQWF Web Client Server' in the 'Server name' field.
- Enter 'MQWF Web Client Server' in the 'Folder' field.
- Select 'WebSphere Servers' - 'WebSphere v4.0 Test Environment' in the
'Server instance type' box.
- Click the 'Finish' button.
- Select 'Yes' when being prompted whether to create a new server project.
- In the 'Server Configuration' view right click on the 'MQWF Web Client Server'
server configuration.
- Select 'Add Project' - 'MQWF Web Client EAR'.
- Double click on the 'MQWF Web Client Server' server instance.
- Select the 'Paths' tab in the properties view.
- 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!
- Make sure this configuration is saved by pressing 'Ctrl-S'.
- Optional: To monitor the TCP/IP traffic create a monitoring server configuration:
- Right click on the 'Server Configurations' folder and choose 'New' -
'Server Instance and Configuration' from the context menu.
- Enter 'MQWF Web Client Monitor' in the 'Server name' field.
- Keep the 'MQWF Web Client Server' folder name.
- Select 'TCP/IP Monitoring Server' in the 'Server instance type' box.
- Click the 'Finish' button.
- 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).
- Start the test server:
- Switch to the 'J2EE' perspective.
- Open the 'MQWF Web Client WAR' - 'webApplication' tree.
- 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.
- 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.
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.
- Create a Web Client configuration and specify the o (Other) option when being
prompted for the application server by fmczutil.
- In
<TCDir>\bin\tomcat.bat
:
- Add the following line at the beginning of the file:
- Add
set CP=%CP%;<MQWFDir>\bin\java<VRMS>\fmcojagt.jar;<MQWFDir>\bin\fmcohcli.jar
|
before the line reading
echo Using CLASSPATH: %CP%
|
- If you are using
JAXP 1.1 from within the Web Client
(for example, the AuditTrailHandler sample), then you
must make sure to have the JAXP 1.1 classes before Tomcat's JAXP 1.0 classes in the
CLASSPATH. To do so, change the line reading
to
- In
<TCDir>\conf\server.xml
add
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).
- To run the Web Client:
- Start
<TCDir>\bin\startup.bat
- Start your Web browser and point it to
http://localhost:8080/MQWFClient-<cfgID>/RTC.html
- 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"
|
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.
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)
- 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.
- Copy
<MQWFDir>\bin\fmcohcli.jar
to
<MQWFDir>\cfgs\<cfgID>\WebClient\WEB-INF\lib\fmcohcli.jar
.
- In
<TCDir>\bin\catalina.bat
:
- Add the following line at the beginning of the file:
- For Tomcat V4.0 and Tomcat V4.0.1 locate the section titled
"Set Up The Runtime Classpath" and change
to read
set CLASSPATH=%CP%;<MQWFDir>\bin\java<VRMS>\fmcojagt.jar
|
- For Tomcat V4.0.2 and later releases locate the line
set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\bin\bootstrap.jar
|
and add the following line right after it
set CLASSPATH=%CLASSPATH%;<MQWFDir>\bin\java<VRMS>\fmcojagt.jar
|
- For Tomcat Version 4.0 - 4.0.3: In
<TCDir>\conf\server.xml
locate the section reading
<!-- Tomcat Root Context -->
<!--
<Context path="" docBase="ROOT" debug="0"/>
-->
|
then add the following lines right after it:
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).
- For Tomcat Version 4.1.2 or higher: In
<TCDir>\conf\server.xml
locate the section where all the
context definitions are made.
Add a context definition for the WebSphere MQ Workflow Web Client:
<Context className="org.apache.catalina.core.StandardContext" crossContext="false" reloadable="false" mapperClass="org.apache.catalina.core.StandardContextMapper" useNaming="true" debug="0" swallowOutput="false" privileged="false" displayName="
MQWF Web Client" wrapperClass="org.apache.catalina.core.StandardWrapper" docBase="D:/IBM/MQSeriesWorkflow/cfgs/<cfgID>/WebClient" cookies="true" path="/MQWFClient-<cfgID>" cachingAllowed="true" charsetMapperClass="org.apache.catalina.util.CharsetMapper">
</Context> |
- To run the Web Client:
- Start
<TCDir>\bin\startup.bat
- Start your Web browser and point it to
http://localhost:8080/MQWFClient-<cfgID>/RTC.html
- 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.
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)
- Create a Web Client configuration and specify the (option j - Other (WAR / EAR)).
- 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.
- In
<TCDir>\bin\catalina.bat
:
- Add the following line at the beginning of the file:
- Locate the section titled
"Add on extra jar files to CLASSPATH" and add the following lines:
set MQBASE=%Your installation directory of WebSphere MQ%
set CLASSPATH=%CLASSPATH%;%MQBASE%\java\lib\com.ibm.mq.jar
set CLASSPATH=%CLASSPATH%;%MQBASE%\java\lib\com.ibm.mqjms.jar
set CLASSPATH=%CLASSPATH%;%MQBASE%\java\lib\jms.jar
set CLASSPATH=%CLASSPATH%;%MQBASE%\java\lib\connector.jar
|
- To run the Web Client:
- Start
<TCDir>\bin\startup.bat
- Start your Web browser and point it to
http://localhost:8080/<Your name>/RTC.html
- Create a Web Client configuration and specify the o (Other) option when being
prompted for the application server by fmczutil.
- In
<WLDir>\startWebLogic.cmd
add
<MQWFDir>\bin\java<VRMS>\fmcojagt.jar;<MQWFDir>\bin\fmcohcli.jar
|
to the PRE_CLASSPATH
setting.
- In
<WLDir>\weblogic.properties
add the following line:
Make sure to use forward slashes ('/') as directory separators.
- To run the Web Client:
- Start
<WLDir>\startWebLogic.cmd
- Start your Web browser and point it to
http://localhost:7001/MQWFClient-<cfgID>/RTC.html
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.
- Create a Web Client configuration and specify the o (Other) option when being
prompted for the application server by fmczutil.
- Make sure the WebLogic server is not running while you are updating its
configuration.
- In the
<WLServerDir>\config\<domain>\startWebLogic.cmd
file, add
<MQWFDir>\bin\java<VRMS>\fmcojagt.jar;<MQWFDir>\bin\fmcohcli.jar
|
to the CLASSPATH
setting.
- 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.
- To run the Web Client:
- Start the WebLogic server. If you get a warning about a missing
fmcohcli.war
file on the console, you can safely ignore that.
- Start your Web browser and point it to
http://localhost:7001/MQWFClient-<cfgID>/RTC.html
- Create a Web Client configuration and specify the o (Other) option when being
prompted for the application server by fmczutil.
- 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.
- Create a new Server for MQSeries Workflow:
- Copy the directory
<JRDir>/servers/default
to
<JRDir>/servers/fmc
.
- Edit the
<JRDir>/lib/jvms.properties
file and add
the following line:
- 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.
- Make sure the JRun Admin Server is running.
- Start the JRun Management Console (JMC).
- Expand the 'JRun MQWF Server' node in the tree on the left.
- 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).
- On the same panel, add
<MQWFDir>/bin/java<VRMS>/fmcojagt.jar
and <MQWFDir>/bin/fmcohcli.jar
to the
'Classpath' setting.
- 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.
- Select the 'Web Applications' branch and delete the two Web
applications from the default server, 'Default User Application' and
'JRun Demo'.
- Click on 'Create an Application'.
- Select 'JRun MQWF Server' in the 'JRun Server Name' list box.
- Enter 'MQSeries Workflow' in the 'Application Name' field.
- Enter '/MQWFClient-<cfgID>' in the 'Application URL' field.
- Enter '<MQWFDir>/cfgs/<cfgID>/WebClient/webpages' in the
'Application Root Dir' field.
- Click on 'create'.
- To run the Web Client:
- Select 'JRun Web Server' in the tree on left.
- Click the 'start server' button.
- Start your Web browser and point it to
http://localhost:8080/MQWFClient-<cfgID>/RTC.html
- 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.
- Create a Web Client configuration and specify the o (Other) option when being
prompted for the application server by fmczutil.
- In
WebClient.properties
, set the following:
- 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
|
- 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.
- Log on, select the HTTP Web Engine, and press 'Manage'.
- Under 'Setup', select 'File Aliases'.
- Add a new entry with Alias Pathname "/MQWFClient-<cfgID>" and Full Pathname
"<MQWFDir>/cfgs/<cfgID>/WebClient/webpages".
- Under 'Servlet Aliases', add the alias "/MQWFClient-<cfgID>/servlet" and under
Servlet Invoked, specify "invoker".
- 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.
- Under 'Properties', specify 'ConfigurationFile' as Name, and
<MQWFDir>\cfgs\<cfgID>\WebClient\WebClient.properties
for the
servlet's properties file.
- To run the Web Client:
- Shutdown and restart the Inprise Application server.
- Start your Web browser and point it to
http://localhost:8080/MQWFClient-<cfgID>/RTC.html
Borland AppServer's Web container is based on Tomcat V3.2, so the setup is very similiar
to the one of Tomcat V3.2.
- Create a Web Client configuration and specify the o (Other) option when being
prompted for the application server by fmczutil.
- In the Borland AppServer's Console open the 'Web Containers' tree of your AppServer
(denoted by <server> in the following).
- Right-click on the 'tomcat3' item and select 'Edit Properties' from the context menu.
- On the 'General' page, select 'Additional Options...'.
- 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.)
- Edit the
<BASDir>\var\servers\<server>\adm\tomcat3\conf\server.xml
file and add the following line:
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).
- To run the Web Client:
- Start the Web container
tomcat3
from the Borland AppServer's Console.
- Start your Web browser and point it to
http://localhost:8080/MQWFClient-<cfgID>/RTC.html
- Create a Web Client configuration and specify the o (Other) option when being
prompted for the application server by fmczutil.
- 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.
- 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.
- Edit the
obj.conf
file and add the following line to the
<Object name="default">
section:
- Edit the
rules.properties
file and add the following line:
- 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
|
- Edit the
contexts.properties
file and add the following lines:
- To run the Web Client:
- 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).
- Start the server for which you configured the Web Client.
- Start your Web browser and point it to
http://localhost/MQWFClient-<cfgID>/RTC.html
- Create a Web Client configuration and specify the o (Other) option when being
prompted for the application server by fmczutil.
- 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.
- 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.
- Edit the
web-apps.xml
file and add the following line before the ending
</vs>
tag:
Again, be sure to use forward slashes as directory separators. For other JSP tuning
parameters, see the iPlanet online documentation.
- 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.
- To run the Web Client:
- 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).
- Start the server for which you configured the Web Client.
- Start your Web browser and point it to
http://localhost/MQWFClient-<cfgID>/RTC.html
Starting with version 3.2, Tomcat has been enabled to support SSL. Setup
is pretty simple:
- Make sure Apache Tomcat V3.2 is configured and working.
- 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.
- Then open the
<TCDir>/doc/tomcat-ssl-howto.html file and follow the
instructions in the section titled SSL direct.
- 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.
- 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.
- Make sure Apache Tomcat V3.2 or Apache Tomcat V4
is configured and working.
- 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.
- 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.
- Make sure the WebSphere server is running and start the WebSphere
Adminstrative Console.
- 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.
- Click 'Finish'. You now must restart the WebSphere server and enter the
Server user ID and password when re-opening the Administrative Console.
- Open the 'Create Enterprise Application' wizard and enter 'MQSeries Workflow'
as application name, then click 'Next'.
- Open the 'Web Applications' node, select 'MQWFClient-<cfgID>', click 'Add',
click 'Next', then click 'Finish' (there is nothing to enter on the last
page).
- 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'.
- Enter 'MQSeries Workflow Web Client' as the Realm name. This is the text
the user will see on the browser's password prompt.
- Select the 'Basic' challenge type and optionally check the 'Use SSL' box
if you configured HTTPS.
- Click 'Finish' (again, there is nothing to enter on the last page).
- Open the 'Configure Security Permissions' wizard to configure
authorizations and select the 'MQSeries Workflow' leaf of the
'Enterprise Applications' node. Then click 'Next'.
- On the 'Permissions' page, select all permissions by pressing Ctrl-A, then
click 'Next'.
- 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...)
- 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.
- Click 'Next'. On this page, you can check that the permissions have been
granted by opening the trees. Click 'Finish'.
- 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).
- 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.
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.
- Shutdown the IBM HTTP server if it is running.
- Create a self-signed certificate (sufficient for demonstration purposes):
- Start the Key Management utility that comes with IBM HTTP Server.
- Select the 'Key Database File' - 'New...' menu option.
- 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.
- 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.
- Select the 'Create' - 'New Self-Signed Certificate...' menu option.
- Enter 'WebClient' as the 'Key Label' and fill in all information about
your organization. Then click OK to create and save the certificate.
- Close the Key Management utility.
- Make sure Apache Tomcat is configured and start it at
least once.
- EF tbd: What about ApacheModuleJServ.dll?
- Edit the
<IHSDir>/conf/httpd.conf
file and add the
following line at the end:
Include "<TCDir>/conf/tomcat-apache.conf"
|
- To run the Web Client using HTTPS:
- Start Apache Tomcat (this must be done before starting IBM HTTP Server
so that the
tomcat-apache.conf
file is up to date).
- Start IBM HTTP Server.
- Start your Web browser and point it to
https://localhost/MQWFClient-<cfgID>/RTC.html
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.
- 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.
- You must restart all application servers using the virtual host for the
changes to become effective.
- Create a self-signed certificate as described above.
- Go to the
<IHSDir>/conf
directory and make a backup
copy of httpd.conf
.
- 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.
- 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
|
- 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:
- 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.
- To run the Web Client using HTTPS:
- Start IBM HTTP Server.
- In the WebSphere Administrative Console, select the
'MQSeries Workflow WebClient' server from the Topology Tree and click
the start button.
- Start your Web browser and point it to
https://localhost/MQWFClient-<cfgID>/RTC.html
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.
- Go to the
<JamesDir>/bin
directory and start the
run.bat
script.
- 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.
- 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.
- 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.
- 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.
- 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.
- Start Outlook Express and select the 'Tools' - 'Accounts...' menu
option.
- Click the 'Add' button and select the 'Mail...' option.
- Enter the descriptive name of the mail user, for example,
'Workflow Admin'. Then click 'Next'.
- 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'.
- Select 'POP3' as incoming mail server type. Enter 'localhost' in
both the 'Incoming mail server' and 'Outgoing mail server' fields, then
click 'Next'.
- 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'.
- Click 'Finish' to create the new account.
- Select the newly created account (named 'localhost') on the 'Mail'
page of the dialog box and click the 'Properties' button.
- 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.
- Close the 'Internet Accounts' dialog box. This concludes the
client-side configuration.
- When e-mail has been sent to this account, simply select the 'Workflow
Admin' option of the 'Send/Recv' button on the toolbar.