MQSeries Workflow - Web Client Extensions contains a sample application to show how you can use its functions. The sample describes the process of a travel expense approval as it can be performed within any company.
This document explains:
The sample application contains the following files:
The following description gives you an overview of the steps that you must perform to set up this sample application. For a detailed description of how to set up a Web Client application within MQSeries Workflow, refer to the on-line documentation of the MQSeries Workflow Web Client.
To set up the sample application:
This section describes how you can use the sample application. It can be helpful for designing your own applications that use MQSeries Workflow - Web Client Extensions.
As for all MQSeries Workflow Web Client applications, you can start the TEA process from the process template list of the Web Client. Then, the "Travel Expense.jsp" is used to initialize the process. The following figure gives you an example of how the Web page can look like:
The TEA input activity is implemented by using the "Using-multiple-JSPs" function that is provided by the Web Client Extensions. You have the "JTEAINPUT.jsp" and the "JTEAENTINPUT.jsp". The "TEAINPUT.jsp" provides a Web page for the TEA input activity as follows:
On this page, the expense data is shown in the "Summary of Expense Items." table. To insert the respective expense items, select the "Add an Expense Item" button. When you click the button, another page is displayed, based on the "TEAENTINPUT.jsp". On this page, you can insert only one expense item. Click "Set Entry" when you have inserted the data. The following figure shows the "Expense Entry" page:
When you click "Set Entry", the inserted data is transferred to the main Web page, where it is added to the "Summary of Expense Items" table. If you want to change a table entry, click "Edit".
The number of expense items is limited to 5 by using the "User Exit" function provided by the Web Client Extensions. If you want to add more than 5 items, an error message is displayed . In addition to setting the limit to 5 expense items, the value check routine has been implemented by using "User Exit" function. This routine checks the Manager Name field.
The travel expense request page contains the following buttons:
When you suspend an activity (save as draft), the worklist of the user is displayed as follows:
The activity state is "Executing" You can restart the activity by clicking the 'Restart' button (the red triangle).
Note:
When you restart an activity that contains suspended data by using the MQ Workflow restart function, instead of resuming it with the Web Client Extensions function, the suspended data of the activity is lost.
The next step within the Trravel Expense process is the approval of the travel expenses. This support pac does not provide a JSP or HTML page for the approval. Instead, this Web page is generated by the MQSeries Workflow Web Client.
If you use the reuse function provided by the Web Client Extensions, the completed process has an additional button. When you click this restart button, you can start another process with the same process template. Then, you can copy the process instantiation data to the new process instance of the Travel Expense Application. The following figure shows a completed travel expense process:
This sections contains helpful information that you can use for developing similar applications that utilize the functions provided by the Web Client Extensions.
The sample process of the Web Client Extensions contains the following workflow definitions: You can change these definitions according to your needs:
If you want to use the Web Client extensions, consider the following: To use the "suspend/resume" (save as draft/restart) function, make sure that the attribute of activity 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. For the Travel Expense Application, this attribute is set. The following figure shows the program activity properties page in the MQSeries Workflow Buildtime component:
To use the "Reuse" function of the Web Client extensions, you must set the "Keep finished processes" attribute in the Buildtime component to "Forever", or specify a time frame, as shown in the following figure:
The Web Client Extensions provides the following JSPs: A Travel Expense.jsp, a JTEAINPUT.jsp, and a JTEAENTINPUT.jsp. The implementation of the Web Client Extensions is similar for all JSPs. Therefore, you can use the the JSP that is described in this section as a reference. This section describes the JTEAINPUT.jsp, which is used as the main interface of the TEA input activity.
The JTEAINPUT.jsp contains four definitions to import Java packages; See the following example:
<%@ page import="com.ibm.workflow.api.*" %> |
The first three import definitions are used for the MQSeries Workflow Web Client (base product). The fourth definition is used for the Web Client extensions, which requires the "com.ibm.workflow.servlet.clientx.wext.*" package.
This JTEAINPUT.jsp contains three definitions to import beans; the first definition is used for the MQSeries Workflow Web Client (base product). The other definitions are used for the Web Client extensions. See the following example:
<jsp:useBean id="context" scope="request" |
The bean "com.ibm.workflow.servlet.clientx.wext.PageController" provides the function to support "multiple JSPs for a single activity". It must have the session scope, and the ID must be identical with the ID that you have defined in the WebClient.properties file. (The default is "pageController"). The bean "com.ibm.workflow.servlet.clientx.wext.ReuseData" provides the function to support the "suspend/resume" and the "reuse of instance data" functions. It must have the request scope, and the ID must be identical with the ID that you have defined in the WebClient.properties file. (The default is "reuseData").
The initialization of the pageController bean is used to define the transition rules for the multiple JSPs function. The first "if" statement sets the reuseData to pageController to pass the data to the other pages. The "initPage()" method initializes the transition rule stored in the pageController bean. In the Web request, the "putPage()" method sets a transition rule. This JSP file is identified by "1", and the "JTEAENTINPUT.jsp" is identified by "2". Specify this statement in the main JSP file which is called when the activity is started.
The "setEventListenerObject()" is used for initializing the "User Exit" functions. It is necessary for defining user-exit functions within the JSP. See the following example:
if (pageController.getReuseData() != reuseData) { |
Because the Web Client extensions use extended add-on handlers, it is recommended that you define the form tag of the JSP with the extended method. The following definition shows the form data with the "x-checkInWorkItem" command. You can replace the action by JavaScript which invokes, for example, submit buttons. See the following example:
<FORM method="post" action='<%=context.getCommand("x-checkInWorkItem",workItem.persistentOid())%>'> |
To use the suspend/resume (save as draft/restart) function in the JSP, the suspended data should be restored into each field. Each field has the value attributes to display the initial data value. Then, the value is retrieved from reuseData bean. The API documentation provided with this package, shows a list of methods that you can use to retrieve data. Example:
<INPUT type="text" name="RequesterORG.MangName" value="<%=reuseData.getHTMLValue("RequesterORG.MangName")%>"> |
The input page of each expense entry has implemented an own JSP file "JTEAENTINPUT.jsp". This sample contains a definition for a page-change button so that you can jump to a certain page. You can specify to which page you want to jump by specifying a value for the "x-pid" command. Depending on the value you specify, the corresponding page is displayed when you click the page-change button. (The target ID of the "x-pid" argument is registered in the pageController bean. Example:
<INPUT type="button" name="changePage" value="Add an Expense Item" onclick="javascript:{ document.forms[0].TmpTarget.value = '<%=j %>'; this.form.action='<%=context.getCommand("changePage", workItem.persistentOid(), "&x-pid=2")%>'; this.form.submit(); }"> |
There are four buttons to manage this activity. The function of each button is explained in How to use the sample application. The first three buttons are used to send the custom command to the Web server. 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();"> |
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 request, the other is for the check-in.
The user exit for the "page change" checks the maximum number of travel expense entries, which is limited to 5. If you request more than 5 entries, an error message is sent to the reuseData bean and the main page is returned to show the error message. The user exit for the check-in checks whether the Manager Field is null. It returns the same page to show the error message. Example:
<%! |