|
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2) B14448-03 |
|
 Previous |
 Next |
|
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2) B14448-03 |
|
|
Previous |
Next |
Chapter 16, "Oracle BPEL Process Manager Workflow Services" discussed how BPEL workflow services enable you to interleave human interactions along with connectivity to systems and services into an end-to-end process flow. The BPEL worklist service provides a programmatic interface to view and manage tasks from the BPEL process. The sample Oracle BPEL Worklist Application described in this chapter is the Web interface that enables users to access and act on tasks assigned to them. The tasks displayed depend on the user's profile, and the actions allowed depend on the user's privileges. The Worklist Application is layered on top of the BPEL worklist service.
This chapter contains the following topics:
Building a Worklist Application Using the Worklist Service APIs
Building a Worklist Application Using the Worklist Service Remote APIs
|
See Also: Appendix F, "Demo User Community" for the organizational hierarchy of the demonstration user community used in examples throughout this chapter |
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).
|
See: Oracle_Home\integration\orabpel\samples\demos for the VacationRequest and LoanDemoPlusWithWorkflow directories
|
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:
|
See:
|
The OrderBooking tutorial also demonstrates how to use the Worklist Application to approve a purchase order manually.
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.
Follow these instructions to access the Worklist Application.
Open a Web browser.
For a list of supported browsers, see Oracle BPEL Process Manager Installation Guide.
Go to the following URL:
http://hostname:9700/integration/worklistapp/Login
where
hostname is the name of the host on which Oracle BPEL Process Manager is installed
You can also select Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL Process Manager 10.1.2, and then Sample Worklist Application.
Type the username and password, and click Login.
The username and password must exist in the user community provided to JAZN. See "Configuring Identity Service" for information on JAZN.
|
Note: With some browsers, when you log in to the sample Worklist Application, the username and password fields remain blank without producing an error message. Refresh the browser so that the login information is successfully processed. |
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.
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:
|
|
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:
|
|
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, |
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
If you click a task in the Title column, the Task Details page is displayed, as shown in Figure 17-3.
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 |
|
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.
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.
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, |
|
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 |
|
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. |
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.
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.
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-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-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-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)
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
Figure 17-12 shows where users add comments. To add a comment, users must have permission to update the task.
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.
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).
Users can select one or more of the attachments and delete them, as shown in Figure 17-14.
Figure 17-15 shows where users reassign 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.
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.
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.
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.
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.
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
If an error is encountered while processing a request, an error message is displayed, as shown in Figure 17-21.
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.
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.
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).
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.
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:
Get the list of actions a user can perform based on the privileges granted to him.
Get the list of actions that can be performed in the current state of the task.
Create a combined list of actions that appear on the preceding lists.
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.
When a BPEL process is aborted, associated tasks are marked as Stale in the Status column of the Worklist Application home page. When a BPEL process instance is deleted, all associated tasks are deleted. When a BPEL process is undeployed, associated tasks are marked as Stale in the Status column of the Worklist Application home page.
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.
Table 17-4 Languages and Java Locales Supported by the Worklist Application
| Language | Java Locale |
|---|---|
|
English |
(en) |
|
English [United States] |
(en_US) |
|
German |
(de) |
|
Spanish [International] |
(es) |
|
Spanish [Spain] |
(es_ES) |
|
French |
(fr) |
|
French [Canada] |
(fr_CA) |
|
Italian |
(it) |
|
Japanese |
(ja) |
|
Korean |
(ko) |
|
Portuguese |
(pt) |
|
Portuguese [Brazil] |
(pt_BR) |
|
Chinese [Simplified] |
(zh_CN) |
|
Chinese [Traditional] |
(zh_TW) |
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.
|
See Also: TheWorklistServlets directory in Oracle_Home\integration\orabpel\samples\hw\worklistxpress\src
|
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
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
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.
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.
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.
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.
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.
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.
The guidelines provided in "Worklist Application Architecture" can be used to modify other pages to suit the application requirements.
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
The worklist service uses the identity service that supports the JAZN file-based community or LDAP communities such as Oracle Internet Directory. A static set of role-actions (privileges) have been defined and assigned to roles. Users then get those privileges by way of roles assigned to them. The most important of the role-actions currently defined include:
ACQUIRE
WITHDRAW
ESCALATE
RENEW
RELEASE
REQUEST_INFO
SUBMIT_INFO
CUSTOM
ADMIN
REASSIGN
SUSPEND
RESUME
VIEW_TASK_HISTORY
The role-actions apply globally; that is, at the application level and not at the process level or instance level.
The Worklist Application can be customized so that the information viewed and the actions performed on a given page can be altered for different sets of users. The first part consists of creating new roles and assigning them to the required users. Then, in the JSP page, the identity service can be used to check if the user has the granted role and determine which code path to take.
For example, you can create a new role called BPMProcessingManager in the file jazn-data.xml (in Oracle_Home \integration\orabpel\system\appserver\oc4j\j2ee\home\config). The required users must be assigned this role, as shown in the following code example:
...
<role>
<name>BPMProcessingManager</name>
<members>
<member>
<type>user</type>
<name>jstein</name>
</member>
</members>
</role>
...
If an LDAP-based service such as OID is used, then these roles must be created and granted to users in that service.
The JSP code can be customized using the identity service as follows.
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
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:
Get the handle to the worklist service.
Authenticate the user with the username and password and get a handle to the worklist context.
Set the required filters for retrieving tasks and get the list of tasks that qualify.
Loop through the task list and display tasks.
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);
}
}
}
|
See Also: Oracle_Home\integration\orabpel\docs\workflow\index.html for Javadoc that describes the worklist service APIs
|
The following worklist service APIs are needed for various actions.
/*
* 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;
}
"Worklist Service APIs" lists the API worklistService.lookupAssignees(), which you use to look up a user. In the following example, the lookup call searches for users that match the string j* and then those users are assigned to the task.
List worklistAssignees = worklistService.lookupAssignees(ctx, IWorklistService.ASSIGNEE_TYPE_USER, "j*"); worklistService.delegateTask(ctx, taskId, worklistAssignees);
In this example, the lookupAssignees call returns jcooper, jaustin, and jstein (users in the demo user community that match j*). If you want to assign the task to jcooper, then use jcooper as the lookup string. Alternatively, you can loop through the worklistAssignees list that is returned and filter out entries that you do not want. The element of the list contains ITaskAssignee objects.
|
See Also:
|
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);
}
}
}
|
See Also: Oracle_Home\integration\orabpel\docs\workflow\index.html for Javadoc that describes the worklist service remote APIs
|
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.
