To realize these requirements, BPEL Server provides access to its functionality through a set of APIs. As the Oracle BPEL Server has been developed in Java, these APIs are packages for use by developers. Using them we can develop our own applications that interact with the server and provide information about the state of the process instances, enable their management, and provide other useful information. Oracle provides Javadoc files to help learn how to use these APIs. The BPEL Console also uses these APIs and the source code is provided (a set of JSPs). Developers can use it to learn how to use the APIs. The BPEL Process Manager provides the following APIs:

• com.oracle.services.bpel.task: Used to interact with the user tasks (discussed later in this chapter).
• com.oracle.bpel.client: Provides interfaces and classes for accessing server functionality, such as performing operations on activities and introspecting processes deployed on a server domain.
• com.oracle.bpel.client.auth: Used to authenticate against a server domain or for administrative authentication.
• com.oracle.bpel.client.dispatch: Used to invoke processes (create process instances) that are deployed on a server domain from Java (for example from JSPs).
• com.oracle.bpel.client.util: Contains utility classes for HTML and SQLinteraction.
• com.collaxa.xml: Provides XML and XPath utility classes. This package might be renamed to a com.oracle package.
• com.collaxa.common.util: Provides access to BPEL Server performance statistics. This package might also be renamed to a com.oracle package.

In the next section we will show how to use some of these APIs to develop user tasks and include user interaction in BPEL processes.

User Interactions and Task Manager

With BPEL we can compose web services (and other resources) into business processes. Real-world business processes sometimes require including user tasks. For example, a user might want to make the final decision about the selected airline ticket, confirm a stock price, or choose a load offer. The BPEL specification does not provide a standard way to include user tasks in BPEL processes.

To solve this problem Oracle BPEL Process Manager provides the Task Manager. Task Manager is a built-in BPEL service (similar to E-mail and JMS service), which enables us to include user tasks in BPEL processes. Task Manager is an asynchronous service and provides two interfaces:

• The first is a WSDL interface used by the BPEL process. A BPEL process simply invokes the Task Manager. Through the invocation it expresses the need for the user interaction (initiateTask operation). It can also update or complete an existing user task (updateTask, completeTask). The Task Manager performs a callback to the BPEL process after the user interaction has been completed (onTaskResult) or if the user task times out (onTaskExpired).
• The second interface of the Task Manager is the client API. Using this API, developers can build custom user interfaces to carry out user interaction. Developers can also list and look up tasks. The client API is available as a Java API (called Worklist API) and can be used to develop user interfaces in Java (JSPs, for example). We will show how to use the Java API in the next example. The client API is also available as a WSDL interface. This enables custom user interfaces to be implemented in Microsoft .NET, Adobe Forms, or any other client technology that supports web services. The client WSDL interface is not available by default and has to be deployed through Worklist Manager service, which is actually a wrapper for the Java Worklist API (c:\orabpel\samples\utils\WorklistManager).

The architecture of the Task Manager is shown in the following figure:

>

User Task Example

To demonstrate how to add a user task to a BPEL process, consider our travel process example. We will add a user task to confirm the selected airline ticket. We will proceed as follows:

• Modify the BPEL process to invoke the Task Manager
• Develop a custom user interface using JSPs
• Deploy and test the example

Modifying the BPEL Process

We first declare an additional namespace that is used by the Task Manager:

<process name="BusinessTravelProcess"
         targetNamespace="http://packtpub.com/bpel/travel/"
         xmlns="http://schemas.xmlsoap.org/ws/2003/03/business-process/"
         xmlns:trv="http://packtpub.com/bpel/travel/"
         xmlns:emp="http://packtpub.com/service/employee/"
         xmlns:aln="http://packtpub.com/service/airline/"
         xmlns:task="http://services.oracle.com/bpel/task" >

We then add a partner link. We will call the partner link userTaskManager. The location of the Task Manager WSDL is http://localhost:9700/orabpel/default/TaskManager/TaskManager?wsdl:

...
   <partnerLink name="userTaskManager"
                partnerLinkType="task:TaskManager"
                partnerRole="TaskManager"
                myRole="TaskManagerRequester" />
...

Next we invoke the Task Manager. For this we create a new scope just after the <switch> activity, where we select the best plane ticket offer. To initiate a user task we invoke the initiateTask operation on the Task Manager. This operation requires a taskMessage parameter that specifies the task details. Therefore we create the taskMessage, fill in the required data, and invoke the initiateTask operation. Finally we wait for the callback onTaskResult (when the user has approved the ticket) and copy the user input to the TravelResponse variable:

<!-- User task to approve the ticket -->
<scope name="ApproveTicket">
   <variables>
      <variable name="ApproveTask" element="task:task"/>
   </variables>

   <sequence>
      <assign>
         <!-- Assign 'title' in task document -->
         <copy>
            <from expression="string('Approve Ticket')"/>
            <to variable="ApproveTask" query="/task/title"/>
         </copy>
         <!-- Assign 'creator' in task document -->
         <copy>
            <from expression="string('TravelUserTask')"/>
            <to variable="ApproveTask" query="/task/creator"/>
         </copy>
         <!-- Assign 'assignee' in task document -->
         <copy>
            <from expression="string('travel@packtpub.com')"/>
            <to variable="ApproveTask" query="/task/assignee"/>
         </copy>
         <!-- Assign 'duration' in task document -->
         <copy>
            <from expression="string('PT1H')"/>
            <to variable="ApproveTask" query="/task/duration"/>
         </copy>
         <!-- Assign 'priority' in task document -->
         <copy>
            <from expression="3"/>
            <to variable="ApproveTask" query="/task/priority"/>
         </copy>
         <!-- Assign 'attachment' in task document -->
         <copy>
            <from variable="TravelResponse" part="confirmationData">
            </from>
            <to variable="ApproveTask" query="/task/attachment"/>
         </copy>
      </assign>

      <scope name="UserInteraction">

         <variables>

            <variable name="taskRequest" messageType="task:taskMessage"/>
            <variable name="taskResponse" messageType="task:taskMessage"/>
         </variables>

         <sequence>
            <!-- Assign task document to taskMessage -->
            <assign>
               <copy>
                  <from variable="ApproveTask"/>
                  <to variable="taskRequest" part="payload"/>
               </copy>
            </assign>


            <!-- Initiate task -->
            <invoke partnerLink="userTaskManager"
                    portType="task:TaskManager"
                    operation="initiateTask"
                    inputVariable="taskRequest" />

            <!-- Receive the outcome of the task -->
            <receive partnerLink="userTaskManager"
                     portType="task:TaskManagerCallback"
                     operation="onTaskResult"
                     variable="taskResponse" />


            <!-- Read task document from taskMessage -->
            <assign>
               <copy>
                  <from variable="taskResponse" part="payload"/>
                  <to variable="ApproveTask"/>
               </copy>
            </assign>
         </sequence>
      </scope>
      <!-- Copy updated task attachment to variable -->
      <assign>
         <copy>
            <from variable="ApproveTask" query="/task/attachment"/>
            <to variable="TravelResponse" part="confirmationData"/>
         </copy>
      </assign>
   </sequence>
</scope>

Using BPEL Designer to Add a User Task

Instead of adding the Task Manager partner link and the related code by hand we could use the

BPEL Designer. To add the partner link we can use the UDDI Browser and select the built-in

BPEL TaskManager service, as shown in the following screenshot: