Editing Web client properties

When you install the Web client, you specify the values of its main configurable properties. The properties are set in the WebClient.properties file. You can change the settings in this file, and can add your own properties to customize the Web client; for example, to the change the format for generated time fields or to specify the name of your own custom Viewer or CommandHandler class.

The WebClient.properties file consists of named sections that start with a [SectionName] line. All properties following this line are part of the section SectionName up to the start line of the next section. The following reference information describes the main settings that you can use for the Web client's own sections in the WebClient.properties file:

For more information about specifying property values when you install the Web client, see the part "The MQ Workflow Web client" in the WebSphere MQ Workflow Installation Guide.

For your own Web client properties you can add your own sections to the WebClient.properties file. For more details about using WebCLient.properties to customize the Web client, see Customizing the Web client.

The WebClient.properties file can contain more properties than described here, for example, properties that belong to the Web client samples. For a description of extra properties, see the Web client samples.

Starting with MQ Workflow 3.3 Service Pack 2, the default location for the WebClient.properties file is the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF directory. If the Web client configuration file is placed in this directory, you need not specify its location using the ConfigurationFile servlet initialization parameter. This addition was made in order to allow the creation of self-contained Web archives (.war files) according to the Servlet 2.2 specification. The ConfigurationFile servlet initialization parameter is still supported for Servlet 2.1 environments.

Note: When deploying .ear files, the WEB-INF directory may be in a location other than <MQWFDir>/cfgs/<cfgID>/WebClient. For example, when using IBM WebSphere Application Server V4 the fully-qualified directory name is <WASDir>/installedApps/MQWFClient_<cfgID>/fmcohcli.war/WEB-INF.

Note: You must ensure that the WebClient.properties file is located in the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF directory or set the ConfigurationFile initialization parameter in the servlet setup of your servlet container to point to this file. If your servlet container supports Servlet API V2.2, edit the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/WEB-INF/web.xml file to set the initialization parameter:
 <init-param>
  <param-name>ConfigurationFile</param-name>
  <param-value>><MQWFDir>/cfgs/<cfgID>/WebClient/WebClient.properties</param-value>
 </init-param>

If you change any properties in the WebClient.properties file, you need to restart the Web client servlet before the changes can be used, because the properties file is only read during initialization of the Web client servlet.

Settings for the [Servlet]

This section describes which properties you can set for the Web client servlet.

Setting Default Value Description
RootURI /MQWFClient-<cfgID> This property describes the root URI of the Web application of the Web client. It can be determined through the Servlet 2.1 APIs so you must set this property only if your application server does not support these APIs. To check whether the APIs are supported, enable logging, and check the resulting servlet.log file. The assumption is that <servletName>=<rootURI>+<servletPath> holds.
DocumentRoot <MQWFDir>/cfgs/<cfgID>/WebClient/webpages This property describes the document root directory Web application of the Web client. It can be determined through the Servlet 2.1 APIs so that you only must set thes property if your application server does these APIs. To check whether the APIs are supported, enable logging , and check the resulting servlet.log file. Check if the the following line exists: Root URI: <rootURI> is <documentRoot>. This setting is also useful if the Application server does not support seperate document root directories for each Web application.
OwnsHttpSessions true This setting controls whether the Web client creates and invalidates the HttpSession objects it uses to store session information between client requests. If this setting is set to false, the Web client servlet's context is responsible for managing the HttpSession object. See com.ibm.workflow.servlet.client.Main. If the Web client is not a standalone Web application but part of a more complex application, set the parameter to 'false' so that the servlet does not interfere with other objects while creating or invalidating HTTP session objects. You must then ensure that the HTTP session object already exists when the Web client receives a request.
RestoreHttpSessions false This setting controls whether the Web client will automatically restore expired HTTP sessions instead of splicing the logon page. This may lead to dangling Workflow sessions if the Workflow session timeout (default: 20 hours) is greater than the HTTP session timeout (default: 30 minutes). Those will be cleaned up when they have expired.
MaxRequestSize 64 This property describes the maxiumum size of HTTP POST requests (in kilobytes (KB)) which the servlet accepts. This limit serves to prevent 'denial of service attacks'.
AgentName MQWFAGENT This property describes the name of the Java Agent that is used to connect to the MQ Workflow system.
AgentLocator LOC_LOCATOR This property describes the locator policy that is used to find the Java Agent. This setting can be LOC_LOCATOR or JNDI_LOCATOR. The other locator policies (RMI_LOCATOR, OSA_LOCATOR, IOR_LOCATOR, and COS_LOCATOR) are deprecated and should no longer be used.
LOC_LOCATOR is the preferred method for accessing the MQ Workflow Java APIs because it eliminates the communication layer between the Java APIs and the Java Agent.
For JNDI, you must also set the AgentNamingFactory and AgentProviderURL.
AgentConfiguration   This property describes the configuration ID that is used for the Java Agent. If you use this setting, the AgentLocator setting is forced to LOC_LOCATOR.
AgentNamingFactory   This property describes the name of the naming factory class. This setting is only needed if you set AgentLocator to JNDI_LOCATOR.
AgentProviderURL   This property describes the URL where the Java Agent has been registered. This setting is only needed if you set AgentLocator to JNDI_LOCATOR.
LogoffOnDestroy true This setting controls that the servlet logs off all currently logged-on users when the servlet is unloaded by the servlet container. Do not change this setting.
Logfile   This property controls the logging for the servlet. If you set this property, all major events are written to the specified log file. Use forward slashes when you specify the path (for non-Unix platforms, too). You cannot delete or move the log file while the application server is running.
DateFormat dd.MM.yyyy This is the format for the generated date fields. For more information about the possible values, see the JDK documentation for class java.text.SimpleDateFormat.
TimeFormat HH:mm:ss This is the format for the generated time fields. For more information about the possible values, see the JDK documentation for class java.text.SimpleDateFormat.
CommandHandler   This property sets the name of a class that implements the CommandHandler interface, which is used to handle custom commands or to extend built-in commands.

If CommandHandler is set to com.ibm.workflow.servlet.sample.CommandHandlerAdapter, you can use multiple CommandHandlers in parallel. Those CommandHandlers must be defined in the [CommandHandlerAdapter] section of the WebClient.properties file. The sample CommandHandlers shipped with the Web client are already in this section and can be activated.

DefaultViewer com.ibm.workflow.servlet.client.DefaultViewer This property sets the name of a class that implements the Viewer interface, which is used to create the customizable pages. The DefaultViewer class provides backward compatibility with HTML templates. The JSPViewer uses JSPs instead of HTML template files to create the response pages.

Settings for accessing the Web client without a client session

These values are used to log on to the Workflow system in a 'Web user' scenario. In this scenario the ’anonymous login’ feature of the Web Client enables users to start business processes without needing to be known in the Workflow system. The UserID and password specified are used to logon and issue the createAndStartInstance command instead of a Workflow system user ID.

The StarterUserID cannot be used to access workflow by a normal logon from the Web client.

Setting Default Value Description
StarterUserID   This setting sets the user ID that is used to log on to the MQ Workflow system. If this user ID or the password is missing, you cannot use the 'Web user' feature.
StarterPassword   This setting sets the password for the specified user ID.
StarterSystemGroup   This setting sets the system group in which you want to start the processes. If this setting is not provided, the default system group is used.
StarterSystem   This setting sets the system within a system group in which you want to start the processes. You are recommended not to use this setting so that you can enable WebSphere MQ clustering.

Settings for the [DefaultViewer]

In the WebClient.properties file, you can also define which areas of the Web client you want to have enabled. If an area is disabled, it cannot be accessed from the drop-down navigator in the Web client. These settings are also used by the JSPViewer subclass of DefaultViewer.

Setting Default value Description
EnableLists true This setting enables the access to the "main" list of lists.
EnableWorklists true This setting enables access to worklists.
EnableTemplatelists true This setting enables access to templatelists.
EnableInstancelists true This setting enables access to instancelists.
AutoRefresh false This setting controls if a list is refreshed automatically after an item has changed. If you set this value to false, only the item that has changed is refreshed. If an item has been deleted, it is removed from the list. If you set this value to true, the entire list is always refreshed when an item has changed. Do not use this value if there are many users connected to the Web client, because this has a noticable performance impact on the MQ Workflow server.
PageAfterLogoff {_HTMLDir_}/Logon.html This setting defines the URL of the page that you want to be displayed after the client is logged off. The default setting is to display the logon page again. The JSPViewer does not use this setting.
GenerateForms true If you set this value to true, a form is generated from the input container when the HTML template file to start a process (Viewer.createAndStartInstanceResponse()), or the HTML template file to start an activity (Viewer.checkOutWorkItemResponse()) does not exist. If you set this value to false, an exception is thrown instead.

Settings for the [CommandHandlerAdapter]

If CommandHandler is set to com.ibm.workflow.servlet.sample.CommandHandlerAdapter, you can use multiple CommandHandlers in parallel. Those CommandHandlers must be defined in the [CommandHandlerAdapter] section of the WebClient.properties file. Each CommandHandler must be given a unique number, in the order in which you want the CommandHandler Adaptor to search for custom commands. The numbers must be assigned in a continuous sequence, starting with 0 (as shown in the following example).

The sample CommandHandlers shipped with the Web client are already in this section and can be activated.

#com.ibm.workflow.servlet.sample.HTMLDocHandler             = 0
#com.ibm.workflow.servlet.sample.StarterPEAHandler          = 1
#com.ibm.workflow.servlet.sample.BasicAuthenticationHandler = 2
#com.ibm.workflow.servlet.sample.AuditTrailHandler          = 3
#com.ibm.workflow.servlet.sample.EmailHandler               = 4