Decision Toolkit
Overview
Decision Toolkit is a suite of tools designed to build, evaluate and test decision models.
Decision Toolkit is constructed based on the Decision Model and Notation (DMN™) specification, which is an industry standard governed by the Object Management Group (OMG®).
Decision Toolkit aims to be performant, reliable, and fully compliant with the DMN™ specification, ensuring accurate evaluation of decision models. All tools are implemented in Rust, a programming language known for its security, efficiency and reliability.
Decision Toolkit offers a range of features, including DMN™ model evaluation, decision table evaluation, and FEEL expression evaluation. It also includes functionality for parsing, validating, and recognizing DMN™ models, decision tables, and FEEL expressions. Users can test DMN™ models, decision tables, and FEEL expressions, and export them to HTML format.
Decision Toolkit provides a comprehensive set of tools for decision model evaluation and testing, leveraging the DMN™ specification and Rust programming language to ensure high performance, reliability and portability.
Main features:
- Evaluation of DMN models
- Evaluation of decision tables
- Evaluation of FEEL expressions
- Parsing and validating DMN models
- Parsing and recognizing decision tables
- Parsing and validating FEEL expressions
- Testing DMN models
- Testing decision tables
- Testing FEEL expressions
- Exporting DMN models to HTML
- Exporting decision tables to HTML
- Exporting FEEL expressions to HTML
📗 NOTE: Current version of this book assumes you’re using Decision Toolkit in version 0.0.4 or later. Please visit Installation chapter to learn how to install or update Decision Toolkit.
Project status
Decision Toolkit is production ready, but there are still some features that may be subject to change or refinement, based on testing and user feedback. We welcome users to try Decision Toolkit out and provide feedback or suggestions to improve its usability or performance.
Installation
Decision Toolkit ships as a single executable without any additional dependencies.
Binary version of Decision Toolkit may be obtained in the following ways:
- downloaded directly from GitHub releases, or
- built and installed from source using Cargo.
Downloading Decision Toolkit from released versions
- Head to GitHub releases.
- Expand the Assets section in selected release version.
- Download the binary of your choice, according to the operating system you need.
💡 HINT: Names of released binary files contain version number and operating system name like dsntk-0.0.4-linux-x86_64. To proceed with the examples presented in this book, just rename the downloaded binary to:
- dsntk for Linux and macOS,
- dsntk.exe for Windows.
Installing Decision Toolkit using Cargo
Install Cargo and run:
$ cargo install dsntk
Getting started
Decision Toolkit provides a set of examples ready to play with.
To install examples in examples directory, enter:
$ dsntk exs examples
For a more detailed description of exs command, please refer to Saving examples.
Evaluate example FEEL expression
$ cd ./examples/e1
$ dsntk efe e1.ctx e1.feel
3
For a more detailed description of efe command, please refer to Evaluating FEEL expressions.
Evaluate example DMN model
$ cd ./examples/e2
$ dsntk edm e2.ctx e2.dmn -i "Greeting Message"
"Hello John Doe"
For a more detailed description of edm command, please refer to Evaluating DMN models.
Evaluate example decision table
$ cd ./examples/e3
$ dsntk edt e3.ctx e3.dtb
0.15
For a more detailed description of edt command, please refer to Evaluating decision tables.
Run Decision Toolkit as a service
$ cd ./examples/e2
$ dsntk srv -v -H 127.0.0.1 -D .
Found 1 model.
Loaded 1 model.
Deployed 1 invocable.
Deployed invocables:
io/dsntk/2_0001/compliance-level-2-test-0001/Greeting%20Message
dsntk 127.0.0.1:22022
Switch to another terminal and enter:
$ curl -s -d "{\"Full Name\":\"John Doe\"}" \
-H "Content-Type: application/json" \
-X POST http://127.0.0.1:22022/evaluate/io/dsntk/2_0001/compliance-level-2-test-0001/Greeting%20Message
{"data":"Hello John Doe"}
For a more detailed description of srv command, please refer to Serving DMN models.
Command-line commands
-h --help
Print this message or the help of the given subcommand(s):
$ dsntk -h
or
$ dsntk --help
-V --version
Print version information.
$ dsntk -V
or
$ dsntk --version
srv
Runs Decision Toolkit as a service. To display all available options of the srv command, enter:
$ dsntk help srv
For a more detailed description of srv command, please refer to Serving DMN models.
edm
Evaluates DMN model. To display all available options of the edm command, enter:
$ dsntk help edm
For a more detailed description of edm command, please refer to Evaluating DMN models.
edt
Evaluates decision table. To display all available options of the edt command, enter:
$ dsntk help edt
For a more detailed description of edt command, please refer to Evaluating decision tables.
efe
Evaluates FEEL expression. To display all available options of the efe command, enter:
$ dsntk help efe
For a more detailed description of efe command, please refer to Evaluating FEEL expressions.
pdm
Parses DMN model. To display all available options of the pdm command, enter:
$ dsntk help pdm
For a more detailed description of pdm command, please refer to Parsing DMN models.
pdt
Parses decision table. To display all available options of the pdt command, enter:
$ dsntk help pdt
For a more detailed description of pdt command, please refer to Parsing decision tables.
pfe
Parses FEEL expression. To display all available options of the pfe command, enter:
$ dsntk help pfe
For a more detailed description of pfe command, please refer to Parsing FEEL expressions.
tdm
Tests DMN model. To display all available options of the tdm command, enter:
$ dsntk help tdm
For a more detailed description of tdm command, please refer to Testing DMN models.
tdt
Tests decision table. To display all available options of the tdt command, enter:
$ dsntk help tdt
For a more detailed description of tdt command, please refer to Testing decision tables.
tfe
Tests FEEL expression. To display all available options of the fte command, enter:
$ dsntk help tfe
For a more detailed description of tfe command, please refer to Testing FEEL expressions.
xdm
Exports DMN model. To display all available options of the xdm command, enter:
$ dsntk help xdm
For a more detailed description of xdm command, please refer to Exporting DMN models.
xdt
Exports decision table. To display all available options of the xdt command, enter:
$ dsntk help xdt
For a more detailed description of xdt command, please refer to Exporting decision tables.
xfe
Exports FEEL expression. To display all available options of the xfe command, enter:
$ dsntk help xfe
For a more detailed description of xfe command, please refer to Exporting FEEL expressions.
rdt
Recognizes decision table. To display all available options of the rdt command, enter:
$ dsntk help rdt
For a more detailed description of rdt command, please refer to Recognizing decision tables.
exs
Saves the examples. To display all available options of the exs command, enter:
$ dsntk help exs
For a more detailed description of exs command, please refer to Saving examples.
Serving DMN models
The core function of Decision Toolkit is serving DMN models. The DMN™ specification precisely defines XML interchange format of decision models. XML files containing decision models are loaded and processed by Decision Toolkit server and exposed as a set of JSON API endpoints. Each endpoint represents a single invocable defined in the decision model. Calling an endpoint is equivalent to executing a decision, business knowledge model or decision service.
To explain in details, how to run and use the Decision Toolkit server (a.k.a. DMN runtime), we assume that Decision Toolkit examples are saved in examples directory and the current directory contains ONLY examples directory:
$ ls
examples
Running Decision Toolkit server
To run Decision Toolkit server, enter the following command:
$ dsntk srv
Found 1 model.
Loaded 1 model.
Deployed 1 invocable.
dsntk 0.0.0.0:22022
Decision Toolkit server is started, accepts connections from all available network interfaces 0.0.0.0 (default) and listens on port 22022 (default). During startup, the Decision Toolkit server scans current working directory (default) and its subdirectories, and searches for decision models stored in XML files having .dmn extension.
During the scanning, in the current working directory, the Decision Toolkit server has found examples directory containing one subdirectory named e2 with decision model file named e2.dmn. This file was loaded and one invocable from this file was deployed — a decision named Greeting Message.
This invocable can be evaluated by calling the endpoint:
examples/e2/io/dsntk/2_0001/compliance-level-2-test-0001/Greeting%20Message
The list of all deployed invocables with endpoint names can be displayed during Decision Toolkit server startup by specifying the option -v or --verbose, like shown below:
$ dsntk srv -v
Found 1 model.
Loaded 1 model.
Deployed 1 invocable.
Deployed invocables:
examples/e2/io/dsntk/2_0001/compliance-level-2-test-0001/Greeting%20Message
dsntk 0.0.0.0:22022
Evaluating the invocable
Having the Decision Toolkit server started, the deployed invocable can be evaluated by calling an endpoint with required input data, using curl for example:
$ curl -s -d "{\"Full Name\":\"John Doe\"}" \
-H "Content-Type: application/json" \
-X POST http://0.0.0.0:22022/evaluate/examples/e2/io/dsntk/2_0001/compliance-level-2-test-0001/Greeting%20Message
{"data":"Hello John Doe"}
The Decision Toolkit version of a hello world program could look like this:
$ curl -s -d "{\"Full Name\":\"world\"}" \
-H "Content-Type: application/json" \
-X POST http://127.0.0.1:22022/evaluate/examples/e2/io/dsntk/2_0001/compliance-level-2-test-0001/Greeting%20Message
{"data":"Hello world"}
Endpoint names
The common endpoint for evaluating invocables exposed by Decision Toolkit server is named:
evaluate
The full URL of the endpoint is built from the following parts:
-
protocol:
http:// or https://
-
host address, like:
0.0.0.0 or 127.0.0.1 or my.domain.com
-
common endpoint name:
evaluate
-
directory names where the file containing DMN model was found during scanning:
examples/e2
-
model namespace converted to RDNN-like path:
io/dsntk/2_0001/compliance-level-2-test-0001
-
invocable name:
Greeting Message
All parts put together, give the following URL of the endpoint:
http://127.0.0.1:22022/evaluate/examples/e2/io/dsntk/2_0001/Greeting%20Message
📗 NOTE: While not all characters are legal in URL, there is %20 between Greeting and Message, which in percent-encoding represents a space. See RFC3986 for more details.
Evaluating DMN models
🚧 work in progress 🚧
Evaluating decision tables
🚧 work in progress 🚧
Evaluating FEEL expressions
🚧 work in progress 🚧
Parsing DMN models
🚧 work in progress 🚧
Parsing decision tables
🚧 work in progress 🚧
Parsing FEEL expressions
🚧 work in progress 🚧
Testing DMN models
🚧 work in progress 🚧
Testing decision tables
🚧 work in progress 🚧
Testing FEEL expressions
🚧 work in progress 🚧
Exporting DMN models
🚧 work in progress 🚧
Exporting decision tables
🚧 work in progress 🚧
Exporting FEEL expressions
🚧 work in progress 🚧
Recognizing decision tables
🚧 work in progress 🚧
Saving examples
Decision Toolkit provides a set of examples ready to play with.
To install examples in examples directory, enter:
$ dsntk exs examples
The resulting structure of directories and files should be similar to the one shown below:
$ tree .
.
└── examples
├── e1
│ ├── e1.ctx
│ └── e1.feel
├── e2
│ ├── e2.ctx
│ └── e2.dmn
└── e3
├── e3.ctx
└── e3.dtb
5 directories, 6 files
Commands cheat sheet
DMN MODEL | FEEL EXPRESSION | DECISIONTABLE | EXAMPLES | |
---|---|---|---|---|
EVALUATE | edm | efe | edt | |
PARSE | pdm | pfe | pdt | |
TEST | tdm | tfe | tdt | |
EXPORT | xdm | xfe | xdt | |
RECOGNIZE | rdt | |||
SERVE | srv | |||
SAVE | exs |
Containerization
Docker
FROM scratch
# copy the binary file of Decision Toolkit to container root directory
COPY ./target/x86_64-unknown-linux-musl/release/dsntk /
# copy example DMN model to container root directory
COPY ./dsntk/src/examples/e2/e2.dmn /
# start DSNTK as a service and display all deployed invocables
CMD ["/dsntk", "srv", "--verbose"]
#!/usr/bin/env bash
# container name
NAME=dsntk
# container version
VERSION=0.0.3
# stop existing Docker container
docker stop $NAME
# remove stopped Docker container
docker rm $NAME
# remove existing Docker image
docker rmi "$(docker images | grep "^$NAME " | awk '{print $3}')"
# build the Decision Toolkit
cargo +stable build --release --target x86_64-unknown-linux-musl
# build new Docker image
docker build -t $NAME:$VERSION .
# start new Docker container
docker run --name $NAME -d -p 22022:22022 $NAME:$VERSION
# display logs from running Docker container
docker logs -f $NAME
# press Ctrl+C to stop following the log file ;-)
command
$ ./docker.sh
.
. (log from executed commands)
.
Found 1 model.
Loaded 1 model.
Deployed 1 invocable.
Deployed invocables:
io/dsntk/2_0001/compliance-level-2-test-0001/Greeting%20Message
dsntk 0.0.0.0:22022
a
$ docker ps
result
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
fcb45779ce7d dsntk:0.0.3 "/dsntk srv --verbose" 2 minutes ago Up 2 minutes 0.0.0.0:22022->22022/tcp dsntk
Podman
🚧 work in progress 🚧
FEEL
Arithmetic
Addition
1 + 1
a + b
x + y
Subtraction
1 - 1
a - b
x - y
Multiplication
1 * 1
a * b
x * y
Division
1 / 1
a / b
x / y
Exponentiation
2 ** 3
a ** b
x ** y
Negation
- 1
- a
- x
Built-in functions
- abs
- after
- all
- any
- append
- before
- ceiling
- coincides
- concatenate
- contains
- count
- date
- date and time
- day of week
- day of year
- decimal
- distinct values
- duration
- during
- ends with
- even
- exp
- finished by
- finishes
- flatten
- floor
- get entries
- get value
- includes
- index of
- insert before
- is
- list contains
- log
- lower case
- matches
- max
- mean
- meets
- median
- met by
- min
- mode
- modulo
- month of year
- not
- number
- odd
- overlaps
- overlaps after
- overlaps before
- product
- remove
- replace
- reverse
- sort
- split
- sqrt
- started by
- starts
- starts with
- stddev
- string
- string length
- sublist
- substring
- substring after
- substring before
- sum
- time
- union
- upper case
- week of year
- years and months duration
License
Decision Toolkit is licensed under either of
- MIT license (see LICENSE-MIT) or
- Apache License, Version 2.0 (see LICENSE and NOTICE)
at your option.
Contributing
Any contributions to Decision Toolkit are greatly appreciated. If you would like to get involved, please don't hesitate to reach out to us. The source files from which the Decision Toolkit book is generated can be found on GitHub.
References
DMN
General
Blockchains and Smart Contracts
Development
Versions
This document covers version 0.0.4 (or later) of Decision Toolkit.
This document covers version 1.4 of DMN™ specification.
This document version is 0.0.12.