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.
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 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.
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.
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.
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.
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.
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.
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 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:
assignToUsersAndGroups. The methods described in the following table specify how the Assignees List is set.
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.
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.
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.
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:
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.
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
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.
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.
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.
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
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.
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.
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
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.
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.
archiveTask—not functional in SP3 or later.
deleteTask—permanently removes Tasks from the WebLogic Integration server. The
deleteTaskmethod can be used for a Task that is in any state, including the suspended state.
purgeTask—deletes all Tasks in completed, aborted state, or final state that have existed longer than the
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:
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
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.
State Type 1
@jc:selectorannotation 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.
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:
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.
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.
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.
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.