Using the Worklist
|
 |
 |
|
|
 |
 |
Advanced Topics
This section provides information about the following topics:
- Extending Worklist Controls
- Querying Tasks Using the Task Worker Control
- Using Task Control Factories
- Using Multiple Authenticators
Extending Worklist Controls
This section contains information about extending the Task and Task Worker controls. It contains information on the following topics:
- About Extending Worklist Controls
- An Example of an Extended Task Control
- Altering Method Signatures—Request and Response
- Adding Custom Methods
- Creating Tasks With the Task Control
- Updating Tasks Using the Task and Task Worker Controls
- State Related Updates Using the Task Control
- State Related Updates Using the Task Worker Control
- Getting and Setting Task Data Values
- Adding Callback Methods
About Extending Worklist Controls
In WebLogic Workshop, when a new Task or Task Worker control is created from the Data Palette, it provides a standard interface for operations and callbacks. These basic signatures offer the most common operations used by the processes that create, configure and manage tasks, and by those who actually take ownership of tasks and perform their work.
You can extend the control instances and customize them in the following ways:
- Signatures can be altered to accept specific data types as arguments. For example, you can design methods to accept XML Beans created from schemas specific to your application.
- New methods can be added to incorporate several different task modifications into a single method.
- Additional callbacks can be added to detect different types of state changes within a business process.
An Example of an Extended Task Control
The following listing shows a customized Task control for managing tasks related to an automated taxi dispatching system.
Listing 5-1 Customized Task Control
/**
* @jc:task
*/
public interface AutoTaxiDispatcher
extends TaskControl, com.bea.control.ControlExtension
{
/**
* @jc:task-create
* name="Pick up {passengerName}"
* description="Find customer at {pickupAddress}"
* claim-due-business-date="5 min"
* claim-calendar="24by7Calendar"
* completion-due-business-date="15 min"
* completion-calendar="24by7Calendar"
* request="<destination>{destinationAddress}</destination>"
* request-type="taxiRideDestination.xsd"
* @jc:task-assign
* group="{locality}Group"
* algorithm="ToUsersAndGroups"
*/
public String passengerReady(String passengerName,
String destinationAddress, String pickupAddress, String locality );
/**
* @jc:task-abort enabled="true"
*/
public void cancelPickup();
/**
* @jc:task-update
* request="<destination>{destinationAddress}</destination>"
*/
public void changeDestination(String destinationAddress);
public interface Callback extends TaskControl.Callback {
/**
* @jc:task-event event-type="claim"
* time="{time}" user="{driver}"
*/
void passengerClaimed(Date time, String driver);
/**
* @jc:task-event event-type="complete"
* time="{time}" user="{driver}"
*/
void passengerPickup(Date time, String driver);
/**
* @jc:task-event event-type="claimExpire" time="{time}" response="{location}"
*/
void nobodyClaimedPassenger(Date time, XmlObject location);
/**
* @jc:task-event event-type="expire" time="{time}" response="{location}"
*/
void nobodyPickedUpPassenger(Date time, XmlObject location);
}
}
Altering Method Signatures—Request and Response
Operations can have arguments that take, as input, the value of a Request or Response document. Callbacks can have return types that return those values.
Because the Request and Response can consist of various formats, operation and callback signatures can be modified to enforce specific types of Request and Response content. The enforcement of the data types can be done either when these values are set or when the values already set are returned.
The method parameters that you use to set the Request or Response, and Return types in method signatures that are used to return the value of the Request or the Response, can be set to the following types:
It is the responsibility of the application to ensure that callbacks return Request or Response types that are compatible with the signatures in the relevant controls. The Worklist must cast the value that is stored in the system, a mismatch causes an exception to be thrown.
The application can determine the type of data stored in the Request or Response using the request type and the response type data values. You can also design an application to use this information in other ways.
The following code examples show you how to write a method that sets the request and response using different data types. They also show how to design a callback that returns the Response as a Purchase Order XML Bean.
- This method sets the request and the response as different data types:
- This shows a callback that returns the response as a purchase order XML bean:
/**
* @jc:task-update
* request={req}
* response={res}
*/
public void setRequestAndResponse(XmlObject req, String res);
/**
* @jc:task-event event-type="complete" response="{response}"
*/
void onTaskCompleted(com.bea.purchaseOrderDocument response);
Adding Custom Methods
Methods on controls can create or update Tasks. Creating or updating Tasks can involve altering data values or affecting the task's state. Custom methods can be added to the controls to incorporate several update steps into a single operation.
To do this, first define your method, passing the parameters needed to create or update the task. Then ensure that the method annotations and attributes specify to the Worklist system which aspects of the task to alter using each parameter.
You can use constants to alter the task in a fixed way. For example, you can set the task name to CallDelinquentCustomer for every new task created. In this way, you do not need to provide the same value as input to the method repeatedly—the value you provide is a constant.
Note that the default methods on a new Task control or Task Worker control use the annotations mechanism. You can look at the default methods on the controls and use them as an example of how to create custom methods.
Note that, in addition to creating new methods for a control, you can customize a control by deleting some of its default methods.
Creating Tasks With the Task Control
Methods that create new tasks can also configure the new tasks in several ways. Operations that allow you to create and configure new tasks are identified by the @jc:task-create annotation. The @jc:task-create annotation contains attributes that specify the way or ways in which the new task is to be configured. Each attribute sets a particular aspect of the task instance, as shown in the following table.
Table 5-1 jc:task-create Attributes to Use For Creating and Configuring Tasks
The following code examples show you how to associate annotations with the methods that create and configure tasks:
- Creates a Task and sets the name, description, comment, and priority:
- Create a Task and set the due dates using an absolute date and referencing a calendar:
- Create a Task, and specifies the request and request-mime-type:
/**
* @jc:task-create
* name="{name}"
* description="{desc}"
* comment="{comment}"
* priority="{priority}"
*/
public String newCollectionsTask (String name, String desc, int priority, String comment);
/**
* @jc:task-create
* name="{name}"
* claim-due-date="{claimDate}"
* completion-due-business-date="{completeDuration}"
* completion-calendar="{completeCal}"
*/
public String createNewTask (String name, Date claimDate, String completeCal, String completeDuration);
/**
* @jc:task-create
* name="{name}"
* request="{req}"
* request-mime-type="{reqType}"
*/
public String createWithRequest(String name, XmlObject req, String reqType);
Updating Tasks Using the Task and Task Worker Controls
In addition to the ability to create and configure new tasks, you can update existing tasks in multiple ways using a single custom method. With the exception of name and description, the same attributes are supported for update operations as for create operations on the Task Control, and you use them in the same way. The annotation associated with update methods is the jc:task-update annotation.
Note that response and response-type attributes are supported for update operations. They are analogous to request and request-type attributes for create operations. The following example code shows the use of the response and response-mime-type attributes.
/**
* @jc:task-update
* comment="{comment}"
* response="{resp}"
* response-mime-type="{ respType }"
*/
public String responseAndComment(String comment, XmlObject resp, String respType);
State Related Updates Using the Task Control
You can use annotations to configure methods that alter task state. Task controls and Task Worker controls use different annotations. The following table lists the annotations and their attributes to use with state transition operations for Task controls.
Table 5-2 Annotations to Use With State Transition Operations for Task Controls
State Related Updates Using the Task Worker Control
You can use annotations to configure methods that alter task state. Task controls and Task Worker controls use different annotations. The following table lists the annotations and their attributes to use with state transition operations for Task Worker controls.
Table 5-3 Annotations to Use With State Transition Operations for Task Worker Controls
Getting and Setting Task Data Values
The default methods on the Task and Task Worker controls can get, set, and remove control data values. To learn about the data values you can set and get for these controls, see Task Data Values. The following examples show annotations you can use with get, set, and remove methods on the controls:
- Get example:
- Set example:
- Remove example:
/**
* @jc:task-get-property name="{name}"
*/
public String getProperty(String name);
/**
* @jc:task-set-property name="{name}" value="{value}"
*/
public void setProperty(String name, String value);
/**
* @jc:task-remove-property name="{name}"
*/
public void removeProperty(String name);
Adding Callback Methods
Callbacks provide a way for a control to asynchronously notify a client that an event has occurred. A callback is a method signature that is defined by a control and for which the method implementation is provided by the client. For example, a business process can implement a callback handler to enable reception of a callback from a control.
You can extend Task controls with callback methods to report state changes, or events. You can implement callback methods only on Task controls—not Task Worker controls—because only Task controls identify with a single active instance of a Task.
Optionally, callbacks can return up to three arguments, as follows:
- user—the user who executes the operation to make the state transition
- time—the time the due date expired or the operation was invoked
- response—the response document
The following example displays the user, time, and response attributes associated with a callback method:
/**
* @jc:task-event event-type="complete"
* response="{response}"
* time="{time}"
* user="{user}"
*/
void onTaskCompleted(XmlObject response, Date time, String user);
To specify the state transition that triggers the callback, set the event-type attribute. Use the appropriate value for the type of event that triggers your method. The following table describes the types of events and the associated value.
Table 5-4 Event Types and event-type Attribute
Querying Tasks Using the Task Worker Control
This section explains how to extend a Task Worker control to query WebLogic Integration tasks. The @jc:select annotation accepts values to search for Tasks, including TaskSelector objects, and returns a set of Task IDs. It contains the following topics:
Search Values and Selectors
The Java annotations for a Task Worker control provide a set of attributes that you can use to query with the @jc:select annotation.
Table 5-5 Task Control Attributes to Use with @jc:select
|
Search by Tasks with a claim due date after the value you provide. |
|
|
Search by Tasks with a claim due date before the value you provide. |
|
|
Search by Tasks with a completion due date after the value you provide. |
|
|
Search by Tasks with a completion due date before the value you provide. |
|
|
Search by Tasks with a creation date after the value you provide. |
|
|
Search by Tasks with a creation date before the value you provide. |
|
|
Search by Tasks with no greater priority than the value you provide. |
|
|
Search by Tasks with no lesser priority of the value you provide. |
|
|
Search by Tasks with a given value for the property defined by |
|
|
Search by the configuration of the To learn more about using this value to pass arguments to |
|
Querying Tasks With Annotations
To provide a method for your custom query, you must extend the Task Worker control. You can start by taking a method that already uses the @jc:select annotation tag to perform a search and modify this method.
For example, the Task Worker control provides the following @jc:select tag and method:
/**
* @jc:task-get-info enabled="true"
* @jc:select task-id="{taskIds}"
*/
public TaskInfoXMLDocument[] getTasksInfoXML(String[] taskIds);
The TasksInfoXML method allows you to search through Tasks by Task ID. You can extend this control to search through Tasks by an additional attribute, such as the claimant. To do so, you can take advantage of the extensibility built into the TasksInfoXML method, which allows you to pass additional arguments to the method, as shown in the following example.
In the following example, the previous example code is extended to query for a claimant. The bold text indicates the additions made to the example.
/**
* @jc:task-get-info enabled="true"
* @jc:selectclaimant="James Gosling"task-id="{taskIds}"
*/
public TaskInfoXMLDocument[] getTasksInfoXML(String[] taskIds);
You can extend your control without setting a default value for the claimant. For example, you can provide a value within curly brackets to indicate the claimant must be a user. You must pass a value for the user parameter to the method at run time.
/**
* @jc:task-get-info enabled="true"
* @jc:selectclaimant="{user}"task-id="{taskIds}"
*/
public TaskInfoXMLDocument[] getTasksInfoXML(String user,String[] taskIds);
To learn more about Worklist control annotations, see Worklist Control Annotations in the WebLogic Workshop Help.
Querying Tasks With TaskSelectors
The Worklist API provides the functionality for creating more advanced search functionality than described in the preceding section, which used the @jc:select Java annotation. You can query on all Task instance properties by making a call to a TaskSelector object. This allows you to order the results of queries, find parent process IDs, use regular expressions, and more.
To use a TaskSelector, you must include the selector attribute and argument with a method. The following code shows a method in the Task Worker control that you can use as a starting point to extend your control.
/**
* @jc:task-get-info
*@jc:select selector="{selector}"*/
public TaskInfoXMLDocument[] getTaskIdsWithSelector(TaskSelector selector);
The method described in the preceding example expects, as input, a TaskSelector that is defined to query by Task ID. The method returns a TaskInfoXMLDocument array of resulting Task properties with Task IDs that match your query.
For more information about the constructor and methods of the TaskSelector class, see Class TaskSelector in the com.bea.wli.worklist.api package, in the BEA WebLogic Integration Javadoc.
Using Task Control Factories
There are two circumstances in which you must use a Factory type of Task Control:
- You are creating multiple tasks in a loop, or you want the number of tasks created to be specified at run time.
- You are interacting with multiple existing tasks in a loop, or with a number of tasks that is not known until run time.
Task Control properties can be useful when using factory type Task Controls. Defining the control's properties in the Property Editor specifies default values for new tasks that are created by any control instance that was created from that factory.
For example, say that your business process loops over a sequence of order elements that creates a new task to approve each order in the body of the loop. Additionally, the task name changes on each iteration, but the assignee is always the same manager. In this case you can set the assignee in the factory control's properties using the Property Editor. You need not specify it when creating a new task, the default assignee will be used.
The basic pattern is to create two Task controls in your business process: one that is a factory type and the other that is not a factory type. Callbacks for tasks created using factory-created task control instances will be received by the factory control callback handler. The following example describes a scenario for which you want to create a task for each iteration through a loop in a business process:
The control's variables in the business process are written as shown in the following code.
/**
* @common:control
*/
private processes.MyTaskCtrlFactory factoryCtrl
/**
* @common:control
*/
private processes.MyTaskCtrl myTaskCtrl;Note: To view the code for the control's variables, click the Source View tab for the business process, then in Document Structure, double-click factoryCtrl.
- In the body of a loop (or any other place you want to create a new task or want to do work on an existing task), create a new control instance using FactoryCtrl. You create this logic in a Perform node as follows:
- From the Data Pallet, select a method from myTaskCtrl, then drag it onto the business process placing it below the Perform node.
In this way, you create a new control that you can use to create a new task or set the Task Id (
setTaskId (String id)) to the ID of an existing task. Because you are designing the process to create a new control instance in a loop, you must create the instance using the factory control. The following figure shows the simple business process described in this example:
Using Multiple Authenticators
This section contains information about configuring your security realm to allow task assignment across users and groups when your WebLogic Integration domain is configured with multiple authenticators. An example of this is when the domain uses the default WebLogic Integration embedded LDAP and Netscape iPlanet.
When a security realm has multiple authentication providers configured, WebLogic Server uses the Java Authentication and Authorization Service (JAAS) classes to authenticate. Specifically, the control flag attribute on each authenticator determines the order of execution. The JAAS documentation (http://java.sun.com/j2se/1.4.2/docs/api/javax/security/auth/login/Configuration.html) provides the following information about this control flag:
1. Required—The LoginModule is required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
2. Requisite—The LoginModule is required to succeed. If it succeeds, authentication continues down the LoginModule list. If it fails, control immediately returns to the application (authentication does not proceed down the LoginModule list).
3. Sufficient—The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed down the LoginModule list). If it fails, authentication continues down the LoginModule list.
4. Optional—The LoginModule is not required to succeed. If it succeeds or fails, authentication still continues to proceed down the LoginModule list.
The overall authentication succeeds only if all Required and Requisite LoginModules succeed. If a Sufficient LoginModule is configured and succeeds, then only the Required and Requisite LoginModules prior to that Sufficient LoginModule need to have succeeded for the overall authentication to succeed. If no Required or Requisite LoginModules are configured for an application, then at least one Sufficient or Optional LoginModule must succeed.
Note: LoginModules are the work-horses of authentication: all LoginModules are responsible for authenticating users within the security realm and for populating a subject with the necessary users and groups. LoginModules that are not used for perimeter authentication also verify the proof material submitted, such as a user's password.
If you have two user communities with exclusive user logins, avoid using Required and Requisite as values unless the authenticator for any of these settings can authenticate a superset of all user communities. Use the WebLogic Server Administration Console to set the JAAS control flags. For information on how to set these flags, see the WebLogic Server Administration Console Online Help at http://download.oracle.com/docs/cd/E13222_01/wls/docs81/ConsoleHelp/index.html.
For more information about using multiple authenticators and external LDAP servers, see the following:
- "Security Fundamentals" in Introduction to WebLogic Security, which is available at the following URL:
- "Setting the JAAS Control Flag Attribute" in "Configuring Security Providers" in Managing WebLogic Security, which is available at the following URL:
- "Using an External LDAP Server" in Security in WebLogic Platform 8.1, which is available at the following URL:
