As the MQ Workflow Client, you can use the Web client to perform several tasks, such as creating worklists, starting and stopping process instances, and starting and stopping activities. This section describes how the Web client handles manual and automatic activities.
Although you can perform similar tasks with both clients, there is a major difference between the setup of the MQ Workflow Client and the Web client. In contrast to the MQ Workflow Client, the Web client does not require MQ Workflow to be installed on the client machine, it only requires a Web browser. This means that the client machine, as a rule, has no WebSphere MQ and no Program Execution Agent (PEA) installed. The following sections describe the different ways to execute activities with the Web client without using a Program Execution Agent.
Note:
The Web client is a piece of code that is running on the application server machine, therefore it cannot start programs on the client machine. This means that you must manually start the PEA or
Note:
A PEA executes programs for an MQ Workflow user and is therefore suited for interactive programs that must be started on the client machine. Each client has an own PEA installed. In contrast, a
Manual activities are displayed as work items on the worklists of the respective eligible users as soon as they are in 'ready' state. A work item can be started or checked out by selecting it from the worklist.
If the Web client starts a work item from the worklist by using the
The MQ Workflow Execution Server sends a program invocation request to the modeled Program
Execution Agent (PEA) or (User-defined) Program Execution Server (startAllowed
request
parameter of the
checkOutWorkItem command is set to true
, which is the case for the standard
worklist, the Web client will start the work item.
To start an activity manually from the Web client, you can either:
startWorkItem
command instead
of the checkOutWorkItem
command.EJBs are not supported 'out of the box' by MQ Workflow so that you cannot model your processes in the MQ Workflow Buildtime to invoke EJBs. However, you can start any activity implementation manually from the Web client by unchecking the 'Program activities can be checked out' flag or by writing your own worklist as described above. The API Samples Support Pac, which is available on the Web, describes how to invoke EJBs in general.
Because most of the manual activities are interactive and there usually is no Program Execution Agent (PEA) installed on the client machine, the standard method for starting a work item is to check it out. Checking out a work item also is the only way to display it in the Web browser window. Starting a work item launches an external program which may require the user to switch to another window.
If the checkout was successful, the default behavior of the Web client is as follows:
It sends a Java Server Page (JSP) to the Web browser that contains a form with the input container data. When this form is submitted, the servlet of the Web client maps the form fields to output container elements. Then, the work item is checked in. The section Invoking Java Server Pages (JSPs) contains an example that describes this behaviour. For further details, also refer to the source code of DefaultViewer
and JSPViewer
, which are part of the Web client. In the sample source code, check the checkOutWorkItemResponse()
method.
This is the recommended method to implement manual activities with the Web client. The JSPViewer
class supports this method by mapping the name of the program assigned to an activity to a JSP. Apart from the name, the Web client ignores all other program settings modeled in the Buildtime component. If
the JSP for a program cannot be found, the Web client either throws an exception or generates an HTML form that is based on the input container and output container layouts. This depends on the
GenerateForms setting.
Activity A has the program DoSomething assigned. The checkOutWorkItem
command is invoked on a work item of activity A. The JSPViewer
checks out the work item first, then forwards the request to the <MQWFDir>/cfgs/<cfgID>/WebClient/webpages/programs/DoSomething.jsp JSP. This
JSP can then access the work item and container data by including the following code:
<%@ page language="java" info="JSP activity implementation" %> <%@ page import="com.ibm.workflow.api.*" %> <%@ page import="com.ibm.workflow.servlet.client.*" %> <jsp:useBean id="context" scope="request" type="com.ibm.workflow.servlet.client.RequestContext"/> <html> <body> <% ReadOnlyContainer inData = context.getContainer(); WorkItem workItem = context.getWorkItem(); %> : <%=context.openForm("checkInWorkItem", workItem.persistentOid())%> : <input type="submit" name="submitData" value="Complete work item"> <input type="button" name="cancel" value="Cancel" onClick="javascript:{location='<%=context.getCommand("cancelWorkItem", workItem.persistentOid())%>';}"> </form> : </body></html>
The openForm()
method used above is a convenient method that generates the following piece of HTML:
<form method="post" action="<%=context.getServletName()%>"> <input type="hidden" name="command" value="checkInWorkItem"> <input type="hidden" name="id" value="workItem.persistentOid()">
Explanation:
If the created HTML form is submitted to the servlet, the HTTP request contains a parameter for each input
field of the form. When the request arrives, the Web client reads all request parameters and checks for each parameter if the output container of the activity contains a member with the same name. If the Web client finds a member with the same name, the respective output container member is filled with the value of the corresponding request parameter. The other request parameters are ignored, except for command
and id
.
Note:
You cannot retrieve the output container of the work item in the JSP and fill it, because these values are overwritten by the checkInWorkItem()
method of the servlet. If you want to set some output container values by coding instead of letting the user enter the values, you can use hidden form fields. You can also use this method to pass container values that have already been set in earlier steps of the process.
The directory <MQWFDir>\scenario\credit\programs contains a sample JSP, named
NCollectCreditData.jsp
.
The Application Data Integration sample is a more elaborate sample. It shows how you can include data in the HTML page that is retrieved from a different source than the MQ Workflow database. In addition, it shows how to store changes to this non-workflow data using a JSP.
You can run applets in the browser of the client by creating a JSP for the activity that contains the appropriate <applet>
tags.
To use an EJB from within an activity implementation JSP, you must:
You can include the data that is retrieved this way in the HTML page that is sent to the browser, or use the data from a submitted form to update an EJB when the work item is checked in. If you want to use data from a submitted form, use the method described in the Application Data Integration sample.
Invoking automatic activities is outside the scope of the Web client because there are no work items for these activities. If you want to invoke automatic activities, you need a Program Execution Agent (PEA) or a User-defined Program Execution Server (UPES). Automatic activities are started automatically by the MQ Workflow Execution Server as soon as they are in 'ready' state. Automatic activities are not displayed on worklists. This only happens if the activity fails and is set to 'InError', so that manual intervention is required.
Depending on the process model, the execution server tries to find one of the following components if an automatic activity is scheduled:
A work list displays the work items that are available. The work item that you select is checked out. Then, the corresponding JSP is invoked. On a worklist, only manual activities are displayed.
The Web client provides a framework that you can extend to select and check out manual activities automatically, although you cannot invoke automatic activities as JSPs. The MQ Workflow Server still handles these activities as manual activities, because it is not the execution server that starts them. Instead, the framework extension of the Web client checks out the activities. The coding for extending the Web client framework is as follows:
Viewer
class that inherits from the built-in JSPViewer
.
The source code for the JSPViewer is provided in the <MQWFDir>/smp/WebClient
directory.logonResponse()
method so that the work list is not returned by
forwarding to the ListViewer.jsp. Instead, select a work item and call the
BuiltinHandler.checkOutWorkItem()
method, and the
JSPViewer.checkOutWorkItemResponse()
method. Then, the first work item after logon is sent to the client browser.checkinWorkItemResponse()
method and apply
the same methods as for the first work item.