JBoss.orgCommunity Documentation

Chapter 2. Getting Started

2.1. Installation
2.2. Creating Your First Process
2.3. Executing your first process

This section describes how to get started with Drools Flow. It will guide you to create and execute your first Drools Flow process.

The best way to get started is to use the Drools Eclipse Plugin for the Eclipse development environment. It allows users to create, execute and debug Drools processes and rules. To get started with the plugin, you first need an installation of Eclipse 3.4.x including the Eclipse Graphical Editing Framework (GEF). Eclipse can be downloaded from the following link (if you do not know which version of eclipse you need, simply choose the "Eclipse IDE for Java Developers", and this one already includes the GEF plugin as well):

http://www.eclipse.org/downloads/

Next you need to install the Drools Eclipse plugin. Download the Drools Eclipse IDE plugin from the link below. Unzip the downloaded file in your main eclipse folder (do not just copy the file there, extract it so that the feature and plugin jars end up in the features and plugin directory of eclipse) and (re)start Eclipse.

http://www.jboss.org/drools/downloads.html

To check that the installation was successful, try opening the Drools perspective: Click the "Open Perspective" button in the top right corner of your Eclipse window, select "Other..." and pick the Drools perspective. If you cannot find the Drools perspective as one of the possible perspectives, the installation probably was unsuccessful. Check whether you executed each of the required steps correctly: Do you have the right version of Eclipse (3.4.x)? Ensure that you have Eclipse GEF installed, by checking whether the org.eclipse.gef_3.4.*.jar exists in the plugins directory in your Eclipse root folder. Make sure that you have extracted the Drools Eclipse plugin correctly, by checking whether the org.drools.eclipse_*.jar exists in the plugins directory in your Eclipse root folder. If you cannot find the problem, try contacting us, either on irc or on the user mailing list. More information can be found on our homepage:

http://www.jboss.org/drools/

The Drools project wizard can be used to set up an executable project that contains the necessary files to get started easily with defining and executing processes. This wizard will set up a basic project structure, the classpath, a sample process and execution code to get you started. To create a new Drools project, simply left-click on the Drools action button (with the Drools head) in the Eclipse toolbar and select "New Drools Project". (Note that the Drools action button only shows up in the Drools perspective. To open the Drools perspective (if you haven't done so already), click the "Open Perspective" button in the top right corner of your Eclipse window, select "Other..." and pick the Drools perspective.) Alternatively, you could also select "File", then "New" followed by "Project ...", and in the Drools folder, select "Drools Project". This should open the following dialog:

Give your project a name and click "Next". In the following dialog you can select which elements are added to your project by default. Since we are creating a new process, deselect the first two checkboxes and select the last two. This will generate a sample process and a Java class to execute this process.

If you have not yet set up a Drools runtime, you should do this now. A Drools runtime is a collection of jars on your file system that represent one specific release of the Drools project jars. To create a runtime, you must either point the IDE to the release of your choice, or you can simply create a new runtime on your file system from the jars included in the Drools Eclipse plugin. Since we simply want to use the Drools version included in this plugin, we will do the latter. Note that you will only have to do this once; next time you create a Drools project, it will automatically use the default Drools runtime (unless you specify otherwise).

Unless you have already set up a Drools runtime, click the "Next" button. The following dialog, as displayed below, shows up, telling you that you have not yet defined a default Drools runtime and that you should configure the workspace settings first. Do this by clicking on the "Configure Workspace Settings ..." link.

The dialog that pops up shows the workspace settings for Drools runtimes. The first time you do this, the list of installed Drools runtimes is probably empty, as shown below. To create a new runtime on your file system, click the "Add..." button. This shows a dialog where you should give the new runtime a name (e.g. "Drools 5.0.0 runtime"), and a path to your Drools runtime on your file system. In this tutorial, we will simply create a new Drools 5 runtime from the jars embedded in the Drools Eclipse plugin. Click the "Create a new Drools 5 runtime ..." button and select the folder where you want this runtime to be stored and click the "OK" button. You will see the selected path showing up in the previous dialog. As we're all done here, click the "OK" button. You will see the newly created runtime shown in your list of Drools runtimes. Select this runtime as the new default runtime by clicking on the check box in front of your runtime name and click "OK". After successfully setting up your runtime, you can now finish the project creation wizard by clicking on the "Finish" button.

The end result should look like this and contains:

By double-clicking the ruleflow.rf file, the process will be opened in the RuleFlow editor. The RuleFlow editor contains a graphical representation of your process definition. It consists of nodes that are connected to each other. The editor shows the overall control flow, while the details of each of the elements can be viewed (and edited) in the Properties View at the bottom. The editor contains a palette at the left that can be used to drag-and-drop new nodes, and an outline view at the right.

This process is a simple sequence of three nodes. The Start node defines the start of the process. It is connected to an Action node (called "Hello" that simply prints out "Hello World" to the standard output. You can see this by clicking on the "Hello" node and checking the action property in the Properties View below. This node is then connected to an End node, signaling the end of the process.

While it is probably easier to edit processes using the graphical editor, users can also modify the underlying XML directly. The XML for our sample process is shown below (note that we did not include the graphical information here for simplicity). The process element contains parameters like the name and id of the process, and consists of three main subsections: a header (where information like variables, globals and imports can be defined), the nodes and the connections.

<?xml version="1.0" encoding="UTF-8"?>
<process xmlns="http://drools.org/drools-5.0/process"
         xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
         xs:schemaLocation="http://drools.org/drools-5.0/process drools-processes-5.0.xsd"
         type="RuleFlow"
         name="ruleflow"
         id="com.sample.ruleflow"
         package-name="com.sample" >

  <header>
  </header>

  <nodes>
    <start id="1" name="Start" x="16" y="16" />
    <actionNode id="2" name="Hello" x="128" y="16" >
      <action type="expression"
                 dialect="mvel">System.out.println("Hello World");</action>
    </actionNode>
    <end id="3" name="End" x="240" y="16" />
  </nodes>

  <connections>
    <connection from="1" to="2" />
    <connection from="2" to="3" />
  </connections>

</process>

To execute this process, right-click on RuleFlowTest.java and select "Run As..." and "Java Application". When the process in executed, the following output should appear in the Console window:

Hello World

If you look at the code of class RuleFlowTest (see below), you will see that executing a process requires a few steps:

package com.sample;

import org.drools.KnowledgeBase;
import org.drools.KnowledgeBaseFactory;
import org.drools.builder.KnowledgeBuilder;
import org.drools.builder.KnowledgeBuilderError;
import org.drools.builder.KnowledgeBuilderErrors;
import org.drools.builder.KnowledgeBuilderFactory;
import org.drools.builder.KnowledgeType;
import org.drools.io.ResourceFactory;
import org.drools.logger.KnowledgeRuntimeLogger;
import org.drools.logger.KnowledgeRuntimeLoggerFactory;
import org.drools.runtime.StatefulKnowledgeSession;

/**
 * This is a sample file to launch a process.
 */
public class RuleFlowTest {

  public static final void main(String[] args) {
    try {
      // load up the knowledge base
      KnowledgeBase kbase = readKnowledgeBase();
      StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
      KnowledgeRuntimeLogger logger =
        KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "test");
      // start a new process instance
      ksession.startProcess("com.sample.ruleflow");
      logger.close();
    } catch (Throwable t) {
      t.printStackTrace();
    }
  }

  private static KnowledgeBase readKnowledgeBase() throws Exception {
    KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
    kbuilder.add(ResourceFactory.newClassPathResource("ruleflow.rf"), KnowledgeType.DRF);
    KnowledgeBuilderErrors errors = kbuilder.getErrors();
    if (errors.size() > 0) {
      for (KnowledgeBuilderError error: errors) {
        System.err.println(error);
      }
      throw new IllegalArgumentException("Could not parse knowledge.");
    }
    KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
    kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
    return kbase;
  }

}

Congratulations, you have successfully executed your first process! Because we added a logger to the session, you can easily check what happened internally by looking at the audit log. Select the "Audit View" tab on the bottom right, next to the Console tab. Click on the "Open Log" button (the first one one the right of the view) and navigate to the newly created test.log file in your project folder. (If you are not sure where this project folder is located, right-click on the project folder and you will find the location in the "Resource" section). An image like the one below should be shown. It is a tree view of the events that occurred at runtime. Events that were executed as the direct result of another event are shown as the children of that event. This log shows that after starting the process, the Start node, the Action node and the End node were triggered, in that order, after which the process instance was completed.

You can now start experimenting and designing your own process by modifying our example. Note that you can validate your process by clicking on the "Check the ruleflow model" button, i.e., the green check box action in the upper toolbar that shows up if you are editing a process. Processes will also be validated upon save, and errors will be shown in the Error View.

Continue reading our documentation to learn about our more advanced features.