Using Worklist

Using Worklist Controls

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 for Worklist that support the integration of business users with business processes. It includes the following topics:

About Worklist Controls

Worklist provides two Java controls: TaskControl and TaskBatchControl. You can use JPDs and these Worklist controls to support the integration of human actors and automated actors. Automated actors interact with the JPD and human actors interact with the Worklist User Portal.

As with other built-in controls in Workshop for WebLogic Platform, you use the controls by adding instances of the controls to your business process. Subsequently, you 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. Business processes can use a TaskControl or TaskBatchControl to change a task and also wait for a task (via a TaskControl) to be changed by a human actor. You can extend Worklist controls through Java annotations. Common extensions include implementing callback functions and performing system queries.

Worklist provides the following controls:

These controls provide simplified construction and initialization of Worklist API resources. These controls are extensible controls that allow you to define extension interfaces containing new methods beyond those on the generic control interface. The new methods of these controls can be annotated to attach Worklist behaviors to them.

TaskBaseControl

TaskControl and TaskBatchControl extend from TaskBaseControl, which provides the built-in control methods and annotations that are common to both TaskControl and TaskBatchControl. It provides the following built-in methods:

TaskBaseControl does not allow any control-level annotations. However, it provides the following method-level annotations, which allow you to assign one or more Worklist behaviors to the methods on a control extension:

Method-level Annotations for TaskBaseControl

The various annotations are:

Task Control

TaskControl encapsulates low-level access to a single task instance throughout its life cycle. It provides methods to set user-defined and system properties of the task, as well as taking actions on a task.

TaskControl provides programmatic and declarative event services as described in the Beehive Controls Development Guide. Control extensions of the TaskControl can define their own event methods, and attach listener configuration attributes to them via annotations.

TaskControl extends TaskBaseControl (thus providing all its methods). TaskControl also provides methods for the following:

Method-level Annotations for TaskControl

The TaskControl control interface is not intended to be a fully functional replacement for the Worklist API. It is expected that users will define extensions of TaskControl, adding any appropriate methods to meet their needs for managing the task.

A TaskControl extension can define any number of methods with any legal Java name. Worklist does not assign any special meaning to a method name. Instead, annotations added to the methods of a TaskControl extension attach behaviors to those methods. A given method can have multiple annotations, and thus accomplish multiple operations on a task in a single method call. In addition, annotations may be placed at the top-level of a control extension (before the interface declaration) that sets behavior (default or otherwise) for all methods in the extension.

TaskControl extensions can be annotated with:

TaskControl allows all the method-level annotations from TaskBaseControl.

TaskControl defines the following additional method-level annotations:

TaskBatch Control

The TaskBatchControl encapsulates low-level access to a batch of task instances. It does not provide event services (for these, you must use TaskControl). Methods on a control extension of TaskBatchControl can define custom task selectors that define the batch or group of task instances upon which the method will act.

The TaskBatchControl extends TaskBaseControl, and thus provides all system methods from TaskBaseControl. It does not define any additional system methods.

Control-level Annotations for TaskBatchControl

The TaskBatchControl supports the select control-level annotations. This acts as a default selector for methods on the control extension.

Method-level Annotations for TaskBatchControl

TaskBatchControl supports the following method-level annotation:

Merging Parameter Values with Annotation Values

Some annotations support parameter markers within them that can be replaced at runtime with the values of parameters provided in a method invocation. This allows dynamic data to be combined with static data from the annotation.

Annotations that support runtime parameter markers are marked with the @SupportsParameters annotation.

public @interface @SupportsParameters {

    String markerBegin() default "{";

    String markerEnd() default "}";

}

Any annotation field of type String can be annotated with the @SupportsParameters annotation. Any unescaped parameter markers in the annotation string value will be interpreted as replaceable parameters. For example:

public @interface TestAnno {

    @SupportsParameters

    String hasParams();

    String noParams();

}

and

public interface MyTest {

    @TestAnno(hasParams="Param1 has value {param1} and param2 = {param2}")

    public void testHasParams(int param1, String param2);

    @TestAnno(noParams="Param1 has value {param1} and param2 = {param2}")

    public void testNoParams(int param1, String param2);

}

In this case, a call to testHasParams with param1=1 and param2="Two" yields an effective runtime value for hasParams of:

Param1 has value 1 and param2 = Two

whereas a call to noParams with param1=1 and param2="Two" yields an effective runtime value for noParams of:

Param1 has value {param1} and param2 = {param2}

Creating Worklist Controls

You can create Task Control and Task Batch Controls and use these controls in a business process.

Creating a Task Control

You can create a task control using any of the following methods:

Creating a Task Control from the Select a Wizard Dialog

To create a Task Control that will trigger the creation of a task instance:

The task control is created based on the selected task plan. You can see the <task control name>.java file in the Package Explorer View.

Creating a Task Control from the Data Palette in Process Perspective

To create a task control:

The task control is created based on the selected task plan. You can see the <task control name>.java file in the Package Explorer View. You can also see the new control listed in the Data Palette View.

Creating a Task Batch Control

You can create a task batch control using any of the following methods.

Creating a Task Batch Control from the Select a Wizard Dialog

To create a Task Batch Control:

The task batch control is created. You can view the <task batch control name>.java file in the Package Explorer View.

Creating a Task Batch Control from the Data Palette in Process Perspective

To create a task batch control:

The task batch control is created based on the selected task plan. You can see the <task control name>.java file in the Package Explorer View. You can also see the new control listed in the Data Palette View.

Creating a Worklist Control Using Task Control Generator

You can use TaskControlGenTask, the Task Control Generator, to create an Apache Beehive control for a task plan. The generated control uses the TaskControl. A developer can change the annotations of the generated controls as required.

For generic information about custom controls, see Developing Custom Controls in Workshop for WebLogic Platform Programmer's Guide.

Generated controls take into account the constructors, steps, and actions defined in the task plan. They contain appropriate methods for creating tasks, taking actions on them, responding to events on them, and getting/setting system and user-defined property information for them.

Design the control interface to ensure that it contains:

Running the Task Control Generator

You can run the Task Control Generator:

Running the Task Control Generator from a Java Client or Command Line

The Java class name is com.bea.wli.worklist.build.TaskControlGen in the WL_HOME/integration/lib/worklist-client.jar file.

To run the generator from a Java client of the command line, type:

java com.bea.wli.worklist.build.TaskControlGen <options>

where options are listed in the following table:

Running the Task Control Generator from Ant

The Ant task class name is com.bea.wli.worklist.build.TaskControlGenTask in the WL_HOME/integration/lib/worklist-client.jar file.

The following Ant script describes how to use TaskControlGenTask:

<!-- Set some initial properties -->

<property environment="env"/>

<property name="wl.home" value="${env.WL_HOME}"/> 

<property name="worklist-client.jar"

location="${wl.home}/integration/lib/worklist-client.jar"/>

<property name="build.dir" value="<some dir to hold build output>"/>

<!-- Define the task to Ant -->

<taskdef name="task-control-gen"

classname="com.bea.wli.worklist.build.TaskControlGenTask"

classpath="${worklist-client.jar}"/>

<!-- Give us a place to build control source files into -->

<mkdir dir="${build.dir}/controlsrc"/>

<task-control-gen

taskPlanFile="<see command-line section -taskPlan arg>"

outputDir="${build.dir}/controlsrc"

hostAppRootDir="<see command-line section -hostAppRootDir arg>"

packageName="<see command-line section -packageName arg">

interfaceName="<see command-line section -interfaceName arg">

<classpath>

<!-- Add this so TaskControlGen can see the needed classes. You can also add your own classes (e.g. XMLBeans classes as needed) -->

<pathelement location="${worklist-client.jar}"/>

</classpath>

</task-control-gen>

Manually Creating Task Control and Task Batch Control

The Task Control Generator and the Worklist Control wizards should be viewed as shortcuts to creating Worklist controls in ways that users commonly need. However, you may create TaskControl and TaskBatchControl extensions manually if they like. The only requirement for these extensions is that they extend TaskControl or TaskBatchControl and are marked with @ControlExtension at the interface level.

You may add any number of methods to these control extensions and mark them up using any of the annotations supported for the given type of control. It may be appropriate to create your own custom control extensions in the following cases (and possibly others as well)

In all these cases, you can start with a control as generated by the Worklist tools, and then manually update the control interface as desired.

Using Task and Task Batch Controls in Business Processes

This section provides information about using business process files (JPDs) and Worklist Controls to support the integration of human actors and automated actors. Automated actors interact with the JPD and human actors interact with Worklist User Portal.

As with other built-in controls in Workshop for WebLogic Platform, you use the controls by adding instances of the controls to your business process. Subsequently, you invoke operations on the controls at the point in the business process at which you want to integrate the business-user logic.

To design the interaction of a Task or Task Batch 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 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 Batch 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 Batch controls can be extended to add customized methods and additional callbacks.

You can create a task instance using a Task Control or Task Batch Control in a JPD. During this process, you need to create a business process file and a Task Control or Task Batch Control, deploy the process. If required, you can create a sample task to validate the task instance creation.

You can use worklist controls in your business process by:

Creating a Business Process

To create a business process that will use the worklist controls:

Invoking the Task Plan Constructor from the Business Process

To invoke the task instance creation constructor to the business process.

Deploying and Validating the Business Process

To deploy and validate the business process:

The Assigned Tasks portlet box displays the task instance created by a JPD using a Control.