Decision Modelling Notation

Decision Modelling Notation (DMN) is an international standard for modelling rules resulting in certain outputs given certain input values. DMN is a machine-readable XML-based format which typically defines one or more decision tables that can be evaluated.

Open Forms supports DMN evaluation in its DMN module. Engine-specific details are implemented in the plugins.

Python API

The public API serves as an abstraction over the various engines.

Reference

Public Python API for the DMN module.

openforms.dmn.service.VariablesMapping

alias of dict[str, Any]

openforms.dmn.service.evaluate_dmn(plugin_id: str, definition_id: str, *, version: str = '', input_values: dict[str, Any]) → dict[str, Any]

Evaluate the decision definition using the spefified plugin.

Parameters

  • plugin_id – identifier of the plugin to use for evaluation

  • definition_id – identifier of the decision definition to evaluate

  • version – optional version of the definition to evaluate, if supported. If versioning is supported but no version is specified, the latest version should be used.

  • input_values – A mapping of variable name -> variable value, used as input variables for the evaluation.

Returns

A mapping of name -> value output variables.

Available implementations

The following plugins are available in Open Forms core.

Camunda DMN

Configuration is done in the admin via Configuratie > Camunda configuration.

Implement the Camunda 7.x DMN engine.

This plugin supports fetching and evaluating decision definitions (and their versions) from the Camunda REST API. Introspection of the DMN XML is also available.

Note that Camunda DMN supports decision definitions containing multiple decision tables for chained evaluation/input. You can trigger this by evaluating the root table and passing all the descendant leaf input variables.

Note

the end-user is responsible for configuring the correct input variable names and correctly processing the output variables. On misconfiguration, Camunda returns a HTTP 500 response which will be logged and an empty result will be returned by Open Forms.

Note

Tested with Camunda 7.16.

Plugin developer reference

Management commands

Open Forms provides two management commands for introspection and (local) testing. Please see the --help for each command for detailed information.

  • dmn_list_definitions: retrieve the available decision definitions and their versions

  • dmn_evaluate: evaluate a particular decision table with provided input variables

Python API

This section serves as a reference for DMN plugins.

class openforms.dmn.base.BasePlugin(identifier: str)
abstract evaluate(definition_id: str, *, version: str = '', input_values: dict[str, Any]) → dict[str, Any]

Evaluate the decision definition with the given input data.

abstract get_available_decision_definitions() → list[openforms.dmn.base.DecisionDefinition]

Get a collection of all the available decision definitions.

The end-user configuring the evaluation selects one of the available choices. Note that different versions of the same definition must be filtered out, as specifying a particular version is a separate action.

abstract get_decision_definition_parameters(definition_id: str, version: str = '') → openforms.dmn.types.DMNInputOutput

Return the input/output clauses for a given decision definition (version).

An input clause defines the id, label, expression and type of a decision table input. It is represented by an input element inside a decisionTable XML element. An output clause defines the id, label, name and type of a decision table output. It is represented by an output element inside a decisionTable XML element.

get_decision_definition_versions(definition_id: str) → list[openforms.dmn.base.DecisionDefinitionVersion]

Get a collection of available versions for a given decision definition.

Backends supporting versioning can implement this method to offer more granularity. By default we assume versioning is not supported and return an empty list.

get_definition_xml(definition_id: str, version: str = '') → str

Return the standards-compliant XML definition of the decision table.

If this is not available, return an empty string.

class openforms.dmn.base.DecisionDefinition(identifier: str, label: str)

Represent a single decision definition.

class openforms.dmn.base.DecisionDefinitionVersion(id: str, label: str)

Represent a version of a decision definition.