Getting started with Drools Flow

Today I will present my latest discovery called JBoss Drools and Drools Flow in particular. I am completely new to the drools framework and because I couldn’t find myself a quick and simple intro to the framework I will post it myself. Presented example is completely useless from the business perspective and it doesn’t describe any real world scenario.

According to the Drools Flow website itself:

Drools Flow provides workflow or (business) process capabilities to the Drools platform. A business process or workflow describes the order in which a series of steps need to be executed, using a flow chart. This makes it much easier to describe a complex composition of various tasks. Processes are especially useful in describing state-based, long-running processes. Drools Flow allows end users to specify, execute and monitor (a part of) their business logic using these processes. The Drools Flow process framework is easily embeddable into any Java application (as a simple Java component) or can run standalone in a server environment.

First of all you need to prepare your development environment. You will need the following:

• Eclipse IDE
• Drools Binaries v.5.1
• Drools Eclipse 3.5 Workbench

For the purpose of this tutorial that’s enough, you can try to download full Drools stack using the installer (including JBoss AS, Eclipse IDE, Birt reporting, Guvnor etc) but I didn’t have any luck with this installer and I guess you will be better off once you do install everything by hand as you learn.

Unpack drools binaries somewhere on your machine and Drools Eclipse workbench into eclipse folder. Restart your IDE and you should be able to create new Drools projects by now.

Select File -> New Project from the Eclipse file menu:

Provide descriptive name for your project:

Un-click all the proposed examples which eclipse plugin wants to generate for you, you can do that later if you want to learn more on drools.

Select Drools runtime, if you have no runtime configured, click ‘Configure Workspace settings’ and point to the directory where you have downloaded your binaries.

After you click finish, you should have a basic Drools project structure created for you:

Let’s create our application entry point with the main method we can execute to test our flow.

You should end up with a simple java class and single main method:

Now lets create our Flow file for the Drools Flow engine, select New -> Other on the project node and under the Drools folder select ‘Flow File’:

Select the name for your flow file:

The last step when creating your flow file is to select the runtime compatibility with the drools engine:

Once your flow file is created make sure its under src/main/rules while in the package explorer window, this will ensure that we can find it easily on our class-path while executing our test application.
Make sure you are in the ‘Drools Perspective’, open the rules file (*.rf) and drop the following onto the designer window:
Assuming you have a start event already placed in your flow (green cirle)

1. 1 Gateway [diverge]
2. 3 Logs (found under ‘service tasks’)
3. 1 Gateway [converge]
4. 1 End event

Once you do that, place them on the screen similary to this screenshot below and connect all together using ‘Sequence Flow’ arrow found at the top of the flow toolbox.

When you have your diagram ready, click on the whitespace anywhere on the diagram designer and under the properties tab provide the ID attribute, for this example we use ‘com.softwarepassion.droolsflowexample’:

Now on the designer select the first Gateway (diverge) and under properties tab set its type to ‘OR’:

For the second Gateway provide the type ‘XOR’, this ensures that we have to get the flow only from one of the nodes to proceed, selecting ‘AND’ for the second gateway would require two branches to be executed but we want to execute just one, either top or bottom log.

Once you select OR for the first gateway you can set constraints describing what exactly has to happen to go to the top branch or the bottom branch.

Click ‘…’ on the Constraints row (inside properties tab):

Select ‘Edit’ button for the top branch (‘To node Log Top’), change its type to ‘java’, dialect to ‘java’ and type in:

Similarly, for the other branch set the condition to return false:

Hardcoding ‘true’ and ‘false’ values is just for now, we will learn later on, how to insert some object into the flow and read its state inside a flow task.

Just for debugging purposes provide descriptive messages to our Log events, you can do that either from the Properties tab or by double clicking the node on the diagram itself.
Because we are using Log events all of them have the name ‘Log’.

Now lets do some wiring. Create a simple handler for our work items, ‘executeWorkItem’ method will be called every time the ‘Log’ task is executed within our workflow.

Wiring it all together, we end up with the following code in our main class:

Click on the class and select ‘Run as..’ -> ‘Java Application’, this will should print something similar to the following messages:

Source for the flow file at this stage of the tutorial is listed below:

If all is fine and working we can continue to the next part of our tutorial showing you how to add data to our workflow which can be read/modified by the workflow tasks.
For this example we will create a very simple POJO which we will pass from one task to the other and based on the properties contained within that POJO we will direct our flow to one of the two branches created earlier in the tutorial.

As you can see this is really simple java class :). Now let’s create an instance of it and add it to the workflow parameters, inside our class with the main method add the following:

Setting the ‘msg’ field to ‘TOP’ will cause to execute our top branch and ‘BOTTOM’ our bottom branch respectively.

For all this to work we need to add a variable to our workflow and change our constraints in the first gateway.

Click somwhere on the workflow to get the properties, select the ‘variables’ row and add a single variable called ‘st’:

Note that we have added our object using the key with the same name as the variable we are defining above. Once our variable is ready to be used in the workflow we can reference it in the Constraints dialogs of our diverging gateway:

Top constraint:

Bottom constraint:

Now you can test the application, changing the property of our injected object will cause going into one of the branches.

I hope it helps anyone trying to get started with the drools flow.

Enjoy!