Open Your Business Rules!
Rules-based
Operational Decision Services
Decision Model and Notation (DMN): Chapter 11 Example
OpenRules-based implementation of the DMN 1.1 Example "Loan Origination Example"
Table Of Contents
Introduction
The Decision Model and Notation (DMN) standard is being developed by Object Management Group (OMG). The primary goal of DMN is to provide a common notation that is readily understandable by all business users, from the business analysts needing to create initial decision requirements and then more detailed decision models, to the technical developers responsible for automating the decisions in processes, and finally, to the business people who will manage and monitor those decisions. DMN creates a standardized bridge for the gap between the business decision design and decision implementation. The requirement for a common notation implies defining and standardizing semantics for decision models.
OpenRules BRDMS fits the DMN requirements quite well from its very beginning. Just two weeks after the very first DMN Specification version 1.0 was published in September-2013, OpenRules published this document that described the first executable implementation of the DMN example "Loan Origination" using the standard OpenRules features available at that time. We called this decision model "DMNPrimer" as it explains the core DMN principles and notations to business users and makes the DMN more specific and tangible. Our implementation of the DMNPrimer was included in the standard OpenRules installation and made available for free downloads. It is still can be found here.
The latest version 1.1 of the DMN Specification was published on June-2016 and is available from here.
OpenRules steadily increases compliance with the current DMN requirements. The newest OpenRules release 6.4.0 supports major DMN FEEL expressions and the DMN interchange format. Below we describes the latest implementation that can be found in the standard OpenRules installation in the project "DecisionLoanOrigination".A reader has several choices to look at the actual implementation of the "DecisionLoanOrigination" while reading this document:
- You may download repository.zip, unzip it to you disk, and simply open the Excel file repository/Process.xls, analyze high-level diagrams, and and follow its hyperlinks to look at the related decisions and decision tables.
- You may download OpenRules® and analyze and execute the project "DecisionLoanOrigination" from the workspace "openrules.dmn". This project is self-sufficient - to execute it double click on run.bat. You may make changes in the decisions, decision tables, test data, then execute the decision model and immediately analyze the results.
Process
The DMN example in chapter 11 starts with a description of the loan origination process model in the terms of BPMN 2.0 standard - see the Figure 1 below. The process handles applications for a loan, obtaining data from a credit bureau only if required for the case, and deciding whether the application should be accepted, declined, or referred for human review.
The process includes the following components:
- The Collect application data task collects data describing the Requested product and the Applicant (e.g. through an on-line application form)
- The Bureau Strategy task calls a decision service which returns two decisions: Strategy and Bureau call type. A gateway uses the value of Strategy to route the case to Decline application, Collect bureau data or Application routing
- The Collect bureau data task collects data from a credit bureau according to the Bureau call type decision, then the case is passed to Application routing
- The Application routing task calls a decision service which returns a single decision: Routing. A gateway uses the value of Routing to route the case to Accept application, Review application or Decline application
- The Review application task allows a credit officer to review the case and decide whether it should be accepted or declined. A gateway uses the credit officer’s decision to route the case to Accept application or Decline application
- The Accept application task informs the applicant that their application is accepted and initiates the product
- The Decline application task informs the applicant that their application is declined.
Decision Requirements Diagrams
High-Level Decision Requirements Diagram (DRD)
The DMN specification shows the entire decision requirements diagram for this model at the very complex and hardly invisible Figure 70 at the page 147:
To make it simpler and more understandable, we created a high-level DRD shown at the following Figure 2:
DRD for Bureau Strategy Decision
Here is the Specification's DRD for the Bureau Strategy decision point:
Our DRD drawn in Excel for the same sub-decision "Bureau Strategy Decision" but with more precise and consistent naming convention is presented on the Figure 3:
Figure 3. DRD for the Bureau Strategy Decision
DRD for Routing Decision
Here the Specification's DRD for the Routing decision point:
The Figure 4 below shows our Excel-based DRD of the same Routing sub-decision:
- by the decision table "Pre-Bureau Risk Category" for the "Bureau Strategy Decision"
- by the decision table "Post-Bureau Risk Category" for the "Routing Decision".
Diagramming Tools
The DMN decision requirements diagrams can be created with any diagramming tool starting with MS Visio and MS Excel. However, there are several tools that have been specifically created to graphically represent decisions (DecisionFirst) or just naturally match the DMN notation:- Decision First Modeler: see how decision diagrams (including an initial DMN submission) can created using an integrated DecisionFirst and OpenRules approach in this webinar recording.
- MS Excel: as you can see in this document and easily adjust using the attached Excel-files. All Excel diagram nodes include hyperlinks that allow you to open the proper Excel files that contain their implementations. Thus, the DRDs also serve natural directory services for the decision model navigation.
- Similarly you may use MS Visio
- Other third party DMN diagramming tools such as Trisotech.
Decision Implementations
Process Implemented as Decision
In the OpenRules implementation we represent this process using the equivalent Excel table:
This decision is a special type of a decision table called "Decision" identified by the keyword "Decision" at the left top corner. This table sequentially executes all (!) rows in the top-down order. The results of already executed rows (process tasks) are taken into consideration during validation of the conditions of the consecutive rows. For example, the task "BureauStrategyDecision" will set a value of the variable "Bureau Strategy", so the next rows will be able to analyze this value to decide to decline or continue to work on the decision.
P.S. While DMN does not define decision tables of the type "Decision" our real-world development practice proves its convenience, intuitiveness, and practicality. In particular, together with the explicitly defined "Glossary" it replaces the need for the quite complex "boxed invocation mechanism" offered by the current DMN.Below we show OpenRules decisions and decision tables that implement the above decision services using basic Excel tables.
Bureau Strategy Decision Service
Bureau Strategy Decision
Our BureauStrategyDecision is implemented as the table of the type "Decision" that simply executes 3 sub-decisions one after another:
Bureau Call Type Decision Table
The Specification defines decision logic that determines Bureau Call Type using the following two tables:
Boxed invocation table
Decision table
We use only one decision table:
This is OpenRules standard single-hit table that corresponds to the DMN decision table with hit policy "U" (Unique). Both decision tables look very similar. However, there are some important differences with the DMN Specifications:
- we don't use the unnecessary boxed invocation
- we don't insist on the strict use of the same name for the decision and the output variable "Bureau Call Type" (even the Specification as you can see contain a mistyping above)
- we don't rely on the italic representation of constants like HIGH,MEDIUM. Of course, a user may chose to use italics but it carries no semantic meaning
- we do not need a column with unused rule numbers
- All our decision tables have the second row with indicators that specify what kind of columns are used, e.g. "Condition", "Action", etc. Our column of the type "Condition" has two sub-columns: one for an operator and the second - for a value ( or a FEEL expression). We believe it is important to explicitly specify that the first rule is satisfied when the value of variable "Risk Category" is one of High or MEDIUM (instead of relying on the assumed interpretation of commas as the operator "is one of" - it could lead to confusions in more complex FEEL expressions).
Determine Bureau Strategy Decision Table
The Specification defines the following decision table to Determine Bureau Strategy:
Our decision table again looks very similar:
We don't need the column "U" with rule numbers but we use a similar cell merge for ELIGIBLE. While we use empty cells when conditions are not relevant, we may use "-" as well. In this case to stay closer to DMN we might use the first column of the type "If" to avoid the sub-column that now contains all operators "Is". However, what is user decides to make changes and use another operator?
Eligibility Decision
Our EligibilityDecision is implemented as the table of the type "Decision" that simply executes 4 sub-decisions one after another:
Below we describe these decisions.
Application Risk Store
The Specification defines decision logic that determines Application Risk Score using the following two tables :
Boxed invocation table
Decision table
This is a DMN example of a multi-hit decision table with a hit policy "C+" that means "Collect and sum".
We will use an equivalent representation using only one OpenRules decision table of the type "DecisionTableMultiHit".
The fact that every satisfied rule inside this table may add (accumulate) some values to the variable "Application Risk Score" is expressed by operators "+=" in the last last column. This is a column of the type "Conclusion" that consists of two sub-columns: one for an operator, and one for a value. It is a much more generic and intuitive approach to compare with the format proposed in the current DMN example. For instance, if under certain conditions we want to subtract or to multiply a value we may use operator "-=" or "*=". Also when there are more than one output variables in the same table, we would not limit by an assumption that "C+" applies to the first variable only.
Please note this table use conditions of the type "If" without operator sub-columns.
Pre-Bureau Risk Category Decision Table
The Specification defines decision logic that determines Pre-Bureau Risk Category using the following two tables :
Boxed invocation table
Decision table
Instead of these two tables, we use an equivalent representation with only one OpenRules decision table:
This table defines the variable "Risk category" needed for "DetermineEligibility" and for the "DetermineCreditContingenceFactor" decision tables below.
Eligibility Decision Table
The Specification defines decision logic that Determines Eligibility using the following two tables:
Boxed invocation table
Decision table
Instead of these two table, we use an equivalent representation with only one standard OpenRules decision table without any priorities specified above by "P":
Affordability Decision
DMN Specification suggests to represent the Affordability calculation logic the following two tables:
Boxed invocation table
Boxed function table
Probably DMN specification selected such complicated representation to demonstrate the use of boxed invocation and boxed functions.
In our representation of the same logic we use only one table "AffordabilityDecision" that simply executes 4 sub-decisions one after another:
Credit Contingency Factor
Our credit contingency factor decision table looks very similar to the one proposed by the Specification (we just use an explicit operator "Is One Of"):
Required Monthly Installment
The calculation logic of the Required Monthly Installment is the most complex one in this DMN example. DMN Specification offers the following tables:
Boxed invocation
Boxed context
The second table is a so-called "boxed context" that calls an external function PMT(Rate,Term,Amount) without explaining how it can be actually done (probably leaving these details to DMN implementers like OpenRules).
Our implementation of the same logic invokes two steps:
1) Calculating an intermediate variable called "PMT" as follows that hopefully are much more understandable:
2) Using the variable PMT to Determine Required Monthly Installment:
We may offer OpenRules users two alternative ways to calculate PMT:
1) Using an external Java function defined as a static method "calc(double rate, int term, double amount)" of Java class PMT (see PMT.java in the project "DecisionLoanOrigination"):
2) implementing this method directly in Excel:
Disposable Income
We use a regular decision table with a FEEL expression to Determine Disposable Income:
Determine Affordability
Routing Decision Service
Routing Decision
This decision implementation uses the same decision tables "DetermineAppilcationRiskScore" and "AffordabilityDecision" as the above decision "BureauStrategy".
Post-Bureau Risk Category
Before executing the "AffordabilityDecision", the Routing Decision executes the decision table "DeterminePostBureauRiskCategory" to re-define the decision variable "Risk Category":
Determine Routing
The "RoutingDecision" also uses its own decision table "DetermineRouting":
Other Sub-Decisions
These sub-decisions are used by the above decisions and are represented in the following tables:
Glossary
Variables that were used across all decisions and decision tables are collected in the following glossary:
The first column contains the names of variables exactly as they were used in decision tables. The second column introduces the business concepts (DMN's information items) to which the variables belong. The third column defined the technical names for all variables to connect them with actual business objects. The fourth (optional) column describes the domains of variables.
Information Items and Test Data
We use OpenRules tables of the types "Datatype" and "Data" to describes DMN information items and 3 test cases. They all are located in the file "Data.xls".
Applicant
The last method "CollectApplicationData" emulates the proper task from the process.
Requested Product
Bureau Data
The last method "CollectBureauData" emulates the proper task from the process.
Internal Variables
The variables that were used inside the decision model but do not belong to its input or output called "internal variables". The proper concept in the Glossary is called "Internal Variables". To support them during the execution of the decision model we created the following tables in Excel:
Test Cases
The following table describes 3 test cases. Each test case contains references to objects to be used for a particular test (see column of the type ActionUseObject) and expected results (see columns of the type ActionExpect):
Business Objects
The following table connects information items (business concepts) described in the glossary with test data described in the above data tables.
Explaining Internal Logic
The following method is used to explain the execution results by displaying the internal variables and their calculated values: 
Executing Decision Model
Now we may execute the decision model using the standard OpenRules engine. Below we show the results of the execution of the first test case:
Execution Results
|
RUN TEST: Test 1 Decision Run has been initialized Decision EmulateLoanOriginationProcess: Collect Application Data CollectApplicationData Applicant(id=0) { SSN=157-82-5344 age=51 employmentStatus=EMPLOYED existingCustomer=true fullName=Peter N. Johnson maritalStatus=M monthlyExpenses=3,000 monthlyIncome=10,000 monthlyRepayments=2,500 } RequestedProduct(id=0) { amount=100000 loanOriginationResult=? productType=STANDARD LOAN rate=0.08 term=36 } Decision EmulateLoanOriginationProcess: Make Bureau Strategy Decision Decision BureauStrategyDecision: Make Eligibility Decision Decision EligibilityDecision: Determine Application Risk Score Conclusion: Application Risk Score += 48 Conclusion: Application Risk Score += 45 Conclusion: Application Risk Score += 45 Decision EligibilityDecision: Determine Pre-Bureau Risk Category Risk Category := VERY LOW Decision EligibilityDecision: Make Affordability Decision Decision AffordabilityDecision: Determine Credit Contingency Factor Credit Contingency Factor: 0.8 Decision AffordabilityDecision: Calculate PMT PMT: ( Amount * (Rate/12) ) / ( 1 - (1 +Rate/12) ** ( -((Term/12)*12) ) ) Decision AffordabilityDecision: Determine Required Monthly Installment Required Monthly Installment: PMT + 20.00 Decision AffordabilityDecision: Determine Disposable Income Disposable Income: Monthly Income - (Monthly Repayments + Monthly Expenses) Decision AffordabilityDecision: Determine Affordability Affordability := true Decision EligibilityDecision: Determine Eligibility Eligibility := ELIGIBLE Decision BureauStrategyDecision: Determine Bureau Call Type Bureau Call Type: NONE Decision BureauStrategyDecision: Determine Bureau Strategy Bureau Strategy: THROUGH Decision EmulateLoanOriginationProcess: Make Routing Decision Decision RoutingDecision: Determine Application Risk Score Conclusion: Application Risk Score += 48 Conclusion: Application Risk Score += 45 Conclusion: Application Risk Score += 45 Decision RoutingDecision: Determine Post-Bureau Risk Category Risk Category := VERY LOW Decision RoutingDecision: Make Affordability Decision Decision AffordabilityDecision: Determine Credit Contingency Factor Credit Contingency Factor: 0.8 Decision AffordabilityDecision: Calculate PMT PMT: ( Amount * (Rate/12) ) / ( 1 - (1 +Rate/12) ** ( -((Term/12)*12) ) ) Decision AffordabilityDecision: Determine Required Monthly Installment Required Monthly Installment: PMT + 20.00 Decision AffordabilityDecision: Determine Disposable Income Disposable Income: Monthly Income - (Monthly Repayments + Monthly Expenses) Decision AffordabilityDecision: Determine Affordability Affordability := true Decision RoutingDecision: Determine Routing Routing := ACCEPT Decision EmulateLoanOriginationProcess: Accept Application Conclusion: Loan Origination Result Is ACCEPT Decision EmulateLoanOriginationProcess: Explain Internal Logic ExplainInternalLogic InternalVariables(id=0) { affordability=true applicationRiskScore=276 bureauCallType=NONE bureauStrategy=THROUGH creditContingencyFactor=0.8 disposableIncome=4,500 eligibility=ELIGIBLE pmt=3,133.64 requiredMonthlyInstallment=3,153.64 review=? riskCategory=VERY LOW routing=ACCEPT } Decision has been finalized Validating results for the test <Test 1> Test 1 was successful ... |
Execution Reports
OpenRules produces execution reports in the HTML format. The reports show only actually executed rules. You may click on the following links to navigate through the automatically generated reports for the first test case described above:
Project "DecisionLoanOrigination"
We organized the rules repository for this project using Excel files distributed within the subdirectory "repository" as shown below:
This repository organization is described in the following OpenRules table Environment (see file Process.xls) and can be easily modified:
Conclusion
The described implementation demonstrates how the latest release of OpenRules® BDMS can implement DMN 1.1 decision models with the use of DMN FEEL language. It shows that DMN Decision Models allow business analysts to stay in charge over the business logic without necessity to learn a rule language while supporting an integration with IT systems. As the DMN standard progresses, OpenRules adds new features to accommodate the latest DMN requirements in a business user-friendly fashion.
