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
Process
Decision Requirements Diagrams (DRD)
       High-Level DRD
       Bureau Strategy Decision DRD
       Routing Decision DRD
      
DMN Diagramming Tools
Decision Implementations
       Process Implemented as Decision
      Bureau Strategy Decision Service
          Bureau Strategy Decision
          Bureau Call Type Decision Table
          Determine Bureau Strategy
          Eligibility Decision
                 Application Risk Score
                 Pre-Bureau Risk Category
                 Eligibility Decision Table
     Routing Decision Service
          Routing Decision
          Application Risk Score
          Post-Bureau Risk Category
          Determine Routing
 
Affordability Decision
     Credit Contingency Factor
     Required Monthly Installment
     Disposable Income
     Determine Affordability
Other Sub-Decisions
     Decline Application
     Accept Application
     Manager Review
Glossary
Information Items and Test Data
     Applicant
     Requested Product
     Bureau Data
     Test Cases
     Business Objects
     Explain Internal Logic
Executing Decision Model
     Execution Results
     Execution Reports
Project "DecisionLoanOrigination"
Conclusion
 


OMG Decision Model and Notation (DMN)

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.

Figure 1. A simple process for loan originations modeled in BPMN 2.0

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.
Note that two decision points (calls to decision services "Bureau Strategy" and "Application Routing") are represented in BPMN 2.0 as business rule tasks. We will explain how to model and execute these decision services with OpenRules-based implementation of the DMN.

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:

 

Figure 2. The high-level decision requirements diagram (DRD)
It contains only two major sub-decisions that corresponds to two decision points "Bureau Strategy" and "Routing". The new DMN 1.1 also shows separate (but overlapping) DRDs for these decision points.

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:
 

 

Figure 4. DRD for the Routing Decision
As we can see, these two decisions share sub-decisions "Application Risk Score" and "Affordability". The "Application Risk Score" is the same for both services. However, the "Affordability Decision" is based on the decision variable "Risk Category" that is defined differently for each decision service:
  • 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.
In this document we rely on the DRDs created directly in Excel - see Process.xls and click on links inside it to open other related xls-files.

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:

This table uses directly a DMN FEEL expression.

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"):

   Here we invoke the external Java method using the standard Java snippet starting with "::=".

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:

         Decline Application

 

 

 

         Accept Application

 

 

 

        Manager Review 

 

 

 

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:

 

These variables get their values during the decision model execution.

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. 

Top