| Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
| Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
The Oracle BPEL Worklist Application (Worklist Application) is a Web interface that enables users to act on their assigned human workflow tasks. This chapter discusses the sample Worklist Application that is provided with Oracle BPEL Process Manager, and how you can modify it to create your own worklist application.
This chapter contains the following topics:
You can use the Web interface of the Worklist Application for any activity that requires you to act on tasks in a BPEL process. A manager can approve employee vacation requests or a loan agent can review a loan application, each of which has been submitted as part of a BPEL process. Supervisors or group administrators can use the Worklist Application to analyze tasks assigned to the group and route them appropriately. Worklist Application users can also update payloads, attach documents or comments, and route the task to other users, in addition to completing tasks by providing conclusions such as approvals or rejections.
The Worklist Application is demonstrated in the following use cases:
Vacation Request—In this use case, an employee files a vacation request that is routed to his manager for approval. The manager sees the task in the Worklist Application in the My Tasks tab.
Document Review—In this use case, an author submits a document for review by multiple reviewers in parallel.
Expense Request Approval—In this use case, an employee's expense request is automatically routed to his manager for approval. The manager sees the task in the Worklist Application in the My Tasks tab. After the manager's approval, the task may be routed further up the management chain, depending on the content of the expense request. The BPEL process uses a decide activity to define the approval chain for a human workflow task dynamically, using Oracle Business Rules. The business rules determine the approval level required for the expense request, based on factors such as the amount of the request and the type of expense. The sample demonstrates how the approval chain for each expense report can be different, and how users can change the rules governing the approvals at run time.
Help Desk Service Request—In this use case, the supervisor resolves a service request by assigning it to any of his reportees using ad hoc routing. The assignee then approves the task after he responds to the service request.
Loan Demo Plus—In this use case, a loan application is assigned to the LoanAgent role. All loan agents see the task in their My & Group tasks view. One of the loan agents claims the task and reviews it. If the loan agent approves it, and if the loan amount is greater than $100,000, then the task is routed further, to two levels of management approval. 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:
SOA_Oracle_Home\bpel\samples\demos for the following directories:
VacationRequest
DocumentReview
ExpenseReportApproval
HelpDeskServiceRequest
LoanDemoPlus
Sample applications that are built with the workflow service APIs and demonstrate common features such as listing, updates, approvals, and login and logout are also provided.
See:
SOA_Oracle_Home\bpel\samples\ for the following:
demos\ExpenseReportApproval
demos\LoanDemoPlus
tutorials\132.UserTasks
utils\AsyncLoanService\ StarLoanUI
The OrderBooking tutorial also demonstrates how to use the Worklist Application to approve a purchase order manually.
Chapter 15, "Oracle BPEL Process Manager Workflow Services" discussed how BPEL workflow services enable you to interweave human interactions along with connectivity to systems and services into an end-to-end process flow. The workflow service provides a programmatic interface to view and manage tasks from the BPEL process. The tasks displayed depend on the user's profile, and the actions allowed depend on the user's privileges. This Worklist Application is layered on top of the BPEL workflow service.
The Worklist Application recognizes different types of users, as listed in Table 16-1.
Table 16-1 Worklist Application User Types
| Type of User | Access |
|---|---|
| End user | Acts on tasks assigned to him or his group and has access to system and custom actions, routing rules, and custom views |
| Supervisor (manager) | Acts on the tasks, reports, and custom views of his reportees, in addition to his own end-user access |
| Process owner | Acts on tasks belonging to the process but assigned to other users, in addition to his own end-user access |
| Group administrator | Manages group rules and dynamic assignments, in addition to his own end-user access |
| Workflow administrator | Administers tasks that are in an errored state, for example, tasks that must be reassigned or suspended. The workflow administrator can also change application preferences and map flex fields, and manage rules for any user or group, in addition to his own end-user access. |
See "Identity Service" for more information about predefined roles in the identity service.
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 LoanDemoPlus sample or support ticket details in the HelpDeskServiceRequest 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 and 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. The reviewer can modify the task priority, include comments, or add 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. See "Task Actions" for more information about system actions.
Use Internet Explorer 6.0 or Mozilla Firefox 1.0.4 to access the Worklist Application.
Open a Web browser.
Go to the following URL:
http://hostname:portnumber/integration/worklistapp/Login
hostname is the name of the host on which Oracle BPEL Process Manager is installed
The portnumber used at installation (typically 9700 or 8888) is noted in bpelsetupinfo.txt, at
SOA_Oracle_Home\install\
You can also select Start, then All Programs, then Oracle - Oracle_Home, then Oracle BPEL Process Manager, and then Worklist Application.
Type the username and password, and click Login.
You can use jstein and welcome1 to access the sample Worklist Application.
The username and password must exist in the user community provided to JAZN. See Oracle BPEL Process Manager Administrator's Guide for the organizational hierarchy of the demonstration user community used in examples throughout this chapter. See "Identity Service" for information on JAZN.
The Worklist Application displays tasks specific to the logged-in user based on the user's permissions and assigned groups and roles. Figure 16-1 shows the Worklist Application for the user jstein, who is a manager and is responsible for approving or rejecting his reportees' vacation requests.
Figure 16-1 Worklist Application—Task Listing (Home) Page
All task interactions—listing tasks, viewing task details, reassigning tasks, performing actions on tasks, setting outcomes, and so on—are initiated from the Task Listing (home) page. As Figure 16-1 shows, when jstein logs in to the Worklist Application, he sees the Task Listing (home) page, which shows the tasks assigned to him and to the group to which he belongs. Because jstein is a manager, the My Staff Tasks tab also appears. For tasks assigned to jstein, he selects an action from the Actions list to participate in the workflow. For tasks assigned to a group to which jstein belongs, he must claim the task before selecting an action. The task is not available to other users until jstein releases it back to the group.
From the home page, you can retrieve worklist tasks by using the Search field to do a keyword search or by using the Category, Priority, and Status fields to specify search criteria. The category filters that are available depend on which tab is selected. From the My Tasks tab, the category filters are My, Group, My & Group, and Previous (tasks worked on in the past). From the My Staff Tasks tab, the only category filter is Reportees. From the Initiated Tasks tab, the only category filter is Creator. In addition to the My Tasks, My Staff Tasks, and Initiated Tasks tabs, other tabs may be displayed, depending on the role granted to the logged-in user, as described in Table 16-2 (Tabs). From the Administration Tasks tab, the category filter is Owner if the user (who has been granted the BPMWorkflowAdmin role in order to see this tab) owns the tasks and Admin otherwise.
Table 16-2 describes the salient features of the Task Listing (home) page of the Worklist Application shown in Figure 16-1.
Table 16-2 Contents of the Worklist Application My Tasks Page
| Location in Figure 16-1 | Page Element |
|---|---|
| Top left | Tabs—The tabs displayed depend on the role granted to the logged-in user. Everyone sees My Tasks and Initiated Tasks. Managers also see My Staff Tasks. A user with the BPMWorkflowAdmin role also sees the Administration Tasks, Manage Rules, Flex Field Mappings, and Application Customization tabs. See "Using the Administration Functions" for more information.
Welcome jstein [jazn.com]—In the banner area, the logged-in user's name appears. Click the user name to display information. See "User and Group Information" for more information. |
| Top right | Reports link—The following reports are available: Unattended Tasks Report, Tasks Priority Report, Tasks Cycle Time Report, Tasks Productivity Report. See "Creating Reports" for more information.
Preferences link—Manages the logged-in user's preferences, including setting vacation and other workflow rules, managing custom views, and customizing worklist displays. See "Setting Preferences" for more information. |
| Left pane | Work Queues—Standard, custom, and proxy views. See "Using Work Queues" for more information. |
| Center pane | Show (Hide) Chart button—Toggles to show or hide a bar chart of the listed tasks in the selected task filter, broken down by status. See "Viewing a Bar Chart of Task Status" for more information. |
| Center pane, Search area | Search Keyword field—Enter a keyword to search task titles, comments, identification keys, and the flex string fields of tasks that qualify for the specified filter criterion.
Category—Select from the following:
Priority—Select from Any or 1 through 5, where 1 is the highest priority. Status—Select from the following: Any, Assigned, Completed, Suspended (can be resumed later), Withdrawn, Expired, Errored (while processing), Information Requested Advanced Search link—Provides additional search filters. See "Using Advanced Search" for more information. |
| Center pane,
task list area |
The default display shows the following columns. You can change the display from the Preferences link. See "Display Preferences" for more information.
Task Number—The task number generated when the BPEL process was created. Title—The title specified when the human workflow task was created. Tasks associated with a purged or archived process instance do not appear. See "Specifying the Task Title, Priority, Outcome, and Owner" for more information. Priority—The priority specified when the human workflow task was created. See "Reviewing the Sections of the Human Task Editor" for more information. Assigned Users—The assignments specified when the human workflow task was created. See "Assigning Task Participants" for more information. Assigned Groups—The assignments specified when the human workflow task was created. See "Assigning Task Participants" for more information. State—One of the following: Assigned, Completed, Errored, Expired, Info Requested, Stale, Suspended, and Withdrawn. See "Overriding Default System Actions" for more information. Created Date—Date and time the task was created using Oracle BPEL Process Manager Expiration Date—Date and time the tasks expires, specified when the human workflow was created. Actions—The group action (Claim) and the custom actions (for example, Accept and Reject) that were defined for the workflow. Other possible actions for a task, such as system actions, are displayed on the Task Details page for a specific task. See "Using Advanced Search" for more information. |
This section contains the following topics:
If you click a task in the Task Title column, the Task Details page for that task is displayed, as shown in Figure 16-2.
This section describes the following elements of the Task Details page:
Figure 16-3 shows a Task Action list. The actions 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 (actions defined in the BPEL process), such as Accept or Reject, are listed first. System actions, such as Escalate or Suspend, are listed below a separator line.
You act on tasks using either the Task Action list or a button. The Task Action list contains actions that do not require additional input, such as accept, reject, renew, and suspend. Buttons are provided for actions that require additional input, such as reassignment and requests for information.
System actions are available on all tasks based on the user's privileges. Table 16-3 lists system actions.
Table 16-3 System Task Actions
| Action | Description |
|---|---|
| Claim | If a task is assigned to a group or multiple users, then the task must be claimed first. Claim is the only action available in the Task Action list for group or multiuser assignments. After a task is claimed, 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. |
| Pushback | Use this action to send a task up one level in the workflow to the previous assignee. |
| Reassign | If you are a manager, you can delegate a task to reportees. A user with BPMWorkflowReassign privileges can delegate a task to anyone. |
| Release | If a task is assigned to a group or multiple users, it can be released if the user who claimed the task cannot complete the task. Any of the other assignees can claim 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 SOA_Oracle_Home\bpel\system\services\config. The default value is P7D (seven days). |
| Submit More Information and Request More Information | Use these actions if another user requests that you supply more information or if you want to request more information from the task creator or any of the previous assignees. 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. |
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.
For every update request (custom or system action) that you submit, the status of the request is displayed in the left portion of the header. If a request is successful, then you see a confirming message, as shown near the top of the page in Figure 16-4.
If a request is not successful, then you see an error message, as shown in Figure 16-5. You can click the link for additional information about the error.
The error shown in Figure 16-5 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 claimed 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.
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.
Figure 16-6 shows the header section. Header information includes the task number and title; the state, outcome, and priority of the BPEL process, and information about who created, updated, claimed, or is assigned to the task. It also displays dates related to task creation, last modification, and expiration.
Figure 16-7 shows the payload section for the Vacation Request Process Request workflow. The fields displayed—Creator, From Date, To Date, Reason—reflect how the BPEL process for vacation approval was designed, using the autogenerated JSP.
See "Automatically Generating a Simple Task Display Form" for information on using the autogenerated JSP in your workflow design.
Figure 16-8 shows where you add or delete comments and attachments. To add or delete a comment or attachment, you must have permission to update the task.
A newly added comment and the comment writer's username are appended to the existing comments. A trail of comments is maintained throughout the life cycle of the task. When adding attachments, you can use an absolute path name or browse for a file or provide a URL.
Figure 16-9 shows the short history for a vacation approval task.
The short history for a task lists all versions created by the following tasks:
Initiate task
Reinitiate task
Update outcome of task
Completion of task
Erroring of task
Expiration of task
Withdrawal of task
Alerting of task to the error assignee
You can include the following actions in the short history list by modifying the shortHistoryActions element in
SOA_Oracle_Home\bpel\system\services\config\wf_config.xml
Acquire
Adhoc route
Auto release of task
Delegate
Escalate
Information request on task
Information submit for task
Override routing slip
Update outcome and route
Push back
Reassign
Release
Renew
Resume
Skip current assignment
Suspend
Update
The full history lists all version changes in a task.
If there is no predetermined sequence of approvers or if the workflow was designed to permit ad hoc routing, then the task can be routed in an ad hoc fashion. For such tasks, a Route button appears on the Task Details page. From the Routing page, you can look up one or more users for routing. When you specify multiple assignees, you can choose whether the list of assignees is for simple (group assignment to all users), sequential, or parallel assignment. In the case of parallel assignment, you provide the percentage of votes required for approval.
From the Task Details page, you can request more information by using the Request Info button. 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.
From the Task Details page, you can reassign a task using the Reassign button. As Figure 16-10 shows, you can either reassign (transfer) or delegate:
Reassign (transfer task to another user or group)—The task is moved from the assignee's worklist to another user's worklist. The newly assigned user then acts on the task, rather than the original user.
Delegate (allow specified user to act on my behalf)—The task is delegated to another user, but it shows up in both the original user's and the delegated user's worklists. The delegated user can act on behalf of the original assignee.
Use the Search button to find assignees and the up and down arrows to select or deselect assignees. Wildcard search is supported.
A supervisor can always reassign tasks to any of his reportees. Users with the BPMWorkflowReassign role can assign tasks to any users in the organization.
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. The SubTasks page 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 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 claim, suspend, or reassign, the workflow 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 must be claimed 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.
If you click the Advanced Search link, the page shown in Figure 16-11 is displayed.
When you search on a task type, the Select Workflow Task Type page is displayed. From this page, you select a task type and are returned to the Advanced Search page.
As Figure 16-12 shows, you can filter the search by adding conditions.
Conditions can be AND operations (the All of the following option) or OR operations (the Any of the following option). Each filter specifies a combination of attribute, operator, and value. The operator and value are tied to the type of the attribute and change based on the attribute chosen. For example, for identity fields such as Created By or Updated By, a flashlight icon appears so that you can search for names using the identity browser. For date fields, a calendar icon appears so that you an pick a date.
When you click the bar chart icon, a bar chart of the tasks is displayed, as shown in Figure 16-13.
The bar chart shows the tasks broken down by status, with a count of how many tasks in each status category.
The Work Queues pane, shown in Figure 16-14, is displayed by default. (Use the work queues icon to reopen a closed pane.)
The Work Queues pane displays the following:
Inbox—Shows all tasks that qualify for the user-chosen filter. The default shows all tasks, including high priority tasks, tasks due soon, new tasks, and so on.
My Work Queues—Shows standard work queues, and custom work queues that users have defined based on specific search criteria.
Proxy Work Queues—Shows queues to which a user has granted access to other users. Other users can act on those tasks on behalf of the user who granted access.
From the Preferences link, the following kinds of preferences are available:
Use the vacation preferences to make yourself unavailable for task assignments. As Figure 16-15 shows, you specify a vacation date range, and optionally create a rule. Based on the rules you specify, tasks can be approved automatically or reassigned to someone else, for example.
Figure 16-15 Setting a Vacation Preference in the Worklist Application
As Figure 16-16 shows, when creating a rule, you can specify which task the rule applies to, add conditions, and delegate or reassign the task to another user or a group.
Use a rule to specify conditions which, if true, cause an automatic action on a task. Examples include vacation rules, as discussed in the previous section, or a rule in which certain types of tasks are approved automatically. As Figure 16-16 shows, you can specify the following when creating a rule:
Rule name and description
Which task the rule applies to—If unspecified, then the rule applies to all tasks.
When the rule applies
Conditions on the rule—These are filters that further define the rule, such as specifying that a rule acts on priority 1 tasks only, or that a rule acts on tasks created by a specific user. The conditions can be based on standard task attributes as well as any flex fields that have been mapped for the specific tasks. See "Using the Administration Functions" for information about mapping flex fields.
Figure 16-17 shows how you add conditions to a rule.
Actions
Reassign to—You can reassign tasks to subordinates or groups you manage. If you have been granted the BPMWorkflowReassign role, then you can reassign tasks to any user or group.
Delegate to—You can delegate to any user or group.
Set outcome to—You can specify an automatic outcome if the workflow task was designed for those outcomes, for example, accepting or rejecting the task. The rule must be for a specific task type. If a rule is for all task types, then this option is not displayed.
Take no action—Use this action to prevent other more general rules from applying. For example, if you want to reassign all your tasks to another user while you are on vacation, with the exception of loan requests, for which you want no action taken, then create two rules. The first rule specifies that no action is taken for loan requests; the second rule specifies that all tasks are reassigned to another user. The first rule will prevent reassignment for loan requests.
Figure 16-18 shows the Rules List page. Rules are executed in the order in which they are listed. Use the Move Up and Move Down buttons to reorder rules. If a rule meets its filter conditions, then it is executed and no other rules are evaluated. For your rule to execute, you must be the only user assigned to that task. If the task is assigned to multiple users (including you), the rule does not execute.
Figure 16-18 Setting User Rules in Worklist Preferences
Figure 16-18 also shows the following:
You can create, delete, and edit rules (click the rule name).
A rule is active (see the Active column in Figure 16-18) if the date range you specified when you created the rule is current.
Use a group rule to specify how a workflow rule applies to members of a group. Examples of group rules include:
Assigning tasks from a particular customer to a member of the group
Ensuring an even distribution of task assignments to members of a group by using round-robin assignment
Ensuring that high-priority tasks are routed to the least busy member of a group
Creating a group rule is similar to creating other rules (see Figure 16-16, "Creating a Rule in the Worklist Application"); only some of the actions are different. For group rules, you can specify the following actions:
Reassign via—You can specify a criterion to determine which member of the group gets the assignment. This dynamic assignment criterion can include round-robin assignment, assignment to the least busy group member, or assignment to the most productive group member. You can also add your custom functions for allocating tasks to users in a group. See the following for more information:
"Runtime Config Service" for more information about dynamic assignment
"Implementing a Dynamic Assignment Function" for more information about custom functions
Reassign to—As with user rules, you can reassign tasks to subordinates or groups you directly manage. If you have been granted the BPMWorkflowReassign role, then you can reassign tasks to any user or group (outside your management hierarchy).
Take no action—As with user rules, you can create a rule with a condition that prevents a more generic rule from being executed.
The group Rules List page is similar to the user Rules List page, with the addition of a list of the groups that you (as the logged-in user) manage. You can select from this list to specify the group for which you are creating a rule.
Use a custom view to customize your task list display. Examples of custom displays include:
Ordering the task list in a particular way
Displaying only those tasks that meet a particular condition
Displaying specific attributes (columns) in your task list
You can also grant other users access to your views.
Figure 16-19 shows the Custom Views page.
The following functionality is available:
You can create, edit, copy, and delete views, and choose to make the view visible or not in the My Views section of the Work Queues pane.
For each view in the Granted Views list, you can choose to make the view visible or not in the Delegated Views section of the Work Queues pane on the Task List page.
Details are available for granted views. You can rename a view granted to you.
Figure 16-20 shows the Create Custom View page.
You can specify the following when creating a custom view:
General—You must specify a name for your view.
Columns—You can specify which columns you want to display in your task list. The columns in the views can be standard task attributes as well as any flex fields that have been mapped for the specific task type. See "Using the Administration Functions" for information about mapping flex fields.
The default columns are the same as the columns in your inbox. You can also choose to show tasks actions in your task list and select ascending or descending order for a single column.
Filter—You can specify which task categories you want to display, for example, My, Group, My & Group, and so on. You can also add conditions, for example, a condition that displays a task only when the title contains the words loan request.
Sharing—You can grant access to this view to another user; for example, if jstein grants access to a My & Group category of tasks to jcooper, then jcooper will see jstein's tasks and group tasks. Sharing a view with another user is similar to delegating all tasks that correspond to that view to the other user; that is, the other user can act on your behalf. Shared views are visible in the Proxy Work Queues section of the worklist (shown in Figure 16-14, "Work Queues Pane").
Use display preferences to customize how tasks are displayed in your worklist. As Figure 16-21 shows, you can use the following options to customize the display:
Maximum number of tasks per page
Page height in pixels
Default ordering of tasks
Show the following columns in the inbox view
Show task actions in task list
Figure 16-21 Setting Display Preferences in the Worklist Application
Administrators are users who have been granted the BPMWorkflowAdmin role. Administrators see the following tabs on the Worklist Application home page:
An administrator uses the Manage Rules tab, shown in Figure 16-22, to view or edit the rules for any user or group.
This tab is useful if an administrator is needed to fix a problem with a rule. Also, for a user who no longer works for the company, administrators can set up a rule for that user so that all tasks assigned to the user are automatically assigned to another user or group.
An administrator uses the Flex Field Mappings tab, shown in Figure 16-23, to promote data from the payload to inline attribute flex fields. By promoting data to flex fields, the data becomes searchable and can be displayed as columns in the Task Listing (home) page.
To create a flex field mapping, an administrator first defines a semantic label, which provides a more meaningful display name for the flex field attribute. Click Create Label to use the Create Payload Mapping Label interface, as shown in Figure 16-24.
As the figure shows, the label amount is mapped to the flex field NumberAttribute1, The payload attribute is also mapped to the label. In this example, the Number attribute type is associated with the amount label. The end result is that the value of the Number attribute is stored in the NumberAttribute1 column, and amount is the column label for that value as displayed in the user's task list. Labels can be reused for different task types. You can delete a label only if it is not used in any mappings.
A mapped payload attribute can also be displayed as a column in a custom view, and used as a filter condition in both custom views and workflow rules. The display name of the payload attribute is the attribute label that is selected when doing the mapping.
When this option is selected, all flex field mappings defined for all task types are displayed, as shown in Figure 16-25.
To display all the payload attributes mapped to a particular label, click the respective row in the label table.
When this option is selected, administrators can view or edit flex field mappings for a particular task type.
To edit mappings by task type:
Select Edit mappings by task type and click the flashlight icon.
Select a task type and click Select, as shown in Figure 16-26.
With the task type displayed in the Edit mappings by task type field, click Go.
All current mappings for the task type are displayed, as shown in Figure 16-27.
Select a mapping label and click Select.
Figure 16-28 shows a completed mapping.
If you want to create a new label, click Create Label and provide a label name, as shown in Figure 16-29. Note that the data type will be restricted based on the data type of the payload attribute.
To add a new mapping, click Add Row (if needed) and select a payload attribute from the list.
Click the flashlight icon and select a label.
Note the following restrictions:
Only simple type payload attributes can be mapped. Mapping specific simple types within a complex type is not supported.
A flex field (and thus a label) can be used only once per task type.
Data type conversion is not supported for the number or date data types. For example, you may not map a payload attribute of type string to a label of type number.
An administrator uses the Application Customization tab, shown in Figure 16-30, to customize the appearance of the Worklist Application.
Values can be specified for the following parameters:
Login page realm label—If the identity service is configured with multiple realms, then the Worklist Application login page displays a list of realm names. LABEL_LOGIN_REALM specifies the resource bundle key used to look up the label to display these realms. The term realm can be changed to fit the user community—terms such as country, company, division, or department may be more appropriate. Administrators can customize the resource bundle, specify a resource key for this string, and then set this parameter to point to the resource key.
See "Customizing the Login Page" for information on customizing the image on the login page.
Branding image location—This is the image displayed in the top left corner of every page of the Worklist Application. (The Oracle logo is the default.) Administrators can provide a .gif, .png, or .jgp file for the logo. This file must be in the public_html directory of the Worklist Application.
See "Customizing Header Information" for information about the header.
Application resource bundle classname—A resource bundle provides the strings displayed in the Worklist Application. By default, this is the class at:
oracle.bpel.services.workflow.resource.WorkflowResourceBundle
Administrators can change the strings shown in the application by copying WorkflowResourceBundle and creating their own. This parameter allows administrators to specify the classpath to this custom resource bundle.
The Worklist Application offers the following reports from the Reports link:
To create a report:
Click the Reports link.
Click the name of the report you want.
Provide inputs to define the search parameters of the report.
See the following sections on each report type for information about input parameters.
Click Run.
As shown in Figure 16-31, report results (for all report types) are displayed in both a table format and a bar chart format. The input parameters used to run the report are displayed under Report Inputs, in the lower-left corner (may require scrolling to view).
Figure 16-31 Report Display—Table Format, Bar Chart Format, and Report Inputs
This report provides an analysis of tasks assigned to users' groups or reportees' groups that have not yet been claimed (unattended tasks). Use the following input parameters to define the report:
Assignee—The tasks analyzed are based on the category chosen as it applies to the user; that is, tasks assigned to the user's groups, tasks assigned to the reportee's groups, tasks where the user is a creator, and tasks where the user is an owner.
Creation Date (range)
Expiration Date (range)
Task State
Priority
See Table 16-2 for descriptions of Creation (or Created) Date, Expiration Date, Task State (or Status), and Priority.
Figure 16-32 shows an example of an Unattended Tasks Report.
The report shows that the California group has 15 unattended tasks, the Supervisor group has 7 unattended tasks, and the LoanAgentGroup has 11 unattended tasks. The unattended (unclaimed) tasks in this report are all DocumentReview tasks. If more than one type of unattended task exists when a report is run, all task types are included in the report, and the various task types are differentiated by color.
This report provides an analysis of the number of tasks assigned to a user, reportees, or their groups, broken down by priority. Use the following input parameters to define the report:
Assignee—Depending on the assignee that you choose, this includes tasks assigned to you (My), tasks assigned to you and groups that you belong to (My & Group), or tasks assigned to groups to which your reportees belong.
Creation Date (range)
Ended Date (range)—This is the end dates of the tasks to be included in the report.
Priority
See Table 16-2 for descriptions of Creation (or Created) Date and Priority.
Figure 16-33 shows an example of a Tasks Priority Report.
The report shows that the California group, the Supervisor group, and the LoanAgentGroup each have 16 tasks of normal priority. The users rsteven and jcooper have 5 and 22 tasks, respectively, all normal priority. Priorities (highest, high, normal, low, lowest) are distinguished by different colors in the bar chart.
This report provides an analysis of the time taken to complete tasks from creation to completion based on users' groups or reportees' groups. Use the following input parameters to define the report:
Assignee—Depending on the assignee that you choose, this includes your tasks or tasks assigned to groups to which your reportees belong.
Creation Date (range)
Ended Date (range)—This is the end dates of the tasks to be included in the report.
Priority
See Table 16-2 for descriptions of Creation (or Created) Date and Priority.
Figure 16-34 shows an example of a Tasks Cycle Time Report.
The report shows that it takes 1 hour and 6 minutes on average to complete DocumentReview tasks, and 1 hour and 28 minutes on average to complete VacationApproval tasks. The bar chart shows the average cycle time in milliseconds.
This report provides an analysis of assigned tasks and completed tasks in a given time period for a user, reportees, or their groups. Use the following input parameters to define the report:
Assignee—Depending on the assignee that you choose, this includes your tasks or tasks assigned to groups to which your reportees belong.
Creation Date (range)—The default is one week.
Task Type—Use the flashlight icon to select from a list of task titles. All versions of a task are listed on the Select Workflow Task Type page, as shown in Figure 16-35.
Figure 16-36 shows an example of a Tasks Productivity Report.
The report shows the number of tasks assigned to the California, LoanAgentGroup, and Supervisor groups. For individual users, the report shows that jcooper has 22 assigned tasks. In addition to his assigned tasks, jcooper has completed 2 tasks. The report shows that mtwain and rsteven have completed 6 and 11 tasks respectively. In the bar chart, the two task states—assigned and completed—are differentiated by color.
In the banner area, the logged-in user's name appears, as in Welcome jstein [jazn.com]. Click the user name to display 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 16-37.
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. The Group Info page displays the list of direct and indirect users (users contained in child groups of the current group).
The identity service determines a user's preferred 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 user's preferred language and time zone are set to the system default (en_US and America/Los_Angeles, as shown in the following sample code).
Using the sample worklist configured with the user community in the JAZN XML file, you can set the user's preferred language and time zone in the demo-users-properties.xml file as follows:
<timeZone>America/Los_Angeles</timeZone> <languagePreference>en_US</languagePreference>
The demo-users-properties.xml file is found in
SOA_Oracle_Home\bpel\system\services\config
The Worklist Application supports the locales shown in Table 16-4.
Table 16-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) |
If an LDAP-based provider such as OID is used, then language settings are 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. Most strings in the Worklist Application come from the worklist application bundle. By default, this is the class
oracle.bpel.services.workflow.resource.WorkflowResourceBundle
However, this can be changed to a custom resource bundle by setting the appropriate application preference. See "Using the Administration Functions" for more information.
For task attribute names, flex field attribute labels, and dynamic assignment function names, the strings come from configuring the resource property file WorkflowLabels.properties. This file exists in the wfresource subdirectory of the services config directory. See Chapter 15, "Oracle BPEL Process Manager Workflow Services" for information on adding entries to this file for dynamic assignment functions and attribute labels.
For custom actions and task titles, the display names come from the message bundle specified in the task configuration file. If no message bundle is specified, then the values specified at design time are used. See Chapter 15, "Oracle BPEL Process Manager Workflow Services" for information on how to specify message bundles so that custom actions and task titles are displayed in the preferred language.
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.
The Worklist Application is available in the samples directory at
SOA_Oracle_Home\bpel\samples\hw\worklistapp
The Worklist Application follows the standard model-view-controller approach, as shown in Figure 16-38.
A request coming from the browser is handled by a servlet. The servlet validates the request and calls the appropriate workflow service client API to query or update data. The worklist client APIs support a variety of different protocols (local and remote EJBs, direct java invocation, SOAP) for invoking the underlying workflow service. The clients send the API request to the workflow services, using the appropriate protocol. After the API call, the servlet stores the data required for rendering the next page in the session. The JSP picks up the data from the session, renders the data, and removes it from the session. Hence the servlets and the JSPs have different functions. The servlets are responsible for making the back-end API calls and the JSPs are responsible for formatting the data.
The Worklist Application servlets are at
SOA_Oracle_Home\bpel\samples\hw\worklistapp\src\worklistapp\servlets
All servlets extend the class worklistapp.servlets.BaseServlet. This class implements common functionality required by all servlets, such as authentication.
The JSPs are at
SOA_Oracle_Home\bpel\samples\hw\worklistapp\public_html
The workflow client API is a public interface made available by the workflow services. The interface is at
oracle.bpel.services.workflow.client.IWorkflowServiceClient
An instance of the API interface can be obtained by invoking the getWorkflowServiceClient method on
oracle.bpel.services.workflow.client.WorkflowServiceClientFactory
See Chapter 15, "Oracle BPEL Process Manager Workflow Services" for more information.
A typical page flow sequence is shown in Figure 16-39.
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 redirects the page to the login JSP that is sent to the browser. The user enters a username and password and the login servlet calls the authenticate method on the task query service. If successful, it redirects to the TaskList servlet URL. The browser's request then goes to the TaskList servlet that calls the queryTasks method on the task query service for getting the tasks that the user should see. Then it redirects the page to the TaskList JSP that is sent to the browser. When a user clicks a task link, the request is handled by the TaskDetails servlet. This calls the getTaskDetailsById method on the task query service and redirects the page to the TaskDetails JSP that is sent to the browser. Page flows for other functionality, such as updating the payload, adding an attachment, reassigning a task, viewing history, and updating user preferences, are similar.
The separation of responsibility—between servlets that handle API calls and processing, and JSPs that handle formatting of the data—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 JSPs (and the Java class HTMLFormatter.java used for formatting HTML data).
Table 16-5 lists the Worklist Application JSPs.
Table 16-5 Worklist Application JSPs
| JSP | Servlet | Notes |
|---|---|---|
AdminPrefs.jsp |
Admin | Application customization preferences |
AdvancedSeach.jsp |
TaskList | Advanced query for tasklist |
Branding.jsp |
-- | Branding information displayed in the top left corner of every page |
ColumnSelectIncludes.jsp |
-- | Control that allows users to select a list of columns. Used in DisplayPrefs.jsp and ViewEdit.jsp |
DisplayPrefs.jsp |
Preferences | User display preferences |
Error.jsp |
-- | All servlets redirect to this page when the exception is caught |
FilterForm.jsp |
-- | Control that allows users to define advanced task queries. Used in AdvancedSearch.jsp and ViewEdit.jsp |
FilterIncludes.jsp |
-- | Control that allows users to define task filtering criteria, used in FilterForm.jsp and RuleEdit.jsp |
Footer.jsp |
-- | Appears at the bottom of every page |
GetHWTaskHistory.jsp |
-- | -- |
Header.jsp |
-- | Appears at the top of every page |
HeaderIncludes.jsp |
-- | Used to include common Javascript function into the page headers |
Home.jsp |
Admin | Used as a container for the administrator pages |
IdentityBrowser.jsp |
IdentityBrowserPopup | Control that allows users to select users and groups |
IdentityBrowserPopup.jsp |
IdentityBrowserPopup | Pop-up window that includes the identity browser control |
Login.jsp |
Login | Application login page |
PayloadMapping.jsp |
Admin | Flex field payload mapping |
PayloadMappingBrowser.jsp |
PayloadMappingBrowser | Flex field payload mapping |
PayloadMappingBrowserPopup.jsp |
PayloadMappingBrowserPopup | Flex field payload mapping |
PayloadMappingEditor.jsp |
-- | Flex field payload mapping |
PayloadMappingLabelPopup.jsp |
-- | Flex field payload mapping |
PopUpHeader.jsp |
-- | Header displayed in pop-up windows |
Preferences.jsp |
Preferences | Used as a container for the user preferences pages |
ReportChart.jsp |
Reports | Task reporting |
ReportEdit.jsp |
Reports | Task reporting |
ReportInput.jsp |
Reports | Task reporting |
ReportOutput.jsp |
Reports | Task reporting |
Reports.jsp |
Reports | Container page for the task reporting pages |
RequestInfo.jsp |
RequestInfo | Task request info requests |
RuleCreate.jsp |
Preferences | Create a new workflow rule |
RuleEdit |
Preferences | Edit workflow rule details |
RuleList.jsp |
Preferences | Listing of workflow rules |
SubTasks.jsp |
SubTasks | View task subtasks |
TaskAssignees.jsp |
TaskAssignee | Handle task reassignment |
TaskDetails.jsp |
TaskDetails | Display task details |
TaskHistory.jsp |
TaskHistory | Display task history |
TaskList.jsp |
TaskList | Main application page. Displays lists of tasks |
TaskRouting.jsp |
TaskRouting | Handle updates to task routing |
TaskTypeDetails.jsp |
TaskType | Display details for workflow tasktype |
TaskTypeList.jsp |
TaskType | Display a list of task types in a pop-up window |
UserInfo.jsp |
UserInfo | Display user information |
UserInfoContent.jsp |
UserInfo | Display user information |
Vacation.jsp |
Preferences | User vacation preference |
ViewDetails.jsp |
Preferences | Details for delegated user task views |
ViewEdit.jsp |
Preferences | Edit details for owned user task views |
ViewList.jsp |
Preferences | Listing of user task views |
The following sections discuss how to customize some commonly used pages.
You can customize the image on the login page (the default is an image of people). In Login.jsp, replace the portion of the image tag shown in bold (people.jpg) with your own image:
<IMG HEIGHT="55" SRC="img/people.jpg">
See "Application Customization" for information on customizing the login page realm label.
The header section appears on every page above the bread crumb navigation. You can customize the header by modifying the Header.jsp file. 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.
See "Application Customization" for information on changing the branding image.
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 Task Details page is 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. The information displayed on this form is typically defined by the task definition for the task being displayed (and the format is controlled by the workflow task designer). You can customize the Task Details page by modifying the TaskDetails.jsp file. See "Generating a Custom Task Display Form" for information on how to customize this file.
The workflow services client interfaces can use a number of protocols to communicate with the workflow services. The client implementations encapsulate all the communication details, and users of the client interfaces do not need to be concerned with the details.
The Worklist Application is deployed in the same container as the workflow services, by default, and the application uses the Java client.
To switch the client type used by the Worklist Application, modify the init method in BaseServlet.java as follows:
public void init(ServletConfig config) throws ServletException
{
super.init(config);
try
{
wfSvcClient
= WorkflowServiceClientFactory.getWorkflowServiceClient(
WorkflowServiceClientFactory.JAVA_CLIENT);
}
catch (Exception e)
{
wlSvcError = getStackTraceString(e);
}
}
Also, change WorkflowServiceClientFactory.JAVA_CLIENT to one of the following:
WorkflowServiceClientFactory.SOAP_CLIENT—to use the SOAP-based Web services interface
WorkflowServiceClientFactory.LOCAL_CLIENT—to use the local EJB interface
WorkflowServiceClientFactory.REMOTE_CLIENT—to use the remote EJB interface
In addition, ensure that the wf_client_config.xml file is correctly set up for the client type that you select.
The top-level directory of the sample Worklist Application contains an ant script, build.xml, that can be used to build and deploy the Worklist Application. This ant script makes use of the properties file orabpel.properties that exists in the same directory. The instructions in this section also provide fixes to some incorrect files in the sample Worklist Application source files configuration.
This section contains the following topics:
Task 4: Building and Deploying the Application
See Also:
"Enabling the Worklist Application for Single Sign-On" after performing these tasks if you want to secure the Worklist Application to be Java single sign-on (JSSO)-enabledThe sample web.xml and worklist-taglib.tld file files are not currently in sync with the ones in the deployed Worklist Application and must be overwritten.
Copy the web.xml file from:
SOA_Oracle_Home\j2ee\OC4J_instance_name\applications\hw_services\worklistapp\WEB-INF\
to:
SOA_Oracle_Home\bpel\samples\hw\worklistapp\config\
Copy the worklist-taglib.tld file from:
SOA_Oracle_Home\j2ee\OC4J_instance_name\applications\hw_services\worklistapp\WEB-INF\
to:
SOA_Oracle_Home\bpel\samples\hw\worklistapp\public_html\WEB-INF\
Ensure that the EJB Server URL in the following file is the same as the value you specify for the oc4j.ormi.url property in Step 5 of "Task 2: Changing the Build File".
SOA_Oracle_Home\bpel\system\services\config\wf_client_config.xml
You must update the SOA_Oracle_Home\bpel\samples\hw\worklistapp\build.xml file for your process.
Update the path element that specifies the classpath to contain the following:
<path id="classpath">
<pathelement location="${orabpel.home}/system/services/lib/
bpm-services.jar"/>
<pathelement location="${orabpel.home}/lib/bpm-infra.jar" />
<pathelement location="${orabpel.home}/lib/orabpel.jar" />
<pathelement location="${orabpel.home}/lib/bicmn.jar" />
<pathelement location="${orabpel.home}/lib/bipres.jar" />
<pathelement location="${j2ee.home}/../../lib/xml.jar" />
<pathelement location="${j2ee.home}/../../lib/xmlparserv2.jar" />
<pathelement location="${j2ee.home}/jazncore.jar" />
<pathelement location="${custom.classpath}" />
</path>
Update the deploy target deploy.oc4j to include the following:
<target name="deploy.oc4j" depends="validate.properties,worklist.ear">
<!-- Deploy application ear -->
<java jar="${j2ee.home}/admin_client.jar" dir="${j2ee.home}" fork="true">
<arg line="${oc4j.ormi.url} ${oc4j.admin.username}
${oc4j.admin.password} -deploy -file
${worklist.classes.dir}/customworklist.ear -deploymentName
customapp -parent orabpel" />
</java>
<java jar="${j2ee.home}/admin_client.jar" dir="${j2ee.home}" fork="true">
<arg line="${oc4j.ormi.url} ${oc4j.admin.username}
${oc4j.admin.password}
-bindAllWebApps -appName customapp" />
</java>
</target>
Update the target worklistapp.ear to include the following:
<target name="worklist.ear" depends="worklist.war">
<ear compress="true" earfile="${worklist.classes.dir}/customworklist.ear"
appxml="${worklist.config.dir}/application.xml">
<fileset dir="${worklist.classes.dir}">
<include name="**/*.war"/>
<exclude name="**/*.ear"/>
</fileset>
<fileset dir="${worklist.config.dir}">
<include name="**/META-INF/orion-application.xml"/>
</fileset>
</ear>
</target>
Open the SOA_Oracle_Home\bpel\samples\hw\worklistapp\orabpel.properties file.
Change OC4J-related properties to the following:
#Standalone OC4J related properties #oc4j.ormi.url=deployer:oc4j:hostname:ormiport oc4j.ormi.url=deployer:oc4j:opmn://host_name:OPMN_request_port/home oc4j.admin.username=oc4jadmin #oc4j.admin.password=password oc4j.admin.password=welcome1
Verify that you have correctly made the changes described in "Task 1: Changing the Application Configuration" through "Task 2: Changing the Build File" before attempting to build and deploy the application.
Verify that you correctly updated the following files in the SOA_Oracle_Home\bpel\samples\hw\worklistapp directory:
config\web.xml
build.xml
orabpel.properties
Verify that you correctly updated the SOA_Oracle_Home\bpel\samples\hw\worklistapp\public_html\WEB-INF\worklist-taglib.tld file.
Ensure all the properties in orabpel.properties have been updated to reflect your environment.
Build and deploy the customized Worklist Application from the command line:
ant deploy.oc4j
Access the customized Worklist Application at the following URL:
http://host:port/integration/customapp/
Log in to the Worklist Application.
The task list page appears.
See Also:
"Enabling the Worklist Application for Single Sign-On" if you now want to secure the Worklist Application to be Java single sign-on (JSSO)-enabledThe Worklist Application offers a number of ways to customize its look-and-feel without editing the JSP code or changing the application servlets.
Every worklist user is able to customize the columns displayed in his inbox, the size of the worklist page, and how many tasks to display at a time. See "Setting Preferences" for more information.
Worklist administrators can also change a number of preferences that influence the appearance of the Worklist Application for all users, such as the branding image. Administrators can specify a different resource bundle and change the label for the list of realms on the login screen. See "Using the Administration Functions" for more information.
You can change the names used for various task attributes in the application by updating the following file (and its associated translations):
SOA_Oracle_Home/bpel/system/services/config/wfresource/WorflowLabels.properties
Note that this changes the labels returned by the task metadata service methods getTaskAttributes and getTaskAttributesForTaskDefinition. Any service clients that use these methods will be affected.
The workflow 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) has 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:
CLAIM
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.
You can customize the Worklist Application so that the information viewed and the actions performed on a given page are 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, the identity service can be used to check if the user has the granted role and to determine which code path to take.
For example, you can create a new role called BPMProcessingManager in jazn-data.xml. This file is at
SOA_Oracle_Home\bpel\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
{
BPMAuthorizationService authorizationService =
ServiceFactory.getAuthorizationServiceInstance(realm);
// lookup user based on worklist context user
BPMUser bpmUser = authorizationService.lookupUser(user);
// 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 10.1.3.1 Worklist Application by default uses a custom authentication mechanism through its own login page. The Worklist Application does not run under OC4J container security and is not Java single sign-on (JSSO)-enabled. The Worklist Application source files are located in the SOA_Oracle_Home\bpel\samples\hw\worklistapp directory. This section describes how to secure the Worklist Application with JSSO.
This section contains the following topics:
Note:
Before performing the tasks in this section, ensure that you have completed the Worklist Application deployment tasks in "Deploying the Custom Worklist Application".Open the SOA_Oracle_Home\bpel\samples\hw\worklistapp\src\worklistapp\servlets\BaseServlet.java file.
Remove the following code fragment that begins on line 218 in the validateSession() method:
else
{
// forward request to login page, if user session is null
//(not if session store or wfCtx is null, as login servlet will set them)
if ( userSession == null )
{
RequestDispatcher rd = getServletContext().getRequestDispatcher(
WorklistappConstants.PAGE_LOGIN_JSP);
if (rd != null)
{
rd.forward(request,response);
return false;
}
}
}
Open the Login.java file in the same directory.
Replace the code up to the end of the try{} block in the handleRequest() method with the following:
String user = getParameter(request,WorklistappConstants.PARAM_LOGIN_USER);
String password = getParameter(request,WorklistappConstants.PARAM_LOGIN_
PASSWORD);String realm = getParameter(request,WorklistappConstants.PARAM_LOGIN_REALM);
String redirectURL = getParameter(request,WorklistappConstants.PARAM_REDIRECT_
URL);HttpSession userSession = request.getSession(true);
SessionStore sessStore = new SessionStore(userSession);
String remoteUser = request.getRemoteUser();
if ((user == null) && (password == null) && (remoteUser == null))
{
pageRedirect(request, response, WorklistappConstants.PAGE_LOGIN_JSP);
return;
}
try
{
IWorkflowContext wfCtx = null;
if ( user != null )
{
//Authenticate the supplied credentials
wfCtx = wfSvcClient.getTaskQueryService().authenticate(user, password, realm,
null);
}
else
{
//Create context using remoteUser in request (pre-authenticated request)
wfCtx = wfSvcClient.getTaskQueryService().createContext(request);
}
initSessionAttributes(sessStore, wfCtx);
initRequestStatus(sessStore);
if (redirectURL != null)
response.sendRedirect(redirectURL);
else
response.sendRedirect(WorklistappConstants.SERVLET_TASK_LIST);
}
Open the Logout.java file in the same directory.
Add the following private method:
//When logging out, we need to know if oc4j SSO util class
//exists in classpath
private static boolean oc4jSSOExists = false;
static
{
//Try and load the class
try
{
Class.forName("oracle.security.jazn.sso.util.JSSOUtil");
//Class was found
oc4jSSOExists = true;
} catch (ClassNotFoundException e)
{
oc4jSSOExists = false;
}
}
Replace the code inside the try{} block in the handleRequest() method with the following:
// destroy context not needed anymore
wfSvcClient.getTaskQueryService().destroyWorkflowContext(wfCtx);
//If we're running in oc4j, ensure SSO knows we've logged out...
if ( oc4jSSOExists )
{
oracle.security.jazn.sso.util.JSSOUtil.logout(response,
request.getContextPath()+"/"+WorklistappConstants.SERVLET_LOGIN);
}
//Invalidate the session
if (userSession != null)
{
userSession.invalidate();
}
//If we're not running in oc4j, handle the redirect to the login page ourselves
if ( !oc4jSSOExists )
{
response.sendRedirect(WorklistappConstants.SERVLET_LOGIN);
}
Go to the SOA_Oracle_Home\bpel\samples\hw\worklistapp\config directory.
Create a directory named META-INF.
Go into the META-INF directory and create a file named orion-application.xml.
Enable deployment by adding the following syntax to orion-application.xml.
<?xml version='1.0' encoding='windows-1252' ?>
<orion-application>
<jazn provider="XML">
<jazn-web-app auth-method="CUSTOM_AUTH"/>
</jazn>
<security-role-mapping name="PUBLIC">
<group name="{{PUBLIC}}" />
</security-role-mapping>
</orion-application>
The sample web.xml file is not currently in sync with the one in the deployed Worklist Application and must be overwritten.
Add the following code to web.xml in the config directory.
<login-config>
<auth-method>BASIC</auth-method>
</login-config>
<security-role>
<role-name>{{PUBLIC}}</role-name>
</security-role>
<security-constraint>
<web-resource-collection>
<web-resource-name>worklistpages</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>{{PUBLIC}}</role-name>
</auth-constraint>
</security-constraint>
If you are using multiple realms, the SOA_Oracle_Home\bpel\system\services\config\wf_client_config.xml file must contain the correct entry for the realm in the following element:
<portal>
<realmMapping>jazn.com</realmMapping>
</portal>
Verify that you have correctly made the changes described in "Task 1: Changing the Servlet Code" through "Task 2: Changing the Application Configuration" before attempting to build and deploy the application.
Verify that you correctly updated the following files in the SOA_Oracle_Home\bpel\samples\hw\worklistapp directory:
src\worklistapp\servlets\BaseServlet.java
src\worklistapp\servlets\Login.java
src\worklistapp\servlets\Logout.java
Verify that you correctly updated the SOA_Oracle_Home\bpel\system\services\config\wf_client_config.xml file.
Verify that you correctly created the SOA_Oracle_Home\bpel\samples\hw\worklistapp\config\META-INF\orion-application.xml file.
Ensure all the properties in orabpel.properties have been updated to reflect your environment.
Build and deploy the customized Worklist Application from the command line:
ant deploy.oc4j
Access the customized Worklist Application at the following URL:
http://host:port/integration/customapp/
You are prompted with the SSO login page.
Log in to the Worklist Application.
After you are authenticated, you see the task list page.
Log out of the Worklist Application.
The SSO login page again appears.
You can build clients for workflow services using the APIs exposed by the workflow service. The APIs enable clients to communicate with the workflow service using local and remote EJBs, SOAP, and HTTP.
You can start with the sample Worklist Application to build your own application.
The typical sequence of calls when building a simple worklist application is as follows:
Get a handle to IWorklistServiceClient from WorkflowServiceClientFactory.
Get a handle to ITaskQueryService from IWorklistServiceClient.
Authenticate a user by passing a username and password to the authenticate method on ITaskQueryService. Get a handle to IWorkflowContext.
Query the list of tasks using ITaskQueryService.
Get a handle to ITaskService from IWorklistServiceClient.
Iterate over the list of tasks returned, performing actions on the tasks using ITaskService.
Example 16-1 demonstrates how to build a client for workflow services. A list of all tasks assigned to jstein is queried. A task whose outcome has not been set is approved.
Example 16-1 Building a Client for Workflow Services—Setting the Outcome to Approved
try {
//Create JAVA WorflowServiceClient
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(WorkflowServiceClientFactory.JAVA_CLIENT);
//Get the task query service
ITaskQueryService querySvc = wfSvcClient.getTaskQueryService();
//Login as jstein
IWorkflowContext ctx = querySvc.authenticate("jstein",
"welcome1",
null, //Use default realm
null);//Not logging in on behalf of another user
//Set up list of columns to query
List queryColumns = new ArrayList();
queryColumns.add("TASKID");
queryColumns.add("TASKNUMBER");
queryColumns.add("TITLE");
queryColumns.add("OUTCOME");
//Create a predicate to query tasks that have a null outcome
String outcome = null;
Predicate predicate = new Predicate(TableConstants.WFTASK_OUTCOME_COLUMN,
Predicate.OP_EQ,
outcome);
//Create an ordering to order tasks by task number
Ordering ordering = new Ordering(TableConstants.WFTASK_TASKNUMBER_COLUMN
,true //Ascending order
,false //Nulls last
);
//Query a list of tasks assigned to jstein
List tasks = querySvc.queryTasks(ctx,
queryColumns,
null, //Do not query additional info
ITaskQueryService.ASSIGNMENT_FILTER_MY,
null, //No keywords
predicate, //Only tasks with no outome set
ordering, //Order by ascending task number
0, //Do not page the query result
0);
//Get the task service
ITaskService taskSvc = wfSvcClient.getTaskService();
//Loop over the tasks, outputting task information, and approving tasks
for(int i = 0 ; i < tasks.size() ; i ++)
{
Task task = (Task)tasks.get(i);
int taskNumber = task.getSystemAttributes().getTaskNumber();
String title = task.getTitle();
String taskId = task.getSystemAttributes().getTaskId();
//Set the outcome
taskSvc.updateTaskOutcome(ctx,taskId,"APPROVED");
System.out.println("Task #"+taskNumber+" ("+title+") is APPROVED");
}
}
catch (Exception e)
{
//Handle any exceptions raised here...
System.out.println("Caught workflow exception: "+e.getMessage());
}
}
See Also:
The following samples, which demonstrate how to write a custom UI for the Worklist Application:
SOA_Oracle_home\bpel\samples\utils\AsyncLoanService\StarLoanUI SOA_Oracle_home\bpel\samples\demos\HelpDeskServiceRequest\HelpDeskUI SOA_Oracle_home\bpel\samples\demos\ExpenseRequestApproval\ ExpenseRequestUI
SOA_Oracle_Home\bpel\docs\workflow\index.html for Javadoc that describes the workflow service APIs
Use the following packages and classes for building clients:
oracle.bpel.services.workflow.metadata.config.model
The classes in this package contain the object model for the workflow configuration in the task definition file. The ObjectFactory class can be used to create objects.
oracle.bpel.services.workflow.metadata.routingslip.model
The classes in this package contain the object model for the routing slip. The ObjectFactory class can be used to create objects.
oracle.bpel.services.workflow.metadata.taskdisplay.model
The classes in this package contain the object model for the task display. The ObjectFactory class can be used to create objects.
oracle.bpel.services.workflow.metadata.taskdefinition.model
The classes in this package contain the object model for the task definition file. The ObjectFactory class can be used to create objects.
oracle.bpel.services.workflow.client.IWorkflowServiceClient
Interface for the workflow service client.
oracle.bpel.services.workflow.client.WorkflowServiceClientFactory
The factory for creating the workflow service client.
oracle.bpel.services.workflow.metadata.ITaskMetadataService
The interface for task metadata service.
oracle.bpel.services.workflow.task.ITaskService
The interface for task service.
oracle.bpel.services.workflow.task.IRoutingSlipCallback
The interface for callback class to receive callbacks during task processing.
oracle.bpel.services.workflow.task.IAssignmentService
The interface for the assignment service.
Any worklist application accesses the various workflow services through the workflow service client. The workflow service client code encapsulates all the logic required for communicating with the workflow services using different local and remote protocols. After the worklist application has an instance of the workflow service client, it does not need to consider how the client communicates with the workflow services.
The advantages of using the client are as follows:
Hides the complexity of the underlying connection mechanisms such as SOAP/HTTP and EJB
Facilitates changing from using one particular invocation mechanism to another, for example from SOAP/HTTP to remote EJB
Helps to program with Java APIs for service input/outputs instead of XML inputs/outputs for SOAP/HTTP or Java WSIF invocation mechanism
The following class is used to create instances of the IWorkflowServiceClient interface:
oracle.bpel.services.workflow.client.WorkflowServiceClientFactory
WorkflowServiceClientFactory has a single method, getWorkflowServiceClient, which takes a single parameter, the client type. The client type can be one of the following:
WorkflowServiceClientFactory.JAVA_CLIENT—The client uses Java to invoke the workflow services directly.
WorkflowServiceClientFactory.LOCAL_CLIENT—The client uses a local EJB interface to invoke the workflow services.
WorkflowServiceClientFactory.REMOTE_CLIENT—The client uses a remote EJB interface to invoke workflow services located remotely from the client.
WorkflowServiceClientFactory.SOAP_CLIENT—The client uses SOAP to invoke Web service interfaces to the workflow services, located remotely from the client.
Through the factory, it is possible to get the client libraries for all the workflow services. Table 16-6 shows the clients available for each of the services.
Table 16-6 Clients Available for the Workflow Services
The client classes use the configuration file wf_client_config.xml for the service end points. This file is at
SOA_Oracle_Home/bpel/system/services/config
In the client classpath, this file should be in the classpath directly, meaning the containing directory should be in the classpath. The wf_client_config.xml file contains:
A section for EJB configuration
<ejb>
<serverURL>ormi://localhost/hw_services</serverURL> <!-- for stand alone -->
<!--serverURL>opmn:ormi://localhost:home/hw_services</serverURL--> <!-- for
opmn managed instance -->
<user>oc4jadmin</user>
<password>welcome1</password>
<initialContextFactory>oracle.j2ee.rmi.RMIInitialContextFactory</initialContextFactory>
</ejb>
A section for SOAP end points for each of the services
<taskService> <soapEndPoint>http://localhost:9700/integration/services/TaskService/ TaskServicePort</soapEndPoint> </taskService>
See Also:
The following for more information about task services:The IWorkflowServiceClient interface provides methods, summarized in Table 16-7, for obtaining handles to the various workflow services interfaces.
Table 16-7 IWorkflowServiceClient Methods
| Method | Interface |
|---|---|
getTaskService |
oracle.bpel.services.workflow.task.ITaskService |
getTaskQueryService |
oracle.bpel.services.workflow.query.ITaskQueryService |
getTaskReportService |
oracle.bpel.services.workflow.report.ITaskReportService |
getTaskMetadataService |
oracle.bpel.services.workflow.metadata.ITaskMetadataService |
getUserMetadataService |
oracle.bpel.services.workflow.user.IUserMetadataService |
getRuntimeConfigService |
oracle.bpel.services.workflow.runtimeconfig.IRuntimeConfigService |
getAuthenticationService |
oracle.tip.pc.services.identity.BPMAuthenticationService |
getAuthorizationService |
oracle.tip.pc.services.identity.BPMAuthorizationService |
The following JAR files are necessary for the Java client classpath.
$BPEL_HOME/bpel/lib/bpm-infra.jar
$BPEL_HOME/bpel/lib/orabpel-common.jar
$BPEL_HOME/bpel/lib/orabpel-thirdparty.jar
$BPEL_HOME/bpel/lib/orabpel.jar
$BPEL_HOME/bpel/system/appserver/oc4j/j2ee/home/jazncore.jar
$BPEL_HOME/bpel/system/appserver/oc4j/j2ee/home/oc4jclient.jar
$BPEL_HOME/bpel/system/appserver/oc4j/lib/xml.jar
$BPEL_HOME/bpel/system/appserver/oc4j/lib/xmlparserv2.jar
$BPEL_HOME/bpel/system/appserver/oc4j/webservices/lib/orasaaj.jar
$BPEL_HOME/bpel/system/appserver/oc4j/webservices/lib/soap.jar
$BPEL_HOME/bpel/system/services/config
$BPEL_HOME/bpel/system/services/lib/bpm-services.jar
$BPEL_HOME/bpel/system/services/schema
wsclient_extended.zip
Note:
Thewsclient_extended.jar file is available as a separate download from the Oracle Technology Network at
http://download.oracle.com/otn/java/oc4j/1013/ wsclient_extended.zip
See the chapter "Web Service Client APIs and JARs" in the section "Simplifying the Classpath with wsclient_extended.jar" in Oracle Application Server Web Services Developer's Guide 10g Release 3 (10.1.3), at
http://www.oracle.com/technology/documentation
If a Web application uses the workflow service local EJBs, then the client application must do the following:
The application must be a child application of the hw_services application.
The application must define the EJB local references in its web.xml file. The local references for each of the services are shown in Example 16-2 and Example 16-3.
Example 16-2 Task Service
<ejb-local-ref id="EjbRef_TaskServiceBean_Message"> <ejb-ref-name>ejb/local/TaskServiceBean</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home>oracle.bpel.services.workflow.task.ejb.TaskServiceLocalHome</local-home> <local>oracle.bpel.services.workflow.task.ejb.TaskServiceLocal</local> <ejb-link>TaskServiceBean</ejb-link> </ejb-local-ref>
Example 16-3 Task Metadata Service
<ejb-local-ref id="EjbRef_TaskMetadataServiceBean_Message"> <ejb-ref-name>ejb/local/TaskMetadataServiceBean</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home>oracle.bpel.services.workflow.metadata.ejb.TaskMetadataServiceLocalHome</local-home> <local>oracle.bpel.services.workflow.metadata.ejb.TaskMetadataServiceLocal</local> <ejb-link>TaskMetadataServiceBean</ejb-link> </ejb-local-ref>
Note:
Only child applications can use local EJBs. This restricts standalone Java clients to using either remote EJBs or SOAP clients.See Chapter 15, "Oracle BPEL Process Manager Workflow Services" for more information on the task query service, task report service, user metadata service, and runtime config service.
Tasks can be initiated programmatically, in which case the following task attributes must be set:
taskDefinitionURI
title
payload
priority
The following task attributes are optional, but are typically set by clients:
creator
ownerUser—Defaults to bpeladmin if empty
processInfo
identificationKey—Tasks can be queried based on the identification key from the TaskQueryService
The task object model is available in the package
oracle.bpel.services.workflow.task.model
To create objects in this model, use the ObjectFactory class.
The task payload can contain multiple payload message attributes. Since the payload is not well defined until the task definition, the Java object model for the task does not contain strong type objects for the client payload. The task payload is represented by the AnyType Java object. The AnyType Java object is created with an XML element whose root is payload in the namespace
http://xmlns.oracle.com/bpel/workflow/task
The payload XML element contains all the other XML elements in it. Each XML element defines a message attribute.
Example 16-4 shows how to set a task payload.
Example 16-4 Setting a Task Payload
import oracle.bpel.services.workflow.task.model.AnyType;
import oracle.bpel.services.workflow.task.model.ObjectFactory;
import oracle.bpel.services.workflow.task.model.Task;
..........
Document document = //createXMLDocument
Element payloadElem = document.createElementNS("http://xmlns.oracle.com/bpel/workflow/
task", "payload");
Element orderElem = document.createElementNS("http://xmlns.oracle.com/pcbpel/test/order", "order");
Element child = document.createElementNS("http://xmlns.oracle.com/pcbpel/test/order", "id");
child.appendChild(document.createTextNode("1234567"));
orderElem.appendChild(child);
payloadElem.appendChild(orderElem);
document.appendChild(payloadElem);
task.setPayloadAsElement(payloadElem);
Note:
TheAnyType.getContent() element returns an unmodifiable list of XML elements. You cannot add other message attributes to the list.Example 16-5 shows how to initiate a vacation request task programmatically.
Example 16-5 Initiating a Vacation Request Task Programmatically
// create task object
ObjectFactory objectFactory = new ObjectFactory();
Task task = objectFactory.createTask();
// set title
task.setTitle("Vacation request for jcooper");
// set creator
task.setCreator("jcooper");
// set task definition URI
task.setTaskDefinitionURI("http://localhost:9700/orabpel/default/VacationRequest/1.0/
VacationApproval/VacationApproval.task");
// create and set payload
Document document = XMLUtil.createDocument();
Element payloadElem = document.createElementNS(TASK_NS, "payload");
Element vacationRequestElem = document.createElementNS(VACATION_REQUEST_NS,
"VacationRequestProcessRequest");
Element creatorChild = document.createElementNS(VACATION_REQUEST_NS, "creator");
creatorChild.appendChild(document.createTextNode("jcooper"));
vacationRequestElem.appendChild(creatorChild);
Element fromDateChild = document.createElementNS(VACATION_REQUEST_NS, "fromDate");
fromDateChild.appendChild(document.createTextNode("2006-08-05T12:00:00"));
vacationRequestElem.appendChild(fromDateChild);
Element toDateChild = document.createElementNS(VACATION_REQUEST_NS, "toDate");
toDateChild.appendChild(document.createTextNode("2006-08-08T12:00:00"));
vacationRequestElem.appendChild(toDateChild);
Element reasonChild = document.createElementNS(VACATION_REQUEST_NS, "reason");
reasonChild.appendChild(document.createTextNode("Hunting"));
vacationRequestElem.appendChild(reasonChild);
payloadElem.appendChild(vacationRequestElem);
document.appendChild(payloadElem);
task.setPayloadAsElement(payloadElem);
IWorkflowServiceClient workflowServiceClient =
WorkflowServiceClientFactory.getWorkflowServiceClient
(WorkflowServiceClientFactory.SOAP_CLIENT);
ITaskService taskService = workflowServiceClient.getTaskService();
IInitiateTaskResponse iInitiateTaskResponse = taskService.initiateTask(task);
Task retTask = iInitiateTaskResponse.getTask();
System.out.println("Initiated: " + retTask.getSystemAttributes().getTaskNumber() + " - " +
retTask.getSystemAttributes().getTaskId());
return retTask;
See "Vacation Request Example" for more information.
The following example shows how to modify the help desk interface that is part of the HelpDeskServiceRequest demo found at
SOA_Oracle_home\bpel\samples\demos\HelpDeskServiceRequest\HelpDeskUI
To write a Worklist Application
Create the workflow context by authenticating the user.
// get workflow service client
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient
(WorkflowServiceClientFactory.JAVA_CLIENT);
//get the workflow context
IWorkflowContext wfCtx =
wfSvcClient.getTaskQueryService().authenticate(userId, pwd,
oracle.tip.pc.services.identity.config.ISConfiguration.getDefaultRealmName(),
null);
This is Step 3 in "Building Clients for Workflow Services".
The login.jsp file of HelpDeskServiceRequest uses the preceding API to authenticate the user and create a workflow context. After the user is authenticated, the statusPage.jsp file displays the tasks assigned to the logged-in user. Example 16-6 shows sample code from the login.jsp file.
Example 16-6 Login.jsp
<%@ page import="javax.servlet.http.HttpSession"
import="oracle.bpel.services.workflow.client.IWorkflowServiceClient"
import="oracle.bpel.services.workflow.client.WorkflowServiceClientFactory"
import="java.util.Set"
import="java.util.Iterator"
import="oracle.bpel.services.workflow.verification.IWorkflowContext"
import="oracle.tip.pc.services.identity.config.ISConfiguration"%>
<%@ page contentType="text/html;charset=windows-1252"%>
<html>
<head>
<title>Help desk request login page</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body bgcolor="#F0F0F0" text="#000000" style="font: 12px verdana; line-height:18px">
<center>
<div style="width:640px;padding:15px;border-width: 10px; border-color: #87b4d9; border-style:
solid;
background-color:white; text-align:left">
<!-- Page Header, Application banner, logo + user status -->
<jsp:include page="banner.jsp"/>
<!-- Initiate Meta Information -->
<div style="background-color:#F0F0F0; border-top:10px solid white;border-bottom:
10px solid white;padding:10px;text-align:center" >
<b>Welcome to the HelpDesk application</b>
</div>
<%
String redirectPrefix = "/HelpDeskUI/";
// Ask the browser not to cache the page
response.setHeader("Pragma", "no-cache");
response.setHeader("Cache-Control", "no-cache");
HttpSession httpSession = request.getSession(false);
if (httpSession != null) {
IWorkflowContext ctx = (IWorkflowContext) httpSession.getAttribute("workflowContext");
if (ctx != null) {
response.sendRedirect(redirectPrefix + "statusPage.jsp");
}
else
{
String authFailedStr = request.getParameter("authFailed");
boolean authFailed = false;
if ("true".equals(authFailedStr))
{
authFailed = true;
}
else
{
authFailed = false;
}
if (!authFailed)
{
//Get page parameters:
String userId="";
if(request.getParameter("userId") != null)
{
userId = request.getParameter("userId");
}
String pwd="";
if(request.getParameter("pwd") != null)
{
pwd = request.getParameter("pwd");
}
if(userId != null && (!("".equals(userId.trim())))
&& pwd != null && (!("".equals(pwd.trim()))))
{
try {
HttpSession userSession = request.getSession(true);
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient
(WorkflowServiceClientFactory.JAVA_CLIENT);
IWorkflowContext wfCtx =
wfSvcClient.getTaskQueryService().authenticate(userId, pwd,
oracle.tip.pc.services.identity.config.ISConfiguration.getDefaultRealmName(), null);
httpSession.setAttribute("workflowContext", wfCtx);
response.sendRedirect(redirectPrefix + "statusPage.jsp");
}
catch (Exception e)
{
String worklistServiceError = e.getMessage();
response.sendRedirect(redirectPrefix + "login.jsp?authFailed=true");
out.println("error is " + worklistServiceError);
}
}
} else
{
out.println("Authentication failed");
}
}
}
%>
<form action='<%= request.getRequestURI() %>' method="post">
<div style="width:100%">
<table cellspacing="2" cellpadding="3" border="0" width="30%" align="center">
<tr>
<td>Username
</td>
<td>
<input type="text" name="userId"/>
</td>
</tr>
<tr>
<td>Password
</td>
<td>
<input type="password" name="pwd"/>
</td>
</tr>
<tr>
<td>
<input type="submit" value="Submit"/>
</td>
</tr>
</table>
</form>
</div>
</div>
</center>
</body>
</html>
Query tasks using the queryTask API from TaskQueryService.
//add list of attributes to be queried from the task
List displayColumns = new ArrayList();
displayColumns.add("TASKNUMBER");
displayColumns.add("TITLE");
displayColumns.add("PRIORITY");
displayColumns.add("STATE");
displayColumns.add("UPDATEDDATE");
displayColumns.add("UPDATEDBY");
displayColumns.add("CREATOR");
displayColumns.add("OUTCOME");
displayColumns.add("CREATEDDATE");
displayColumns.add("ASSIGNEEUSERS");
displayColumns.add("ASSIGNEEGROUPS");
// get the list of tasks
List tasks = wfSvcClient.getTaskQueryService().queryTasks
(wfCtx,
displayColumns,
null,
ITaskQueryService. ASSIGNMENT_FILTER_MY_AND_GROUP,
null,
null,
null,
0,
0);
// create listing page by using above tasks
//add href links to title to display details of the task by passing taskId
as input parameter
Use getTaskDetailsById(IWorkflowContext wftx, String taskId);
This is Step 4 in "Building Clients for Workflow Services".
The statusPage.jsp file of HelpDeskServiceRequest is used to display the status of help desk requests. Example 16-7 shows the statusPage.jsp example code.
Example 16-7 statusPage.jsp
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<%@ page import="oracle.tip.pc.services.identity.BPMAuthorizationService,
oracle.bpel.services.workflow.verification.IWorkflowContext,
oracle.tip.pc.services.common.ServiceFactory,
oracle.bpel.services.workflow.client.IWorkflowServiceClient,
oracle.bpel.services.workflow.client.WorkflowServiceClientFactory,
oracle.bpel.services.workflow.query.ITaskQueryService,
oracle.bpel.services.workflow.task.model.Task,
oracle.bpel.services.workflow.task.model.IdentityType,
oracle.tip.pc.services.identity.BPMUser,
java.util.List,
java.util.Calendar,
java.text.SimpleDateFormat,
java.util.ArrayList"%>
<%@ page contentType="text/html;charset=UTF-8"%>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<title>RequestPage</title>
<style TYPE="text/css">
Body, Form, Table, Textarea, Select, Input, Option
{
font-family : tahoma, verdana, arial, helvetica, sans-serif;
font-size : 9pt;
}
table.banner
{
background-color: #eaeff5;
}
tr.userInfo
{
background-color: #eaeff5;
}
tr.problemInfo
{
background-color: #87b4d9;
}
</style>
</head>
<body bgcolor="White">
<%
HttpSession httpSession = request.getSession(false);
httpSession.setAttribute("pageType","STATUSPAGE");
%>
<table bordercolor="#eaeff5" border="4" width="100%">
<tr><td> <jsp:include page="banner.jsp"/> </td></tr>
</table>
<%
BPMUser bpmUser = null;
String redirectPrefix = request.getContextPath() + "/";
IWorkflowContext ctx = null;
if (httpSession != null) {
ctx = (IWorkflowContext) httpSession.getAttribute("workflowContext");
if (ctx != null) {
bpmUser = getAuthorizationService(ctx.getIdentityContext()).
lookupUser(ctx.getUser());
}
else
{
response.sendRedirect(redirectPrefix + "login.jsp");
return;
}
}
else
{
response.sendRedirect(redirectPrefix + "login.jsp");
return;
}
if(bpmUser == null)
{
response.sendRedirect(redirectPrefix + "login.jsp");
return;
}
String status = (String)httpSession.getAttribute("requeststatus");
if(status != null && !status.equals(""))
{
%>
<p></p>
<div style="text-align:left;color:red" >
<%= status %>
</div>
<%
}
httpSession.setAttribute("requeststatus",null);
IWorkflowServiceClient wfSvcClient =
WorkflowServiceClientFactory.getWorkflowServiceClient(
WorkflowServiceClientFactory.JAVA_CLIENT);
List displayColumns = new ArrayList();
displayColumns.add("TASKNUMBER");
displayColumns.add("TITLE");
displayColumns.add("PRIORITY");
displayColumns.add("STATE");
displayColumns.add("UPDATEDDATE");
displayColumns.add("UPDATEDBY");
displayColumns.add("CREATOR");
displayColumns.add("OUTCOME");
displayColumns.add("CREATEDDATE");
displayColumns.add("ASSIGNEEUSERS");
displayColumns.add("ASSIGNEEGROUPS");
List tasks = wfSvcClient.getTaskQueryService().queryTasks
(ctx,
displayColumns,
null,
ITaskQueryService.ASSIGNMENT_FILTER_CREATOR,
null,
null,
null,
0,
0);
%>
<p></p>
<div style="text-align:left;color:green" >
<b>
Previous help desk request
</b>
</div>
<p></p>
<div style="text-align:center" >
<table cellspacing="2" cellpadding="2" border="3" width="100%">
<TR class="problemInfo">
<TH>TaskNumber</TH>
<TH>Title</TH>
<TH>Priority</TH>
<TH>CreatedDate</TH>
<TH>Assignee(s)</TH>
<TH>UpdatedDate</TH>
<TH>UpdatedBy</TH>
<TH>State</TH>
<TH>Status</TH>
</TR>
<%
SimpleDateFormat dflong = new SimpleDateFormat( "MM/dd/yy hh:mm a" );
for(int i = 0 ; i < tasks.size() ; i ++)
{
Task task = (Task)tasks.get(i);
int taskNumber = task.getSystemAttributes().getTaskNumber();
String title = task.getTitle();
int priority = task.getPriority();
String assignee = getAssigneeString(task);
Calendar createdDate = task.getSystemAttributes().getCreatedDate();
Calendar updateDate = task.getSystemAttributes().getUpdatedDate();
String updatedBy = task.getSystemAttributes().getUpdatedBy().getId();
String state = task.getSystemAttributes().getState();
String outcome = task.getSystemAttributes().getOutcome();
if(outcome == null) outcome = "";
String titleLink = "http://" + request.getServerName() +
":" + request.getServerPort() +
"/integration/worklistapp/TaskDetails?taskId=" +
task.getSystemAttributes().getTaskId();
%>
<tr class="userInfo">
<td><%=taskNumber%></td>
<td><a href="<%=titleLink%>" target="_blank"><%=title%></a></td>
<td><%=priority%></td>
<td><%=dflong.format(createdDate.getTime())%></td>
<td><%=assignee%></td>
<td><%=dflong.format(updateDate.getTime())%></td>
<td><%=updatedBy%></td>
<td><%=state%></td>
<td><%=outcome%></td>
<tr>
<%
}
%>
</table>
</div>
<%!
private BPMAuthorizationService getAuthorizationService(String identityContext)
{
BPMAuthorizationService authorizationService = ServiceFactory.getAuthorizationServiceInstance();
if (identityContext != null)
authorizationService = ServiceFactory.getAuthorizationServiceInstance(identityContext);
return authorizationService;
}
private String getAssigneeString(Task task) throws Exception
{
List assignees = task.getSystemAttributes().getAssigneeUsers();
StringBuffer buffer = null;
for(int i = 0 ; i < assignees.size() ; i++)
{
IdentityType type = (IdentityType)assignees.get(i);
String name = type.getId();
if(buffer == null)
{
buffer = new StringBuffer();
}
else
{
buffer.append(",");
}
buffer.append(name).append("(U)");
}
assignees = task.getSystemAttributes().getAssigneeGroups();
for(int i = 0 ; i < assignees.size() ; i++)
{
IdentityType type = (IdentityType)assignees.get(i);
String name = type.getId();
if(buffer == null)
{
buffer = new StringBuffer();
}
else
{
buffer.append(",");
}
buffer.append(name).append("(G)");
}
if(buffer == null)
{
return "";
}
else
{
return buffer.toString();
}
}
%>
</body>
</html>
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. It also discusses how you can create and share custom views, manage user and group rules, customize task display settings, and perform administrative tasks such as flex field mapping and application customization. Instructions are provided for customizing the Worklist Application (including a number of language settings) and for building your own Worklist Application using the workflow service APIs.
