test

Sun Worklist Manager Service Engine User's Guide

Customizing the Worklist Manager Console

You can customize the sample Worklist Manager Console to update the look and feel, and to extend the functionality. The following topics provide information about how the Worklist Manager Console was designed, the standards implements, and how you can customize it.

About the Worklist Manager Console

The following topic provide information about the technology behind the Worklist Manager Console:

Pages

The application itself consists of the following four pages:

Addressable Entities

Given the above pages list, you can define which items need to be directly addressable by the user (from the browser), these include:

For the tasks list (both unfiltered and filtered), it should also be possible to address a certain page with a specific page size.

Technologies

The web application is based on the following APIs, libraries, technologies, and standards.

Server

Client

Communication Protocol

The web application supports the following server-side environment:

The web application supports the following browsers and operating systems in the client-side environment.

Browsers

Operating Systems

Functionality and UI Semantics Specification

The following topics describe the pages of the web application, listing all the active UI elements and several passive elements, and describing their purpose and the result of the user actions.

Common page elements

All pages of the web application contain the following elements:

Page Header

The page header provides helper information for the user as well as some common controls. It includes the following blocks:

Page Footer

This control shows additional information about the current page and the web application as a whole. It includes the following elements:

Login Page Elements

The URL of this page is: context-root/login.jsp. In addition to the common page elements the Login page shows the Login form, which allows a user to authenticate in the system using a private username and password combination.

Tasks List Page Elements

The URL of the page is: context-root/index.jsp or just context-root/. In addition to the common page elements the Tasks List page shows the Tasks List Table, which is the main user interface element on the page. The table contains data about all the tasks that are currently available to the user. The tasks are displayed in pages, the display can be controlled by the pages navigator, the page size selector and the sort selector.

If no tasks were found the contents of the table are not shown, instead the user is presented with an appropriate information message. By default the tasks displayed in the table are those that allow any action from the user, which are those in one of the following states: ASSIGNED, ESCALATED, CLAIMED This can be refined using the Advanced search box. Each row in this table corresponds to a single task.

The table includes the following elements:

Tasks List Table

Page Navigator

This control helps you to navigate between the paged list of the available tasks. It is displayed twice, before the Tasks list table and after it. It is a composite control and contains the following elements:

Page Size Selector

This is a drop-down list. It allows you to define how many tasks should be shown on a single page. The available options are: 10, 20, 50 and 100. When the value of the selector changes, the page is reloaded and the user is presented with the updated list, this field's value on the reloaded page will contain the chosen value. This fact is reflected in the URL of the page in the size query string parameter. The system tries to keep you on the same page you were viewing before changing the size of the page. For example, if you were viewing page with the index 5, you will stay on this page unless there are not enough pages. In the latter case you is taken to the last page of the updated tasks list.

Sort Selector

This is a drop-down list. It allows you to define the sort order of the tasks list. The available options are ID, Title, Submitted on, Assigned to, Deadline, Priority, Claimed by, Status. The corresponding sort directions are ascending, ascending, descending, ascending, ascending, descending, ascending, ascending.

When the value of the selector changes the page is reloaded and the user is taken to the same page of the tasks list he was viewing before changing the sort order (that is, the index of the tasks list page stays the same.) This field's value on the reloaded page will contain the chosen value. The sort order is shown in the URL of the page in the order query string parameter.

Priorities Legend

This is a static block explaining the color values of the task priorities. Basically the priorities are split in three groups: blue (1-3), yellow (4-7) and red (8-10).

Search Box

This block contains one of the two possible sub-blocks: Basic search box and Advanced search box. By default the Basic search box is visible and the Advanced search box is hidden.

Basic Search Box

The basic search box allows you to perform a simple text-based search on the tasks list, and includes the following elements:

Advanced Search Box

This block allows you to define fine-grained search criteria, and includes the following elements:

Task Info Page Elements

The URL of the page is: context-root/task.jsp. In addition to the common page elements the Task Info page includes the following elements:

Task Info Box

This is a block of static text providing general information about the task being viewed. It includes the following elements:

Task Input Data Box

This block of user interface controls shows the information and the available actions for the current task and its input data. Since this is one of the major points for user-customization, we specify only the default controls here.

Task Output Data Box

This block of user interface controls shows the information and the available actions for the current task and its output data. Since this is one of the major points for user customization, only the default controls are specified here. This block is shown only if the task is in one of the following states: CLAIMED, COMPLETED, EXPIRED, ESCALATED, or FAILED.

Help Page Elements

The URL of the page is: <context-root>/help.jsp. The Help page is inherently very simple. In addition to the common page elements, it shows a block of static text describing the usage scenarios of the web application.

Customizing the Worklist Manager Console

The following topics list the possible customization points of the web application that a developer might use to customize the application. This primarily involves customizing the appearance of the application, localizing the application, correcting security settings, and, most importantly, providing custom forms for different types of tasks.

All paths referenced in the instructions are relative to the sources root of the web application project.

For a list of the functions included in the client API, see WLM Client WSDL API

Customizing the Appearance

All style-defining information for the application pages is contained in the CSS style sheets. You can modify these files customize the appearance of the web application.

The following conventions were used in authorizing the default web application:

Localizing

There is only one localizing bundle for the application, which is located at /src/java/com/sun/glassfishesb/wlm/console/Messages.properties. You can add your own localizations according the standard Java rules (appending the language and country elements to the bundle name) and you can alter the current labels to fit the terminology used in your organization.

Correcting security settings

The application uses container-managed security exclusively. All security bindings are located in /web/WEB-INF/web.xml and /web/WEB-INF/sun-web.xml files. In the web.xml file, it is in the security-constraint and the security-role elements. By default the application accepts users with the staff role. If you need more roles, add more security-role elements and list them within auth-constraint.

The authentication realm used is file, and you can add another realm by editing the realm-name element. For GlassFish, the security roles defined in web.xml need to be mapped to user groups, which is done in the sun-web.xml file in the security-role-mapping element.

Correcting the Task Input Data Display

In order to customize the display of the task input data field, you need to perform the following steps:

  1. Create the JSP file that will display the input data field and place it in the /web/WEB-INF/handlers/input/ directory.

  2. Edit the /web/WEB-INF/includes/input-handler.jsp file. The if-else statement needs to be updated to make sure the newly created JSP file is included if the current task (represented by the iha_task variable) has the desired type (the iha_task.getTaskDefId() method).

In the actual JSP file that will render the task input data field, the following context is available via request attributes. Following are the attribute names, their types, and their meaning:

The handler JSP file is expected to output the HTML code suitable for display in the web browser.

You can also consult these files to get a better understanding of the processing logic that needs to be defined:

Correcting the Task Output Data Display

To customize the display and, potentially, the behavior of the task output data field, you need to perform the following steps:

  1. Create the JSP file that will display the output data field and place it in the /web/WEB-INF/handlers/output/ directory.

  2. Edit the /web/WEB-INF/includes/output-handler.jsp file. You need to update the if-else statement to make sure the newly created JSP file is included if the current task (represented by the oha_task variable) has the desired type (the oha_task.getTaskDefId() method).

In the actual JSP file that renders the task output data field, the following context is available through request attributes. Following are the attribute names, their types, and their meaning:

The task output data handler is much more complex than the one for the input data. First it should be able to operate in two modes, and instructions on which mode to use are passed in with the corresponding request attribute. It should either render the output data in HTML, or parse the updated output data. There is no standard way to do this, as the customized handler prepares the input form itself and is the only entity that knows what the request parameter names are and how to use them. Second it should be able to store it into the request attribute. In the latter case the output data handler is expected to prepare the org.w3c.dom.Element object and place it in the com.sun.glassfishesb.wlm.console.task-output-data request attribute.

When in rendering mode, the output handler should watch out for two flags:

In rendering mode, the handler JSP file is expected to output the HTML code suitable for display in the web browser. You can also consult these files to get a better understanding of the logic that needs to be defined: