JBoss.orgCommunity Documentation

Chapter 19. Authoring Rule Assets

19.1. Creating a package
19.1.1. Empty package
19.1.2. Copy, Rename and Delete Packages
19.2. Business rules with the guided editor
19.2.1. Parts of the Guided Rule Editor
19.2.2. The "WHEN" (left-hand side) of a Rule
19.2.3. The "THEN" (right-hand side) of a Rule
19.2.4. Optional attributes
19.2.5. Pattern/Action toolbar
19.2.6. User driven drop down lists
19.2.7. Augmenting with DSL sentences
19.2.8. A more complex example:
19.3. Templates of assets/rules
19.3.1. Creating a rule template
19.3.2. Define the template
19.3.3. Defining the template data
19.3.4. Generated DRL
19.4. Guided decision tables (web based)
19.4.1. Types of decision table
19.4.2. Main components\concepts
19.4.3. Defining a web based decision table
19.4.4. Rule definition
19.4.5. Audit Log
19.4.6. Real Time Validation and Verification
19.5. Guided Decision Trees
19.5.1. The initial editor layout
19.5.2. First steps
19.5.3. Editing Data Object nodes
19.5.4. Editing Field Constraint nodes
19.5.5. Editing Action nodes
19.5.6. Managing the tree
19.6. Spreadsheet decision tables
19.7. Scorecards
19.7.1. (a) Setup Parameters
19.7.2. (b) Characteristics
19.8. Test Scenario
19.8.1. Knowledge Session Selector
19.8.2. Given Section
19.8.3. Expect Section
19.8.4. Global Section
19.8.5. New Input Section
19.9. Functions
19.10. DSL editor
19.11. Data enumerations (drop down list configurations)
19.11.1. Advanced enumeration concepts
19.12. Technical rules (DRL)

Configuring packages is generally something that is done once, and by someone with some experience with rules/models. Generally speaking, very few people will need to configure packages, and once they are setup, they can be copied over and over if needed. Package configuration is most definitely a technical task that requires the appropriate expertise.

All assets live in "packages" in Drools Workbench - a package is like a folder (it also serves as a "namespace"). A home folder for rule assets to live in. Rules in particular need to know what the fact model is, what the namespace is etc.

So while rules (and assets in general) can appear in any number of categories, they only live in one package. If you think of Drools Workbench as a file system, then each package is a folder, and the assets live in that folder - as one big happy list of files.

To create an empty package select "Package" from the "New item" menu.


As already mentioned on Project Explorer section, users can copy, rename or delete a package directly from Project Explorer.

As you can see in the following screenshots, those operations behave very similar to counter part actions in most workbench editors.




Guided Rules are authored with a UI to control and prompt user input based on knowledge of the object model.

This can also be augmented with DSL sentences.

B : This shows a pattern which is declaring that the rule is looking for a "LoanApplication" fact (the fields are listed below, in this case none). Another pattern, "Applicant", is listed below "LoanApplication". Fields "creditRating" and "applicationDate" are listed. Clicking on the fact name ("LoanApplication") will pop-up a list of options to add to the fact declaration:-

C : The "minus" icon ("[-]") indicates you can remove something. In this case it would remove the whole "LoanApplication" fact declaration. Depending upon the placement of the icon different components of the rule declaration can be removed, for example a Fact Pattern, Field Constraint, other Conditional Element ("exists", "not exists", "from" etc) or an Action.

D : The "plus" icon ("+") allows you to add more patterns to the condition or the action part of the rule, or more attributes. In all cases, a popup option box is provided. For the "WHEN" part of the rule, you can choose from a list of Conditional Elements to add:

If you just put a fact (like is shown above) then all the patterns are combined together so they are all true ("and").

E : This shows the constraint for the "creditRating" field. Looking from left to right you find:-

F : This shows the constraint for the "applicationDate" field. Looking from left to right you find:

H : This shows an "action" of the rule, the Right Hand Side of a rule consists in a list of actions. In this case, we are updating the "explanation" field of the "LoanApplication" fact. There are quite a few other types of actions you can use:-


In the above example, you can see how to use a mixture of Conditional Elements, literal values, and formulas. The rule has 4 "top level" Patterns and 1 Action. The "top level" Patterns are:

  1. A Fact Pattern on Person. This Pattern contains two field constraints: one for birthDate field and the other one is a formula. Note that the value of the birthDate restriction is selected from a calendar. Another thing to note is that you can make calculations and use nested fields in the formula restriction (i.e. car.brand). Finally, we are setting a variable name ($p) to the Person Fact Type. You can then use this variable in other Patterns.

    Note

    The generated DRL from this Pattern will be:

    $p : Person( birthDate < "19-Dec-1982" , eval( car.brand == "Ford" && salary > (2500 * 4.1) ))
  2. A From Pattern. This condition will create a match for every Address whose street name is "Elm St." from the Person's list of addresses. The left side of the from is a regular Fact Pattern and the right side is an Expression Builder that let us inspect variable's fields.

    Note

    The generated DRL from this Pattern will be: Address( street == "Elm St." ) from $p.addresses

  3. A "Not Exist" Conditional Element. This condition will match when its content doesn't create a match. In this case, its content is a regular Fact Pattern (on Person). In this Fact Pattern you can see how variables ($p) could be used inside a formula value.

    Note

    The generated DRL from this Pattern will be: not Person( salary == ( $p.salary * 2 ) )

  4. A "From Accumulate" Conditional Element. This is maybe one of the most complex Patterns you can use. It consist in a Left Pattern (It must be a Fact Pattern. In this case is a Number Pattern. The Number is named $totalAddresses), a Source Pattern (Which could be a Fact Pattern, From, Collect or Accumulate conditional elements. In this case is an Address Pattern Restriction with a field restriction in its zip field) and a Formula Section where you can use any built-in or custom Accumulate Function (in this example a count() function is used). Basically, this Conditional Element will count the addresses having a zip code of 43240 from the Person's list of addresses.

    Note

    The generated DRL from this Pattern will be: $totalAddresses : Number() from accumulate ($a : Address( zipCode == " 43240") from $p.addresses, count($a))

The guided rule editor is great when you need to define a single rule, however if you need to define multiple rules following the same structure but with different values in field constraints or action sections a "Rule Template" is a valuable asset. Rule templates allow the user to define a rule structure with place-holders for values that are to be interpolated from a table of data. Literal values, formulae and expressions can also continue to be used.

Rule Templates can often be used as an alternative for Decision Tables in Drools Workbench.

When you have completed the definition of your rule template you need to enter the data that will be used to interpolate the "Template Key" place-holders. Drools Workbench provides the facility to enter data in a flexible grid within the guided editor screen. The data entry section is located on the Data tab within the editor.

The rule template data grid is very flexible; with different pop-up editors for the underlying fields' data-types. Columns can be resized and sorted; and cells can be merged and grouped to facilitate rapid data entry.

One row of data interpolates the "Template Key" place-holders for a single rule; thus one row becomes one rule.


The guided decision table feature allows decision tables to be edited in place on the web. This works similar to the guided editor by introspecting what facts and fields are available to guide the creation of a decision table. Rule attributes, meta-data, conditions and actions can be defined in a tabular format thus facilitating rapid entry of large sets of related rules. Web-based decision table rules are compiled into DRL like all other rule assets.

The guided decision table is split into two main sections:-


When a new empty decision table has been created you need to define columns for Facts, their constraints and corresponding actions.

Expand the "Decision table" element and you will see three further sections for "Conditions", "Actions" and "Options". Expanding either the "Conditions" or "Actions" sections reveals the "New column" icon. This can be used to add new column definitions to the corresponding section. Existing columns can be removed by clicking the "-" icon beside each column name, or edited by clicking the "pencil" icon also beside each column name. The "Options" section functions slightly differently however the principle is the same: clicking the "Add Attribute/Metadata" icon allows columns for table attributes to be defined (such as "salience", "no-loop" etc) or metadata added.


A Wizard can also be used to assist with defining the decision table columns.

The wizard can be chosen when first electing to create a new rule. The wizard provides a number of pages to define the table:-

Decision tables are validated after each cell change. If any issues are found the results will be shown in the column on the right side of the table. Validation and verification covers the following issues:

The Workbench supports authoring of simple Decision Trees.

Multiple rules can be stored in a spreadsheet. Each row in the spreadsheet is a rule, and each column is either a condition, an action, or an option. The Drools Expert section of this document discusses spreadsheet decision tables in more detail.


To use a spreadsheet, you upload an XLS file. To create a new decision table: launch the new "Decision Table (Spreadsheet)" wizard, you will get an option to upload one.

A scorecard is a graphical representation of a formula used to calculate an overall score. A scorecard can be used to predict the likelihood or probability of a certain outcome. Drools now supports additive scorecards. An additive scorecard calculates an overall score by adding all partial scores assigned to individual rule conditions.

Additionally, Drools Scorecards will allows for reason codes to be set, which help in identifying the specific rules (buckets) that have contributed to the overall score. Drools Scorecards will be based on the PMML 4.1 Standard.

The New Item menu now allows for creation of scorecard assets.


The above image shows a scorecard with one characteristic. Each scorecard consists of two sections (a) Setup Parameters (b) Characteristic Section

The setup section consits of parameters that define the overall behaviour of this scorecard.

  1. Facts: This dropdown shows a list of facts that are visible for this asset.

  2. Resultant Score Field: Shows a list of fields from the selected fact. Only fields of type 'double' are shown. If this dropdown is empty double check your fact model. The final calculated score will be stored in this field.

  3. Initial Score: Numeric Text Field to capture the initial score. The generated rules will initialize the 'Resultant Score Field' with this score and then is added to the overall score whenever partial scores are summed up.

  4. Use Reason Codes: Boolean indicator to compute reason codes along with the final score. Selecting Yes/No in this field will enable/disable the 'Resultant Reason Codes Field', 'Reason Code Algorithm' and the 'Baseline Score' field.

  5. Resultant Reason Codes Field: Shows a list of fields from the selected fact. Only fields of type 'java.util.List' are shown. This collection will hold the reason codes selected by this scorecard.

  6. Reason Code Algorithm: May be "none", "pointsAbove" or "pointsBelow", describing how reason codes shall be ranked, relative to the baseline score of each Characteristic, or as set at the top-level scorecard.

  7. Baseline Score: A single value to use as the baseline comparison score for all characteristics, when determining reason code ranking. Alternatively, unique baseline scores may be set for each individual Characteristic as shown below. This value is required only when UseReasonCodes is "true" and baselineScore is not given for each Characteristic.

On Clicking the 'New Characteristic' button, a new empty characteristic editor is added to the scorecard. Defines the point allocation strategy for each scorecard characteristic (numeric or categorical). Each scorecard characteristic is assigned a single partial score which is used to compute the overall score. The overall score is simply the sum of all partial scores. Partial scores are assumed to be continuous values of type "double".

On Clicking the 'New Attribute' button, a new empty attribute editor. In scorecard models, all the elements defining the Attributes for a particular Characteristic must all reference a single field.


  1. Operator: The condition upon which the mapping between input attribute and partial score takes place. The operator dropdown will show different values depending on the datatype of the selected Field.

    1. DataType Strings: "=", "in".

    2. DataType Integers: "=", ">", "<", ">=", "<=", ">..<", ">=..<", ">=..<=", ">..<=".

    3. DataType Boolean: "true", "false".

    Refer to the next sub-section (values) for more details.

  2. Value: Basis the operator selected the value specified can either be a single value or a set of values separated by comma (","). The value field is disabled for operator type boolean.

    Table 19.1. Operators / Values
    Data Type Operator Value Remarks
    String = Single Value will look for an exact match
    String in Comma Separated Values (a,b,c,...) The operator 'in' indicates an evaluation to TRUE if the field value is contained in the comma separated list of values
    Boolean is true N/A Value Field is uneditable (readonly)
    Boolean is false N/A Value Field is uneditable (readonly)
    Numeric = Single Value Equals Operator
    Numeric > Single Value Greater Than Operator
    Numeric < Single Value Less Than Operator
    Numeric >= Single Value Greater than or equal To
    Numeric <= Single Value Less than or equal To
    Numeric >..< Comma Separated Values (a,b) (Greater than Value 'a') and (less than value 'b')
    Numeric >=..< Comma Separated Values (a,b) (Greater than or equal to Value 'a') and (less than value 'b')
    Numeric >=..<= Comma Separated Values (a,b) (Greater than or equal to Value 'a') and (less than or equal to value 'b')
    Numeric >..<= Comma Separated Values (a,b) (Greater than Value 'a') and (less than or equal to value 'b')
  3. Partial Score: Defines the score points awarded to the Attribute.

  4. Reason Code: Defines the attribute's reason code. If the reasonCode attribute is used in this level, it takes precedence over the ReasonCode associated with the Characteristic element.

  5. Actions: Delete this attribute. Prompts the user for confirmation.

Note

If Use Reason Codes is "true", then Baseline Score must be defined at the Scorecard level or for each Characteristic, and Reason Code must be provided for each Characteristic or for each of its input Attributes. If Use Reason Codes is "false", then BaselineScore and ReasonCode are not required.

Test Scenarios are used to validate that rules and knowledge base work as expected. When the knowledge base evolves, Test Scenarios guard against regression.


Given section lists the facts needed for the behaviour. Expect section lists the expected changes and actions done by the behaviour. Given facts are passed for the Test Scenario before execution. During the rule execution, changes in the knowledge base are recorded. After the execution ends the recorded actions, existing facts in the knowledge base and knowledge base output is compared against the expectations.


Functions are another asset type. They are NOT rules, and should only be used when necessary. The function editor is a textual editor. Functions


The DSL editor allows DSL Sentences to be authored. The reader should take time to explore DSL features in the Drools Expert documentation; as the syntax in Drools Workbench's DSL Editor is identical. The normal syntax is extended to provide "hints" to control how the DSL variable is rendered and validated within the user-interface.

The following "hints" are supported:-


Data enumerations are an optional asset type that technical folk can configure to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to.

The contents of an enum config are a mapping of Fact.field to a list of values to be used in a drop down. The strings are either a value to be shown in a drop down, or a mapping from the code value (what ends up used in the rule) and a display value.


If you wish to use a mapping between value used in the rule and the value shown in the UI you need to separate the code value and display value with an equals sign. For example:

'Person.gender' : ['M=Male','F=Female']

In this example F will be used in the rules but Female shown in the UI.

Drop down lists can also depend on other field values.

Lets imagine a simple fact model, we have a class called Vehicle, which has 2 fields: engineType and fuelType. We want to have a choice for the engineType of "Petrol" or "Diesel". Now, obviously the choice type for fuel must be dependent on the engine type (so for Petrol we have ULP and PULP, and for Diesel we have BIO and NORMAL). We can express this dependency in an enumeration as:


This shows how it is possible to make the choices dependent on other field values. Note that once you pick the engineType, the choice list for the fuelType will be determined.

There are a few other advanced things you can do with data enumerations.

Technical (DRL) rules are stored as text - they can be managed in Drools Workbench. A DRL can either be a whole chunk of rules, or an individual rule. If it's an individual rule, no package statement or imports are required (in fact, you can skip the "rule" statement altogether, just use "when" and "then" to mark the condition and action sections respectively). Normally you would use the IDE to edit raw DRL files, since it has all the advanced tooling and content assistance and debugging. However, there are times when a rule may have to deal with something fairly technical in a package in Drools Workbench. In any typical package of rules, you generally have a need for some "technical rules" - you can mix and match all the rule types together of course.