Customizing the MQSeries Workflow Web Client

You can customize the Web Client involving different levels of complexity:

Create custom pages for starting processes and for activity implementations

An easy-to-implement solution is to create custom HTML pages for activity implementations. How you can achieve this depends on the implementation of the checkOutWorkItemResponse() method of the Viewer used. The Web Client contains two ready-to-use Viewers: The DefaultViewer and the JSPViewer. The source code for both Viewers is provided in the <MQWFDir>/smp/WebClient directory.

If you are using the DefaultViewer, activity implementations and process start forms (which are used to provide input data when starting a process) are loaded as HTML templates from the <MQWFDir>/WebClient/webpages/programs and <MQWFDir>/WebClient/webpages/processes directories. These HTML templates are a proprietary mechanism that were developed before JSPs were available. See the documentation of the DefaultViewer class for the substitution variables that are supported for the various response pages. It is recommended that you use JSPs, which provide greater flexibility than HTML templates.

If you are using the JSPViewer, activity implementations and process start forms can be implemented as JSPs. The JSPs are loaded from the <MQWFDir>/WebClient/webpages/programs and <MQWFDir>/WebClient/webpages/processes directories. Refer to the Java Server Pages section for details on how to develop JSPs for the Web Client.

Change pages provided or created by the Web Client

The second level of customization is to change the look and feel of the HTML pages that are created by the Web Client. There are two alternatives available. If the changes required are rather small, it can be sufficient to change several of the HTML templates (when using the DefaultViewer) or JSP files (when using the JSPViewer) that are provided. If you need more complex adaptions, you have to implement and register your own Viewer. This interface allows you to change the HTML response of every built-in command of the Web Client. The message flow is as follows:

Message flow for builtin commands

If a command is processed, the built-in command handler invokes the appropriate MQSeries Workflow APIs and stores the results in a bean. This bean is then passed to the registered Viewer, which transforms the bean into an HTML page, which is sent back to the client. By inheriting from an existing Viewer and overriding the needed commandResponse() methods (command is the name of some built-in command) or by implementing the entire Viewer interface, you can fully control the resulting pages. For a list of built-in commands, see the online documentation of the BuiltinHandler class.

Add new commands to the Web Client

The third level of customization is to add your own commands to the Web Client if you need additional commands to those offered by the built-in commands. This means that you implement and register your own CommandHandler. The message flow for this scenario is as follows:

Message flow for custom commands

If the Web Client receives a command that it does not recognize, it passes the command on to a custom handler, if one has been registered. The custom handler has to return the response page directly, because the built-in Viewer does not know how to render the results of custom handlers. For a list of the built-in commands see the API documentation of BuiltinHandler.

Note that you cannot overwrite built-in commands since they partly depend on each other. To avoid name clashes with future extensions to the Web Client, it is recommended to prefix your own commands with "x-". See also the Group Worklist - Tutorial, part 3.

Using properties

If you are deploying your own Viewer or CommandHandler, you can add their properties to the Web Client's WebClient.properties file. Add a new section with the settings you need. You can then access these properties programatically in the Viewer.init() and CommandHandler.init() methods.

Servicability considerations

If you are changing JSPs or other files that are part of this package, you must take care they are not overwritten by a Web Client update you install. It is recommended that you create your own copy of the files you need to change so that you can easily compare them with newer versions that come with a Web Client update and make the necessary changes in your files, if any. If you are customizing JPSs like ListViewer.jsp, you should create your own Viewer which extends JSPViewer and only overrides the methods that use the JSPs you customized.


© Copyright IBM Corporation 1999, 2001. All Rights Reserved.