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.

Worklist Manager Service Engine Features

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

• Graphical Wizard and Editor: The WLM SE includes a wizard to automate the process of creating a task definition framework, and an editor where you can define all of the elements of the task definition.

• Worklist Manager Console: This web-based application provides complete task management functionality, including claiming, completing, and reassigning tasks.

• Searchable Tasks: The Worklist Manager Console provides comprehensive full-text and keyword search capabilities and also supports AND, OR, and NOT operations. It can also filter results by status, user, and group.

• Notifications: Tasks can be configured to send out email or other notifications when a task is escalated or changes status, or after a deadline or duration of time passes.

• Escalations: The WLM SE supports automatic task escalation if it is not completed by a deadline or within a specific period of time.

• Timeouts: The WLM SE allows you to define a timeout period or deadline after which the task returns an error to the BPEL process.

• XPath Support: Support for XPath syntax lets you add variables and expressions that dynamically derive task elements and properties from the input message.

• Security: Security for the web-based console is propagated through the Java EE Service Engine. The WLM SE supports both file realm and LDAP security.

• LDAP Support: The WLM SE supports using LDAP for authentication and user management, and provides an LDAP browser for you to easily assign tasks and notifications.

• Client API: The WLM SE includes a client API in the form of a static WSDL document to interact with the task management service. The API provides complete task handling functions.

• Persistence: Task information and status is preserved in the Worklist Manager database, so users can continue processing tasks following a system failure.

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.

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

• Task Definition Wizard

• Task Definition Editor

• About the Worklist Manager Console

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.

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. For information about supported database platforms and versions, see Java CAPS 6.3 Components and Supported External Systems in Planning for Oracle Java CAPS 6.3 Installation .

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:

• Source View: The Source tab displays the underlying code for the task definition. You can use the Source view to write the entire task definition, make refinements to an existing definition, or to review the underlying code created by the Task Definition Editor.

• Design View: The Design tab displays a task definition in graphical view on a series of tabbed pages that each display specific information about the task. The tabbed pages allow you to graphically assign tasks and define escalations, notifications, deadlines and durations, and variable updates.

• Mapper View: The Mapper tab provides a framework to define values for input and output variables. Currently the Mapper can only be used from the Actions tab. The Mapper provides a variety of XPath functions that you can use to manipulate the input and output data.

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

• The BPEL Project

• The Composite Application Project

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

• Task Definition Schema

• XPath Expressions in Task Definitions

• Automatic email Notifications

• Changing Variables

• Task Escalations and Timeouts

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:

• A title and priority for the tasks.

• The users and groups which the tasks are assigned.

• Keywords by which users can search on the Worklist Manager Console for tasks.

• Durations or deadlines by which a task must be completed before it is escalated to the specified users or groups.

• Durations or deadlines by which a task will time out if it is not completed.

• Email or other types of notifications that are sent out when certain events occurs, such as a task being created, completed, or escalated.

• Default values for task output fields (implemented as variable initializations).

• Variable updates that are made when a task status changes, such as inserting the timestamp in a date field when a task is completed.

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. For information about supported LDAP servers and their versions, see Java CAPS 6.3 Components and Supported External Systems in Planning for Oracle Java CAPS 6.3 Installation .

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).