Guided Rules with the Guvnor

August 24, 2009

Importing the fact model into Guvnor

Switc hing back to the Guvnor, we’re now going to create a package to hold our
brand new model that we created in the previous steps.


	If you want, you can clear out the samples of Hello World from the last
	chapter. Remember that you can't actually delete the items, but you can
	archive them. Either way, none of the older samples will get in the way of
	what we're doing in this chapter.

From the lefthand side menu, select the Packages tab.
Go to Package | Create New Package (org.sample) | Create Package.
From just below the Packages tab, highlight Create New and then select the
New model (jar) of fact classes.
Fill out the dialog box that is displayed, as follows. The Name (SalesModel)
and Package (org.sample) should be the same as the ones we created in
Eclipse. Click on the OK button.

Back in the main Guvnor screen, check that everything is in place.

In addition to the upload button (that we’re going to use in a minute), this screen
also has a Download button (to retrieve JAR files that you may have uploaded
earlier). It also has the usual Save, Copy, Archive, and Delete options.

To upload our fact model JAR into Guvnor , follow the steps shown below:

Click on the Browse button, and then navigate to and select the JAR file that
we exported earlier. Click on OK.
After returning to the screen above, click on the upload button (actually, the
‘up’ arrow icon to the right of upload).
If everything goes well, you will get the message File was uploaded
successfully. Click on OK to return to the SalesModel/Package tab.
Save the updated package (by clicking on the Save Changes button). As with
other saves/check-ins you’ll be asked for an optional checkin comment.
We can check whether Guvnor has successfully picked up the new package
information by expanding the org.package that was created.

You can see from this example that in the Configuration section, under Imported
types, our class (org.sample.Sales) is listed. This means that Guvnor has not only
uploaded our class file, but will also allow us to write rules that use this class. Now
that Guvnor knows the format of the information that we want to pass in and out,
we can start writing rules using Guvnor.

Guided rules using the fact model

Back at the chocolate factory, we’ve decided to implement a customer loyalty
scheme. When any customer has sales of greater than 100 dollars, we want to give
them a fl at rate discount of 10 dollars. To put it in a slightly more ‘rules-like’ format,
our new business rule will look something like this:


	when
		w e have a sale greater than 100
	then
		Give a discount (by adding a 'negative' sale)

Yes, as a business rule it’s slightly clunky, but it keeps things simple. In real life we’d
just update our sales object with the new balance after the discount (and keep a note
of what discount was given).

Of course, we’re going to write this rule using the Guvnor. Or rather, you’re going
to try to write the rule in Guvnor based on the last chapter’s tour of the guided
editor. I’ll show you the full step-by-step answer soon, but the end result will look
something similar to the following:

Some key notes and buttons to use in the Guvnor are:

You’re going to create a new rule using the guided editor in Guvnor.
Click the ‘+’ next to WHEN and THEN to add new conditions/consequences
(such as greater than 100 and Insert Sales -10).
The ‘green arrow’ icon allows you to refine these further.
Guvnor will pick up the sales model that we imported earlier and offer it as
choice to you on a menu.
If you make a mistake, the ‘-’ icon allows you to delete a line.

The step-by-step answer

Before we write a rule we must make sure that we have a category assigned to it.
We can use any existing category or we can create a new one (under the Admin tab,
expand Categories | New Category). For this step-by-step example, we’ve created
a new SalesCategory. But categories are just descriptive tags, so it will work with
pretty much any name.

After you’ve chosen a category, follow these steps:

Create a new business rule by selecting menu option rules | create new |
New business rule (guided editor).
Enter the following values in the screen that is displayed. We will give the
new rule a name (SalesDiscount—although anything descriptive is OK). We
will assign a category (the SalesCategory that we created earlier). Then we
will pick the package (org.sample) from the drop-down list. After entering a
description (optional) we need to click on OK.

We’ll then be taken to the guided business rule editor that we saw earlier on
our quick tour. In the main section, click on the ‘+’ sign next to the WHEN
label, to add a condition (that is, to restrict the circumstances under which
our rule will fire).

The Add a condition to the rule dialog will be displayed. We’re going to
choose a fact type of Sales. (Actually, this will be the only fact type in the
drop-down list.) This means that our rule will fire only when a sales fact is
present. To put it another way, our rule only applies to the rules spreadsheet.

After choosing this, we’ll automatically be taken back to the guided
rule-editing screen.
Back on the main screen, we’ll see that Sales has been added as a condition.
Currently, this rule will fire for all sales, so we want to restrict it to only those
sales of more than 100 dollars.

Because we want to elaborate on the WHEN condition, we need to click
on the green ‘arrow’ icon immediately next to the Sales condition. We’ll be
shown the Modify constraints for Sales dialog box, shown as follows:

The first dropdown field contains a list of all of the fields (columns) available
for the Sales object. We’ll choose sales (that is, the dollar value or amount )
from the drop-down list.
Back in the gu ided editor, another line will have been added. The default
value is please choose. Change this to greater than or equal to, as shown in
the following diagram.

Now we need a value to compare this field to (as part of the filter). Click on
the pencil icon to set this. In the Field value dialog box that is displayed, click
on Literal value. Literal values are numbers we can enter directly.

Back in the guid ed editor, a new text box will have appeared. Enter 100
(the value we want to use in our rule) in this text box.

That’s it—the WHEN part of the rule is done and should look like the objective
picture that we saw at the very start of this sample). Now would be a good time to
save the rule (and enter a comment if you see fit).

The THEN part is somewhat easier, in that there are fewer steps to create it.

Click on the green plus sign next to the Then section. The Add a new action
dialog box will be displayed:

We choose to insert a new fact (in the first dropdown). Sales will be the only
option in this menu. Inserting a new fact is like adding a new row to the
Excel Spreadsheet (that is another line of information into the memory).


	Logically insert a new fact does the same thing as inserting a new fact,
	but automatically removes the row/fact/object as soon as the condition
	stops being true. For this example, this wouldn't change anything as the
	Sales won't stop being more than 100, but it would make a difference to
	more dynamic rules (for example, if another rule reduced the price, and
	we wanted to withdraw the discount in this circumstance).

Back in the guide d editor, the text Insert Sales will now be displayed. Click
on the green arrow next to this to begin setting to values for our new sales
object (this is similar to saying: once we insert a new line into the Excel
Spreadsheet, here are the values that I want to use in the newly created cells).

First we’re going to add a name field. This will appear in the main guided
editor. Click on the pencil next to the name field to add a value. Enter the
value Discount (so that the purpose of the new line/new fact is clear).
Now that we’ve created our first field, we can repeat the process for the
second one—Sales. Add a field (click the green icon next to Insert sales) and
choose sales. Back in the guided editor, click on the pencil next to the new
line, and enter a value of -10.
By now, the screen will look like the screenshot back at the start of this
section. Now is a good time to save your rule. Validate the rule by clicking on
the Validate button. All being well, you will see a dialog box similar to the
following example. To close the dialog box, click on the ‘x’ in the upper-right
corner of the dialog box.


	Remember that validation is only a check to catch the most obvious
	errors. It's still possible to get warning messages when we run and test
	our rule in the next section.

To confirm that the guided editor has written the rule for us, click on the View
source button. The meaning (give a discount for sales of 100) is pretty much as we’d
expect. We’ve converted the rule into plain English.


	Rule "SalesDiscount"
	//name of the rule
	// use the slightly more readable mvel
	when
		we can find a fact / line of more than 100 sales
	then
		create a new line / fact
		set the name to "discount"
		set the sales to –10
		add the line back to the model
	end
	// end of rule

You’ll notice that this text is read-only. In the next chapter, we’ll show you how to
create your rule directly in the text (technical rule) editor. For the moment we’ve a
more pressing problem—how do we try this rule out?

Running this scenario

The solution is similar to the one we used for running the Hello World example in
the previous chapter. The rule we want to exercise is a little bit more complicated, so
the scenario that we need to construct is also a little more complicated.

To start, expand the Package tab and then create a new test scenario. Give it a name
(for example TestSales), and select the same package for our rule (org.sample). You
will be presented (again) with the blank scenario test screen. The scenario that we’re
going to create is similar to the following screenshot:

The steps for building this screen are similar to those we used before. We use the ‘+’
sign to insert a new GIVEN/EXPECT, the small green arrow to refine the scenario,
and the ‘–’ sign to remove.

Click on the plus sign next to GIVEN and choose to insert a new sales fact
(under any name). Click on Add.
Click on the Add a field button that appears. In the dialog box, select the
name field.
Click on the green arrow next to sales to add another field (column in our
new row). In this case, use Sales and give it a value of 200 (that is, greater
than 100!).
Click on the green ‘+’ next to EXPECT. In the New Expectation dialog box
that is displayed, click on show list and then choose the Sales Discount rule.
Change the default (that we expect this rule to fire at least once) to
Expect Rules, to fire this many times, and then enter ’1′ in the new text box
that appears.
Save this test scenario using the button at the top of the screen.

All being well, if you now click the Run Scenario button, you will get a green
bar at the top of the screen saying Results 100%, along with some additional text:
Rule [SalesDiscount] was activated 1 times, which indicates that our rule is running
as expected.

What just happened?

The test scenario that we created was equivalent to passing in a spreadsheet with one
row (that is, one Sales Java object with sales of 200 and a name of Acme Corp). We’d
expect our sales discount rule to fire under these circumstances and we tell our test
scenario to look out for this. When we run the scenario, our rule behaves as expected
and fires, giving Acme Corp a discount of –10 Sales for their order.