DMN Method and Style

3rd Edition, with DMN Cookbook

by Bruce Silver
Publisher: Cody-Cassidy Press
Publication Date: January 2024
Pages: 312

It’s been over five years since DMN Method and Style 2nd Edition was published and a lot has changed since then. So I’m pleased to announce that DMN Method and Style 3rd Edition is now available. You can get the print edition on Amazon and other online bookstores, and you can order the e-book edition right here on my website.

The new edition is based on the draft DMN 1.6 spec, which contains many features unavailable in the second edition of the book, which was based on DMN 1.2. And while that book was targeted at business users, the new edition balances the needs of business and technical modelers. Part I is the Guide to Decision Modeling, which explains all the modeling elements – DRDs, decision tables, other boxed expressions, and FEEL – in a business-friendly way. Part II is the DMN Cookbook, formerly a separate volume, with “recipes” for various modeling challenges, aimed at more technical modelers. Looking back on the original DMN Cookbook, based on the draft DMN 1.2 spec, I am struck by how few of those recipes would be done in the same way today.

Another impetus to writing a new edition is my own experience in DMN engagements. Seemingly obscure parts of FEEL – double iteration, handling lists of lists, interpolation of published data, complex data validation – can be critical in real-world projects, and those things all made their way into the new edition.

Preface

Decision Model and Notation (DMN) is a model-based language for decision automation. Model-based means it uses diagrams and tables instead of program code, so it is designed to be used by subject matter experts in the business, not just by programmers. In today’s terminology, DMN is a Low-Code language, used by solution “makers” both in business and IT. Low-Code solutions are faster to design and deploy and provide a way past the notorious programmer bottleneck.

Moreover, DMN is an open standard maintained by the Object Management Group (OMG), so it is vendor-neutral, and its intellectual property is free to use. DMN creates decision models, which describe graphically – through diagrams and tables – both the logical structure of a business decision, called decision requirements, and its executable decision logic, the rules and formulas for each model element. Graphical design makes the model logic transparent and maintainable by business.

Model-Based

The model-based aspect of DMN is crucial.

  • The model is the decision requirements.
  • The model is the decision logic.
  • The model is the decision documentation.
  • The model is the decision code.
  • The model is verifiable.
  • What you model is what you execute! (D Gagne)

Because the diagrams and tables are easy to create and easy to understand, they engage subject matter experts, help them understand the bigger picture, and make them not only willing but eager to participate in the project. Also, unlike the text-based requirements documents of traditional business rules projects, models can be validated and verified for completeness and consistency.

Not only is DMN business-friendly, but it is also a powerful language. While it is possible to use DMN only to create decision requirements handed off to IT for implementation, DMN is capable of defining the complete decision logic itself, down to the finest details, using standard tabular formats called boxed expressions and a friendly expression language FEEL inside the table cells.

Decision Automation

The automation aspect is also crucial. DMN is not just about understanding the components of your operational decision logic. It gives you that, certainly, but it’s really about automating that logic, deploying it as an executable decision service.

The models you create are directly executable on a native DMN automation engine. If the model is complete, there is no need to hand it off to programmers for interpretation and translation into some other language. And as an industry standard, DMN’s notation, syntax, and operational semantics are defined in an open specification, so it works the same in any tool. Models may even be interchanged between tools using a standard DMN XML format.

What You Model Is What You Execute

Unification of decision modeling and execution is a big deal. With DMN, the decision model provides both the requirements and the implementation. That means one language, one repository, one source of truth. Thus, DMN breaks down the barriers between business and IT that have long hampered traditional business rules projects, fostering a closer, more agile collaboration between those groups.

Empowering Business Users I need to say something more about the importance of executable decision logic. You might hear some people insist that business users should go nowhere near it. That’s just nonsense. I’m not saying business users are going to create and deploy DMN models into production on their own with zero IT involvement. They are still going to need IT for testing, staging, deployment, all that DevOps stuff. But if you want business users to specify decision logic that actually works, they need to be able to create and test it themselves, to see that the results, when executed, are correct. In the end, a DMN tool that cannot do that doesn’t realize the true promise.

Why a Third Edition

Many of these characteristics of DMN, while they seem obvious today, were not apparent to me in 2016 when I published the first edition of DMN Method and Style. At that time, version 1.1 of the standard had just been finalized and was being readied for public release. The basic features of the language – the graphical notation, the FEEL expression language – were little changed from DMN 1.0, but bugs in the original metamodel and schema had until that point made executable implementation impossible.

With DMN 1.1, the standard became available for implementation, but it required explanation to the world. The specification was dense and near impenetrable, but as a member of the DMN task force in OMG I had a good understanding of it, and there were no serious DMN books yet available. It seemed like a good time to write one.

But in reality, it was not. It’s one thing for a standard to be implementable and quite another to have tools that implement it properly. The few tools available at that time didn’t closely follow the spec. They omitted important elements of the Decision Requirements Diagram (DRD). They used their own syntax for decision tables, and they ignored the FEEL expression language entirely. Worse, they couldn’t execute what they modeled. The examples in the book suffered mightily as a result.

DMN Method and Style 2nd edition in 2018, based on DMN 1.2, was much better. By then I was using the Trisotech platform, which supported FEEL and all of the diagram elements and boxed expression types in the standard. It could execute the models and deploy them as REST services in the cloud. The language itself was significantly improved, with key enhancements to both the diagrams and FEEL.

This brings up another great thing about DMN: It is a living language. Unlike, say, BPMN or CMMN, DMN maintains an active Revision Task Force in OMG, which produces a new version of the standard approximately once a year, continually making the language more powerful and easier to use as adoption increases.

Now five years later, we are working on DMN 1.6, and the latest improvements – even some not yet officially adopted = are described in DMN Method and Style 3rd edition. The Trisotech platform has improved as well, and many examples in the previous edition are more easily modeled today.

But another reason I wanted to produce a third edition is that now I can draw upon my own experience in real-world DMN projects. I see more clearly now the aspects of DMN that for real projects, users need to know – how the language is actually used versus how it is laid out in the standard.

Also, in the second edition I was completely focused on the use of DMN by business users. It certainly is suited for that, but it’s clear that developers as well are interested in Low-Code tools like DMN. They like that DMN is consistent with today’s preferred IT architecture, based on orchestration of REST services in the cloud. Unlike legacy business rule languages, DMN is squarely aimed at creating stateless decision services that can be cloud-deployed.

To address those more technical modelers, in 2018 I also wrote the DMN Cookbook, organized as referenceable solution examples in the “cookbook” style familiar to developers. But today, DMN 1.5/1.6 is so much improved over the original DMN Cookbook‘s DMN 1.1 that almost all of the examples in that book would use different recipes today. Also, since Low-Code solution makers today include both business and IT, a separate book for developers no longer makes sense. For those reasons, DMN Method and Style 3rd Edition includes within it a completely updated DMN Cookbook. Readers of the new edition get a business-oriented explanation of DMN’s elements and usage in the first part of the book, and referenceable recipes for various modeling challenges in the second part.

Books vs Training

I have come across other DMN books that focus on things like what is a decision, why you should want to model your decision logic, how decision management relates to business architecture, how to organize the projects, and so on… everything but how to do DMN modeling yourself!

This book is not like that.

My goal is not to inflate the page count. I like to keep it short. My assumption is you already know why you want to model your decision logic. What you want to know is how to do it using DMN. That’s my focus. You will learn not just the names of the various elements of DMN, but how to use them properly to describe, document, and automate your decision logic.

In my experience, one important difference between developers and business users is that the former can become productive in a new language by reading a book, while the latter use books to understand how the language works and what its basic elements and techniques entail, but will require hands-on practice with a tool to become a productive user of it. For that I also offer DMN Method and Style training.

The training content is aligned with the third edition of the book, but it also includes in-class exercises using Trisotech Decision Modeler, quizzes, and a post-class certification exercise which must be iterated by the student until it is perfect. Students get 60-day use of the Trisotech platform as part of the training. Once they complete certification, students have become competent DMN modelers, capable of using all the boxed expressions and FEEL functions and operators. You can see more information on the training on my website, methodandstyle.com.

Even if you’re not ready for training, I strongly urge you to get a good DMN tool and try your hand at decision modeling. You can get a free trial of the Trisotech tool by going to https://www.trisotech.com/trials/.

Are You DMN-Ready?

You may have heard that DMN is too hard for business users. That is absolutely not true, but what is true is that not all business users can do it… as I’ve learned from doing DMN training for 6 years.

It’s not easy to say with any precision who can and who cannot master DMN. I have said in the past that if you can use the Formulas ribbon in Excel you can do it. It helps to have a prior understanding of basic concepts such as datatypes, expressions, and functions. Since that’s a little abstract, I’ve created a short pre-test to see how challenging DMN will be for you. It doesn’t require that you already know DMN, just that you can readily understand and apply book-learning about it, like you will get from this book or my DMN Method and Style training. (Of course, in the training it’s reinforced with hands-on exercises, repetition, and quizzes.)

The pre-test provides very brief explanations of some DMN elements and asks four multiple choice questions. Read the explanations and questions carefully and write down your answers. At the end I’ll provide the correct answers.

DRD

A Decision Requirements Diagram defines the logic dependency of a decision on supporting decisions and input data. Input data, the ovals in the diagram, are values supplied at the time of logic execution. Decisions, the rectangles in the diagram, contain a value expression that computes an output value based on the values of its inputs. The inputs to a decision are other decisions and input data connected by incoming solid arrows called information requirements. The decision’s value expression can reference only variables that are direct information requirements. The wavy shape in the DRD, called a knowledge source, represents background information about the decision. It is not an information requirement and plays no direct role in the value expression.

Q1. Based on that explanation, the value expression for Loan prequalification in the diagram above may reference which variables?

  1. Credit score, Affordability category
  2. Credit score, Affordability category, Loan approval guidelines
  3. Credit score, Down payment, Purchase price, Monthly income, Loan rate pct
  4. Credit score, Affordability category, Down payment, Purchase price, Monthly income, Loan rate pct

Decision Tables

The most familiar boxed expression type in DMN is a decision table, like the one below.

Decision tables are easy to read. Columns to the left of the double line are the inputs. Below the input name is its datatype – is the value text, a number, a date, etc.? – including any constraints on the allowed values, such as a numeric range or enumerated values. The column to the right of the double line is the output. Each numbered row is a decision rule. Each input cell in a rule represents a test of the input, true or false. For example, for rule 1 column 1, that cell is true if Credit score is greater than 720, otherwise false. And for rule 1 column 2, the cell is true if Affordability category is either “Affordable” or “Marginal”. A hyphen (“-“) in a condition cell means the input is irrelevant in this rule; the cell is true by default. If all condition cells in a rule are true, the rule is said to match and the expression in the output column is selected as the decision table output.

If it is possible that for some combination of input values, more than one rule may match, the rules are said to overlap. The hit policy code in the upper left corner, here A for Any, is used in that situation. Hit policy A means the table may contain overlapping rules if they have the same output value. For example here, the combination Credit score 610 and Affordability category “Unaffordable” matches both rules 6 and 7. Thus these rules overlap but have the same output value, so hit policy A is correct.

One more thing to mention: A numeric range in a condition cell uses the format you see in rules 2-5. A square bracket means include the endpoint; a parenthesis means exclude the endpoint. For example, rule 2 column 1 tests the condition Credit score greater than 680 and less than or equal to 720.

Q2. What is the Loan prequalification output for Credit score 720, Affordability category “Unaffordable”?

  1. “Likely approved”
  2. “Possibly approved”
  3. “Likely disapproved”
  4. null (no match)

Functions

A Business Knowledge Model (BKM) is a unit of decision logic formulated as a modeler-defined function, meaning its value expression references parameters specified in the BKM definition. In the DRD, a BKM is connected to a decision that invokes it by a dashed arrow called a knowledge requirement. A decision invokes the BKM – i.e., calls the function – by passing it values of each parameter, called arguments. The BKM plugs those arguments into its value expression and returns the result to the decision. In addition to BKMs, which are modeler-defined functions, the FEEL expression language also provides a large number of built-in functions, which are invoked without a knowledge requirement.

In both cases, the invocation is defined by the decision’s value expression, which maps the decision’s information requirements to BKM parameter values. BKMs allow modelers to create reusable decision logic, since different decisions (typically in different DMN models) can send their own particular argument values to the BKM.

Below you see the definition of a BKM called Loan amortization formula, which calculates the monthly payment for a fixed-rate home loan. Below it you see its documentation, which explains each of the parameters. In the BKM definition, the parameter names and their datatypes are enclosed in parentheses, below which is the BKM’s value expression. The second parameter of this BKM is the annual interest rate for the loan expressed as a decimal (not a percent). The formula is just arithmetic, but it is complicated and hard to remember, so perfect for a BKM. If you have the BKM, you don’t need to remember the formula or know how to derive it; you just need to understand its parameters and how to invoke it.

The DRD showing invocation of BKM Loan amortization formula by decision Monthly payment is shown below. Input data Loan rate pct is the annual loan rate expressed as a percent.

The invocation expression has the format BKM name(arg1, arg2, arg3), where arg1, arg2, and arg3 are expressions for the value of each of the BKM parameters. The order of arguments inside the parentheses must match the parameter order in the BKM definition.

Q3. What are the BKM’s parameters?

  1. Loan amount, Loan rate pct, Loan term
  2. Loan.amount, Loan.rate pct, Loan.term
  3. p, r, n
  4. principal, rate, number of months

Q4. What is the invocation expression?

  1. Loan amortization formula(Loan amount, Loan rate pct, Loan term)
  2. Monthly payment(p, r, n)
  3. Monthly payment(p, r/100, n)
  4. Loan amortization formula(Loan amount, Loan rate pct/100, Loan term)

Answers

Did you write down your answers to the four questions? If not, go back and do that now. Below are the answers.

Q1. The correct answer is a. Credit score, Affordability category. A decision’s value expression may reference only its direct information requirements, and there are just two of those.

Q2. The correct answer is c. “Likely disapproved”. Credit score 720 is true for rules 2, 3, and 7. Affordability category “Unaffordable” is true for rules 6 and 7. Thus the only matching rule is rule 7, “Likely disapproved”.

Q3. The correct answer is c. p, r, n. The BKM’s parameters are listed in parentheses in the BKM definition.

Q4. The correct answer is d. Loan amortization formula(Loan amount, Loan rate pct/100, Loan term). The expression starts with the BKM name, not the decision name. Because Loan rate pct is a percent, it must be divided by 100 to convert it to a decimal, the format for parameter r.

So how did you do on the four questions? If you got them all, you’re definitely ready. If you missed one, but you just overlooked some detail and you understand the explanation, you’re also ready. Otherwise, if the Answers above still don’t make sense, you might find DMN a challenge. But don’t give up yet; you haven’t even read the book! And in my DMN training, we go over things like this multiple times, and you are hands-on with the tool. But you do need to be able to grasp the basic concepts. And yes, there is a little math (but just a little).

Outline of the Book

Guide to Decision Modeling

Part I, the first 13 chapters of the book, comprising the Guide to Decision Modeling, roughly follows my DMN Method and Style training.

Chapter 1, What Is DMN?, starts by demonstrating a decision model by example, so you see concretely exactly how the various elements are used to model and execute a decision. It then goes on to outline the key benefits of model-based decision automation.

Chapter 2, DMN Elements, explains each of the core building blocks of DMN, including the decision requirements diagram (DRD), the metamodel and schema, decision tables and other boxed expressions, and DMN’s standard expression language FEEL. It concludes by reviewing DMN’s essential characteristics.

Chapter 3, Decision Requirements, drills into the DRD and the mechanics of creating it.

Chapter 4, Decision Tables, discusses DMN’s most familiar boxed expression type, the decision table, including what is allowed to be put in each cell and how the table output value is selected. It explains all the various hit policies and when to use each one, as well as best practice conventions with decision tables, many of which can be validated with tool-based Decision Table Analysis.

Chapter 5, Data Modeling and Reuse, explains the importance and mechanics of assigning datatypes to process variables. It explains how the internal data language FEEL relates to externally defined data submitted to DMN at execution time, notably XML and JSON, and use of the special FEEL value null. It goes on to explain how the logical data model defined by DMN can be linked to conceptual data models defined outside of DMN to provide unambiguous meaning to key business terms.

Chapter 6, Literal Expressions, begins the explanation of DMN’s expression language FEEL. It includes a complete discussion of formulas involving the built-in String and Number functions, and how expressions are nested inside other expressions.

Chapter 7, Business Knowledge Models, explains the importance and benefits of these modeler-defined logic functions, how they are defined and two ways to invoke them. It also explains how BKMs can be used to call external functions, and how libraries of commonly used functionality can be maintained for consistent reuse across multiple process models.

Chapter 8, Contexts, explains how this boxed expression type is used to simplify complex literal expressions without adding extra elements to the DRD. It also shows how contexts are used to create structured values, such as rows in a table.

Chapter 9, Decision Services, how these units of model execution are defined and invoked. In addition to invocation by an external client application or process, decision services may be invoked by a decision in DMN. In that context, the differences between a decision service and a BKM are explained.

Chapter 10, Calendar Arithmetic, shows how DMN handles dates, times, and durations, and uses them in decision logic. It also discusses FEEL’s recently added Temporal Logic functions.

Chapter 11, Lists and Tables, explains some of DMN’s most useful capabilities, including creating a list or table, querying tables using filters, joining related tables, iterating over a list or table, and performing set operations.

Chapter 12, Data Validation, explains an issue ignored by beginners but crucial in real projects, which is checking that data submitted to a decision service at execution time is complete and valid. After explaining the various ways FEEL can check for missing or invalid data, we discuss four different ways to implement data validation, and when to use each one.

Chapter 13, Orchestrating DMN, discusses how decision services are integrated with BPMN and CMMN to define a sequence of decisions and related actions.

DMN Cookbook

Part II, Chapters 14 to 20, comprising the updated DMN Cookbook, is organized as a collection of recipes that illustrate use of DMN in a wide variety of modeling tasks.

Chapter 14, About the DMN Cookbook, explains how FEEL is actually more powerful and more business-friendly than Microsoft’s Low-Code expression language, Power FX. It also provides a brief discussion of one of FEEL’s most powerful but controversial features, recursion.

Chapter 15, String Recipes, discusses casting to a string, including handling null values, parsing a string, joining a collection of strings, formatting numeric and date strings, and use of regular expressions.

Chapter 16, Calendar Arithmetic Recipes, provides additional examples of calculations involving dates, times, and durations.

Chapter 17, List and Table Recipes, provides a few more complex examples , including iteration over item index and sorting using a named precedes function.

Chapter 18, Math Recipes, discusses FEEL’s wealth of rounding functions as well as how to handle invalid items in functions combining lists of numbers. Because FEEL provides relatively few built-in math functions, we discuss how to gain access to many more by calling the free api.mathjs.org service from a BKM, how to interpolate values from published data tables, and numeric methods including Taylor Series and the Newton-Raphson method.

Chapter 19, Machine Learning Recipes, discusses various ways DMN can be used in machine learning, including correlation of two datasets and linear regression. In addition to an analytical solution to linear regression, we illustrate how to use recursion in DMN to perform linear regression using gradient descent, a technique used in a wide variety of machine learning algorithms. We also show how a BKM can directly execute any machine learning model packaged using the PMML standard.

Chapter 20, Data Validation Recipes, contains a single example, a detailed walkthrough of one of the four methods described in Chapter 12, but too complex to discuss there.

Acknowledgments

This book would not have been possible without the efforts of Trisotech to create software that is not only faithful to the DMN standard but makes it easy for non-technical modelers to use. To Denis Gagne, Simon Ringuette, and the rest of the Trisotech team, thank you. There are many DMN platforms, but Trisotech is without doubt the best of the best. I could not have wished for better partners. I want to thank Denis, Simon, and Matteo Mortari of Red Hat as well for their helpful comments and suggestions for the book.

I also must acknowledge the contributions of other members of the DMN Revision Task Force in OMG, led by Alan Fish and Falko Menge, whose efforts continue to make the standard ever richer and easier to use, turning out a new and improved version every year!

Thanks also to Carol Leyba for assistance with the cover design.

Bruce Silver

Pasadena, CA, January 2024