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.
This section describes the built-in controls provided by WebLogic Integration that support the integration of business users with business processes. It includes the following topics:
To support the integration of business users with the Worklist system, WebLogic Integration provides two Java controls: the Task control and the Task Worker control.
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.
The operations invoked on the controls allow the process to create tasks, get information about tasks, update tasks, and so forth.
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.
You can customize Task controls for different business purposes, by adding new operations or callbacks, or by altering the signatures of existing operations or callbacks.
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.
This section includes the following topics:
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 setActiveTaskId
method.
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.
A Task Control can create a new Task with the following operations:
Both operations create a new Task, return the instance ID of that new task, and set the task control's Active Task ID to the ID of the new task.
The 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.
The 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.
Worklist controls assign Tasks according the following methods:
assignTaskToUserInGroup
methods and the ToUserInGroup
property
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.
assignTaskToUsersAndGroups
methods and the ToUsersAndGroups
property
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 assignTaskToUser
or assignTaskToUserInGroup
methods, the Task goes directly into a claimed state, and that user becomes the claimant.
If you create a Task with no users or groups on the Assignees List, the Task behaves as if it were unassigned.
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 following methods, among others, allow a Task to be put back into an assigned state:
To learn about Task states and operations, see Task Operations. To learn more about the Worklist API, see the com.bea.wli.worklist.api
package in the BEA WebLogic Integration Javadoc.
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.
Table 2-1 Setting Data Values with Operations
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.
Table 2-2 Operations That Affect Task State
Assigns tasks to the user whose name you provide as an argument to the method. The specified user must belong to the WebLogic Integration Users Group. The Assignees List is set accordingly for the task instance. The task is then automatically claimed for the specified user. To learn about users and groups for Worklist controls, see Task Users and Groups. |
||
Assigns the task to a user in the group whose name you provide as an argument to the method. The Worklist uses a load balancing algorithm to choose the least busy user in the group. |
||
Assigns the task and sets the Assignees List to contain the users and groups that you provide as an argument to the method. The users and groups specified must belong to the WebLogic Integration Users Group. |
||
Alters the state through assignment. To learn more about Task properties and XML, see Using XML With the Task Control. |
||
Purges all logged tasks from the worklist history tables. To learn more about purging Tasks, see System Configuration in Managing WebLogic Integration Solutions. |
||
Causes the claim operation to be called. The currently executing principal claims the task. |
||
Causes the claim operation to be called. Claims the task on behalf of the user whose name is specified as an argument to the method. This is an administrative function. |
||
Removes the task instance completely and permanently at run time. You can also use the WebLogic Integration Administration Console to remove task instances. This is an administrative function. |
||
Invokes the return operation on a task. This method places Tasks back into the assigned state and makes no changes to the Assignee List. |
||
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 com.bea.wli.worklist.api.TaskInfo
object:
TaskInfoXMLDocument
contains 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.TaskInfo
object 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.
Similarly, you can use the mapper to extract several values from a Task Status XML document to set several values for a business process at once.
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 worklist system calls the following method using the value of the name element in the TaskCreationXMLDocument
:
public String createTask(TaskCreationXMLDocument doc)
The method then parses the document, element by element, invoking a state-related operation or a data-setting operation on the task instance for each.
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:
<TaskCreationXML xmlns="http://www.bea.com/wli/worklist/xml">
<name>My Task</name>
<comment>This work is important</comment>
<priority>5</priority>
<completionDueBusinessDate>
<day>3</day>
<calendar>
<userOrGroup>CustomerSupport</userOrGroup>
</calendar>
</completionDueBusinessDate>
<assignee>
<user>BillSmith</user>
<algorithm>ToUser</algorithm>
</assignee>
</TaskCreationXML>
In the preceding listing, note the following elements:
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.
<request>
<message>
<line:line-item xmlns:line="http://www.bea.com/line-item">
<line:name>Widget</line:name>
<line:quantity>100</line:quantity>
</line:line-item>
</message>
<mime-type>LineItem</mime-type>
</request>
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.
You can use a TaskUpdateXML
document as an argument to the following method to update an existing Task instance in various ways in a single step:
public void updateTask(TaskUpdateXMLDocument doc)
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).
To import the Worklist schema into your application:
Note: If the Application tab is not visible in WebLogic Workshop, choose View
The Schemas project you create contains WebLogic Integration System XSD files, including Worklist.xsd
.
Note: You can name your schemas project anything you want, except when you plan to use the project for application view channels and schemas. In that case, you must name it Schemas.
You can use the Task Control Properties Sheet to set property defaults for new task instances created by a control.
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:
Table 2-3 Task Control Properties
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.
To view or edit properties for control instances:
Note: If the Data Palette or the Property Editor is not visible, from the menu bar, click View
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.
The following figure shows the Property Editor for the example taskCTRL instance:
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.
Task controls provide callback methods. Other resources can use the callback interface to receive notification of events, such as changes in states or properties.
Table 2-4 Task Control Callback Methods
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.
Table 2-5 State Transitions for Tasks
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 true
and false
)can-be-returned
(valid values are true
and false
)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.
Only certain users can create tasks. To learn more, see Task Users and Groups and Tasks and User Permissions.
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.
Task instances work with transaction contexts in the following ways:
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.
All operations on Task instances behave like an EJB operation with a required transaction attribute.