JBoss.orgCommunity Documentation

Chapter 15. Console

15.1. Installation
15.1.1. Installing Guvnor
15.1.2. Changing the persistence configuration of your runtime data
15.1.3. Changing the persistence configuration of your history data
15.1.4. Installing the reporting engine
15.1.5. User authentication
15.1.6. Configure memory settings
15.2. Adding process definitions in Guvnor
15.3. Running the process management console
15.3.1. Managing process instances
15.3.2. Human task lists
15.3.3. Reporting
15.4. Adding new process / task forms

Drools processes can be managed through a web console. This includes features like managing your process instances (starting/stopping/inspecting), inspecting your (human) task list and executing those tasks, and generating reports.

The Drools build system generates two wars for you that can be deployed in your application server and contains the necessary libraries, the actual application, etc. One jar contains the server application, the other one the client. Download gwt-console-server-drools-{version}.war and gwt-console-drools-{version}.war and deploy them to your application server, {AS_HOME}/server/{configuration}/deploy (so for example, we are using jboss-4.2.3.GA/server/default/deploy).

The easiest way to get started with the console is probably to use the installer. This will download, install and configure all the necessary components to get the console running, including Guvnor, a human task service, etc. Check out the chapter on the installer for more information. If you want to manually install the console, you can continue reading here.

You need to have an application server installed. This chapter assumes you are using the JBoss AS version 4.2.3.GA, but other versions or other application servers should be possible as well.

The reporting engine is based on the Eclipse BIRT engine. You need to install the Eclipse BIRT runtime engine in your application server to be able to use the reporting functionality. To do so, create a new directory called {AS_HOME}/server/{configuration}/data/birt. Download the Eclipse BIRT report engine version 2.3.2 (birt-runtime-2_3_2_2.zip), extract it and copy the ReportEngine directory to the newly created directory (the other directories are not needed).

Next, you need to copy your process instance reports to the newly created directory as well. Eclipse BIRT allows you to define your own reports based on existing data sources. The console expects two different reports:

We have created some example reports you could use and customize according to your own requirements. The example report templates can be found in the drools-bam module (src/test/resources). Note that these example reports are also using the H2 in memory database (in server mode). If you configured the persistence of the history data differently, you will have to update the data source of these reports accordingly. You also need to copy your database drivers to the reporting plugin. In our case, using H2, copy the h2-1.0.77.jar to {AS_HOME}/server/{configuration}/data/birt/ReportEngine/plugins/ org.eclipse.birt.report.data.oda.jdbc_2.3.2.r232_v20090212/drivers.

You are now ready to startup the application server. If you are using human tasks in your processes, you should also make sure you have the task service running (on 127.0.0.1:9123). Also make sure your database is up and running of course.

Drools Guvnor allows you to manage all your business knowledge in a (logically) centralized location. This includes all your process definitions, business rules, etc. The process management console automatically retrieves all the processes from the latest snapshot of the "defaultPackage" package on Guvnor. To find out how to get processes on the Guvnor repository (for example manually uploading them, or using the Eclipse Guvnor synchronization), check out the Guvnor documentation. After deploying Guvnor to your application server, navigate to the following URL to open up Guvnor (replace the host and/or port depending on how the application server is configured): http://localhost:8080/drools-guvnor

The following screenshot shows an example where the "defaultPackage" package contains one "Evaluation" process. After adding the necessary process definitions, make sure to build the package, so that the built package can be downloaded by the web console.

It is important that you make sure that (1) you add your processes to the package with the name "defaultPackage", otherwise your processes won't show up in the console, and (2) that your processes also define "defaultPackage" as the package of the process. Guvnor does not allow a process to be built if it is not put in the same package as it defines.

Now navigate to the following URL (replace the host and/or port depending on how the application server is configured): http://localhost:8080/gwt-console

A login screen should pop up, asking for your user name and password.

After filling these in, the process management workbench should be opened, as shown in the screenshot below. On the right you will see several tabs, related to process instance management, human task lists and reporting, as explained in the following sections.

The "Processes" section allows you to inspect the process definitions that are currently part of the installed knowledge base, start new process instances and manage running process instances (which includes inspecting their state and data).

Forms can be used to (1) start a new process or (2) complete a human task. We use freemarker templates to dynamically create forms. To create a form for a specific process definition, create a freemarker template with the name {processId}.ftl. The template itself should use HTML code to model the form. For example, the form to start the evaluation process shown above is defined in the com.sample.evaluation.ftl file:



<html>
<body>
<h2>Start Performance Evaluation</h2>
<hr>
<form action="complete" method="POST" enctype="multipart/form-data">
Please fill in your username: <input type="text" name="employee" /></BR>
<input type="submit" value="Complete">
</form>
</body>
</html>

Similarly, task forms for a specific type of human task (uniquely identified by its task name) can be linked to that human task by creating a freemarker template with the name {taskName}.ftl. The form has access to a "task" parameter that represents the current human task, so it allows you to dynamically adjust the task form based on the task input. The task parameter is a Task model object as defined in the drools-process-task module. This for example allows you to customize the task form based on the description or input data related to that task. For example, the evaluation form shown earlier uses the task parameter to access the description of the task and show that in the task form:



<html>
<body>
<h2>Employee evaluation</h2>
<hr>
${task.descriptions[0].text}<br/>
<br/>
Please fill in the following evaluation form: 
<form action="complete" method="POST" enctype="multipart/form-data">
Rate the overall performance: <select name="performance">
<option value="outstanding">Outstanding</option>
<option value="exceeding">Exceeding expectations</option>
<option value="acceptable">Acceptable</option>
<option value="below">Below average</option>
</select><br/>
<br/>
Check any that apply:<br/>
<input type="checkbox" name="initiative" value="initiative">Displaying initiative<br/>
<input type="checkbox" name="change" value="change">Thriving on change<br/>
<input type="checkbox" name="communication" value="communication">Good communication skills<br/>
<br/>
<input type="submit" value="Complete">
</form>
</body>
</html>

Data that is provided by the user when filling in the task form will be added as parameters when completing the task. For example, when completing the task above, the Map of outcome parameters will include result variables called "performance", "initiative", "change" and "communication". The result parameters can be accessed in the related process by mapping these parameters to process variables.

Forms should be included in the drools-gwt-form.jar in the server war.