cDMN Solver

To be able to execute a spreadsheet, you need to use the cDMN solver. The cDMN solver consists of two main parts:

  1. A Python converter from cDMN to IDP language;
  2. The IDP-Z3 system, a knowledge reasoning engine (can be run online or downloaded via Pip).

1. Installation

Installing the solver is easy via the Python repositories:

$ pip3 install cdmn

The full source code for the solver is available at our GitLab repository. It has been tested with Python 3.7=<. Other versions will probably work, but there’s no guarantee. The list of dependencies is as follows:

  • openpyxl
  • ply
  • numpy
  • python-dateutil
  • idp-engine

2. Usage

The main usage is as follows:

usage: cdmn [-h] [--version] [-n name_of_sheet [name_of_sheet ...]] [-o outputfile] [--idp idp] [--idp-z3] [--interactive-consultant] [--main]
                 [--errorcheck-overlap overlaptable] [--errorcheck-shadowed shadowedtable] [--errorcheck-rule ERRORCHECK_RULE]
                 [--errorcheck-gap ERRORCHECK_GAP]
                 path_to_file

Run cDMN on DMN tables.

positional arguments:
  path_to_file          the path to the xlsx or xml file

options:
  -h, --help            show this help message and exit
  --version, -v         show program's version number and exit
  -n name_of_sheet [name_of_sheet ...], --name name_of_sheet [name_of_sheet ...]
                        the name(s) of the sheet(s) to execute
  -o outputfile, --outputfile outputfile
                        the name of the outputfile
  --idp idp             the path to the idp executable
  --idp-z3
  --interactive-consultant
                        generate file specifically for the Interactive Consultant
  --main                create a main, to use when generating for the IDP-Z3 Interactive Consultant
  --errorcheck-overlap overlaptable
                        the table to check for overlap errors: table is identified by table id
  --errorcheck-shadowed shadowedtable
                        the table to check for shadowed rules: table is identified by table id
  --errorcheck-rule ERRORCHECK_RULE
                        the rule to check for being erronous
  --errorcheck-gap ERRORCHECK_GAP
                        the table to check for input gaps: table is identified by table id

For example, to execute the sheet named Problem1 in the .xlsx file located at Data/DMNImplementation.xlsx, the following command is used.

$ cdmn Data/DMNImplementation.xlsx -n "Problem1" -o "~/idp/Files/"

This will convert a sheet called Problem1 from the DMNImplementation.xlsx file and save it in as ~/idp/Files/Problem1.idp. It’s also possible to set the name of the idp name yourself, by changing the output to ~/idp/Files/custom_name.idp.

If you wish to immediately execute the IDP specification, you can do so by supplying the --idp-z3 flag. This will automatically run the IDP-Z3 system, and print its output.

$ cdmn Data/DMNImplementation.xlsx -n "Problem1" -o "problem.idp" --idp-z3

Some cDMN specification can get large, so sometimes it makes sense to create a logical separation in different sheets. It is possible to run multiple sheets together by supplying multiple names after the -n flag. For example:

$ cdmn Examples/DMChallenges.xlsx -n "Balanced_Assignment" "Balanced_Assignment_Datatable

Alternatively, if your cDMN model is spread over all sheets in the table, you can use the --all-sheets flag.

$ cdmn Examples/set.xlsx --all-sheets

Create a file for the Interactive Consultant interface

The Interactive Consultant interface is an IDP-based, user-friendly interface which allows for straightforward interaction with a cDMN model. In order to create a file that can be used in the interface, the interactive-consultant-idp-z3 flag can be used.

$ cdmn Data/DMNImplementation.xlsx -n "Problem1" -o "problem.idp" --interactive-consultant-idp-z3

In the case that a file is being generated for use in the IDP-Z3 webIDE, the --main flag should also be supplied.

Note

If your cDMN tables contain annotations, these will also show up in your IDP-Z3 file. This makes the Interactive Consultant more explainable, so make full use of it!

Use DMN as input

If you wish to execute DMN XML instead of a spreadsheet, you can do so by simply supplying the XML file as input.

Otherwise, it is also possible to create DMN tables inside a spreadsheet. In this case however, it is still necessary to create a glossary for the DMN specification. This can easily be done by filling out the Constant glossary table with all the variable names.