How to execute activities with the Web client

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 (U)PES that is necessary to handle 'start' requests.

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 (U)PES is not related to a particular user and is therefore suited for executing non-interactive programs. A UPES is usually installed on a server machine.

Manual activities

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.

Starting a work item

If the Web client starts a work item from the worklist by using the WorkItem.start() API, the system behaves as follows:

The MQ Workflow Execution Server sends a program invocation request to the modeled Program Execution Agent (PEA) or (User-defined) Program Execution Server ((U)PES). This also applies to automatic activities (see 'Automatic activities'). Because there usually is no PEA installed on the client machine, the default behavior is to check out the work items. Only if a work item cannot be checked out and the 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:

Using Enterprise Java Beans (EJBs)

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.

Checking out a work item

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.

Invoking Java Server Pages (JSPs)

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.

Example:

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.

Using Applets

You can run applets in the browser of the client by creating a JSP for the activity that contains the appropriate <applet> tags.

Using Enterprise Java Beans (EJBs)

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.

About using servlets

Automatic activities

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:

It is not possible to invoke automatic activities as JSPs because the execution server sends the corresponding invocation requests directly to the PEA or to the UPES.

Invoking Java Server Pages (JSPs) automatically

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: