17 Worklist Application

17.1 Use Cases for the Worklist Application

Consider the scenario where a manager needs to approve a vacation request for an employee, or a loan agent needs to review a loan application that has been submitted as part of the BPEL process. These users typically log in to a Worklist Application to view tasks assigned to them and perform actions on these tasks. Common actions performed on tasks include updating the payload, attaching documents or comments, routing the task to other users, and completing the task by providing a conclusion such as approve or reject.

The Worklist Application is demonstrated in two samples: VacationRequest and LoanDemoPlusWithWorkflow. In the VacationRequest use case, an employee files a vacation request that is routed to his manager for approval. The manager sees the task in the worklist in the My tasks view. In the LoanDemoPlusWithWorkflow use case, a loan application is assigned to a LoanAgent role and then sent to two levels of approval through the management chain if the loan amount is greater than $100,000. When any of the loan agents log in to their worklists, they see the task in their My & Group tasks view. One of the loan agents acquires the task and reviews it. If the loan agent approves it, the task is routed further, to two levels of management approval, if the loan amount is greater than $100,000. When the loan agent's managers log in to their worklists, they see tasks that were routed to them and the actions performed by the previous approvers (for example, suggested APR, comments, or attachments).

Two simple applications built using the Worklist Service APIs are also provided that demonstrate using the most common features such as listing, update, approve, login, logout, acquire, and others:

The OrderBooking tutorial also demonstrates how to use the Worklist Application to approve a purchase order manually.

17.2 Overview of Worklist Application Concepts

The Worklist Application enables users to participate in a BPEL process by performing tasks that require manual intervention. The worklist user interface displays tasks specific to the logged-in user based on the user's permissions and assigned groups and roles. In general, when a user logs in, the following types of tasks that require action are displayed:

• Tasks assigned to the user—In this case, the user has to act on the task before it is routed further.

• Tasks assigned to the groups or roles that the user belongs to—In this case, one of the users belonging to the group has to acquire the task before acting on it. If one user in a group acquires the task, it is not available to other users until it is released back to the group.

Users can review tasks for their reportees, tasks that were created by them, tasks owned by them, or any previous task that the user participated in.

A work item or task that is assigned to a user has the following components:

• Task attributes—includes task title, number, status, priority, expiration, identification key, assignees, and other flex fields.

• Task form—consists of detailed information (the payload) about the task; for example, a loan application in the LoanDemoPlusWithWorkflow sample or support ticket details in the HelpDeskRequest sample.

• Task comments—comments entered by various users who have participated in the workflow.

• Task Attachments—other documents or reference URLs that are associated with a task. These are typically associated with the workflow by the BPEL process or attached and modified by any of the participants in the workflow.

• Task history—consists of the approval sequence as well as the update history for the task. The history maintains an audit trail of the actions performed by the participants in the workflow and a snapshot of the task payload and attachments at various points in the workflow.

The types of actions that users can perform on a task include:

• Update task details—The task form can include content that needs to be added or modified by the task reviewer. Additionally, a user can modify flex fields, task priority, or include comments or attachments to the task.

• Change outcome for the task—As part of the process model, the workflow designer can include various custom outcomes for the task (for example, approve or reject, acknowledge, defer). If a user modifies a task outcome, it is removed from his worklist and routed to the next approver or back to the business process based on the workflow pattern.

• Perform system actions—In addition to the custom actions specified as part of workflow modeling, the user can perform other system actions such as escalate or delegate. These actions are available on all tasks based on the user's privileges. The process owner or workflow administrator can always perform any of these operations on processes that they own. The various system actions allowed on a task are as follows:

  • Escalate—This operation enables a user to escalate a task to his manager for further action.

  • Reassign—A manager can delegate a task to reportees. Similarly, the process owner or a user with BPMWorkflowReassign privileges can delegate a specific task to any other person in the organization.

  • Request More Information—Any participant in the workflow can request more information from the task creator or any of the prior assignees of the task. The user requesting more information can either have the additional information sent to him, or the user can require that the task be resubmitted through the intermediate approvers.

  • Submit More Information—This operation enables a user to respond to a request for additional information. This action is performed after the user has made the necessary updates to the task or has added comments or attachments containing additional information.

  • Route—This operation enables a user to enter an outcome and then route the task in an ad hoc fashion to the next user who must review the task.

  • Suspend—This operation enables process owners (or users with the BPMWorkflowSuspend privilege) to put a workflow on hold temporarily. In this case, task expiration and escalation do not apply until the workflow is resumed. No actions are permitted on a task that has been suspended (except resume and withdraw).

  • Resume—This operation enables process owners (or users with the BPMWorkflowSuspend privilege) to remove the hold on a workflow. After a workflow is resumed, actions can be performed on the task.

  • Acquire—This operation enables a user to obtain an exclusive right to work on a task that is assigned to a group or multiple users. No action can be performed on a task assigned to a group or multiple users until it is acquired. Only one user can acquire a task at any given time.

  • Release—This operation enables a user to abandon the exclusive right to work on a task that is assigned to a group or multiple users. After a task is released, any other user who is assigned to the task can acquire it.

  • Renew—If a task is about to expire, a task assignee can renew the task and request more time to perform the task. This operation is not allowed if the process modeler has restricted task renewal on the workflow.

  • Withdraw—The creator of the task can withdraw a pending task. A process owner can also withdraw a task on behalf of the creator.

17.2.2 Features of the Sample Worklist Application

After you log in (see "Logging In to the Worklist Application"), the home page of the Worklist Application is displayed, as shown in Figure 17-1.

Figure 17-1 Worklist Application Home

Description of "Figure 17-1 Worklist Application Home"

From this page, you can retrieve worklist tasks by using the Search field to do a keyword search or by using the Task Filter, Priority, and Status fields to specify search criteria. Table 17-1 describes the salient features of the Worklist Application home page shown in Figure 17-1.

Table 17-1 Contents of the Worklist Application Home

Page Element	Location in Page	Description
User link	top right of Figure 17-1	Click the user name link to see the logged-in user's full name, contact information, title, manager's name, reportees' names, and assigned groups and roles. The manager and reportee names are also links to the same information on those individuals.
Search Keyword field	top center of Figure 17-1	Enter a keyword to search task titles, comments, identification keys, and the flex string fields of tasks that qualify for the specified filter criterion.
Task Filter list	top right of Figure 17-1	Select from the following: My—retrieves tasks directly assigned to the logged-in user Group—tasks assigned to the groups to which the logged-in user belongs My & Group—tasks assigned to the user and the groups to which the logged-in user belongs Reportees—tasks assigned to the users who report to the logged-in user Owner—tasks that are owned by the logged-in user by way of process ownership Creator—tasks that were created or initiated by the logged-in user Previous—tasks that the logged-in user has updated Admin—appears only if the logged-in user has been granted the BPMWorkflowAdmin role All—tasks from all of the above
Priority list	top right of Figure 17-1	Select from Any or 1 through 5, where 1 is the highest priority.
Status list	top right of Figure 17-1	Select from the following: Any Assigned Completed Suspended (can be resumed later) Withdrawn Expired Errored (errored while processing; a user with the BPMWorkflowAdmin role can troubleshoot the problem.) Information Requested
Go button	top right of Figure 17-1	Click Go after selecting from the search fields.
Advanced Search link		Click to go to the Advanced Search page, which provides additional search filters.
Show (Hide) Chart button	right side of Figure 17-1	Shows a bar chart of the listed tasks in the selected task filter, broken down by status. See Figure 17-2 for an example.
Number column	right side of Figure 17-1	Displays the task number for the task.
Title column	middle of Figure 17-1	Tasks associated with a purged or archived process instance do not appear. Click the column name for ascending or descending sorts.
Priority column	middle of Figure 17-1	Click the column name for ascending or descending sorts.
Status column	middle of Figure 17-1	Status states are as follows: Assigned, Completed, Errored, Expired, Info Requested, Stale, Suspended, and Withdrawn. Click the column name for ascending or descending sorts.
Assignees column	middle of Figure 17-1	Person or group to whom the task is assigned.
Expiration Date column	middle of Figure 17-1	Date and time the tasks expires. Click the column name for ascending or descending sorts.
Modified Date column	middle of Figure 17-1	Date and time the task was modified. Click the column name for ascending or descending sorts.
Actions column	middle of Figure 17-1	The possible actions that apply to the task. See"Task Actions" for more information.
Next or Previous links	bottom left of Figure 17-1	Click Previous or Next to go the previous or next page in the list. The absolute row numbers of the tasks are shown in square brackets. The size of the page (number of rows per page) is controlled by an optional parameter, oracle.tip.worklist.sampes.tasklist.maxrows, in the file pc.properties, which appears in Oracle_Home\integration\orabpel\system\services\config. The default value is 20.

If you click Show Chart, a bar chart of the tasks is displayed, as shown in Figure 17-2.

Figure 17-2 Worklist Application Home with Chart Displayed

Description of "Figure 17-2 Worklist Application Home with Chart Displayed"

If you click a task in the Title column, the Task Details page is displayed, as shown in Figure 17-3.

Figure 17-3 Task Details Page

Description of "Figure 17-3 Task Details Page"

Table 17-2 describes the Task Details page shown in Figure 17-3, and also references other figures in this chapter. (The table does not include page elements, such as the User link or the search fields, already described in Table 17-1.)

Table 17-2 Contents of the Task Details Page

Page Element	Location in Page	Description
Task Action list	top left of Figure 17-3	Shows the actions you can perform on a task, such as approving a vacation request or escalating a purchasing decision, depending on how the process flow was defined in JDeveloper BPEL Designer. See "Task Actions" for more information.
Route... button	top right of Figure 17-4	Routes the task to another user. The button appears only if the task was designed to support dynamic routing (that is, no predetermined set of approvers, for example). See "Routing" for more information.
Request More Info... button	top right of Figure 17-3	Requests more information from the task creator or a previous approver in a simple or sequential approval process. See "Requesting More Information" for more information.
View SubTasks button	top right of Figure 17-16	Click to go to the Subtasks page. This button is available only for a parent task of a parallel flow. See "Parallel Tasks" for more information.
View History button	top right of Figure 17-16	Click to see the complete trail of changes made to a task. See "Task History and Sequence (Version) Numbers" for more information.
Header section	top of Figure 17-3	The header includes the process name, state, and priority, and information about who created, modified, acquired, or is assigned to the task. It also displays dates related to task creation, last modification, and expiration. The task flow pattern is also displayed.
Payload section	middle of Figure 17-3	Click HTML Form View (default) or XML Source View for the display options. See "The Payload" for more information.
Comments and Attachments section	bottom of Figure 17-3	Click the Add button in the Comments section to add comments. Click the Change... button in the Attachments area to add or change an attachment. See "Comments" and "Attachments" for more information.
Reassign button	lower left of Figure 17-15	Click this button if you want to change the assignment of a task to other users. You must have permission to reassign a task, which is granted through the BPMWorkflowReassign role. See "Reassignment" for more information.
Update Fields button	middle right of Figure 17-16	Click to go to the edit page for updating task header fields such as priority, identification key, and flex fields.

The following sections describe activities provided by the Worklist Application.

17.2.2.1 Task Actions

Figure 17-4 shows the Task Action list. The tasks in the list depend on the task design, the state of the task (for example, if the task has been completed, then no actions are listed), and the roles assigned to the logged-in user. Custom actions, such as Accept or Reject, are listed first. Custom actions are defined in JDeveloper BPEL Designer when you define the business process. System actions, such as Escalate or Suspend, are listed below a separator line.

Figure 17-4 Task Actions

Description of "Figure 17-4 Task Actions"

After you select one of the actions, the task is routed to the next step, depending on how the business process was designed. When a task is completed, all actions and form elements are disabled.

System actions are described in Table 17-3.

Table 17-3 System Task Actions

Action	Description
Acquire	If a task is assigned to a group or multiple users, then the task must be acquired first. Acquire is the only action available in the Task Action list. After a task is acquired, all applicable actions are listed.
Escalate	If you are not able to complete a task, you can escalate it and add an optional comment in the Comments area. The task is reassigned to your manager.
Release	If a task is assigned to a group or multiple users, it can be released if the user who acquired the task cannot complete the task. Any of the other assignees can acquire and complete the task.
Renew	If a task is about to expire, you can renew it and add an optional comment in the Comments area. The task expiration date is extended one week. A renewal appears in the task history. The renewal duration for a task can be controlled by an optional parameter, oracle.tip.worklist.samples.taskactin.renew.duration, in the file pc.properties, which appears in Oracle_Home\integration\orabpel\system\services\config. The default value is P7D (seven days).
Submit More Info	Use this action if another user requests that you supply more information. If reapproval is not required, then the task is assigned to the next approver or the next step in the business process.
Suspend and Resume	If a task is not relevant at present, you can suspend it. These options are available only to users who have been granted the BPMWorkflowSuspend role. Other users can access the task by selecting Previous in the task filter or by looking up tasks in the Suspended status. Buttons that update a task are disabled after suspension.
Withdraw	If you are the creator of a task and do not want to continue with it, for example, you want to cancel a vacation request, you can withdraw it and add an optional comment in the Comments area. The business process determines what happens next. You can use the Withdraw action on the home page by using the Creator task filter.

17.2.2.2 Routing

If there is no predetermined sequence of approvers and the actual set of approvers is determined dynamically, then the task can be routed in an ad hoc fashion. Note that the process must have been designed for supporting ad hoc routing. For such tasks, a Route button appears on the Task Details page, as shown in Figure 17-5.

Figure 17-5 Routing a Task

Description of "Figure 17-5 Routing a Task"

Clicking Route displays the ad hoc Routing page. Like the Reassign page, the user can look up the next approver by selecting My & Group and providing a complete or wildcard search string name. The difference between reassign and route is that in the case of route, the user's conclusion is added to the task and the task is sent to the new user as the next approver in the ad hoc sequence. Note that the new user or users are selected for the next phase of approval only. A chain or sequence of approvals is not denoted. The user must select a conclusion and can optionally add comments before routing the task.

17.2.2.3 Requesting More Information

Figure 17-6 shows where you request more information. The Reapproval Needed field appears if previous approvers must reapprove given the additional information, assuming that the process was designed to support reapproval. You can also add comments. After you have requested additional information, the task is assigned to the user from whom the additional information is needed. The user from whom additional information is requested uses Submit More Info to fulfill the request, as described in Table 17-3.

Figure 17-6 Requesting More Information

Description of "Figure 17-6 Requesting More Information"

17.2.2.4 Task History and Sequence (Version) Numbers

Figure 17-7 and Figure 17-8 show task history and sequence numbers (versions). Each time a task is updated or an action is performed, and sequencing (versioning) has been requested, a new sequence number is created. Task sequence numbers are automatically created for important actions and changes, such as adding and deleting attachments and payloads.

Figure 17-7 Task HIstory

Description of "Figure 17-7 Task HIstory"

Figure 17-8 Task Sequence (Version) Numbers

Description of "Figure 17-8 Task Sequence (Version) Numbers"

If a task requires sequential approval, the list of approvers is displayed.

You can also view the flow of the corresponding business process by clicking the Business Process History link at the bottom of the page. Oracle BPEL Console containing the process flow is displayed, as shown in Figure 17-9.

Figure 17-9 Process Flow

Description of "Figure 17-9 Process Flow"

17.2.2.5 The Payload

Figure 17-10 shows a payload in the HTML form view using a customized XSL template to render the original XML payload in an HTML format. The HTML form view can also be displayed using a custom payload JSP page. See Chapter 16, "Oracle BPEL Process Manager Workflow Services" for information on using an XSL template or using the autogenerated JSP.

Figure 17-10 Task Payload (XSL Transformed Payload)

Description of "Figure 17-10 Task Payload (XSL Transformed Payload)"

By default the payload display form is automatically generated. As shown in Figure 17-10, it consists of a form containing inputs for each of the elements of the payload and the values corresponding to the original values of the elements when the task was initiated. Using the Update Fields... button changes the values.

Figure 17-11 shows a payload in the XML source view. Users can edit the payload in this window, or, for complex payloads, they can copy the XML data into an external XML editor and paste the edited XML back into the XML payload window.

Figure 17-11 Task Payload—XML Source View

Description of "Figure 17-11 Task Payload—XML Source View"

17.2.2.6 Comments

Figure 17-12 shows where users add comments. To add a comment, users must have permission to update the task.

Figure 17-12 Adding a Comment

Description of "Figure 17-12 Adding a Comment"

A newly added comment and the comment writer's username are appended to the existing comments, as shown in Figure 17-3. A trail of comments is maintained throughout the life cycle of the task.

17.2.2.7 Attachments

Figure 17-13 shows where users add attachments. Users can add a file by using an absolute path name, as shown in the figure, or by using the Browse button. Users can associate a URL with a task by providing a name and a well-formed address (for example, http://www.oracle.com).

Figure 17-13 Adding Attachments

Description of "Figure 17-13 Adding Attachments"

Users can select one or more of the attachments and delete them, as shown in Figure 17-14.

Figure 17-14 Deleting an Attachment

Description of "Figure 17-14 Deleting an Attachment"

17.2.2.8 Reassignment

Figure 17-15 shows where users reassign a task.

Figure 17-15 Reassigning a Task

Description of "Figure 17-15 Reassigning a Task"

The page lists the current assignees and new assignees. Users can use Lookup to find additional names from the JAZN user community. Names that match the search string (wildcard search is supported) are added to the list of new assignees. Deselecting an assignee name drops the user from the list. After a task has been reassigned, it is available in the worklists of the new assignees.

17.2.2.9 Parallel Tasks

Parallel tasks are created when a parallel flow pattern is specified for scenarios such as voting. In this pattern, the parallel tasks have a common parent. The parent task is visible to a user only if the user is an assignee or an owner or creator of the task. The parallel tasks themselves (referred to as subtasks) are visible to whomever the task is assigned, just like any other task. It is possible to view the subtasks from a parent task. In such a scenario, the Task Details page of the parent task contains a View SubTasks button, as shown in Figure 17-16. Clicking this button displays the SubTasks page, which lists the corresponding parallel tasks. In a voting scenario, if any of the assignees updates the payload or comments or attachments, the changes are visible only to the assignee of that task. A user who can view the parent task (such as the final reviewer of a parallel flow pattern), can drill down to the subtasks and view the updates made to the subtasks by the participants in the parallel flow.

Figure 17-16 The View SubTasks Button

Description of "Figure 17-16 The View SubTasks Button"

17.2.2.10 Flex Fields and Task Fields Updates

A task can be associated with a set of flex fields of different types. Each flex field can have a custom name. The flex fields are displayed in the Task Details page, as shown in Figure 17-17.

Figure 17-17 Viewing Flex Fields

Description of "Figure 17-17 Viewing Flex Fields"

Clicking Update Fields… displays the Header Fields page. This page allows the user to update the flex fields and other task header fields, such as priority and identification key, as shown in Figure 17-18.

See Chapter 16, "Oracle BPEL Process Manager Workflow Services" for information on how flex fields are defined in the advanced option of the Workflow wizard.

Figure 17-18 Updating Flex Fields

Description of "Figure 17-18 Updating Flex Fields"

17.2.2.11 Request Status

For every update request (custom or system action) the user submits, the status of the request is displayed in the left portion of the header. If a request is successful, then the user sees a confirming message, as shown in Figure 17-19.

Figure 17-19 A Successful Update Request

Description of "Figure 17-19 A Successful Update Request"

If a request is not successful, then the user sees a failure message, as shown in Figure 17-20. Clicking the error message displays the Error Information page. See "Error Information" for more information.

Figure 17-20 An Unsuccessful Update Request

Description of "Figure 17-20 An Unsuccessful Update Request"

17.2.2.12 Error Information

If an error is encountered while processing a request, an error message is displayed, as shown in Figure 17-21.

Figure 17-21 Error Message Display

Description of "Figure 17-21 Error Message Display"

The main message of the error is displayed by default. Click Show/Hide Details for details (mostly useful for application developers or administrators). Clicking Back displays the previous page where the request was made.

The user error shown in Figure 17-21 occurs when a user has attempted an action that is not permitted. This is possible in the following scenarios:

• The task expired between the time the user loaded the page and actually performed the action.

• The task was acquired and updated concurrently by another user (such as a manager, owner, or administrator) between the time the user loaded the page and actually performed the action.

The Error Message page also displays system errors, which should be reported to the administrator.

Errored tasks are not assigned to a specific user. They are only assigned to the bpeladmin user. If you are a user other than bpeladmin and want to see these errors, select All in the Category list and Errored or Any in the Status list of the Oracle BPEL Worklist Application.

17.2.2.13 User and Group Information

If a user clicks the link in the header that identifies the logged-in user, the User Info page appears. This page displays information such as the user's full name, telephone number, e-mail address, manager, reportees, groups to which the user belongs, and roles that have been granted, as shown in Figure 17-22.

Figure 17-22 User Information

Description of "Figure 17-22 User Information"

The roles that have been granted control the actions that the user can perform in the application. The user can click the manager and reportee links to get user information by traveling up and down the management chain. Clicking a group displays the Group Info page for that group, as shown in Figure 17-23. The Group Info page displays the list of direct and indirect users (users contained in child groups of the current group).

Figure 17-23 Group Information

Description of "Figure 17-23 Group Information"

17.2.2.14 Advanced Search

The Advanced Search page, shown in Figure 17-24, provides additional filters for performing a fine-grained search, based on business process, expiration date, and creation date. The standard search box that appears in the top-right corner is not displayed in the advanced search option.

Figure 17-24 Advanced Search Page

Description of "Figure 17-24 Advanced Search Page"

17.2.2.15 Determining Action Permissions

A user can view a task when associated with the task as one of the following: current assignee (directly or by group membership), current assignee's manager, creator, owner, or a previous actor.

A user's profile determines his group memberships and roles. The roles determine a user's privileges. Apart from the privileges, the exact set of actions a user can perform is also determined by the state of the task, the custom actions, and restricted actions defined for the task flow at design time.

The following algorithm is used to determine the actions a user can perform on a task:

1. Get the list of actions a user can perform based on the privileges granted to him.

2. Get the list of actions that can be performed in the current state of the task.

3. Create a combined list of actions that appear on the preceding lists.

4. Remove any action on the combined list that is specified as a restricted action on the task.

The resulting list of actions is displayed in the listing page and the Task Details page for the user. When a user requests a specific action, such as acquire, suspend, or reassign, the worklist service ensures that the requested action is contained in the list determined by the preceding algorithm.

Step 2 in the preceding algorithm deals with many cases. If a task is in a final, completed state (after all approvals in a sequential flow), an expired state, a withdrawn state, or an errored state, then no further update actions are permitted. In any of the these states, the task, task history, and subtasks (parent task in parallel flow) can be viewed. If a task is suspended, then it can only be resumed or withdrawn. A task that is assigned to a group has to be acquired first before any actions can be performed on it.

See "Identity Service" for information about the identity service and how privileges can be assigned to users.

17.3 Accessing the Worklist Application in Local Languages

The identity service determines a user's preferred locale (language) and time zone. This information is extracted from either the JAZN file-based community or from an external directory service such as Oracle Internet Directory. If no preference information is available, then the locale and itemizing for the user is set to the system default.

For example, if you are using the sample worklist configured with the user community in the JAZN XML file, then you can set the user's preferred language in users-properties.xml (in Oracle_Home\integration\orabpel\system\services\config) as follows:

<bpm:timeZone>America/Los_Angeles</bpm:timeZone>
<bpm:preferredLanguage>en_US</bpm:preferredLanguage>

If an LDAP-based provider such as OID is used, then language settings changed in the OID community.

When a user opens a browser and logs in to the Worklist Application, the worklist screens are rendered in the browser's locale and time zone. For custom actions, flex fields, and task titles, the display names come from the message bundle, if specified in the configuration. If no message bundle is specified, then the values specified in the wizard at design time are used. See Chapter 16, "Oracle BPEL Process Manager Workflow Services" for more information on how to specify message bundles so that custom actions, flex fields, and task titles are displayed in a preferred local language.

The Worklist Application supports the locales shown in Table 17-4.

17.4 Customizing the Worklist Application

The sample Worklist Application described in this chapter is fully functional. Use it as a starting point to create a customized Worklist Application to suit your specific needs. This section discusses the architecture of the Worklist Application and provides specific details for customizing it.

17.4.1 Worklist Application Architecture

The Worklist Application follows the standard model-view-controller approach, as shown in Figure 17-25. A request coming from the browser is handled by a servlet. The servlet validates the request and calls the appropriate worklist service API to either fetch the required data from the back end or to update a task. After the API call, the servlet stores the data required for rendering the next page in the session. The JSP page picks up the data from the session, renders the data, and removes it from the session. Hence the servlets and the JSP pages have different functions. The servlets are responsible for making the back-end API calls and the JSP pages are responsible for formatting the data.

Figure 17-25 Worklist Application Architecture

Description of "Figure 17-25 Worklist Application Architecture"

A typical page flow sequence is shown in Figure 17-26. This sequence encompasses logging in to the application to view the details of a task. The first time a user enters the login URL, the login servlet performs a page redirect to the login JSP page that is sent to the browser. The user enters the username and password and the login servlet calls the authenticateUser() API. If successful, it sends a redirect to the TaskList URL. The browser's request then goes to the TaskList servlet that calls the getWorklistTasks() API for getting the tasks that the user should see. Then it performs a page redirect to the TaskList JSP page that is sent to the browser. When a user clicks a task link, the request is handled by the TaskDetails servlet. This calls the getWorklistTaskDetails() API and performs a page redirect to the TaskDetails JSP page that is sent to the browser. Page flows for other functionality, such as updating payload, changing priority, adding an attachment, reassigning a task, viewing history, and requesting more information, are similar.

Figure 17-26 A Typical Page Flow Sequence

Description of "Figure 17-26 A Typical Page Flow Sequence"

The separation of responsibility facilitates customizing the application. The page flow requirements for many customer requirements are probably similar to the page flow for the sample Worklist Application. Therefore, it may be sufficient to modify the JSP pages (and the Java class HTMLFormatter.java used for formatting HTML data).

The following sections discuss how to customize some of the commonly used pages for a different look and feel to suit various application requirements.

17.4.1.1 Login Page

A common requirement for customizing the login page is to add corporate branding, as shown in Figure 17-27. Replace the image tag <img src="img/login.jpg"> in the Login.jsp page with your image tag, such as <img src="img/acmeLogin.jpg">. Everything else remains the same.

Figure 17-27 Login Page

Description of "Figure 17-27 Login Page"

17.4.1.2 Header Info

The header section appears on every page above the bread crumb navigation. This section can be customized by modifying the Header.jsp file, as shown in Figure 17-28. The logo and the name of the application in the left corner are contained in the Branding.jsp file that is included in the header.

Figure 17-28 Header Information

Description of "Figure 17-28 Header Information"

The upper-right area contains HTML controls for filters and search criteria for retrieving tasks. The filters can be customized to include only those choices that are relevant to the application.

17.4.1.3 Task Home (Listing) Page

The home (or listing) page lists all the tasks that match the search criteria specified by the user. It also contains a chart that summarizes the task counts for the category (task) filter. As shown in Figure 17-28, both the listing and the chart content can be customized to suit application requirements. You can customize the list by modifying the displayFilteredTasks() method in the src/WorklistServlets/HTMLFormatter.java class. Some of the formatting code is included in this class for modularity and reuse. You can customize the list to display only those columns that are relevant to the application. The contents of the columns can be customized as well. You can customize the list of task actions by modifying the displayTaskActionsDropdown() method in the same class. You can customize the chart, for example, to show only counts for statuses that are relevant to the application by modifying the ListChart.jsp file. Customize the overall layout by modifying the TaskList.jsp file.

17.4.1.4 Task Details Page

The Task Details page is typically used to examine the contents of the task and view or update the payload. The layout of the details page consists of the actions and buttons at the top, a header section, the payload section, and the footer section consisting of optional contents such as comments and attachments. All of these can be customized by modifying the TaskDetails.jsp file.

In the example shown in Figure 17-29, the header section can be customized to display only the task fields that are relevant to the application. The payload section contains the autogenerated JSP file based on the payload XSD. See Chapter 16, "Oracle BPEL Process Manager Workflow Services" for information on how to customize this file. The footer section can be customized, moved to the top section, or eliminated, depending on the application requirements.

Figure 17-29 Task Details Page

Description of "Figure 17-29 Task Details Page"

17.4.1.5 Additional Pages

The guidelines provided in "Worklist Application Architecture" can be used to modify other pages to suit the application requirements.

17.4.1.6 Configuration Parameters

In addition to customizing pages, you can modify parameters in Oracle_home\integration\orabpel\system\services\config\pc.properties to change the behavior of the application as follows:

• To change the page size on the listing page, change:

  oracle.tip.worklist.samples.tasklist.maxrows=5
  
  

• To change the renewal duration for tasks, change:

  oracle.tip.worklist.samples.taskaction.renew.duration=P7D
  

...
  <role>
    <name>BPMProcessingManager</name>
    <members>
      <member>
        <type>user</type>
        <name>jstein</name>
      </member>
    </members>
  </role>
...

import="oracle.tip.pc.services.common.ServiceFactory"
import="oracle.tip.pc.services.identity.*"
 
boolean canEditTaskHeaderPriority = false;
// get info from identity service
try
{
  BPMIdentityService mIdentityService = 
             ServiceFactory.getIdentityServiceInstance();
  // lookup user based on worklist context user
  BPMUser bpmUser = mIdentityService.lookupUser(ctx.getUser());
  // check for BPMProcessManager role
  if (bpmUser.isInRole("BPMProcessingManager "))
     canEditTaskHeaderPriority = true;
 }
 catch (Exception e)
 {
  out.println("Could not get information from identity service");
 
 }
 // use the canEditTaskHeaderPriority flag to control HTML behavior
 if (canEditTaskHeaderPriority)
   // display the priority information & edit controls
 else
   // just display the priority information

17.5 Building a Worklist Application Using the Worklist Service APIs

The Worklist Application that is included with Oracle BPEL Process Manager provides a good starting point for building applications from scratch or for building composite applications.

The typical sequence of calls to the worklist service is as follows:

1. Get the handle to the worklist service.

2. Authenticate the user with the username and password and get a handle to the worklist context.

3. Set the required filters for retrieving tasks and get the list of tasks that qualify.

4. Loop through the task list and display tasks.

5. Perform actions on specific tasks.

A code example for calling the regular (local) worklist service APIs for performing this sequence of actions is as follows:

// required imports
import oracle.tip.pc.api.worklist.*;
import oracle.tip.pc.services.hw.worklist.WorklistService;
// 1. get a handle to the worklist service
WorklistService wlSvc = WorklistService.getWorklistService();

// 2. get worklist context for current user after authentication
String user = "jstein";
String password = ÒwelcomeÓ;
IWorklistContext ctx = wlSvc.authenticateUser(user, password);

// 3. set filters for retrieving ÒMyÓ tasks with ÒAssignedÓ status
// sorted by task title is ascending order
Map filterMap = new HashMap();
filterMap.put(IWorklistService.FILTER_TYPE_TASK_FILTER,
              IWorklistService.TASK_FILTER_MY);
filterMap.put(IWorklistService.FILTER_TYPE_STATUS_FILTER,
              IWorklistService.STATUS_FILTER_ASSIGNED);
String keywords = ÒÓ;

List tasks = wlSvc.getWorklistTasks(ctx,
             keywords,
             filterMap,
             IWorklistService.SORT_FIELD_TASK_TITLE,
             IWorklistService.SORT_ORDER_ASCENDING);

// 4. APPROVE all Vacation Request tasks that are assigned to user
if (tasks != null)
{
  for (int i=0; i<tasks.size(); i++)
  {
    Task task = (Task) tasks.get(i);
    String taskId = task.getTaskId();
    // check if the task is a vacation request 
    if (task.getTitle().startsWith("Vacation request"))
    {
      wlSvc.appendTaskComments(ctx, taskId, "foo"); 
      // now approve the task
      String action = "APPROVE";
      wlSvc.customTaskOperation(ctx, taskId, action);
    }
  }
}

/*
 * Perform user authentication
 */
public IWorklistContext authenticateUser(String user,
                                         String password)
throws PCException;

/*
 * Get information for the specified group
 */
public IWorklistGroup getGroupInfo(IWorklistContext ctx,
                                   String group)
throws PCException;

/*
 * Get information for the specified user
 */
public IWorklistUser getUserInfo(IWorklistContext ctx,
                                 String user)
throws PCException;

/*
 * getWorklistTasks retrieves qualifying tasks from the start
 * row to the last row for the given filter/sort criterion
 * and user using the paging 
 *
 */

public List getWorklistTasks(IWorklistContext ctx,
                             String keywords,
                             Map filterMap,
                             String sortField,
                             String sortOrder,
                             int startRow,
                             int lastRow)
throws PCException;


/*
 * getWorklistTaskDetails retrieves the details for the
 * specified task
 */
public IWorklistTask getWorklistTaskDetails(IWorklistContext ctx,
                                            String taskId)
throws PCException;

/*
 * getWorklistTaskVersionDetails retrieves the details for the
 * specified version of the task
 */
public IWorklistTask getWorklistTaskVersionDetails(
                         IWorklistContext ctx,
                         String taskId,
                         int version)
throws PCException;

/*
 * getWorklistTaskHistory retrieves the history for the
 * specified task
 */
public List getWorklistTaskHistory(IWorklistContext ctx,
                                   String taskId)
throws PCException;

/*
 * Return a list of deployed business process names
 */
public List getWorklistTaskBusinessProcesses(IWorklistContext ctx)
throws PCException;

/*
 * acquireTask lets the user acquire the task
 */
public IWorklistTask acquireTask(IWorklistContext ctx, String taskId)
throws PCException;

/*
 * releaseTask lets the user release the task
 */
public IWorklistTask releaseTask(IWorklistContext ctx, String taskId)
throws PCException;

/*
 * escalateTask lets the user escalate the task
 */
public IWorklistTask escalateTask(IWorklistContext ctx,
                                  String taskId)
throws PCException;

/*
 * renewTask lets the user renew the task
 */
public IWorklistTask renewTask(IWorklistContext ctx,
                               String taskId,
                               String durationDays)
throws PCException;

/*
 * withdrawTask lets the user withdraw the task
 */
public IWorklistTask withdrawTask(IWorklistContext ctx,
                                  String taskId)
throws PCException;

/*
 * suspendTask lets the user suspend the task
 */
public IWorklistTask suspendTask(IWorklistContext ctx, String taskId)
throws PCException;

/*
 * resumeTask lets the user resume the task
 */
public IWorklistTask resumeTask(IWorklistContext ctx, String taskId)
throws PCException;

/*
 * requestInfoForTask lets the user request additional info for the task
 */
public IWorklistTask requestInfoForTask(IWorklistContext ctx,
                                        String taskId,
                                        String user,
                                        boolean reapprovalNeeded,
                                        String comments)
throws PCException;

/*
 * submitInfoForTask lets the user submit additional info for the task
 */
public IWorklistTask submitInfoForTask(IWorklistContext ctx,
                                       String taskId)
throws PCException;

/*
 * delegateTask lets the user delegate (reassign) the task
 */
public IWorklistTask delegateTask(IWorklistContext ctx,
                                  String taskId,
                                  List worklistAssignees)
throws PCException;

/*
 * customTaskOperation lets the user perform custom operation on the task
 */
public IWorklistTask customTaskOperation(IWorklistContext ctx,
                                         String taskId,
                                         String operation,
                                         String comments)
throws PCException;

/*
 * completeAndRouteTask lets the user route the task to another user 
after adding a conclusion
 */
public IWorklistTask completeAndRouteTask(IWorklistContext ctx,
                                          String taskId,
                                          String conclusion,
                                          String comments,
                                          List worklistAssignees)
throws PCException;

/*
 * updateTask lets the user update the task
 */
public void updateTask(IWorklistContext ctx, IWorklistTask task)
throws PCException;

/*
 * appendTaskComments lets the user appends comments to the task
 */
public IWorklistTask appendTaskComments(IWorklistContext ctx,
                                        String taskId,
                                        String comments)
throws PCException;

/*
 * addTaskAttachment lets the user add an attachment to the task
 */
public void addTaskAttachment(IWorklistContext ctx,
                              String taskId,
                              String name,  
                              String value, 
                              String type,  
                              InputStream dataStream)
throws PCException;

/*
 * removeTaskAttachment lets the user delete attachments from the task
 */
public void removeTaskAttachment(IWorklistContext ctx,
                                 String taskId,
                                 String[] names)
throws PCException;

/*
 * lookupAssignees gets a list of assignee of the specified assignee type
 * (users/groups/reportees) who match the userLookupList
 */
public List lookupAssignees(IWorklistContext ctx,
                            String assigneeType,
                            String userLookupList)
throws PCException;

}

   List worklistAssignees = worklistService.lookupAssignees(ctx, 
IWorklistService.ASSIGNEE_TYPE_USER, "j*");     
   worklistService.delegateTask(ctx, taskId, worklistAssignees);

17.6 Building a Worklist Application Using the Worklist Service Remote APIs

It is possible to build a worklist application that works in a separate container and uses remote APIs to reference the workflow services in the BPEL container. The worklist service supports session bean-based remote APIs.

To use this approach, the JNDI and classpath configuration must be set up correctly. In the client Java program, the first step is to create a RemoteWorklistServiceClient instance and call its init() method. The init() method loads the JNDI properties based on the classpath and creates a local object that enables the client to talk to the remote server (the container where Oracle BPEL Process Manager is running). After a handle to RemoteWorklistServiceClient is obtained, most other operations are simple.

For using the Worklist Service Remote APIs, the JAVA classpath of the client program must contain the following:

oc4jclient.jar;bpm-infra.jar;bpm-services.jar;orabpel.jar;orabpel-common.jar;
orabpel-thirdparty.jar;config_directory 

where config_directory is a directory that contains the pc.properties and hw_worklist_jndi.properties files. A sample hw_worklist_jndi.properties file is provided in the Oracle_Home\integration\orabpel\system\services\config directory. The property settings in the hw_worklist_jndi.properties file are based on the type of Oracle BPEL Process Manager installation you are using:

• BPEL Process Manager for OracleAS Middle Tier:

  java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory
  java.naming.provider.url=opmn:ormi://localhost:6003:OC4J_BPEL/hw_services
  java.naming.security.principal=admin
  java.naming.security.credentials=welcome
  dedicated.connection=true
  
  

• BPEL Process Manager for Developers:

  java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory
  java.naming.provider.url=ormi://localhost/hw_services
  java.naming.security.principal=admin
  java.naming.security.credentials=welcome
  dedicated.connection=true
  
  

The following example shows a code fragment for using the remote service.

    // 1. get a handle to the remove worklist service client
    client = new RemoteWorklistServiceClient(); 
    client.init();

    // 2. set approver's user and password
    String user = "jstein";
    String password = globalPassword;
    System.out.println("vacationRequestTest: connecting as " + user);

    // 3. get worklist context for user
    IWorklistContext ctx = client.authenticateUser(user, password);
    System.out.println("vacationRequestTest: got Worklist Context");

    // 4. set filters for retrieving My tasks with Assigned status
    Map filterMap = new HashMap();

filterMap.put(IWorklistService.FILTER_TYPE_TASK_FILTER, 
                  IWorklistService.TASK_FILTER_MY);
   filterMap.put(IWorklistService.FILTER_TYPE_STATUS_FILTER, 
                 IWorklistService.STATUS_FILTER_ASSIGNED);

    List tasks = client.getWorklistTasks(ctx, 
                     filterMap, 
                     IWorklistService.SORT_FIELD_TASK_TITLE,
                     IWorklistService.SORT_ORDER_ASCENDING);

    // 5. APPROVE all vacationRequest tasks that are assigned to user
    if (tasks != null) 
    {
      for (int i=0; i<tasks.size(); i++)
      {
        Task task = (Task) tasks.get(i);
        String taskId = task.getTaskId();
        // check if the task is a vacation request
        if (task.getTitle().startsWith("Vacation request"))
        {
          // get custom actions that can be performed
          List customActions = client.getCustomActions(ctx, taskId);
          for (int j=0; j<customActions.size(); j++)
          {
            String customAction = (String) customActions.get(j);
          }
          // get system actions that can be performed
          List systemActions = client.getSystemActions(ctx, taskId);
          for (int j=0; j<systemActions.size(); j++)
          {
            String systemAction = (String) systemActions.get(j);
          }
          // add some comments to the task 
          client.appendTaskComments(ctx, taskId, "foo"); 
          // now approve the task
          String action = "APPROVE";
          client.customTaskOperation(ctx, taskId, action);
        }
      }
    }

17.7 Summary

This chapter describes how to access a user's tasks, view task details, and perform actions on the tasks in the sample Oracle BPEL Worklist Application. This application is available in many languages. Instructions are provided for customizing the Worklist Application and for building your own Worklist Application using the worklist service APIs.