Using the Worklist
Java Controls are server-side components managed by the Workshop framework. Controls expose Java interfaces that can be invoked directly from business processes. In other words, controls are the interfaces between your business processes and other resources.
As with other built-in controls in WebLogic Workshop, you use the controls by adding instances of the controls to your business process and then invoke operations on the controls at the point in the business process at which you want to integrate the business-user logic.
The underlying control implementation takes care of most of the details of the interaction for you. Business processes invoke operations on the controls using Control Send and Control Send with Return nodes. Business processes can block at Control Receive nodes waiting for events to be returned from controls. In other words, Control Receive nodes are triggered by control callbacks. You can extend Worklist controls through Java annotations. Common extensions include implementing callback functions and performing system queries.
An instance of a Task control can create one or more Task instances. The single type of Task control creates a single Task instance. The factory type of Task control creates multiple Task instances. To learn about creating multiple Task instances, see Using Task Control Factories.
A Task control instance can also interact with a task instance that already exists by setting its active task ID. After creating or setting the active task ID, your control instance can get information about that task or update that task in various ways.
For instructions on creating a new Task control, see Creating a New Task Control in the WebLogic Workshop Help.
The Task Worker control allows specified users to acquire ownership of Tasks, work on them, and complete them. It also provides administrative privileges, such as starting, stopping, deleting, and assigning. Access to the Task Worker control can be done with a business process or through a user interface. You can customize each Task worker control for different business purposes.
For instructions on creating a new Task Worker control, see Creating a New Task Worker Control in the WebLogic Workshop Help.
To design the interaction of a Task or Task Worker control with a business process, you must decide which methods on the control you want to call from the business process to support the business logic.
In the same way that you design the interactions between business processes and other controls in the WebLogic Workshop, you can bind the Worklist control method to the appropriate control node in your business process (Control Send, Control Receive, and Control Send with Return). You do this in the Design View by simply dragging a control method from the Data Palette onto the business process at the point in your business process at which you want to design the logic. After you create an instance of a Task or Task Worker control, you can invoke its methods from within your business processes to perform operations on Task Instances. Your business processes can also wait to receive callbacks from task instances. Note that the Task and Task Worker controls can be extended to add customized methods and additional callbacks.
Each instance of a Task Control only operates on a single task instance. Each task has a unique ID—the Active Task ID on a control uses this ID to identify the task instance on which a task control operates. All operations on a task control are performed on the active task.
The Active Task ID is set either by creating a new task, or by invoking the
setTaskId method. When a new task is created, the Active Task ID is automatically set to the ID of the newly created task. In this way, subsequent operations are performed on the new task.
A consequence of the active task model is that a Task control instance can create a single task only. However, you can use a Task control factory to create new instances of Task controls dynamically. This means that you can use a Task control factory to create a new Control instance every time a new Task is required. To learn more about Task control factories, see Using Task Control Factories.
Because it is possible to use the Task ID to determine which task a control operates or receives callbacks from, multiple business processes can incorporate controls that operate on the same task. New processes, that is, processes that are instantiated after a task that already exists can interact with that task using the
The Task Worker control does not use the active task model. Instead, to specify which tasks need to be updated, Task IDs are passed explicitly to methods on the Task Worker control. For example, the business process shown in the following figure is designed to receive a Task ID from another business process that created a new task. The business process sets the Active Task ID for a Task control, and then waits for the
onCompletion callback, which indicates that the task is completed.
createTaskByName(String name) method sets the task name to the value specified in the input parameter; other data values are set to their default values or values specified in the Property Editor.
createTask(TaskCreationXMLDocument xml) method first creates a new task and names it according to the name specified in the XML document. Then it alters the task in some way, using the elements in the XML document to do so.
These methods and properties accept the name of a group. The method and property use a load balancing mechanism to select a single user from that group to be the claimant, and then place the Task in a claimed state.
The load balancing algorithm selects the user with the fewest assigned and claimed Tasks that are not in completed, aborted, or suspended states. If more than one user is identified (that is, if two or more users in the group have the same number of assigned and claimed tasks), then the algorithm chooses one user randomly.
Although you can assign multiple users and groups to a Task, only one user on the Assignees List can place a Task in a claimed state. If the Assignees List contains only one user, such as in the case of
assignTaskToUserInGroup methods, the Task goes directly into a claimed state, and that user becomes the claimant.
Worklist controls allow a Task instance to be returned to the assigned state from the claimed state. The ability to assign a previously claimed Task depends on the privileges of the user initiating the assignment. To learn about the permissions required for changing Task states, see Permissions for Modifying Task Properties.
You can reassign Tasks, placing them back into the assigned state while changing the Assignees List, effectively giving them to different users. You can also return Tasks, placing them back into the assigned state with the same Assignees List. You can return or reassign Tasks for work that repeats on a continuing basis.
The data values for tasks that you can set depend on the permissions you have been granted in the system. To learn about the Data values for task instances, the permissions you need to alter the task data, and the valid values for each type of data, see Task Data Values.
The Task control supports an operation that takes a
TaskUpdateXML document. You can use this operation to set multiple data values in a single step. To learn how, see Using XML With the Task Control.
Control operations set values for business dates, such as due dates, completion dates, and claim dates, to make sure that work in done in a timely manner. To learn more, see Task Due Dates.
Some methods on the Task control cause the state of a task instance to transition to a new state. Some of these methods also set related data values for the task instance in the business process. To learn more about Task states, see Task States.
To learn about users and groups for Worklist controls, see Task Users and Groups.
To learn more about Task properties and XML, see Using XML With the Task Control.
To learn more about purging Tasks, see System Configuration in Managing WebLogic Integration Solutions.
The Task and Task Worker controls provide operations to access data values associated with a task instance. You can use these operations to access individual values, to receive a
TaskInfoXMLDocument, and to return a
TaskInfoXMLDocumentcontains a summary of the task and data values in a single XML document. To learn about the
TaskInfoXMLDocument, see Using XML With the Task Control.
com.bea.wli.worklist.api.TaskInfoobject contains a summary of the task and data values in a Java object.
For ease of use, several operations on the Worklist controls offer an XML interface. These operations are concise and convenient. They allow you to configure and perform multiple operations on a Task instance in a single step; they allow you to access the summary for a task instance in a single document. The real power of these operations is through their use with the XML mapper.
For example, if a business process contains several variables, all of which contain information relevant to the creation of a new task, the XML mapper can extract the values from each of these variables and construct a single XML document that specifies aspects of a new task. You can review the XML document in the mapper to get an overview of the data values that will be set for a given task.
You can use a TaskCreationXML document to create a new Task instance and configure that new instance in a single step. Operations on the Task Control take the document as an argument and use it to create a Task. Each element in the TaskCreationXML document causes the new Task to be updated in a different way. This section describes the following methods:
The following is an example of an XML document that you can use to create a new task named My Task, assign it to a user named Bill Smith, set the priority to 5, specify a task comment, specify the completion due date for 3 business days, and specify that the due date is calculated based on the CustomerSupport group's business calendar:
<comment>This work is important</comment>
completionDueBusinessDate—Allows optional specification of a Business Calendar, either specifying the Calendar's name, or the name of a user or group whose calendar is to be used. To set the due date as a
java.util.Date, this calendar converts the business-time duration to an absolute time.
assignee—Assign the task directly to a user, a user in a group, or to set the Assignees List to contain a list of users or groups. The example XML in the preceding listing shows how to specify the assignee as a single user (assignToUser). The following XML is also valid to assign a task to a user in a group, and to specify a list of users and groups for the Assignees list:
You can use an XML element to set the request property for the Task Instance. The message value of this element can be any XML appropriate for the task instance. The mime-type element is for informational purposes only and can be interpreted by the application. To learn more about the mime-type elements, see Request and Response Documents.
You can use public
TaskInfoXMLDocument getTaskInfoXMLDocument() to get a
TaskInfoXMLDocument on the Worklist Controls. It contains the task properties, state, and other attributes in a single document.
Each element in the
TaskUpdateXML document causes the Task to be updated in a different way. The XML document is similar to the
TaskCreationXML document described for public String createTask(TaskCreationXMLDocument doc).
When a new task is created with the control, the values in the properties sheet are used, unless the creation operation passes a parameter that explicitly overrides the value. If values are not set by the method parameters and do not exist in the properties sheet, the Worklist defaults are used for those values.
For example, if the properties sheet specifies values for the task name, task owner, and priority, and the user creates a new task with a TaskCreationXML document that specifies only the task description and priority, the following takes place:
In WebLogic Workshop, the controls you create in your application are represented as JCX files in the Application pane. Instances of controls that you create in your business process are displayed in the Data Palette. You can view and edit the properties of control instances and their parent types in the Property Editor.
Note that when you open the Property Editor for an instance of a control, the properties for that instance are listed at the top of the Property Editor and the properties specified for the parent control (that is, the control on which the current instance is based) are listed at the bottom in the Referenced Control section. The properties displayed in the Referenced Control section are read-only. You can edit the referenced control properties by opening the JCX file.
To learn how to specify properties for control types versus control instances using the Property Editor, see Setting Control Properties in the WebLogic Workshop Help.
For example, if you create an instance of a File control in your business process, and name it taskCTRL, the instance is displayed in the Data Palette. To view the instance, in the Data Palette, click taskCTRL. The instance is highlighted and its properties are displayed in the Property Editor.
Default properties for Task control instances appear encoded in the Worklist control JCX file as attributes of the
@jc (Java control) annotations. For detailed information on the @jc annotations, see Worklist Control Annotations in the WebLogic Workshop Help.
To learn more about Task states, see Task States.
You can also create custom callback methods. To learn more about building your own Worklist callback methods, see Querying Tasks Using the Task Worker Control.
When any operation is invoked on a Task, the Worklist verifies that the current principal that is executing the operation has the permission to do so. Permission is granted based on the user's assigned role, the state of the task, the operation being invoked, and possibly data values associated with the task instance. To learn more about permissions, see Tasks and User Permissions.
Whether a user has permission to modify a Task property depends on factors including the state of the task, the current user that is executing the Task, and the particular property to be modified. The following list provides the details:
To learn more about Task states and moving Tasks between states, see Task States.
Task owners and Integration Administrators are always granted the permission to reassign and return Tasks. Additionally, Worklist controls provide the following Boolean properties that specify whether an assignee or claimant can reassign or return a Task:
can-be-reassigned(valid values are
can-be-returned(valid values are
To learn about the methods provided on the Worklist controls that allow a Task to be put back into an assigned state, see Task Operations.
Which users and groups are granted permissions to modify a task property depend on several factors: the state of the task, the current user executing the operation, and the property to be modified, as described in the following list:
To learn about the data values and the permissions required to modify them, see Task Data Values.
The invocation of a method on the Worklist API or a control operation is done within the context of the current transaction. If the transaction rolls back, the effects of the operations on the task are undone.