Overview

ÐecisionToolkit is a set of tools for designing, testing and executing decision models based on the DMN™ specification, an industry standard governed by OMG®.

ÐecisionToolkit 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.

ÐecisionToolkit offers a range of features, including DMN models evaluation, decision tables evaluation, and FEEL expressions 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.

Features

• Serving DMN models
• Evaluating DMN models
• Evaluating decision tables
• Evaluating FEEL expressions
• Parsing DMN models
• Parsing decision tables
• Parsing FEEL expressions
• Testing DMN models
• Testing decision tables
• Testing FEEL expressions
• Exporting DMN models
• Exporting decision tables
• Exporting FEEL expressions

Status

ÐecisionToolkit is PRODUCTION READY, although some features may still be refined or changed based on testing and user feedback. We encourage users to try ÐecisionToolkit and share their feedback to help us enhance its usability and performance.

License

ÐecisionToolkit is licensed under either of

• MIT license (see LICENSE-MIT) or
• Apache License, Version 2.0 (see LICENSE and NOTICE)

at your option.

Contribution

Any contributions to ÐecisionToolkit are greatly appreciated. All contributions intentionally submitted for inclusion in the work by you, shall be dual licensed as above, without any additional terms or conditions.

Versions

Installation

ÐecisionToolkit is distributed as a single executable with no external dependencies.

You can either download a prebuilt binary or install from source using Cargo.

Download a prebuilt binary

• Go to GitHub releases.
• Select a version and expand the Assets section.
• Download the archive for your operating system.
• Extract it and run the ÐecisionToolkit executable.

Install with Cargo

Make sure you have Cargo installed, then run:

cargo install dsntk

Caution

Installing ÐecisionToolkit using Cargo may require installation of gcc (or a similar C/C++ toolchain like clang), as ÐecisionToolkit depends on math library written in C.

Getting started

ÐecisionToolkit provides a set of examples ready to play with.

To install examples in examples directory, run:

dsntk exs examples

For more details, refer to Saving examples.

Evaluate example FEEL expression

cd examples/e1

dsntk efe e1.ctx e1.feel

Output:

3

For more details, refer to Evaluating FEEL expressions.

Evaluate example DMN model

cd examples/e2

dsntk edm e2.ctx e2.dmn -i "Greeting Message"

Output:

"Hello John Doe"

For more details, refer to Evaluating DMN models.

Evaluate example decision table

cd examples/e3

dsntk edt e3.ctx e3.dtb

Output:

0.15

For more details, refer to Evaluating decision tables.

Serve example DMN model

cd examples/e2

dsntk srv -v -H 127.0.0.1 -D .

Output:

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

Open a new terminal window and run:

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

Output:

{"data":"Hello John Doe"}

For more details, refer to Serving DMN models.

Command-line

Cheat sheet

Commands

srv

Runs ÐecisionToolkit as a service and serves DMN decision models

To display all available options of the srv command, run:

dsntk help srv

For more details, refer to Serving DMN models.

edm

Evaluates DMN decision model

To display all available options of the edm command, run:

dsntk help edm

For more details, refer to Evaluating DMN models.

edt

Evaluates decision table

To display all available options of the edt command, run:

dsntk help edt

For more details, refer to Evaluating decision tables.

efe

Evaluates FEEL expression

To display all available options of the efe command, run:

dsntk help efe

For more details, refer to Evaluating FEEL expressions.

pdm

Parses DMN model

To display all available options of the pdm command, run:

dsntk help pdm

For more details, refer to Parsing DMN models.

pdt

Parses decision table

To display all available options of the pdt command, run:

dsntk help pdt

For more details, refer to Parsing decision tables.

pfe

Parses FEEL expression

To display all available options of the pfe command, run:

dsntk help pfe

For more details, refer to Parsing FEEL expressions.

tdm

Tests DMN model

To display all available options of the tdm command, run:

dsntk help tdm

For more details, refer to Testing DMN models.

tdt

Tests decision table

To display all available options of the tdt command, run:

dsntk help tdt

For more details, refer to Testing decision tables.

tfe

Tests FEEL expression

To display all available options of the tfe command, run:

dsntk help tfe

For more details, refer to Testing FEEL expressions.

xdm

Exports DMN model

To display all available options of the xdm command, run:

dsntk help xdm

For more details, refer to Exporting DMN models.

xdt

Exports decision table

To display all available options of the xdt command, run:

dsntk help xdt

For more details, refer to Exporting decision tables.

xfe

Exports FEEL expression

To display all available options of the xfe command, run:

dsntk help xfe

For more details, refer to Exporting FEEL expressions.

exs

Saves the examples

To display all available options of the exs command, run:

dsntk help exs

For more details, refer to Saving examples.

Options

Below is a list of all ÐecisionToolkit options.

help

Print help:

dsntk --help

or short:

dsntk -h

version

Print version:

dsntk --version

or short:

dsntk -V

Serving DMN models

The core functionality of the ÐecisionToolkit is serving DMN models. The specification precisely defines XML interchange format for decision models. XML files containing decision models are loaded and processed by ÐecisionToolkit 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 ÐecisionToolkit server, we assume that the built-in examples are already saved in the ~/examples directory (see Saving examples for details).

Change to the directory containing the examples:

cd ~/examples

Running a server

To start ÐecisionToolkit server, type the following command:

dsntk srv

Expected output should look like this:

Found 1 model.
Loaded 1 model.
Deployed 1 invocable.
dsntk 0.0.0.0:22022

ÐecisionToolkit server is started. By default, ÐecisionToolkit server accepts connections from all available network interfaces 0.0.0.0 and listens on port 22022. During startup, the server scans the current directory with all its subdirectories, and searches for decision models stored as XML files with .dmn extension.

In our example, during directory scanning, the ÐecisionToolkit server has found the dm directory containing one decision model file named dm.dmn. This file was loaded, and one invocable was deployed: decision named Greeting Message.

To stop the ÐecisionToolkit server, press Ctrl+C.

The list of all deployed invocables with endpoint names can be displayed during 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 invocable:
  dm/org/decision-toolkit/greetings/Greeting%20Message

dsntk 0.0.0.0:22022

Evaluating invocables

After starting the ÐecisionToolkit server, the deployed invocable can be evaluated by calling its endpoint with required input data, using e.g. curl tool.

In a new terminal window, run:

curl -s -w '\n' -d '{"Full Name":"Solomon L. Pollack"}' -H "Content-Type: application/json" -X POST http://0.0.0.0:22022/evaluate/dm/org/decision-toolkit/greetings/Greeting%20Message

Expected output:

{"data":"Hello Solomon L. Pollack"}

The ÐecisionToolkit version of a hello world program could look like this:

curl -s -w '\n' -d '{"Full Name":"world"}' -H "Content-Type: application/json" -X POST http://0.0.0.0:22022/evaluate/dm/org/decision-toolkit/greetings/Greeting%20Message

Expected output:

{"data":"Hello world"}

Endpoint names

The JSON API endpoint for evaluating invocables exposed by the ÐecisionToolkit server is named evaluate/.

The full URL of the endpoint is composed of the following parts:

• the protocol:

  http:// or https://

• host address:

  0.0.0.0 or 127.0.0.1 or my.domain.com/ alike

• endpoint name:

  evaluate/

• path built from directory names where the file containing the DMN model was found during startup scanning:

  dm/

• model namespace converted to RDNN-like path:

  org/decision-toolkit/

• model name:

  greetings/

• the name of the invocable:

  Greeting%20Message

All parts put together give the following URL of the endpoint:

http://127.0.0.1:22022/evaluate/dm/org/decision-toolkit/greetings/Greeting%20Message

While not all characters are legal in URLs, there is %20 between Greeting and Message, which represents a space in percent-encoding. See RFC3986 for more details.

Evaluating DMN models

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Evaluating decision tables

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Evaluating FEEL expressions

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Parsing DMN models

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Parsing decision tables

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Parsing FEEL expressions

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Testing DMN models

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Testing decision tables

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Testing FEEL expressions

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Exporting DMN models

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Exporting decision tables

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Exporting FEEL expressions

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

Saving examples

ÐecisionToolkit provides a set of examples ready to play with.

To install the examples in the examples directory, run:

dsntk exs examples

The resulting structure of directories and files should be similar to the one shown below:

tree examples

examples
├── dm
│   ├── dm.ctx
│   └── dm.dmn
├── dt
│   ├── dt.ctx
│   └── dt.dtb
└── fe
    ├── fe.ctx
    └── fe.feel

4 directories, 6 files

FEEL

• Arithmetic
• Built-in functions

Arithmetic

• Addition
• Subtraction
• Multiplication
• Division
• Exponentiation
• Negation

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

Containerization

• Docker
• Podman

Docker

Dockerfile

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 ÐecisionToolkit as a service and display all deployed invocables
CMD ["/dsntk", "srv", "--verbose"]

docker.sh

#!/usr/bin/env bash

# container name
NAME=dsntk

# container version
VERSION=0.3.0

# 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 ;-)

Run 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

Display running containers:

docker ps

result

CONTAINER ID   IMAGE        COMMAND                  CREATED         STATUS         PORTS                     NAMES
fcb45779ce7d   dsntk:0.3.0  "/dsntk srv --verbose"   2 minutes ago   Up 2 minutes   0.0.0.0:22022->22022/tcp  dsntk

Podman

⏳ Detailed documentation is on the way…

Tip

Contributions are always welcome!

If you’d like to help expand or improve this documentation, please open a Pull Request in our GitHub repository: https://github.com/DecisionToolkit/decisiontoolkit.github.io

References

DMN

• DMN Specification
• DMN Cookbook
• DMN Method and Style
• DMN Technology Compatibility Kit (TCK)

General

• Decision Management Community
• Contributor Covenant
• Keep a Changelog
• Semantic Versioning

Blockchains and Smart Contracts

• Combining DMN and Blockchain
• Smart Contract Decision Model

Development

• Graph algorithms
• Java integration using JNI
• Language Server Protocol