Using the Worklist
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:
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:
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).
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:
Worklist provides the option to set one or both of the following due dates for a Task Instance:
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.
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
.
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
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:
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:
To learn more about the business calendar options of the WebLogic Integration Administration Console, see Business Calendar Configuration in Managing WebLogic Integration Solutions.
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-2 Control Methods That Operate on Task States
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
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
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. |
|
Behaves in the same way as the |
|
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. |
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.
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.
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.
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.
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 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.
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:
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.
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:
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.
Whether a user can change Task properties after the Task is created depends on the following parameters:
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
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
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.
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.
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.
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:
The tracking level setting in the WebLogic Integration Administration Console determines the data that is logged as follows:
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.
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:
The following tables show the task information that can be stored in the history tables.
Table 3-7 Data in the Task History Tables
The ID of the business process that created the Task. (Only for Tasks created by business processes.) |
|
An integer that represents the action recorded. For more information, see Table 3-8. |
|
An integer that represents the state of the Task. For more information, see Table 3-8. |
|
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
State Type 1 | ||||
---|---|---|---|---|
@jc:selector
annotation tag or TaskSelector objects. To learn more about queries, see Querying Tasks Using the Task Worker Control.
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:
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
Returns only those tasks for which the instance ID is matched. |
|
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: |
|
Returns only those tasks for which the comment matches the value passed in. Optionally, you can specify that the value matches a patterns. |
|
Returns only those tasks for which the description matches the value passed in. Optionally, you can specify that the value matches a pattern. |
|
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. |
|
Returns only those tasks for which the claimant is on the specified list. You can specify a list of user and group names. |
|
Returns only those tasks for which the associated Assignees List contains the specified assignee. |
|
Returns only those tasks for which the state is on the list of specified values. |
|
Returns only those tasks that were created by one of the processes whose ID is in the specified list. |
|
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: |
|
You can specify whether the date should be before or after the specified date. |
|
Returns only those tasks completed before or after the specified |
|
Returns only those tasks whose date is before or after the specified |
|
Returns only those tasks that were created before or after the specified |
|
Returns only those tasks whose data value matches the boolean specified. |
|
You can specify a maximum and minimum range. Returns only those tasks for which the priority falls within the specified range. |
|
Returns only those tasks with a named property defined—the name is specified in the query. |
|
Returns only those tasks for which a named property has a value equal to the String specified. |
Some query criteria can be patterns that match strings with wildcards. These strings can contain the following wildcards:
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 \_.
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
.
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.
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.
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.
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:
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 URIlisteningProcessUri
—identifies the type of the URI invoking a controlparentProcessIds
—identifies the process ID of the parent process that invokes a controlparentProcessUri
—identifies the URI of any parent processes that invoke a controlTo learn how to extend to a Task Worker control to query WebLogic Integration Tasks instance properties, see Querying Tasks Using the Task Worker Control.