Skip to main content

Boxed Expressions

Boxed Expressions are a standard way to visualize and edit decision logic in DMN. They provide a structured, graphical representation of logic that maps directly to FEEL expressions.

Introduction​

In DMN, every decision node has an associated expression that determines its value. Boxed expressions decompose this logic into nested "boxes," making complex logic easier to understand and maintain than a single long text expression.

Types of Expressions​

The platform supports all standard DMN boxed expressions:

Literal Expression​

The simplest form of logic. A single block of text containing a FEEL expression (e.g., a formula or a variable reference).

Decision Table​

A tabular representation of conditional logic. It maps a set of inputs to outputs based on defined rules. This is the most common expression type.

Context​

A list of key-value pairs. Each entry has a name and an expression. It is similar to defining a local object or a set of variables.

List​

An ordered collection of items. Each item in the list is itself an expression.

Relation​

A table of data where each row represents an entity and columns represent attributes. It acts like a static database table.

Function Definition​

Defines a reusable piece of logic with parameters. Boxed functions can be standard FEEL expressions or use external logic.

Invocation​

Calls a defined function (Business Knowledge Model) with specific arguments.

Nesting​

A key feature of boxed expressions is nesting. A Context entry can contain a Decision Table, which in turn can contain a List, and so on. This allows you to model arbitrarily complex logic in a structured way.

FAQ​

Which boxed expression should I use?

Pick by the shape of the logic. Decision Table for conditional rules — anything that fits cleanly in rows of inputs and outputs. Literal Expression for a one-line formula or simple calculation. Context when the logic has intermediate steps you want to name — it acts as a small block of local variables ending in a result. List for an ordered collection of values. Relation when you have static reference data laid out as rows and columns (essentially a baked-in table). Function Definition when you want to package reusable logic as a Business Knowledge Model. Invocation to call a Business Knowledge Model with specific argument bindings. When in doubt, start with a decision table — it covers the most common case, and you can always nest other boxed expressions inside its cells later.

What's the difference between a Literal Expression and a Context in DMN?

A Literal Expression is a single block of FEEL that produces a value directly — (MonthlyIncome * 12) + Bonus or if Score > 80 then "High" else "Normal". A Context decomposes the same logic into named intermediate steps and a final result: Annual: MonthlyIncome * 12, Total: Annual + Bonus, with Total as the result. Both produce the same value, the Context is easier to read and maintain when the computation has several meaningful intermediate values that benefit from names, while the Literal is faster to write for short calculations. Use a Context the moment a Literal expression starts needing comments to explain what it's doing.

What's the difference between a Context and a Relation in DMN?

A Context is a single key-value object — one map with named entries. A Relation is a list of contexts with a fixed shape — a table where every row has the same column names. So a Context describes one thing (a customer, a configuration, a result), while a Relation describes a collection of things (customers, configurations, reference data). At the FEEL level, a Context returns {key1: value1, key2: value2} and a Relation returns [{...}, {...}, {...}]. If your data is one record, use a Context, if it's a list of records with identical structure, use a Relation.

What's the difference between a List and a Relation in DMN?

A List is a flat ordered collection — [1, 2, 3] or ["red", "green", "blue"] — whose items can be of any type but typically share a single simple type. A Relation is also a list, but specifically a list of Contexts with a fixed column structure — [{Name: "Alice", Age: 30}, {Name: "Bob", Age: 25}]. Use a List when items are atomic (numbers, strings, booleans) or when the structure varies. Use a Relation when items are structured records that share the same fields — it makes the column layout explicit in the modeler and acts like a static database table.

What's the difference between a Function Definition and an Invocation in DMN?

A Function Definition is the implementation — the body of reusable logic with named parameters, like function(a, b) a + b. It's the boxed expression used inside a Business Knowledge Model (BKM). An Invocation is the call site — the binding of argument expressions to a function's parameters, like calling CalculateRisk(Age: Applicant.Age, Income: Applicant.Income). So Function Definition is what the BKM contains, Invocation is how a decision (or another BKM) invokes that BKM with specific inputs. Looking at it from each side: the function author writes the Function Definition once, the function caller writes an Invocation each time they use it.

Can boxed expressions be nested in DMN?

Yes — nesting is a core feature. Any boxed expression can appear wherever another expression is expected. A Context entry can contain a Decision Table, a List item can be a Context, a Decision Table cell can be a Literal Expression that itself uses a function Invocation, and so on to arbitrary depth. This lets you model complex logic as a hierarchy of structured boxes rather than one long opaque FEEL expression, which makes the model easier to read and easier to modify in isolation. The recommendation is to keep individual boxes small and let nesting carry the complexity — a deeply nested expression with small boxes is more maintainable than a flat expression with one giant decision table.