Capture your decisions with DMN

Introduction

Business Rules Management Systems have been around since the early 2000 or more. Till last year, there was no standard to define them so users were forced to write rules in a proprietary language. This situation has leaded to many difficulties:

On boarding a new rule designer requires a specific training.
Sharing knowledge across the organization is quite complex and ambiguous.
Moving from a rule engine implementation to another is quite destructive, requiring a big effort in training and rule translation.

I also think that this has limited the spread of Business Rules approach in the IT Architecture, due to the lack of confidence in an “esoteric” technology that relies on not well known standards. Indirectly, many teachers avoided spending much time going in the details of a specific implementation, with the result of keeping the Business Rules Management in a kind of dark matter space.
Finally, a new era is raising for the Decision Management thanks to OMG group that defined a new standard notation to catch the decision logic: the Decision Model and Notation (DMN in short).
In reality, the DMN work started years ago and the version 1.0 of the specification was published in September 2015. Nonetheless, at the beginning the focus was mainly on the knowledge documentation, whereas the version 1.1 (June 2016) with some semantic fix made the language more easily digestible by a machine.
The version 7 of Red Hat JBoss BRMS is just around the corner and one of the more noteworthy feature is the DMN 1.1 execution engine (conformance level 3).
So, it’s time to get prepared to this exciting capability doing some experiments with the community project that reached in these days the version 7.1.

Decision Model and Notation concepts

The DMN has the following graphical representation, known as Decision Requirements Diagram (DRD):

The squared box represent the Decision: the act of determining an output given some inputs data. For example in the rule The discount is 10% for silver customers, “silver” is the input and the “10%” is the output.
The rounded corners box represent the Input Data.
The rectangle with the clipped corners is the Business Knowledge Model (BKM) that encapsulates business know-how in the form of business rules, analytic models, or other formalism. Basically, it can be considered a sort of function call. The designer can draw one or more BKM, splitting the decision logic in many parts (eventually nested): it’s a matter of style and usually it is recommended to emphasize the re-usability of a BKM or to associate different Knowledge Sources.
The arrows that link the Decision with a BKM or with an Input Data explicit a “requirement” relationship: in the picture the Decision requires an Input Data and Knowledge Business Model.
The Knowledge Sources have mainly a documentation purposes and define as the name suggests the source of the knowledge. Some examples from the specification:

Governance of decision-making by people (e.g., a manager)
Regulatory bodies (e.g., an ombudsman)
Documents (e.g., a policy booklet)
Bodies of legislation (e.g., a government statute)

The executable logic is defined by the FEEL expression language, which stands for Friendly Enough Expression Language, and has the following features:

Side-effect free
Simple data model with numbers, dates, strings, lists, and contexts
Simple syntax designed for a wide audience (a person able to write an Excel function)
Three-valued logic (true, false, null) based on SQL and PMML

FEEL language is used in a graphical frame called Boxed Expression.
There are many flavor of boxed expressions:

boxed FEEL expression
boxed function
boxed context
decision table
boxed invocation
boxed list
relation

The DMN editor

At the moment, the Drools project has not already developed a standard DMN editor, so you should look around at the available alternatives on internet. I did my experiments using the Trisotech DMN editor that is an excellent software.
They have a really complete Business Modeling Suite that is particularly suited for Business Analysts, in addition to the DMN editor they offer a BPMN editor, a CMMN editor and other useful tools to help in the discovery and analysis phase.

DMN in practice

Let’s design a simple decision logic:

A person is eligible for a driver license when the his / her age is at least 18 years.

Here a possible model:

The decision is “Driving License Eligibility” that requires a “Person” as Input Data and the Business Knowledge Model of a “Minimum Age”.
In this simple case the knowledge model is a kind of over design introduced just for educational purposes, because the logic is pretty simple and it could be modeled directly in the decision. The model structure depends on the emphasis that the designer would place on the BKM, in this case for example, it could make sense to list all requirements of a driving license as BKM, for instance adding “Written Exam Passed” and so forth.
After the Decision Requirements Diagram, we have to delve in the details that make a DMN executable:

Bind a data type to the Input Data: from context menu select Attributes > Input Data Type. Create a new type with three fields: name, age, country.
Define a Decision Logic for the Business Knowledge Model: from context menu select Attributes > Decision Logic. Then, select Function (expression), select tPerson as input parameter and insert this FEEL expression: Person.age >= 18 (The editor should help you with code suggestions and syntax highlight).
To complete the DMN, add a logic to the Decision. The literal expression is enough in this case: Minimum age(Person). In the FEEL language the BKM is just a function call.

Running the DMN

Now, it’s time to make it real and call the DMN logic from your java code.
Create your maven project in your favorite Java IDE and add this dependencies to the POM:
https://gist.github.com/dmarrazzo/71c9a52fafb6fae526c21f3b636971f3
Add the Knowledge Deplyment Descriptor kmodule.xml in /src/main/resources/META-INF:
https://gist.github.com/dmarrazzo/afcacab09dc4a7919ea414b04fc0a85b
Export from your DMN editor the standard XML file and place it under src/main/resources.
Create a Java class and add the following code to the main() method to launch the DMN evaluation and print the results in the console:
https://gist.github.com/dmarrazzo/45d087d3a68cf05172ba9ace0b1af1e9
Modify the code to match the namespace and the name of your DMN file.
Finally, you will get your first DMN rules running! Well done!
Here the GitHub repository with the complete project:

DMNRunner.java is a standalone java program that executes the driving-license.dmn rules
driving-license.dmn is the above described DMN
LicenseTest.java is a JUnit class that tests 4 cases in the context of driving-license-2.dmn
driving-license-2.dmn is the second version of DMN that implements the modifications proposed in the following paragraph

Implementing the Decision Table

Let´s do a step further to make the BKM logic a bit more sophisticated modeling the following requirement:

A person is eligible for a driver license when the his / her age is at least 18 years old, unless he / she lives in US where the minimum age is 16.

To achieve this goal we have to change the BKM logic:

From Home ribbon, select Delete > Clear Logic
Select Function (Context)
Add Person parameter using tPerson from existing types
Insert minimum age as row name
Select Decision Table as row implementation and edit it to look like the following picture
At the bottom line, insert the following FEEL expression minimum age

Noteworthing:

The table hit policy indicates how overlapping rules have to be handled, in our case we chose FIRST, that means the first hit by rule order is returned.
We used the Function (context) in order to keep unchanged the BKM input parameter (tPerson).
The dash symbol (‘-’) is used to mean the input is irrelevant for the containing rule.
The DMN decision table has a quite flexible syntax for the test cell, we uses >= 18 but it is possible to express intervals [low, high], negation not (val), lists val1, val2, …, etc.
The default output is set to false.

Further learning opportunities

If you like me want to learn by examples, you’ll find a great source in the Decision Management Community: among others, there is a nice DMN solution published by our senior Drools developer Edson Tirelli.
I also suggest reading the specification, at least the first chapters and keep it as a reference for the FEEL language.
In the Bruce Silver’s website Method & Style, there are many interesting articles on the subject. He also published a valuable book , where he delves in the methodology and good practices.

Conclusions

Soon Red Hat will offer a production ready DMN engine, so I think that it’s time to bring the DMN values on the table and start a pilot project.
For your experiments and proof of concepts, you can start working today with the community project at drools.org.