Chapter 7. Writing rules

The asset editor provides access to information about assets and gives users the ability to edit assets.

The editor contains Editor, Overview, Source, and Data Objects tabs.

Figure 7.1. The Guided Decision Table - Editor Tab

Figure 7.2. The Guided Decision Table - Overview Tab

Figure 7.3. The Guided Decision Table - Source Tab

Figure 7.4. The Guided Decision Table - Data Objects Tab

Business rules are edited in the Guided Rule Editor. The Guided Rule Editor prompts users for input based on the object model of the rule being edited.

Assets used in a rule that belong to a different package must be imported into the rule. Assets in the same package are imported by default. Define your imports in the Data Objects tab.

Example 7.1. The Guided Rule Editor

The Guided Rule Editor consists of the When and Then parts. Under the Then part is a (show options…​) link that enables you to set additional rule attributes, such as ruleflow-group, salience, and similar. For more information about the Guided Rule Editor, see Section 7.5.1, “The Guided Rule Template”.

Figure 7.5. Rule Attributes

You can narrow down the facts available during rule creation and modification by using a file called package-names-white-list. Use this file to narrow down a group of facts that are loaded and are visible. This helps to speed up the loading of these facts while creating new rules.

When you create a new project in the root directory, an empty package-names-white-list file is automatically created along with the pom.xml and project.imports project files. For existing projects, create the package-names-white-list file manually. In Business Central, you can view the file through the repository view of a project in the Project Explorer.

By default (when the file is empty), all the facts within the project itself are visible while those from the project’s dependencies are restricted.

Rules for Defining Packages

The package-names-white-list file is a text file that accepts single package names on each line. Packages can contain wildcards, for example:

You can include specific packages from a dependency by adding appropriate entries into the package-names-white-list file. You can also include or remove all packages from specific dependencies. For more information, see Adding Dependencies.

A rule consists of multiple parts:

With the Guided Rule Editor, it is possible to add more conditions to the when (conditional) part of the rule and more actions to the then (action) part of the rule. For instance, if an applicant under the age of 21 had a guarantor for a loan application, the bank may decide to approve the loan application.

Each rule has a salience value which is an integer value that defaults to zero. The salience value represents the priority of the rule with higher salience values representing higher priority. Salience values can be positive or negative.

With the Guided Rule Editor, it is possible to add more conditions to the when (conditional) part of the rule and more actions to the then (action) part of the rule. For instance, if a loan applicant under the age of 21 had a guarantor for a loan application, the bank may decide to approve the loan application.

To add the guarantor to the condition, first add the guarantor field to the application fact type (Data Object in Business Central) of the mortgage model. For further information about how to add a field to a fact type, see Section 6.1, “Data Modeler”.

With the guarantor field now added to the applicant fact type, you can modify the rule to include a guarantor as a condition.

Technical (DRL) rules are stored as text and can be managed in the Red Hat JBoss BRMS user interface. A DRL file can contain one or more rules. The condition and the action of the rule are the when and then parts of the rule respectively.

Red Hat JBoss Developer Studio provides tools for creating, editing, and debugging DRL files, and it should be used for these purposes. However, DRL rules can be managed within the Red Hat JBoss BRMS user interface. The DRL editor provides syntax highlighting for Java, DRL, and XML.

rule "approval"
  salience 100 // This can short-circuit any processing.
  when
    a : Approve()
    p : Policy()
  then
    p.setApproved(true);
    System.out.println("APPROVED:" + a.getReason());
end

Rules can be stored in spreadsheet decision tables. Each row in the spreadsheet is a rule, and each column is either a condition, an action, or an option. The Red Hat JBoss BPM Suite Development Guide provides details for using decision tables.

To convert the uploaded spreadsheet to a Guided Decision table:

We are here considering a simple example for an online shopping site which lists out the shipping charges for the ordered items. The site agrees for a FREE shipping with the following conditions:

The listed shipping rates are as follows:

The above conditions can be presented in a spreadsheet as:

The (web based) Guided Decision Table feature 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.

To create a new decision table, click on New Item Guided Decision Table. Enter the name of the table and select whether you want the extended entry or limited entry table (Section 7.4.2, “Types of decision tables”). Optionally select to use the Guided Decision Table Wizard.

Click OK when done. If you didn’t select the wizard, you will be presented with the editor for Guided Decision Tables. If you selected the wizard, you will be presented with the first screen of the wizard.

The wizard helps you define your imports, facts, patterns and columns, but not the rows. Rows are added in the Guided Decision Table Editor, which is what you are presented with at the end of the wizard (or directly if you didn’t use the wizard).

When you build your own application comprising guided decision tables, ensure that you have the necessary dependencies added to your class path. For more information about dependencies for guided decision tables, see the Dependency Management for Guided Decision Tables, Scorecards, and Rule Templates section of the Red Hat JBoss BPM Suite Development Guide.

There are broadly two types of decision tables, both of which are supported:

For a description of column constraint types, see Section 7.4.5.3, “Condition Columns”.

You can set a default value, but normally if there is no value in the cell, that constraint will not apply.

Figure 7.6. Column Configuration

To add a column within the Guided Decision Table Editor, click on the icon.

The following column type selection dialog appears:

Figure 7.7. Advanced Column Options

By default, the column type dialog shows the following types:

Clicking on "Include advanced options" adds the following options:

Rules are created in the main body of the decision table using the columns that have already been defined.

Rows of rules can be added or deleted by clicking the plus or minus symbols respectively.

Figure 7.22. Rule Definition

The icon in the top left of the decision table toggles cell merging on and off. When cells are merged, those in the same column with identical values are merged into a single cell. This simplifies changing the value of multiple cells that shared the same original value. When cells are merged, they also gain an icon in the top-left of the cell that allows rows spanning the merged cell to be grouped.

Figure 7.23. Cell Merging

Cells that have been merged can be further collapsed into a single row. Clicking the [+\-] icon in the top left of a merged cell collapses the corresponding rows into a single entry. Cells in other columns spanning the collapsed rows that have identical values are shown unchanged. Cells in other columns spanning the collapsed rows that have different values are highlighted and the first value displayed.

Figure 7.24. Cell Grouping

When the value of a grouped cell is altered, all cells that have been collapsed also have their values updated.

Condition columns defined with literal values that use either the equality == or inequality != operators can take advantage of a special decision table cell value of otherwise. This special value allows a rule to be defined that matches on all values not explicitly defined in all other rules defined in the table. This is best illustrated with an example:

when
  Cheese( name not in ("Cheddar", "Edam", "Brie") )
  ...
then
  ...
end

when
  Cheese( name in ("Cheddar", "Edam", "Brie") )
  ...
then
  ...
end

To use the otherwise keyword:

Rule Templates enable you to define a rule structure. They provide a place-holder for values and data, and they populate templates to generate many rules. From the user’s perspective, Guided Rule Templates are parametrized guided rules that contain a data table which provides parameter values. The templates enable more flexible decision tables and can enhance the flexibility of rules in existing databases. For information about managing dependencies of Rule Templates, see the Dependency Management for Guided Decision Tables, Scorecards, and Rule Templates section of the Red Hat JBoss BPM Suite Development Guide.

Figure 7.25. Guided Template Editor

The Guided Rule Template Editor in Business Central allows you to set rule templates where the data is kept separate from the rules.

Make sure you have already set a data model for your project as described in Section 6.4, “Creating a Data Object”.

The THEN section of a rule holds the actions to be executed when it matches the WHEN section.

Data tables provide variables for guided rule templates that you define. This generates a number of rules, based on your settings. Data tables can be altered within the Guided Template Editor by clicking on the Data tab. Consider the following example:

A company offers phone service, internet service, and TV service. The monthly payment differs based on the active services that a customer has. The template for our example looks as follows:

To populate the rules:

Data enumerations are an optional type of asset that can be configured to provide drop-down lists for the Guided Decision Table Editor. Double-click on a cell to view the enumeration drop-down list if the cell condition is based the same fact and field as the enumeration.

They are stored and edited just like any other asset and only apply to the package they are created in.

The contents of an enumeration configuration are the mapping of a fact.field to a list of values. These values are used to populate the drop-down menu. The list can either be literal or use a utility class (which must be added to the classpath) to load the strings. The strings contain either a value to be shown in the drop-down menu or a mapping from the code value (which is what is used in the rule) and a display value, e.g., M=Mini.

Example 7.2. An Example Enumeration Configuration

'Board.type' : [ 'Short', 'Long', 'M=Mini', 'Boogie']
'Person.age' : [ '20', '25', '30', '35' ]

This can be also be configured in Business Central as follows:

Drop-down lists are dependent on field values. With enumerations it is possible to define multiple options based on other field values.

A fact model for insurance policies could have a class called Insurance, consisting of the fields, policyType and coverage. The choices for policyType could be Home or Car. The type of insurance policy will determine the type of coverage that will be available. A home insurance policy could include property or liability. A car insurance policy could include collision or fullCoverage.

The field value policyType determines which options will be presented for coverage, and it is expressed as follows:

 'Insurance.policyType' : ['Home', 'Car']
 'Insurance.coverage[policyType=Home]' : ['property', 'liability']
 'Insurance.coverage[policyType=Car]' : ['collision', 'fullCoverage']

A list of Strings from an external source can be retrieved and used in an enumeration menu. This is achieved by adding code to the classpath that returns a java.util.List (of strings). Instead of specifying a list of values in the user interface, the code can return the list of strings. (As normal, you can use the "=" sign inside the strings if you want to use a different display value to the rule value.) For example, you could use the following:

'Person.age' : ['20','25', '30', '35']

To:

'Person.age' : (new com.yourco.DataHelper()).getListOfAges()

This assumes you have a class called DataHelper which has a method getListOfAges() which returns a list of strings. The data enumerations are loaded the first time the guided editor is used in a session. To check the enumeration has loaded, go to the package configuration screen. You can "save and validate" the package; this will check it and provide feedback about any errors.

Scorecard is a Risk Management tool which is a graphical representation of a formula used to calculate an overall score. It is mostly used by financial institutions or banks to calculate the risk they can take to sell a product in market. Thus it can predict the likelihood or probability of a certain outcome. Red Hat JBoss BRMS now supports additive scorecards that calculates an overall score by adding all partial scores assigned to individual rule conditions.

Additionally, Drools Scorecards 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.

In general, a scorecard can be created more or less in this way:

To explain it in detail, following is an example:

Figure 7.34. Scorecard Example

When you build your own application comprising guided scorecards, ensure that you have the necessary dependencies added to your classpath. For more information about dependencies for guided decision tables, see the Dependency Management for Guided Decision Tables, Scorecards, and Rule Templates section of the Red Hat JBoss BPM Suite Development Guide.

Business Central provides verification and validation feature to help ensure that a guided decision table is complete and error free. The feature looks for gaps in the logic of a guided decision table and validates the relationship between different cells. Most of the issues that the Business Central verification and validation feature reports are gaps in the author’s logic. The verification and validation feature does not prevent you from saving your work if you choose to ignore the verification and validation notifications.

When you edit a guided decision table, the verification and validation feature notifies you if you do something wrong. For example, if you forget to set an action for a row of the guided decision table or if you have a duplicate row, a new panel, Analysis, will open in the Business Central with a notification about the issue. The Analysis panel presents a list of issues found in the guided decision table, each item also pointing out the affected guided decision table rows. If you select an item in the list of issues, you will see a more in-depth description of the problem.

The validation and verification feature helps you resolve issues around:

The verification and validation feature of Business Central reports different issue levels in the Analysis panel while you are updating a guided decision table.

The decision table verification and validation feature of Business Central is enabled by default. You can disable it by setting the org.kie.verification.disable-dtable-realtime-verification system property value to true.

For example, if you are using JBoss EAP as your application server, navigate to $EAP_HOME directory and run the following command:

./standalone.sh -Dorg.kie.verification.disable-dtable-realtime-verification=true

Alternatively, set this property in the standalone.xml file:

<property name="org.kie.verification.disable-dtable-realtime-verification" value="true"/>