How to use the Web Client Extensions

With the Web Client Extensions Version 1.0, you can reuse the data that has been used to instantiate an existing process, and you can interrupt and resume activity implementations if required. To improve the usability of the Web Client, you can now use multiple JSPs for implementing a single activity. Finally, a framework for user-exit functions is provided, so that you can define user-exits according to your needs.

This document contains the following sections:

  1. Reusing process instantiation data
    This section describes the steps that are necessary if you want to reuse existing data for instantiating a process.
  2. Suspending and resuming activitiy implementations
    This section describes the setup for suspending and resuming an activity that is currently being executed.
  3. Using multiple JSPs for a single activity implementation
    This section describes how you can implement a single activity by using more than one JSP. With this function, you can provide a variety of Web interfaces.
  4. Using the framework for user-exit functions
    This section describes how you can use the user-exit framework to develop, for example, additional checking routines for the activity implementation.
  5. Adding a resource file to the Web Client Extensions to support your language
    This section describes how you can add National Language Support (NLS) to the Web Client Extensions.

Reusing process instantiation data

This section describes how you can reuse the data of "finished" processes for the instantiation of new process instances. With this function, you can reduce the effort of entering the same data more than once.

How to customize the WebClient.properties file

To reuse existing process data, you must register a command handler and a bean ID. Therefore, you must modify the WebClient.properties file. This step is necessary only once. Change the settings as follows:

  1. To register a command handler, set:

    [CommandHandlerAdapter]
    com.ibm.workflow.servlet.clientx.wext.ReuseProcessDataHandler = n
    ("n" is an index number that is listed in the Command Handlers list.)

  2. To change the bean ID, set:

    [WebClientExtentions]
    DataBeanID=reuseData

You can choose any name for the data bean ID. If no ID is specified, the default ID is used ("reuseData").

How to change your process definition

You can change the definition of a process by using the MQSeries Buildtime component. You can only reuse data for processes for which you have set the 'keep finished' flag. If you want to reuse process data, make sure that finished processes are kept in the MQSeries Workflow system. Therefore, set the process properties in the MQSeries Workflow Buildtime accordingly. In the process properties window, specify a time frame for keeping the processes, or select "forever".

The following figure shows the process properties page in the MQSeries Workflow Buildtime component:

How to change your activity implementation JSPs

After you have customized the Web Client properties file, you must edit the JSP file(s) that correspond to the process instance. Depending on your needs, you can use an existing JSP, or create a new one. The JSPs of a process instance are stored in the "process" directory of the document base directory with the name of workflow definition. For example, the JSP for the process instance of the travel expense activity TEA)is stored as "<webpages>/process/TEA.jsp", where <webpages> represents the document base directory of the MQSeries Workflow Web Client.
For example, <webpages> is the following directory:

.

Changing the JSP

Changing the JSP for reusing process instantiation data includes the import declaration of the "com.ibm.workflow.servlet.clientx.wext.*" package, and the "jsp:useBean" tag for the "reuseData" beans as shown in the following example:


<%@ page import="com.ibm.workflow.servlet.clientx.wext.*" %>


<jsp:useBean id="reuseData" scope="request"
class="com.ibm.workflow.servlet.clientx.wext.ReuseData"
type="com.ibm.workflow.servlet.clientx.wext.ReuseData"/>



In the example, the default ID is used for the reuseData bean. If you have specified a different ID in the WebClient.properties file, use the one you have specified.

How to reuse the stored data for form fields:

The "reuseData" bean stores the data that is used for the instantiation of a different process instantiation. You can retrieve the data from the bean, and use it as default entries or or default values for the form fields. The following example shows how you can set default values for the fields "FirstName" and "LastName".

FirstName <INPUT type="text" name="FirstName" value="<%=reuseData.getHTMLValue("FirstName")%>"><br>
LastName <INPUT type="text" name="LastName" value="<%=reuseData.getHTMLValue("LastName")%>"><br>


If you want to know which Java methods you can use for this bean, refer to the Java API documentation.


Suspending and resuming activities

This section describes how you can suspend one or more activities that are currently being executed, and resume them again when required.

How to customize the WebClient.properties file

If you want to use the suspend/resume function, you must register a command handler and a bean ID. Therefore, you must modify the WebClient.properties file. Change the settings as follows:

  1. To register a command handler, set:

    [CommandHandlerAdapter]
    com.ibm.workflow.servlet.clientx.wext.RestartAsDraftHandler = n
    ("n" is an index number which is listed in the Command Handlers list.)


  2. To change the bean ID, set:

    [WebClientExtensions]
    DataBeanID=reuseData

You can choose any name for the data bean ID. If no ID is specified, the default ID is used ("reuseData").

How to change your process definition

To restart an activity, the corresponding data (also called 'draft data') is stored in the output container of the activity. If you want to use the suspend/resume (save as draft/restart) function, make sure that the attribute is set to "manual exit" in the program activity properties page. If this attribute is set in MQSeries Workflow Buildtime, the activity will not be completed automatically. The following figure shows the program activity properties page in the MQSeries Workflow Buildtime component.

How to change your activity implementation JSPs

After you have customized the WebClient.properties file, you must edit the JSP file that is used for the activity implementation. Depending on your needs, you can use an existing JSP, or create a new one. The JSPs for the activity implementation are stored in the "program" directory of the web document base directory with the name of the activity implementation. For example, the JSP for the activity associated with the program "JTEAINPUT" is stored as "<webpages>/program/JTEAINPUT.jsp."

Changing the JSP

Changing the JSP for suspending/resuming an activity includes the import declaration of "com.ibm.workflow.servlet.clientx.wext.*" package, and "jsp:useBean" tag for the "reuseData" beans. The following sample shows an initialization of JSPs for the process instantiation:


<%@ page import="com.ibm.workflow.servlet.clientx.wext.*" %>

<jsp:useBean id="reuseData" scope="request"
class="com.ibm.workflow.servlet.clientx.wext.ReuseData"
type="com.ibm.workflow.servlet.clientx.wext.ReuseData"/>

In the example, the default ID is used for the reuseData bean. If you have specified a different ID in the WebClient.properties file, use the one you have specified.

Defining the form tag

Because the extension of the MQSeries Workflow Web Client uses extended add-on handlers, define the form tag of the JSP with the extended method. The following definition posts the form data with the command "x-checkInWorkItem". You can replace the action by JavaScript which is invoked, for example, when you click the 'submit' button. Example:

<FORM method="post" action='<%=context.getCommand("x-checkInWorkItem", workItem.persistentOid())%>'>

Defining the input tag

If you want to use the suspend/resume (save as draft/restart) function, restore the saved data values to each field of a JSP. Each field has the attribute to display a default value. The default values are retrieved from the "reuseData" bean. The Java documentation that is provided with this support pac contains a list of methods that you can use to retrieve data. Example:

<INPUT type="text" name="RequesterORG.MangName" value="<%=reuseData.getHTMLValue("RequesterORG.MangName")%>">

Defining buttons

To use the suspend/resume function, you must use the following (additional) commands to submit the form data. These are:

  1. "x-completeWorkItem"

  2. The "x-completeWorkItem" command executes the check-in and completes the activities. The standard "checkInWorkItem" command does not complete the activities because the attribute of the activities is set to "manual exit".
  3. "x-checkInWorkItem"

  4. The "x-checkInWorkItem" command triggers the suspending of an activity. The activity is checked in and the data is stored in the output container.
  5. "x-retrieveDraftWorkItem"

  6. The "x-retrieveDraftWorkItem" command cancels the check-in command and retrieves the saved data. You can use this data for further processing. during the session. You can use the standard "cancelWorkItem" command of the MQSeries Workflow Web Client for the JSP. Note that the "cancelWorkItem" command also cancels the suspended data. If you use it, you must restart the activity.

Example:

<input type="button" name="completeWorkitem" value="Complete Activity" onClick="this.form.action='<%=context.getCommand("x-completeWorkItem", workItem.persistentOid())%>';this.form.submit();">

<input type="button" name="checkinWorkitem" value="Save as Draft" onClick="this.form.action='<%=context.getCommand("x-checkInWorkItem", workItem.persistentOid())%>';this.form.submit();">

<INPUT type="button" name="retrieveDraftWorkItem" value="Cancel (Back to Saved Draft)" onclick="this.form.action='<%=context.getCommand("x-retrieveDraftWorkItem", workItem.persistentOid())%>';this.form.submit();">

<INPUT type="button" name="cancelWorkItem" value="Cancel (Destroy Saved Draft) " onclick="this.form.action='<%=context.getCommand("cancelWorkItem", workItem.persistentOid())%>';this.form.submit();">

Notes:

To store the data of the suspended activity, output container is used. Further, the output container of the activity is cleared when the activity is checked out. Therefore, you must use one of the commands described above to handle the respective activity. Note that if you use the 'Back' button of the browser, at the resumed activity the data of any suspended activity is lost.

Using multiple JSPs for a single activity implementation

This section describes how you can implement a single activity by using more than one JSP. With this function, you can provide a variety of Web interfaces, and easily insert complex data sets in a JSP.

How to customize the WebClient.properties file

To use more than one JSPs for a single activity implementation, you must register a command handler and a bean ID. Change the settings as follows:

  1. To register a command handler, set:

    [CommandHandlerAdapter]
    com.ibm.workflow.servlet.clientx.wext.ChangePageHandler = n
    ("n" is an index number that is listed in the Command Handlers list.)

  2. To change the bean ID, set:

    [WebClientExtensions]
    DataBeanID=reuseData
    PageID=x-pid

You can choose any name for the dataBeanID (default="reuseData"), and the PageID (default="pageController"). If no IDs are specified, the default IDs are used. The PageID is used for the argument name in the "change pages" Web request.

How to change your activity implementation JSPs

After you have customized the WebClient.properties file, you must edit the JSP so that you can use multiple JSPs for one activity implementation. In the following, we use the term "main JSP" for the JSP which is directly invoked for check out operation. The main JSP is stored in the program directory of the web document base with the name of the activity implementation. For example, the main JSP for the activity associated with the program "JTEAINPUT" is stored as "<webpages>/program/JTEAINPUT.jsp." In the JSP, you can implement this function as follows:

Changing the JSP

Changing the JSP for using multiple JSPs for one activity implementation, includes the import declaration of the "com.ibm.workflow.servlet.clientx.wext.*" package, and the "jsp:useBean" tag for the "reuseData" and the "pageController" beans. The following sample shows a complete initialization of JSPs for the process instantiation. In this sample, the default IDs are used for the beans.


<%@ page import="com.ibm.workflow.servlet.clientx.wext.*" %>

<jsp:useBean id="pageController" scope="session"
class="com.ibm.workflow.servlet.clientx.wext.PageController"
type="com.ibm.workflow.servlet.clientx.wext.PageController"/>

<jsp:useBean id="reuseData" scope="request"
class="com.ibm.workflow.servlet.clientx.wext.ReuseData"
type="com.ibm.workflow.servlet.clientx.wext.ReuseData"/>

You must also specify code for the initialization of the "multiple JSP pages" support. The following example shows the "if" statement that is required to transfer the data between the JSP pages. The information for navigating through the pages is registered in the pageController bean by using the "putPage" method. The following initialization is required only for the main JSP that is invoked when the activity is checked out.

if (pageController.getReuseData() != reuseData) {
    pageController.setReuseData( reuseData );
}

pageController.initPage();
pageController.putPage("1", "/programs/JTEAINPUT.jsp");
pageController.putPage("2", "/programs/JTEAENTINPUT.jsp");

Defining a page change button

The page change request is sent to the web server as web post request. The form data must be submitted with the appropriate command, which generally is implemented as a button. The following sample shows a button that requests to move to the page "2". The button uses Java Script to change the request command to "changePage". The argument of the "x-pid" shows the target ID that is registered in the pageController bean. When the PageID is modified in the WebClient.properties file, you must use the modified PageID.

<INPUT type="button" name="changePage" value="Goto Page2" onclick="javascript:{ this.form.action='<%=context.getCommand("changePage", workItem.persistentOid(), "&x-pid=2")%>'; this.form.submit(); }">

Defining an input tag

To define how the data is passed between the multiple JSPs, the reuseData bean is used in the same way as for the other functions. Example:

<INPUT type="text" name="RequesterORG.MangName" value="<%=reuseData.getHTMLValue("RequesterORG.MangName")%>">

Using the framework for user-exit functions

This section describes how you can use the framework to define user-exits according to your needs. For example, you can specify code that provides evaluation data before or after a certain Web command is executed. Because the code is specified in JSPs, you need not know how to compile and publish this code. The data is evaluated on Web servers, therefore you can use any Web browser. By using the user-exit functions, you can also check an enterprise database, for example. You can specify the following exit functions:

How to customize the WebClient.properties file

To use the user-exit framework, you must register a command handler and a bean ID. Therefore, you must modify the WebClient.properties file. Change the settings as follows:

  1. To register a command handler, set:

    [CommandHandlerAdapter]
    com.ibm.workflow.servlet.clientx.wext.PageEventHandler = n
    ("n" is an index number that is listed in the Command Handlers list.)

  2. To change the bean ID for the PageController, set:

    [WebClientExtensions]
    PageBeanID=pageController

If no ID is specified, the default ID ("pageController") is used.

How to change your activity implementation JSPs

After you have customized the WebClient.properties file you must edit the JSP for the activity implementation so that you can use the user-exit framework. The JSP is stored in the program directory of the web base with the name of the activity implementation. For example, the JSP for the activity associated with the program "JTEAINPUT" is stored as "<webpages>/program/JTEAINPUT.jsp."

Changing the JSP

To define the user exit, you must use the "pageController" bean and implement it as follows:


<%@ page import="com.ibm.workflow.servlet.clientx.command.*" %>


<jsp:useBean id="pageController" scope="session"
   class="com.ibm.workflow.cus.PageController"
   type="com.ibm.workflow.cus.PageController"/>


<%

pageController.setEventListenerObject(this);

%>

Defining a user-exit function

This JSP provides samples to show how you can use the user-exit function. There are two types of user exits. The one user exit is invoked before the page change is requested, the other is used for the check-in. According to the sample, the user exit for "page change" checks the maximum size of the travel expense entries, which is limited to 5 entries. If you request more than 5 entries, an error message is set to the reuseData bean and the main page that displays the error message is returned. The user exit for the CheckIn checks, whether the Manager Field is null. It returns the same page as the "page change" to show the error message. You can implement the user-exit samples in JavaScript. You can also use more complex user exits with the provided framework. For example, a check routine can be developed that uses data that is located in the enterprise database. This is possible because the user exits are evaluated on a Web server. Example:

<%!
public ResponsePage queryPageChange(RequestContext context, PageController pageController, PostedValues values) {

  ReuseData reuseData = pageController.getReuseData();
  int entmax = 5;
  context.log("executed queryPageChange", false);
  String page = values.getParameter("TmpTarget");
  int tmp = new Integer( page ).intValue();
  if (tmp < entmax ) return null;
    reuseData.setValue("ERR", "Enpense entry is limited to "+entmax);
  return new ResponsePage(context, "/programs/JTEAINPUT.jsp");
}


public ResponsePage queryCheckInWorkItem(RequestContext context, PageController pageController, PostedValues values) {

  ReuseData reuseData = pageController.getReuseData();
  context.log("executed queryCheckInWorkItem", false);
  String man = values.getParameter("RequesterORG.MangName");
  if (man == null)
    man = reuseData.getValue("RequesterORG.MangName");

  if (man != null && man.length() != 0) {
    reuseData.setValue("ERR", "");
    return null;
  }

  reuseData.setValue("ERR", "Manager field is required");
  return new ResponsePage(context, "/programs/JTEAINPUT.jsp");
}
%>

Notes:

The described exit functions can only be invoked when you request the extended Web commands. So the exit functions "queryCheckinWorkItem" and "postCheckinWorkItem" can only be invoked if you request the Web commands "x-completeWorkItem" and "x-checkInWorkItem". The exit function "queryPageChange" is invoked when the Web command "changePage" is requested. The exit function "postCancel" is invoked when the Web commands "x-retrieveDraftWorkItem" and "x-cancelWorkItem" is requested.
The prefixes of the commands "query" and "post" mean "before the evaluation of web command", and "after the evaluation of web command", respectively.

Adding a resource file to the Web Client Extensions to support your language

This section describes how you can add a resource file for different languages to the Web Client Extensions.
The Web Client Extensions V1.0 support pac includes button descriptions that are displayed when you click a command button with the mouse. These descriptions are contained in a resource file. The Web Client Extensions V1.0 support pac supports the following languages:

If you want to use a different language for the Web Client Extensions, add the respective resource file as follows:

  1. Copy the resource file WExtResource.properties, which is located in the same directory as the source files of the Web Client Extensions, to WExtResource_xx.properties, where xx represents the language you want to use.

    The contents of the WExtResource.properties file is as follows:

    Command.ReuseAndStartInstance=Reuse Process Data
    Command.RestartAsDraftWorkItem=Resume Suspended Item

  2. Edit the new properties file and translate these descriptions into your language. Then, save this file.
  3. Translate the new properties file with the "native2ascii.exe" tool of JDK.
  4. Bind this properties file into a new jar file, fmcojext.jar.


© Copyright IBM Corporation 2001. All Rights Reserved.