Debugging Business Rules

Motivation

If you are an author of a real-world business decision model, you may have troubles to understand why certain rules inside your model were not executed while others did. When complex logical errors occur, even the best explanation reports and execution traces could be difficult to follow.  What you need is a Rule Debugger!

To deal with complex logical errors, software developers usually rely on very powerful Code Debuggers. However, business users don’t deal with executable code. What they need is a powerful while easy to use Rule Debugger to debug their business logic in business terms without becoming de-facto programmers.

OpenRules Rule Debugger is the tool that helps business users to figure out what is going wrong with their business logic as fast as possible. It allows them to step through the execution of their business decision models, pause the execution at any rule or ruleset, and inspect the state of the decision model. And it provides all this functionality with ease-of-use! Watch a quick tour.

Rule Debugger is a component of OpenRules Explorer, an integrated graphical decision management environment. To show the debugger in action, we’ll use the relatively complex business decision model “Loan Origination” from the DMN Section 11.  and its OpenRules implementation described here. The decision model “Loan Origination” in available as one of many downloadable samples.

Running and Debugging Sample Decision Model

To open OpenRules Explorer, double-click on “explore.bat” inside the standard sample “LoanOrigination”. You will see this decision model diagram (click on it to enlarge):

To test this model, click on the icon “Run” in the title bar.
The Test View will be opened from which you can Run or Debug this model against different test cases – it is shown on the top of this page. The left panel contains all available test cases under the title “Run Tests“. These tests are defined in an Excel table that can be opened when you click on the test’s name. It also contains “Execution Path” that shows an automatically defined sequence of different rulesets specified inside this decision model.

Click on the “Run” button, a green circle near the test case “Test 1”:
The Explorer will execute the decision model against this test and will show this “Execution Console“:

You can scroll through this (not very friendly) view that shows all executed rules and the execution results. A much better view will be shown when you click of the “Execution Report” at the top right corner:

This report shows all executed rulesets (decision tables) and rules along with values of related decision variables in the moment when these rules were executed. Our customers love this report and use it for explanations.

However, when it’s too big, it’s still difficult to analyze it. Instead, you may switch to the Rule Debugger.

Stepping Through Execution Flow

Click on the “Debug” button (a green bug next to the Test 1).
The Explorer will start a debug session by showing this Debug View:

This view consists of the grey panel with executed rules and the right panel that shows Variables/Value or Breakpoints. Initially, the debugger will stop before (!) executing the very first rule of the first ruleset – in this case it is the Rule #1 of the decision table “ApplicationRiskScore” shown in red. The rule itself is shown in green – it means it is about to be executed. This decision table is a scorecard and the first rule unconditionally sets the initial score to 0.

The panel on the right shows all decision variables with their current values. If you select “Related Variables Only” you will see only those decision variables that participate in the current rules. To make the debug panel larger, you can temporarily collapse the left panel with test cases and make the protocol panel at the bottom of the screen smaller (by choosing the smallest rectangle).

Now you may click on button “Next Rule” to see the following view:

The first rule was executed and the Debugger stopped at the next Rule #2:

Contrary to the first (green) rule, this rule is shown is grey meaning it would not be executed. Why? Let’s look at the current values on the related decision variables on the right:

The condition of this rule checks if the decision variable ‘Age’ is within [18..21] but its actual value is 51.

The values of all decision variables are shown BEFORE evaluation and possible execution of the currently selected rule!

To check a description of any decision variable in Glossary click on the arrow next to the variable’s name.

Let’s continue to click on the “Next Rule” until you reach the next ruleset:

As you can see, only 4 “green” rules out of 11 were actually executed (#1, #6, #8, and #11). This rule is “grey” and will not be executed. Why?

Inspecting the State of Decision Model

The box on the right shows the current values of decision variables before evaluation of the Rule#1 of the next ruleset “PreBureauRiskCategory”:

This rule will not be executed (it’s shown in grey) because the calculated Application Risk Score is 138 while the rule’s condition expects it to be less than 100.

Now let’s click on the button “Next Ruleset”:

The Debugger will stop before calculating PMT. If you don’t want to see anymore the rules that haven’t been executed, you can select and the debug view will become more compact (without showing grey rules). Let’s click on “Next Rule” again:

Note that we’ve reached the 4th ruleset “RequiredMonthlyInstallment” and it is about to execute the Rule #2. Also note that a previous rule inside this decision table was skipped – we do not see it because we checked “Executed Rule Only”.

If now we click on the button “GoTo End/Breakpoint” the decision model will be executed to the end showing the following results:

The row “Completed” is being selected and we can see the final values of ALL decision variables.

Using Breakpoints

Let’s say you want to stop before calculating “Disposable Income” and “Bureau Strategy”. You can click on the left of the corresponding rules to set breakpoints (shown as red circles):

Now if you click on the button “Restart“, the Debugger will stop at the first break point and will show the current values of the related variables on the right:

So, now we have a complete picture of what’s going on at this particular execution point.  You can click on “GoTo End/Breakpoint” and the debugger will execute all rules until it reaches the next breakpoint. You may set as many breakpoints as you wish. The second click on a breakpoint removes it. If you push the radio-button “Breakpoints” in the top right corner, you will see all breakpoints (if any):

From here you can enable/disable/delete some or all of them.

Every rule in the Debugger’s panel shows its original location inside the proper Excel file, e.g. in this rule

(B8:F8)  identifies the Excel cell in the file “Rules.xls”. If you click on the highlighted (B8:F8), this Excel file will be opened with the cursor pointing to the cell B8:F8.

The best way to appreciate the power and the ease-of-use of this Rule Debugger is to install OpenRules Decision Manager and try to debug standard or your own decision models.

OpenRules Debugger satisfies all requirements for the modern state-of-art easy-to-use debugging tool oriented to business users. It provides practical help to creators of business decision models when they need to understand the behavior of their models and to find bugs in the most complex logical situations.