test

Sun Worklist Manager Service Engine User's Guide

Worklist Manager Service Engine Overview

The Worklist Manager Service Engine (WLM SE) is a JBI-based service engine that introduces manual tasks into an automated workflow. A workflow is a coordinated series of business activities intended to produce a specific result. In some cases, the entire workflow cannot be automated and human interaction is required to complete the process. The WLM SE allows you to define the tasks that require human intervention and during an otherwise automated process. During processing, the WLM SE generates a worklist of these tasks.

Installing the WLM SE includes an editor, a wizard, and the service engine itself. A default database and task management console are also included for development and testing purposes. The service engine provides the runtime services for executing Worklist Manager tasks. The editor and wizard allow you to easily define Worklist Manager tasks in the NetBeans IDE design-time environment. The database stores information about each task, and is accessed by the Worklist Manager Console for task management.

The WLM SE uses a simple task definition to describe the manual tasks that cannot be automated. These tasks can then be inserted into a workflow, such as a BPEL process. Once the workflow begins, you can manage the manual tasks using the Worklist Manager Console, where users can view, claim, complete, and reassign tasks. A task definition includes user and group assignments and any of the following: search keywords, task timeouts, automatic escalations and notifications, deadlines for task completion, default values for the task output, and trigger actions that change variable values.

Installation Requirements

The WLM SE is installed as an add-on to GlassFish ESB. For information and instructions on installing the WLM SE, see Installing the GlassFish ESB Platinum Pack in Using the GlassFish ESB Installation GUI.

When you install the WLM SE, a sample Worklist Manager Console is deployed as a web application to the GlassFish server. In addition, sample Worklist Manager projects and Worklist Manager Console projects are made available in the NetBeans IDE.

Worklist Manager Service Engine Features

The WLM SE provides the following features to enable Worklist Manager task processing:

Worklist Manager Service Engine Architecture

The Worklist Manager Service Engine functions as part of a larger workflow, which can include multiple binding components, BPEL processes, and worklist tasks. The following diagram illustrates the general architecture of a Worklist Manager system.

Figure shows the architecture of a Worklist Manager system.

    The following describes the flow of data through a Worklist Manager system:

  1. An external system or client sends a message to the workflow system.

  2. The message is received through a binding component and is then processed through the Normalized Message Router (NMR) to the BPEL process.

  3. When the BPEL process comes to the human task, it sends a request to the Worklist Manager Service Engine.

  4. The Worklist Manager Service Engine writes the task to the Worklist Manager database, and waits for the task to be claimed and completed.

  5. A WLM user claims and completes the task.

    • Each time a user changes the task status, the information is sent from the web client through the Java EE Service Engine and NMR to the Worklist Manager Service Engine, and the Worklist Manager Service Engine updates the database.

    • If email notifications are defined, email messages are sent out from the Worklist Manager Service Engine through the NMR and the Email Binding Component to the external email service. This happens each time a notification trigger event occurs.

  6. Upon task completion, the Worklist Manager Service Engine sends a reply to the BPEL process. Additional notifications may be generated.

  7. The BPEL process generates a message back out through the NMR and binding component to the external system or client.

Worklist Manager Components

In addition to the service engine itself, which handles runtime processing, the WLM SE also includes the following components:

Worklist Manager Database

The Worklist Manager database stores information about each human task generated by a BPEL process or other workflow. All tasks generated from the same instance of the WLM SE are stored in the same database. The database tracks the status of each task, the users and groups assigned to a task, its priority, due dates, input and output data, and so on. The database also persists the status of each task so incomplete tasks are recovered in the event of system failure, and users can continue to process each task.

The WLM SE supports Oracle, MySQL, and Java DB (Derby) databases. For development and testing purposes, the connection pool and JDBC resource for a Java DB database are automatically created when you install the WLM SE, and the Java DB database is automatically generated the first time you start the WLM SE.

The database maintains a complete history of tasks completed, which can grow to be a very large number of records. You should periodically archive older completed tasks to prevent the tables from growing too large.

Task Definition Wizard

The Task Definition Wizard takes you through the basic steps of creating a task definition file, and uses the task-related information you enter to define the Worklist Manager task. This allows you to quickly create a framework for the task definition without any coding. Once you create the task definition, you can configure the task using the Task Definition Editor. The wizard automatically defines the title for a new task, using the name you specify in the wizard, and assigns a priority of 5 to the task.

Task Definition Editor

Once a task definition file is created by the wizard, you can use the Task Definition Editor to further customize and configure the task. From the Task Definition Editor, you can assign users and groups to a task and define escalations, notifications, timeout periods, and trigger actions. The editor provides graphical tools so you can easily edit task definitions. You can also edit the file's source code directly.

You can edit the task definition in any of the following editing windows called views, which are accessible from the Task Definition Editor toolbar:

When a task definition is open in the editor, the Navigator window appears in the lower left side of NetBeans. This window provides a logical view of the task definition. When you select a field in the Design view, the corresponding element is highlighted in the Navigator. If you double-click an element in the Navigator, the corresponding field is shown in the Design view. You can also right-click elements in the Navigator and select to either go to that element in the source or go to that element in the design. The Imports section of the Navigator list any XSD or WSDL files that are referenced from the task definition.

About the Worklist Manager Console

The Worklist Manager Console is a web-based tool to manage the human tasks that are generated from workflow processes. The console accesses the Worklist Manager tasks from the Worklist Manager database to display information about each task. Assigned users can access the console to view, claim, update, complete, and reassign tasks.

An installation of the WLM SE includes a default Worklist Manager Console that is already deployed and available from the GlassFish server. You can use this console for testing and development purposes. A similar Worklist Manager Console is also provided as sample projects in NetBeans. The sample projects include a web application and its corresponding composite application. You can download and modify these projects to create a custom Worklist Manager Console based on the default console. You can also create your own custom console using the client API provided by the Worklist Module project.

Worklist Manager Projects

A typical Worklist Manager configuration includes the following projects:

The Worklist Module Project

A Worklist Manager task is defined in a Worklist Module project in NetBeans. Each Worklist Module project includes a WSDL files to define the input, output, and binding for the task; optional XSD files to define the schema; and a task definition file that defines the scope of the task. The task definition file has a “.wf” extension. Once you build the WLM project, you can incorporate it into a BPEL business process and then into a composite application.

The BPEL Project

The BPEL process defines how data is processed and specifies where in the automated workflow the human intervention occurs. It also defines how the results of the human task are processed once the task is complete. Worklist Manager tasks are incorporated into a BPEL process through an Invoke activity. The BPEL process uses the WSDL document created for the Worklist Manager project for the partner link to the task.

When a running BPEL process comes to a Worklist Manager task, the task is written to the Worklist Manager database and the BPEL process is not completed until a WLM user claims and completes the task. The BPEL process checks the Worklist Manager database for the status of the task in order to determine whether the task is complete and the process can be continued.

The Composite Application Project

The composite application project combines the Worklist Manager and BPEL projects to create a service assembly that can be deployed to the application server. The service assembly is created by simply dragging the appropriate projects and WSDL documents onto the CASA Editor and then building the composite application to generate the connections. You can create test cases in the composite application project to test different scenarios in the worklist system you created.

About Worklist Manager Tasks

Worklist Manager tasks are defined and configured by a task definition file. A task is exposed as a web service operation by the WLM SE, and request and reply web service operations are defined for each task in the project's WSDL file. The input message of this operation is the task input and the output message of the operation is the task output.

The following topics provide information about the structure of the files that define a task and about the supported features of Worklist Manager tasks:

Task Definition File

When you define a task using the Task Definition Wizard, the wizard generates a new task definition file, which has a “.wf” extension in the WLM project. The task definition file is in XML format, and can be edited through the Task Definition Editor or by editing the XML text directly. A task generally has an input from the BPEL process, and upon completion generates output back to the BPEL process for continued processing.

The task definition file specifies the following information:

Task Definition Schema

The XML schema file for the Worklist Module project defines the structure of the data that will be sent to and output by the worklist task. It is referenced from the messages element of the WSDL file, and its namespace prefix is used in the XPath expressions in the task definition file.

XPath Expressions in Task Definitions

The task definition file supports XPath expressions to help define the properties for each task. You can use XPath expressions in task definitions to define literal values for task properties and to define variables whose values are dynamically derived from the input data. You can also use XPath functions to manipulate data and define how data is processed. A mapper is available on the Actions tab of the Task Definition Editor to automatically generate the XPath syntax for the actions you define. For basic properties, escalations, and notifications, you can enter XPath expressions directly into the fields on the Task Definition Editor or directly into the source code.

The Task Definition Editor supports the XPath 1.0 specification in Design view. The Source view also supports XPath 2.0 expressions, which allows you to define if-then-else conditions. To use XPath expressions to retrieve data from the task input, you need to register a prefix for the XML schema file namespace in the task definition file. Once you do this, you will use the prefix in the actual XPath expressions. You can manipulate input and output data using the WLM variables: $TaskInput and $TaskOutput. For example, an expression that extracts information about the price of an item might look similar to the following:

$TaskInput:part1/ns1:price where 'ns1' is the namespace prefix you defined.

Automatic email Notifications

You can configure a task to automatically generate notifications to certain users or groups of users when a certain action occurs. The WLM SE can send notifications via email when a task's status changes, or when an escalation or task timeout occurs. The Email BC is used to send the notifications. For example, when a task is assigned to a user or group of users, an email can be sent to each user to inform them that the task is ready to be worked on. Then, when the task is completed, another notification can be sent to the user's manager letting them know it is done. You can also define custom notifications that do not use email, but instead invoke a web service, for example.

When you create notifications in the task definition file, a WSDL file named EmailNotificationHandler.wsdl is automatically generated to handle the notifications. This file will require some customization to match your email server settings.

Changing Variables

When a task is being processed, you might want certain actions to change the value of an output variable. For example, you might want to insert the current date and time into the output message when a task is completed. The Task Definition Editor supports mapping literal values or values from input messages to the output variables using XPath 1.0 expressions.

Task Escalations and Timeouts

You can manage the task handling process by defining automatic escalations and timeout periods for each task. A task escalation can assign a task to another user, such as a manager, when the task is not completed within the specified time period. This ensures that a process is not held up because a human workflow task is not completed. Tasks can be escalated based on a duration or on a deadline.

A task timeout defines a deadline or duration after which a task fails. If you define a task timeout and the task is not completed within the specified duration or by the specified deadline, the task is treated as failed and returns to the workflow (BPEL process) with a system fault. This is useful for cases when a task is not completed even after it has been escalated.

Security

The Worklist Manager Console is secured using the standard Java EE security mechanism for web applications. The WLM SE supports both file realm security and LDAP security for authentication, authorization, and management of Worklist Manager Console users. Both the file realm and LDAP realm are configured through the GlassFish Admin Console. For the file realm, users and their login information are also configured through the GlassFish Admin Console. For LDAP, you can use your existing directory structure. For escalation, it is useful to have a clearly defined user hierarchy so tasks can be escalated to a user's manager or supervisor.

You can assign users and groups from an LDAP directory using the compact LDAP browser in the Task Definition Editor. The WLM SE supports the following LDAP servers:

Worklist Manager Task Validation

The Task Definition Editor includes a validation function to help you create code that is valid, correctly formatted, and schema-compliant. The editor validates the task definition file against the WLM schema and validates the XPath expressions to verify that the location paths and functions are valid. It also checks for any broken references.

The above validation occurs automatically in real time. You can also validate the task definition and any imported WSDL files by selecting the validate icon on the Task Definition Editor. Any validation failures are listed in the Output window and contain links to the location of the error in the task definition source code.

Steps to Implement a Worklist Manager Task

    Below are the basic steps you need to perform to implement a Worklist Manager task:

  1. Defining Worklist Manager Tasks

  2. Configuring Advanced Task Options (optional)

  3. Creating the Worklist Manager Database

  4. Configuring Worklist Manager Service Engine Runtime Properties (optional)

  5. Defining Worklist Manager Console Security

  6. Including the Worklist Manager Task in a BPEL Process

  7. Creating and Deploying the Composite Application

Once you implement the Worklist Manager task, you can test the system by running messages through the system and using the Worklist Manager Console to manage the Worklist Manager tasks (described in Using the Default Worklist Manager Console).