Using the Worklist

Creating and Managing Worklist Tasks

Task Instances have properties that define what work needs to be done, who does the work, how the work is performed, and so on. This section describes the details of working with task instances. It includes the following topics:

• Overview
• Task Due Dates
• Task States
• Task Users and Groups
• Tasks and User Permissions
• Task Data Values
• Task Operations
• Worklist Tracking Data
• Task Queries
• The Relationship Between Processes and Tasks

 

---

Overview

Task instances are part of the WebLogic Integration server and exist independently of Worklist controls or specific business processes. Tasks remain in the run-time engine indefinitely, until they are either explicitly deleted or purged by the WebLogic Integration purging process. You create, delete, and manage Tasks through the following mechanisms:

• The Task and Task Worker controls in WebLogic Workshop.
• The Worklist module the WebLogic Integration Administration Console.
• The public Worklist API, using Enterprise Java Beans, and Message Beans.

There are no task types, all task instance lifecycles conform to the same state diagram and have the same types of data associated with them. In other words, task instances cannot be extended (in the Object Oriented sense).

 

---

Task Due Dates

Business processes can take actions to address overdue work by setting and tracking Task due dates. For example, a purchase order business process can email the manager assigned to approve the purchase order if that manager takes more than three business days to do so.

This section describes Task Dates and calendars. It contains the following topics:

• Claim and Completion Due Dates
• To Set Task Due Dates Using Absolute Time
• To Set Task Due Dates Using Business Time
• To Specify a Calendar to Use When You Set Due Dates
• Formats for Business Time Duration

Claim and Completion Due Dates

Worklist provides the option to set one or both of the following due dates for a Task Instance:

• Claim Due Date—specifies the deadline for a task to be Claimed by a user on the Assignees List. Setting claimDueDate to null indicates that there is no due date.
• Completion Due Date—specifies the deadline for a task to have reached the Completed state. Setting completionDueDate to null indicates that there is no due date.

Due Dates are stored as java.util.Date values. They mark a precise instant in time. You can specify Due Dates using Business Time or system time. To learn about business time, see To Set Task Due Dates Using Business Time.

At run time, when Worklist detects that a due date has passed, it checks whether the associated task is claimed or completed. If the task is not claimed or completed, Worklist invokes callbacks on any Task controls that are blocking on the task becoming overdue. Business processes can incorporate these callbacks that are invoked when due dates expire, allowing the processes to execute logic when the task becomes overdue.

To Set Task Due Dates Using Absolute Time

You can set Task due dates by specifying a java.util.Date. The due date is a specific instant of time. You can unset Task due dates by passing null for the java.util.Date.

To Set Task Due Dates Using Business Time

You can set Task due dates by specifying a duration of business time. Business Time durations are strings that define a period of time relative to a specified Business Calendar. Business calendars are required to convert business time durations to real time. In other words, business-time durations have no meaning if they are not associated with a business calendar that converts the durations to real time. The Worklist system uses the addBusinessTime method to calculate the due dates.

For example, a business calendar defines business hours as Monday, Tuesday, and Wednesday from 9AM to 5PM. If on Saturday the 16th, you set a Task's duration for four business days, the resulting due date is Monday the 25th (Monday the 18th, Tuesday the 19th, Wednesday the 20th, Monday the 25th).

To learn more about business calendars and the WebLogic Integration Administration Console, see Business Calendar Configuration in Managing WebLogic Integration Solutions

To Specify a Calendar to Use When You Set Due Dates

If you use a business time duration, but do not specify a business calendar to use, the WebLogic Integration System Business Calendar is used. To specify a business calendar for the system to use when it calculates due dates, do one of the following:

• Explicitly pass the name of the business calendar to a Task control. To learn how, see "Specify a Due Date for Completion of the Task" in Step 4. Create Task and Assign to User in Tutorial: Building a Worklist Application.
• Specify a user or group. In this case, the business calendar associated with that user or group is used to calculate the due date. To learn how to associate business calendars with users and groups in your system, see "Assigning Business Calendars to Users and Groups" in Business Calendar Configuration in Managing WebLogic Integration Solutions

Formats for Business Time Duration

Business-time durations are strings that use the following format: X d Y h Z min. You can specify days, hours, or minutes, or a subset of these values. For example, you can specify just days, or just hours and minutes:

• 3 business days = 3 d
• 2 business hours and 30 business minutes = 2 h 30 min.

To learn more about the business calendar options of the WebLogic Integration Administration Console, see Business Calendar Configuration in Managing WebLogic Integration Solutions.

 

---

Task States

The Task and Task Worker controls allow a business process or Worklist UI to cause a Task Instance to transition from one state to another. Operations on the controls, or the API, guide the task through its lifecycle.

A Task can be in one of the states defined in Table 3-1. Many of the methods on Worklist controls make changes to states or properties of a Task instance. The transitional state operations for Worklist controls are defined in Table 3-2.

Note: The operations that can be invoked for a given Task depend on the state of the task and user permissions. To learn about user permissions, see Tasks and User Permissions.

Table 3-1 Task States

State	Description
ASSIGNED	New tasks begin in the ASSIGNED state. The Assignees List is important in this state, as is specifies which users are allowed to become the claimant through the act of claiming the task. Note that the Assignees List may be empty, in which case the task is assigned to nobody, effectively unassigned.
CLAIMED	Claiming an ASSIGNED task causes the state to become CLAIMED. The claimed state specifies that a user on the Assignees List has taken ownership of the task, and intends to complete the task. The claimant value will be set when a Task is CLAIMED. Although the claimant has ownership of the work, the claimant may not yet have started working on it.
STARTED	The STARTED state indicates that the claimant started working on the task, that is, is currently spending time on the work required to complete the task. The STARTED state exists for reporting purposes, allowing companies to track precisely how much time users spend working on individual tasks. There can be significant time between declaring ownership of work (claiming the task) and starting doing that work.
COMPLETED	The COMPLETED state indicates that the work required to complete the task is finished, or as much of the work as is possible to do is finished. You can use the response document to record the details of how work was done or the results of doing work.
SUSPENDED	A SUSPENDED task is frozen—it cannot be worked on. SUSPENDED tasks can be resumed at a later time, returning to the state previous to their suspension. The SUSPENDED state can be used to temporarily mark that a task cannot progress for some reason.
ABORTED	An ABORTED task is effectively cancelled. The ABORTED state is generally used to indicate that something went wrong while work was being done on the task. This state can also be used to mark work that should be permanently abandoned.

 

Table 3-2 Control Methods That Operate on Task States

Operation	Description
create	Creates a new task instance in the ASSIGNED state. Some data values, such as the description, can be set only when this operation is invoked. Note that the currently executing principal must belong to a group that is specific to the Worklist system before permissions are granted to create a new task.
assign	Causes a task to move to the ASSIGNED state. The Assignees List must be set when this operation is performed and specify which users can claim the task. This operation can be performed on tasks in a final state, such as COMPLETED or ABORTED. This allows you to work on the task again. This operation can unassign or reassign a task. Assignment can be performed on a single task instances multiple times throughout its lifecycle. When assigning a task, an algorithm must be specified to determine how to set the Assignees List. To learn about the algorithms, see Assignment Algorithms. This operation is performed by the task owner, task creator, an assignee, or an administrator.
claim	Causes a task in the ASSIGNED state to become CLAIMED. A user that is on the Assignees List is set as the claimant of the task. This signifies that a user on the Assignees List has marked ownership of the task and intends to complete it. This operation is performed by a user who wishes to become the claimant for a task, or by an administrator or task owner on behalf of another user.
start	Causes a task in the CLAIMED state to become STARTED. It signifies that the claimant is starting to work on the task. This operation is performed by the claimant, or by an administrator or task owner on behalf of a claimant.
stop	Causes a task in the STARTED state to return to the CLAIMED state. It signifies that the claimant is stopping work on the task, possibly temporarily. They can start it again when they are ready to continue working. This operation is performed by the claimant, or by an administrator or task owner on behalf of the claimant.
complete	Causes a task in the STARTED state to become COMPLETED. It signifies that the claimant has finished the work required to complete the task, or as much of the work as is possible to do is finished. This operation is performed by the claimant, or by an administrator or task owner on behalf of the claimant.
suspend	Causes a task to become SUSPENDED. It signifies that the task no longer progresses and should not be worked on, possibly temporarily. The task can be resumed (using the resume operation) when work should continue. This operation is performed by an administrator or task owner.
resume	Causes a SUSPENDED task to return to the state it was in previous to its suspension. This operation is performed by an administrator or by the task owner.
abort	Causes a task to become ABORTED. It signifies that the task should be cancelled and should not complete. In other words, work on the task is no longer necessary and should cease. This operation is performed by the claimant, an administrator, or the task owner.

 

Assignment Algorithms

Whenever a Task is assigned, one of the following assignment methods must be specified: assignToUser, assignToUserInGroup, or assignToUsersAndGroups. The methods described in the following table specify how the Assignees List is set.

Table 3-3 Assignment Algorithms

Method	Description
assignToUser	Sets the Assignees List to a specific IntegrationUser. The name of the user must be specified. Because this user is the only one on the Assignees List, this operation automatically causes the task to be claimed for the specified user. For examples of how to use this method, see Step 4. Create Task and Assign to User in the Tutorial: Building a Worklist Application.
assignToUserInGroup	Behaves in the same way as the assignToUser method. However, when you use the assignToUserInGroup method, a load balancing algorithm is used to select the user in the specified group that has the fewest assigned and claimed tasks that are not completed, aborted, or suspended. A group name must be specified for this method.
assignToUsersAndGroups	Sets the Assignees List to contain the users and groups specified. This operation requires a list of user names, or a list of group names, or both. Any of the users on the Assignees List can then claim the task.

 

 

---

Task Users and Groups

People and systems may play various roles with respect to a task instance. They can be the Task Owner in the role of managing the task, a user on the Assignees List who may claim the task, the claimant who has declared ownership and intent to complete the task, or an WLI Administrator.

The following list describes the roles in which a given user can be with respect a task instance. These roles determine what operations they are permitted to perform on a Task instance.

To learn more about the permissions that allow different groups and users to create and manage task instances, see Tasks and User Permissions.

• Task Owners
• Assignee Lists
• Claimants
• Integration Administrators
• Task Creators

Task Owners

The Task Owner is the user or group with managerial responsibility for the work required to complete a Task Instance. For example, a dispatcher at a taxi company can be the task owner for tasks assigned to drivers to deliver a patron to his required destination.

Although a Task Owner usually does not complete the task, they can perform managerial operations on the task. For example, the manager in a collections office can reassign the task of calling a delinquent customer to a different collections officer when the officer originally assigned to the task (the claimant) is on vacation.

Task owners have administrative privileges for the tasks they own. They are effectively in the role of the WebLogic Integration Administrator when permissions are checked in the event an operation is invoked on that task. Note that the Task Owner is set automatically to the current user when a task is created, unless a different Task Owner is explicitly specified at creation time.

Assignee Lists

The Assignees List specifies the users or groups that are permitted to take ownership of a task by claiming it. All instances of Tasks have an associated Assignee List. When a task is assigned or reassigned, the Assignees List is updated and the state of the Task is set to ASSIGNED.

The Assignees List that is associated with a task can specify several users or groups (or both), but only one user can claim a Task to perform the work. For a user to be on the Assignees List, either the user name is explicitly listed or a group to which the user belongs is explicitly on the list. The user in the Assignees List that claims the task, becomes the claimant.

Claimants

A Claimant is the user from the Assignees List who claims a Task and performs the work needed to complete the Task. Certain Task operations require a user to be the claimant.

Any user in the Assignee List can claim a task, thereby becoming the Claimant. The State of the Task is set to Claimed when a user claims the Task.

Integration Administrators

WebLogic Integration server users with administrative privileges can perform any operation on a Task, including the creation of new Tasks. To learn about the default roles and groups in WebLogic Integration, see User Management in Managing WebLogic Integration Solutions.

Task Creators

Task Creators are users who, like the Integration Administrators, have permissions to create new Tasks.

WebLogic Integration provides a default group that defines which users can create new tasks. By default, the anonymous user is a member of this group in a new domain. To learn how you can enforce strict restraints on who can create new tasks, see Worklist Administration in Managing WebLogic Integration Solutions.

 

---

Tasks and User Permissions

Only Integration Administrators and users in the TaskCreationRole can create Tasks and simultaneously set new Task properties. The Worklist system verifies that the user attempting to create tasks and invoke operations on Tasks has the required permissions to do so. This section includes:

• Worklist Security
• Who Has Permission to Create Tasks?
• Who Has Permission to Modify Task Data Values?
• Who Has Permission to Invoke Task Operations?

Worklist Security

The Worklist relies on the WebLogic Server security framework and authentication provider to enforce security.

If more than one security provider is defined in the active realm of the domain, the Worklist gathers information from all of them. These authentication providers can or can not implement some of the MBeans that are used by Worklist.

If the following MBeans are not present, some features are deactivated, but the Worklist is still functional:

• UserReaderMBean—used to validate users when assigning a Task or setting the Task owner.
• GroupReaderMBean—used to validate a group when assigning a Task to a group or setting the Task Owner.
• GroupMemberListerMBean—used when assigning a Task using the algorithm ToUserInGroup.

If UserReaderMBean or GroupReaderMBean is not present, all the users and groups validations for the task owner and task assignee are deactivated. If GroupMemberListerMBean is not present you cannot use the algorithm ToUserInGroup when assigning a task. Additionally, you cannot select all the tasks whose assignee is in a specific group.

Who Has Permission to Create Tasks?

Only Integration Administrators and users in the TaskCreationRole can create Tasks and simultaneously set new Task properties.

Default WebLogic Integration Users—Any domain that supports WebLogic Integration includes a set of default WebLogic Integration roles and groups. Default security policies define the roles authorized to access specific WebLogic Integration resources. You must be logged in as a member of one of the following groups to make changes to task states: IntegrationAdministrators, IntegrationUsers, or IntegrationOperators. To learn about the default roles and groups in WebLogic Integration, see User Management in Managing WebLogic Integration Solutions.

You can configure the TaskCreationRole using the WebLogic Integration Administration Console. To do so, complete the following steps:

Open the WebLogic Integration Administration Console.
From the Home page, select the System Configuration module.
From the left panel, select Worklist.
On the View Worklist Configuration page, click Configure.
From the Task Creation Role drop-down list, select the role.
Click Submit to update the setting and return to the View Worklist Configuration page.

By default, the TaskCreationRole role contains the WebLogic Server Anonymous role. Thus, anonymous users have the permissions to create tasks. You can change this specification if you want more stringent control over the creation of tasks.

Who Has Permission to Modify Task Data Values?

Whether a user can change Task properties after the Task is created depends on the following parameters:

• The state of the Task. You can not change the value of a Task property if the Task is in an aborted, suspended, or completed state.
• The role and group identification of the user executing the property change. Integration Administrators are never denied permissions to change Task properties in any circumstances where the operation is allowed; they have no restrictions.
• The status of the user executing the property change with respect to the Task:
• For a Task that is in the assigned state, the user who modifies the Task must be an assignee, the Task owner, or an Integration Administrator.
• For a Task that is in the claimed or started state, the user who modifies the Task must be the claimant, the Task owner, or an Integration Administrator.

Who Has Permission to Invoke Task Operations?

Any operation on a Task requires the Worklist system to verify that the current principal executing the operation has the permissions to perform that operation.

Whenever an operation is invoked on a task instance, the Worklist system checks if the currently executing principal has the permission to do so. The decision to grant a permission is a function of the role of the current principal with respect to the task, the state of the task, the operation being invoked, and possibly some of the task data values, such as the value of canBeReassigned.

A user can take on one of several roles when interacting with a task instance. These roles are described in Task Users and Groups. The following table presents the permissions that different users have to perform the operations on Tasks that result in a change to the state of a task. Each row presents the possibilities for a given starting Task state.

Table 3-4 User Roles and Task Operations

Starting State	Ending State	Relevant Operations	Permitted Users
Assigned Claimed Completed Started	Aborted	abortTask	Assignee list users and groups (if can-be-aborted property true) Claimant (if can-be-aborted property true) Task Owner Integration Administrator
Assigned, Claimed Started	Aborted	abortTask	Assignees List, if task is ASSIGNED and canBeAborted is TRUE. Claimant if canBeAborted is true. Task Owner and Integration Administrator
Assigned, Claimed, Started	Suspended	suspendTask	Task Owner and Integration Administrator
Suspended	Whatever the Task State was when suspended	resumeTask	Task Owner and Integration Administrator
Assigned	Assigned	assignToUsersAndGroups	Assignees List if canBeReassigned is TRUE. Task Owner and Integration Administrator
Completed or Aborted	Assigned	assignToUsersAndGroups	Task Owner and Integration Administrator
Assigned	Claimed	claimTask	Assignees List. Task Owner and Integration Administrator
Claimed	Assigned	returnTask	Claimant if canBeReturned is true. Task Owner and Integration Administrator
Assigned	Claimed	assignToUserInGroup, assignToUser	Assignees List if canBeReassigned is TRUE. Task Owner and Integration Administrator
Completed or Aborted	Claimed	assignToUserInGroup, assignToUser	Claimant if canBeReassigned is TRUE. Task Owner and Integration Administrator
Claimed	Started	startTask	Claimant.Task Owner and Integration Administrator
Started	Claimed	stopTask	Claimant.Task Owner and Integration Administrator
Started	Completed	completeTask	Claimant. Task Owner and Integration Administrator
Any	Not Existing	deleteTask	Task Owner and Integration Administrator

 

 

---

Task Data Values

There are various data values associated with Task Instances. They provide a mechanism for describing the work that needs to be done to complete a task. They also describe work that is already done, who should do the work, by when, the results of work, and so on.

Some of these values are specified only at the time a new Task is created; some values can be modified throughout the lifecycle of the instance. Each data value has rules that specify the users that have permissions to modify the value.

The following table describes the Task Instance data values.

Table 3-5 Task Instance Data Values

Name	Purpose	How to Set	Type	Unset Value	Default	Notes	Only Admin. Can Modify
TaskId	Identifies Task instance. Unique Value	System sets at creation time, user cannot set.	String	Always non-null	NA		NA
Name	Any String.	Set by user at creation time only.	String	Always non-null	NA		NA
Description	Description of the task.	Set by user at creation time only.	String	Can be null	Null		NA
ParentProcessURI	The business process type that created the task, if any.	System sets at creation time, user cannot set	String	Can be null	NA		NA
ParentProcessId	The instance ID of the process that created the task, if any.	System sets at creation time, user cannot set	String	Can be null	NA		NA
Assignees	The Assignees List for the task, that is, those users that can claim it.	Set by user using an assignment operation.	String Array	Can be empty list, but non-null	Empty	List of user and group names. All should be members of IntegrationUsers group	NA
Claimant	Tracks who claimed the task. This user completes the task.	Set by user using a claim() operation.	String	Can be null	Null	Must be a user name, a user that is on the Assignees List, or a member of a group on the Assignees List.	NA
Comment	Any	Set by user	String	Can be null	Null		False
Priority	Can be zero or any positive integer. Worklist does not do anything with this value; the application can interpret or ignore.	Set by user	Integer	Always non-null	1		True
CreationDate	When the task was created.	Set by Worklist system	java.util.Date	Always non-null	NA		NA
CanBeReassigned	Allows a user on the Assignees List assign to reassign the task. Otherwise requires administrative privileges.	Set by user	Boolean	Always non-null	True		True
CanBeReturned	Allows the claimant to return the task after claiming it; otherwise requires administrative privileges.	Set by user	Boolean	Always non-null	True		True
CanBeAborted	Allows the claimant to abort the task; otherwise requires administrative privileges.	Set by user	Boolean	Always non-null	True		True
Request	Can describe what work should be done, how to do it, or what information is needed to complete the work.	Set by user	Byte array can hold XML, String, RawData, and so on.	Can be null	Null		False
Response	Can describe what was done, how the work was done, what problems were encountered, and so on.	Set by user	Byte array can hold XML, String, RawData, and so on.	Can be null	Null		False
State	Describes where in the Task life cycle the task is currently: ASSIGNED, CLAIMED, STARTED, COMPLETED, ABORTED, SUSPENDED.	System maintains this; operations cause it to change.	String	Always non-null	NA		NA
Request Type and Response Type	Can be used to describe the format of the Request or Response value of this task instance.	Set by user when Request or Response are set.	String	Can be null	NA	System does nothing with this value; application can interpret and use.	False
Owner	Can be user or group name	Set by user	String	Can be null	principal executing when task is created	User or Group must be member of IntegrationUsers group	True
ClaimDueDate	Deadline for some user to have claimed the task	Set by user	java.util.Date	Can be null	Null	Null means no due date	True
CompletionDueDate	Deadline for claimant to have completed the task	Set by user	java.util.Date	Can be null	Null	Null means no due date.	True
Arbitrary, User Defined Properties	Any	Set by user	String	Can be null	NA		True

 

Request and Response Documents

Documents can be associated with task instances: the documents describe what work needs to be performed to complete the task, the progress of the work, or the results of what was attempted or completed for the task. These documents populate the request and response data values, as described in the preceding table.

You use a Task Request to specify what work needs to be done to complete a task, or how to do the work. For example, a Task Request can contain a Purchase Order document that needs to be approved by a user. This value of a Task Request can be read by the person who performs the work and completes the task. In addition, assignees can view this information to decide whether or not to claim the task.

The Task Response can specify the work that took place after a user worked on the task, or the resulting data generated as the result of the work performed to complete the task, or both. Callbacks can return the Response value to business processes that are waiting for a particular task state.

For example, the Task Response can capture the agreement made between a collections agent and a delinquent customer after a telephone conversation. The process that created the Task to call that customer can use those results to decide what to do next.

Format and Type of Request and Response Documents

The Request and Response documents are stored as byte arrays in the Worklist system. This means that they can hold any type of object. Methods and callbacks on the controls can set or get these values as XmlObjects, Strings, Raw Data Types, or XML Bean types.

For example, you can create a Task that matches purchase orders with receipts, and include an electronic version of a purchase order as request data. When the Task completes, it can include a matching receipt with the purchase order, along with a document that explains any differences, as response data.

The request and response types can be stored as mimeType, which can be any String. The value of the mimeType is provided for the interpretation of the application; it is not used by the Worklist system.

For example, the RequestType can be set to xml, string, word document, or com.xyz.PurchaseOrder. A custom Worklist UI can use these values to determine how to display a request or response value to the user.

 

---

Task Operations

You use operations to create new tasks, alter task states or properties, delete tasks, or read information about an existing task. Some operations allow combinations of these actions in a single step. Examples of Task operations are contained in the following table.

Table 3-6 Task Operations

Operation	Description
Create Tasks	When a new Task Instance is created, the Worklist system assigns a unique ID (a taskId) to that instance. Depending on the operation, the Task State can be defined at creation time either as Assigned or Claimed. Note: Some Task Properties are specified at the time an instance of a Task is created and cannot be changed after the instance is created.
Modify Task Properties	Some Task Properties can be specified and modified after an instance of a Task is created.
Get Task Properties	You can use Get Task operations to access the properties of any Task Instance at any point during its lifecycle.
Modify Task State	Task Instances can transition between states based on the operations defined for them. Different operations to modify a Task's State are valid depending on the State in which the task is to start.

 

 

---

Worklist Tracking Data

Each worklist task instance generates events that can be logged into worklist history tables in the run-time repository. The following types of events can be tracked:

• Changes in task state and associated values—the type of transition and associated values. For example, a task is reassigned or claimed. In this case, the change in state and identity of the new assignee or claimant can be tracked.
• Expiration of task claim or complete due date—the task is unclaimed or incomplete on the due date for claiming or completing.
• Changes in task owner or assignees—the type of change and new values can be tracked.
• Task requests and task responses—the request and response XML.

The tracking level setting in the WebLogic Integration Administration Console determines the data that is logged as follows:

• Full—All transitions and changes, including task requests and responses, are logged.
• Basic—Transitions and changes are logged. Task requests and responses are not logged.
• None—No task history is tracked.

The Task Worker control provides the following methods for logging and deleting Tasks:

• archiveTask—not functional in SP3 or later.
• deleteTask—permanently removes Tasks from the WebLogic Integration server. The deleteTask method can be used for a Task that is in any state, including the suspended state.

Warning: Use the deleteTask method with caution. No mechanism exists for rollback or retrieval of deleted Tasks.

• purgeTask—deletes all Tasks in completed, aborted state, or final state that have existed longer than the purgeDelay setting.

To learn about the Task states and the operations available for tracking, see Task Operations.

To optimize performance, the amount of tracking data stored in the run-time database should be kept to a minimum. To help ensure this, the tracking and purge process can be configured to run at regular intervals by an administrator. Additionally, the reporting data policy for a process can be set to on or off. If on, the data is transmitted to the reporting database if the reporting data stream is enabled; if off, the data is not transmitted to the reporting database.

Stored information can be used for generating reports and compiling statistics about task processing in your WebLogic Integration application. To learn more about configuring your application for tracking and purging Task data, see System Configuration in Managing WebLogic Integration Solutions.

Task History Tables

As described in the preceding section, worklist task instances generate events that can be logged in worklist history tables in the run-time repository. By default, Task instance information is stored in the following history tables:

• wli_task_archiving
• wli_task_data_archiving

The following tables show the task information that can be stored in the history tables.

Table 3-7 Data in the Task History Tables

Name	Description
task_id	The unique Task ID.
process_instance	The ID of the business process that created the Task. (Only for Tasks created by business processes.)
action_type	An integer that represents the action recorded. For more information, see Table 3-8.
state_type	An integer that represents the state of the Task. For more information, see Table 3-8.
action_time	The time of the action.
action_user	The user for which the action happens.
details	Any other relevant information.

 

The following table presents the action types and state types (see action_type and state_type in the preceding table) that can be stored, along with the integer that represents the action type or state type in the history tables.

Table 3-8 Integers That Represent Action and State Types in the History Tables

Action Type	Integer		State Type 1	Integer
create	0		assigned	0
assign	1		claimed	1
claim	2		started	2
suspend	3		suspended	3
resume	4		completed	4
complete	5		aborted	5
abort	6
return	7
start	8
stop	9
updateComment	10
updatePriority	11
updateExpirationDate	12
updateClaimDate	13
updateOwner	14
updateCanBeReassigned	15
updateCanBeReturned	16
updateCanBeAborted	17
updateRequest	18
updateResponse	19
addListener	20
removeListener	21
claimExpire	22
expire	23

1. State types can be used in queries using the @jc:selector annotation tag or TaskSelector objects. To learn more about queries, see Querying Tasks Using the Task Worker Control.

 

---

Task Queries

Task Queries allow a business process or UI to find tasks in the Worklist system that meet user-defined criteria. This is analogous to SQL queries executed on Database Tables. The application defines the criteria, executes the query, and is returned results for each task that matches the criteria.

Business processes can use the task query mechanism to find tasks relevant to the business process, and then perform work on the tasks that are returned. For example, a manufacturing application can find all tasks related to a cancelled order and abort them.

You can create custom UI Pages that use the query mechanism to find tasks relevant to the user that is using the page, and display information about those tasks. For example, a bug tracking UI can allow users to query for tasks that are assigned to them, have a certain priority or higher, and are due within a certain number of days. BEA recommends using the WorklistScrollableResultManager Interface for scalability and performance.

This section includes the following topics:

• To Specify the Criteria for a Query
• To Specify How the Results Are Sorted
• To Execute a Query
• To Limit the Results Set
• WorklistScrollableResultManager Interface

To Specify the Criteria for a Query

The criteria you specify when you define a query determine the tasks that are returned by the query. When you specify a query, you can set the following criteria:

Table 3-9 To Specify Criteria for a Query

Query Criteria	Description
Task Ids	Returns only those tasks for which the instance ID is matched.
Task Name	Returns only those tasks for which the name matches the value passed in. Optionally, you can specify that the value matches a pattern. For example: OrderNumber%. See the Note About String Patterns
Comment	Returns only those tasks for which the comment matches the value passed in. Optionally, you can specify that the value matches a patterns.
Description	Returns only those tasks for which the description matches the value passed in. Optionally, you can specify that the value matches a pattern.
Owners	Returns only those tasks for which the task owner is on the specified list. Optionally, you can specify a list of user and group names.
Claimant	Returns only those tasks for which the claimant is on the specified list. You can specify a list of user and group names.
Assignee	Returns only those tasks for which the associated Assignees List contains the specified assignee.
State	Returns only those tasks for which the state is on the list of specified values.
ParentProcessId	Returns only those tasks that were created by one of the processes whose ID is in the specified list.
ParentProcessURI	Returns only those tasks that were created by a processes whose URI matches the value passed in. Optionally, you can specify that the value matches a pattern. Example: %PurchaseOrderProcess%
Completion Due Date	You can specify whether the date should be before or after the specified date.
Completed Date	Returns only those tasks completed before or after the specified java.util.Date.
ClaimDueDate	Returns only those tasks whose date is before or after the specified java.util.Date.
Creation Date	Returns only those tasks that were created before or after the specified java.util.Date. You can specify whether the date should be before or after the specified date.
canBeReassigned	Returns only those tasks whose data value matches the boolean specified.
canBeAborted
canBeReturned
Priority	You can specify a maximum and minimum range. Returns only those tasks for which the priority falls within the specified range.
User Defined Property Name	Returns only those tasks with a named property defined—the name is specified in the query.
User Defined Property Value	Returns only those tasks for which a named property has a value equal to the String specified.

 

Note About String Patterns

Some query criteria can be patterns that match strings with wildcards. These strings can contain the following wildcards:

• % characters to match any sequence of characters
• _ characters to match any single character.

For example:

A query for task names like %Process_ returns PurchaseOrderProcess1, but not PurchaseOrderProcess23455.

If you want to apply patterns checking, the query must specify that explicitly. Special characters can be escaped using a back slash: \%, or \_.

To Specify How the Results Are Sorted

A query can return results that are sorted according to the specified criteria. To define the sort order, you set an integer value for each sort criteria. Values are sorted in an descending manner.

For example, if you specify the sort value for name to be 1, and the sort value for comment to be 2, the results of the query are sorted first by name, then by comment. The values are returned sorted first by the lowest number, then the second lowest, and so on.

By default, all the criteria are set to the same value. In this way, they are all weighted equally in the sort. Specifically, the default sort value is set as java.lang.short.MAX_VALUE.

To Execute a Query

The Task Worker control can execute a query and return results. The API also provides operations on the com.bea.wli.worklist.api.WorklistManager interface to execute queries. For more information, see the BEA WebLogic Integration Javadoc.

To Limit the Results Set

You can specify a maximum results value for a query. It limits the maximum number of results returned by the query.

Results can be returned as either an array of TaskInfo objects or an array of Task Ids. TaskInfo objects contain a summary of the state and data values of a task instance.

WorklistScrollableResultManager Interface

The WorklistScrollableResultManager Interface returns a specified number of records rather than returning all query results. Additionally, it allows you to scroll backward and forward to fetch different ranges of results. This ability improves scalability and performance for querying operations and is the recommended interface. For an example of using the WorklistScrollableResultManager, see "Use Case 2" in the Worklist Sample in the Solution Samples.

 

---

The Relationship Between Processes and Tasks

For the case in which a business process creates a task, the Worklist tracks not only the task, but also the business process that created it. For example, the Worklist tracks business processes that are blocking, that is, waiting for a callback from a particular task instance.

You can view and manage tracking information using the WebLogic Integration Administration Console. For a particular task instance, the console reports the business processes that are currently blocking that task instance. For a particular business process, the console reports the tasks that are blocking that business process.

The Worklist Task system in WebLogic Integration keeps track of the relationships between task instances and process instances, as follows:

• Which business processes are blocking on a given Task
• Which business processes, if any, created each Task instance

In your queries, you can access information about the task instances for which the specified processes are listening, or access information about tasks that were created by the specified processes with the following IDs and URIs:

• listeningProcessIds—identifies the process ID of a listening process such as a URI
• listeningProcessUri—identifies the type of the URI invoking a control
• parentProcessIds—identifies the process ID of the parent process that invokes a control
• parentProcessUri—identifies the URI of any parent processes that invoke a control

To learn how to extend to a Task Worker control to query WebLogic Integration Tasks instance properties, see Querying Tasks Using the Task Worker Control.