D User Task 2.0 Macro

D.3.1.1 Defining a Partner Link for the TaskManager Service

You need a partner link in your process to indicate that you are calling the TaskManager service from your BPEL process (just as for any other Web service). The WSDL file for the TaskManager service can be found on your local Oracle BPEL Process Manager installation at this location:

http://localhost:9700/orabpel/default/TaskManager/TaskManager.wsdl

The outcome of adding the partner link is as illustrated in the TaskSample process referenced in the See Also note. The deployment descriptor bpel.xml file references the TaskManager service WSDL file, as shown below.

<properties id="reviewManager">
   <property name="wsdlLocation">
      http://localhost:9700/orabpel/default/TaskManager/TaskManager?wsdl
   </property>
</properties>

The BPEL process definition in the TaskSample.bpel file uses this property to define a partner link for the TaskManager.

xmlns:task="http://services.oracle.com/bpel/task"
.
<partnerLink name="reviewManager"
             partnerLinkType="task:TaskManager"
             partnerRole="TaskManager"
                myRole="TaskManagerRequester"/>

D.3.1.2 Declare and Initialize the Task Document

Before the TaskManager service can be invoked, a taskMessage must be constructed. The following BPEL code from TaskSample.bpel shows how to construct this message using the BPEL assign activity.

<scope name="review" variableAccessSerializable="no">
   <variables>
      <variable name="reviewTask"
                element="task:task"/>
...
</variables>
<sequence>
...
<assign name="configureTask">
   <!-- Assign 'title' in task document -->
   <copy>
      <from variable="input" part="payload"
         query="/stockReviewSheet/symbol"/>
      <to variable="reviewTask" query="/task/title"/>
   </copy>
   <!-- Assign 'assignee' in task document -->
   <copy>
      <from expression="string('jsmith@finance.com')"/>
      <to variable="reviewTask" query="/task/assignee"/>
   </copy>
   <!-- ... See the full source for the other field settings -->
   <!-- Assign 'attachment' in task document -->
   <copy>
      <from variable="input" part="payload"/>
      <to variable="reviewTask" query="/task/attachment"/>
   </copy>
</assign>

D.3.1.3 Initiate the Task

The next step in your BPEL process is to initiate the TaskManager by invoking its initiateTask operation, passing the data defined above. Specifically, you pass a taskMessage that you set up as a wrapper around the task document.

<scope name="reviewUserInteraction" variableAccessSerializable="no">
   <variables>
      <variable name="taskRequest" messageType="task:taskMessage"/>
      ...
   </variables>
   <sequence>
      <!-- Assign task document to taskMessage -->
      <assign name="setPayload">
         <copy>
            <from variable="reviewTask"/>
            <to variable="taskRequest" part="payload"/>
         </copy>
      </assign>
   <!-- Initiate task -->
   <invoke name="initiateTask"
           partnerLink="review"
           portType="task:TaskManager"
           operation="initiateTask"
       inputVariable="taskRequest"/>
      ...
   </sequence>
</scope>

This creates the task and assigns it to the assignee specified in the task document. The task is available to you through the Worklist Java API.

D.3.1.4 Task Completion

At this point, the task is created and assigned to the assignee specified in the task document and is available through the Worklist Java API.

The BPEL process waits for the TaskManager service to call it back. The callback passes back an updated taskMessage, indicating that the task has been completed or has expired.

<variable name=" taskResponse"
   messageType="task:taskMessage"/>
   ...
<!-- Receive the outcome of the task -->
<receive name="receiveTaskResult"
         partnerLink="review"
         portType="task:TaskManagerCallback"
         operation="onTaskResult"
         variable="taskResponse"/>
<!-- Read task document from taskMessage -->
<assign name="readPayload">
   <copy>
      <from variable="taskResponse" part="payload"/>
      <to variable="reviewTask"/>
   </copy>
</assign>

The receive activity shown above does not complete until a callback is received from the TaskManager service. As with all asynchronous activities, the BPEL process is dehydrated reliably during this time, and rehydrated and executed when the task completion (or expiration) event occurs.The type for the TaskManager service response data is the same taskMessage message type that was used for the initiate message. However, because the type for the attachment field is an XML schema anyType and is application-defined, the attachment data returned can be any type and specifically does not need to be the same type as the initiate message attachment.Typically, the conclusion field contains information that tells the BPEL process how the task was completed (for example, Approved, Rejected, or Canceled). This kind of information can also be passed through the attachment; it is up to the programmer to pass task data in the preferred manner.

D.3.3.1 List the Assigned Tasks

Using the Java Worklist API to the TaskManager service from the client perspective involves the following high-level steps. The code shown in this section is taken from C:\orabpel\samples\tutorials\110.UserTasks\TaskSampleUI\listTasks.jsp.

1. Use the com.oracle.bpel.client.Locator class to return a worklist service handle (an IWorklistService).

   <%@page import="com.oracle.bpel.client.Locator" %>
   <%@page import="com.oracle.bpel.services.task.IWorklistService" %>
      ...
      // Obtain a reference to BPEL domain 'default' using password 'bpel'
      Locator locator=new Locator("default", "bpel");
      IWorklistService worklist =
        (IWorklistService)
            locator.lookupService(IWorklistService.SERVICE_NAME);
   
   

2. Use the com.oracle.bpel.services.task.IWorklistService interface to fetch com.oracle.bpel.services.task.ITask objects, manipulate them, complete them, and so on.

<%@page import="com.oracle.bpel.services.task.ITask" %>
   ...
   ITask[] tasks=
      worklist.listTasksByAssignee("jsmith@finance.com");
   ...

You can fetch tasks by other criteria as well. For example, you can look up a task by its unique taskId assigned by the TaskManager service or based on a specified creator attribute (which is programmer-defined). You can also build an arbitrary search criterion using the com.oracle.bpel.client.util.WhereCondition utility class (for example, to fetch all the expired tasks assigned to a particular user). For more information, including full documentation on the interfaces for the classes used in the code in this section, see Oracle BPEL Process Manager API Javadocs (located at C:\orabpel\docs\apidocs\index.html).The code below shows how to iterate through the list of tasks in the JSP page and, for each task, display some basic descriptive information and a link that displays a details page (displayTask.jsp) for the task.

<h1>My Custom Task List Page</h1>
<table border="1">
<tr>
   <th>Title</th>
   <th>Due Date</th>
   <th>Priority</th>
</tr>
<%
   // Iterate through the list of tasks
   for (int i=0; i < tasks.length; i ++)
   {
      ITask thisTask=tasks[i];
      // We are interested in tasks assigned to "jsmith@finance.com"
      // and generated by the TaskSample BPEL process. Often the BPEL
      // process initiating a task will assign its name to the
      // creator field of the task document. This is at least the
      // case with the TaskSample BPEL process.
      if (! "TaskSample".equals(thisTask.getCreator()))
   {
      // This task has been generated by another BPEL process
      // and should therefore not be in the list.
      continue;
      }
      // Read the title assigned to the task. The title is to
      // a task what a subject would be to an email.
      String title=thisTask.getTitle();

      // Get the unique ID/key associated with this task.
      // This is passed from page to page to identify the
      // task the user is reviewing and completing.
      String taskId=thisTask.getTaskId();

      // Read the expiration date assigned to the task.
      Date expiration=null;
   if (thisTask.getExpirationDate() != null)
      expiration=thisTask.getExpirationDate().getTime();
   // Read priority associated with the task
   int priority=thisTask.getPriority();
%>
   <tr>
      <td>
      <a href="displayTask.jsp?taskId=<%= taskId %>">
         <%= title %></a>
      </td>
      <td>
      <%= expiration %>
      </td>
      <td>
      <%= priority %>
      </td>
   </tr>
<%
   }
%>
</table>

D.3.3.2 Display the Payload Data for a Task

The displayTask.jsp page invoked from the hyperlink in the code above gets passed a taskId (again, a unique string identifier generated by the TaskManager service) and uses the same Locator and IWorklistService objects as above to fetch the task associated with that taskId. Then, to manipulate the payload data associated with a task, it uses the facade capability, which provides a thin Java interface on top of arbitrary XML data. Note that facades are not at all like JAXB-style bindings because they do not attempt to fully map XML to Java. They merely provide a Java envelope for XML data that is then accessed through JavaBeans-style getter and setter functions. This enables facades to avoid all of the problems associated with JAXB bindings as schemas get complex.The facade construct is described in more detail in "Using an XML Facade to Simplify DOM Manipulation"; however, at a very high level, the basic steps for working with the XML facade are as follows:

1. Use the schemac Ant task (or command-line tool) in your build.xml script to generate facade classes for XML schema types. For example:

   <schemac input="${basedir}/TaskSample.wsdl"
            out="${basedir}/TaskSampleUI/WEB-INF/classes"/>
   
   

   This command generates the facade classes for the XML schema types described in TaskSample.wsdl, namely:

   <element name="stockReviewSheet" type="finance:StockReviewSheetType" />
   <complexType name="StockReviewSheetType">
      <sequence>
         <element name="symbol" type="string" />
         <element name="targetPrice" type="float" />
         <element name="currentPrice" type="float" />
         <element name="action" type="string" />
         <element name="quantity" type="int" />
         </sequence>
   </complexType>
   
   

   The facade classes generated include a factory for creating new instances of the StockReviewSheet element and then getter and setter methods for manipulating the data fields within the instances. If you want to review the exact interfaces exposed by the generated classes, you can either view the generated Java classes or create Javadocs for them by using the -j option to the schemac command.

2. Within your code, you can use the generated classes to manipulate instances of XML data types through a simple Java interface. The code below from C:\orabpel\samples\tutorials\110.UserTasks\ TaskSampleUI\displayTask.jsp uses the Locator and IWorklistService objects to fetch a particular task by taskId. It then gets the payload of the task, which is a W3C DOM element type, and uses that and the facade StockReviewSheetFactory class to instantiate a StockReviewSheet facade instance. Finally, the facade class getter and setter methods are used to fetch appropriate data fields from the payload and display them in the JSP page.

   <%@ page import="com.otn.samples.finance.StockReviewSheet" %>
   <%@ page import="com.otn.samples.finance.StockReviewSheetFactory" %>...
   
   Locator locator=new Locator("default", "bpel");
   
   IWorklistService worklist=(IWorklistService)
      locator.lookupService(IWorklistService.SERVICE_NAME);
   
   ITask task=worklist.lookupTask(taskId);
   
   // Get a reference to the XML StockReviewSheet document attached to the
   // task. If you look at the implementation of the TaskSample BPEL
   // process, you will notice that a StockReviewSheet element is assigned
   // to the task as an attachment.
   Element rsElement=(Element) task.getAttachment();
   
   StockReviewSheet srs =
      StockReviewSheetFactory.createFacade(rsElement);
   // Use the friendly bean interface of the XML facade to access the data
   // contained in the XML attachment.
   String symbol=srs.getSymbol();
   float targetPrice=srs.getTargetPrice();
   float currentPrice=srs.getCurrentPrice();
   ...
   <tr>
      <td>Symbol</td>
      <td><input type="text" name="Symbol"
                 value="<%= symbol %>"/></td>
      <td>(String)</td>
   </tr>
   ...
   
   

   The displayTask JSP page provides an HTML form that enables the user to fill in the action and quantity fields for the stock review sheet, as well as to edit any of its other fields. When the form is submitted, it passes these values, along with the taskId, to completeTask.jsp.

D.3.3.3 Update the Payload Data and Complete the Task

The final step is to use the generated facade classes to create the appropriate attachment data element (the task document) to be returned to the task and then pass it to the TaskManager service along with an indication that the task has been completed.

In this example, this is done in completeTask.jsp, which creates a new instance of the StockReviewSheet element and fills it in with the form data passed to it. It then looks up the task by taskId, as before. What is new about this code from completeTask.jsp is shown below. It sets some fields of the task object (including the updated attachment) and then informs the worklist service that the task has been completed.

StockReviewSheet srs=StockReviewSheetFactory.createFacade();

// Populate symbol from data submitted as part of the post
srs.setSymbol(request.getParameter("symbol"));
..
ITask task=worklist.lookupTask(taskId);

task.setAttachment(srs.getRootElement());

// Conclusion is user-defined – here it is ÒbuyÓ or ÒsellÓ
task.setConclusion(strAction);

worklist.completeTask(task);

out.println("This task has been successfully completed.");

At this point, the TaskManager service calls back asynchronously to the process that is waiting for this task, passing it the updated task attributes and attachment data.

D.4.1.1 Sending Notifications

It is common to send a notification message to a user when a task is assigned to that user (or when the timeout duration is reached, when the task is reassigned, or in other situations). This notification can be done in BPEL at the same time that the TaskManager service is initiated; therefore, anything that can be done in BPEL (invoking a Web service, sending an e-mail message or a JMS message, executing some Java code, and so on) can be done to notify a user of a task-related event.The TimeOffRequestFlow sample includes a code example of using the Oracle BPEL Process Manager Mail Service to send an e-mail notification to a user when a time-off request approval task has been assigned to that user. In this case, the e-mail includes an XML document attachment describing the time-off request and contains a link to a JSP page where the request can be approved or rejected.

D.4.1.2 Reassigning Tasks

Reassigning a task is as simple as changing the assignee field in the task document and then invoking the updateTask operation on the TaskManager service. A code example of this is shown in the "Enabling Expiration/Timeouts for Tasks". If the application requires that once a task is reassigned it cannot be completed by the original assignee, then the user interface that completes a task must first fetch the task document and check that the assignee has not changed before completing a task.

D.4.1.3 Assigning Tasks to Groups and Resolving Roles

The TaskManager service has a very simple construct for the assignee attribute of a task: it is a string identifier that is not interpreted by the TaskManager service to have any special meaning. Although simple, this construct is powerful and flexible. In particular, it allows for role resolution and the concept of group worklists to be implemented in a straightforward manner.When a task is assigned to a group, this typically means that several users can see the task in their worklists. When one of them selects the task on which to work, it disappears from the worklists of the other users in the group. Additionally, it is common to set up a timeout period such that if the individual working on the task does not complete it within a specified time, it may revert back to group assignment and then reappear on the group worklists.The most common way to implement this use case with the TaskManager service is as follows:

1. The task is assigned to the group identifier.

2. The worklist user interfaces for members of the group show all tasks assigned to the group.

3. When a user selects a task on which to work, it is checked to ensure it has not already been reassigned. If not, it is reassigned to the individual's user ID.

4. Optionally, notifications and timeouts can be used effectively here.

Role resolution works in much the same way. Because special interpretation is not given to the assignee for a task, the assignee can actually be a role, and resolution can happen on the user interface side. Alternatively, it is fairly simple to integrate a BPEL process with directory services such as LDAP and perform dynamic role resolution at the time the task is created.