Decision Toolkit

Appearance

Serving DMN™ models ​

The core functionality of the Decision Toolkit is serving DMN™ models. The DMN™ specification precisely defines XML interchange format for 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, 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:

shell
$ cd ~/examples

Running a server ​

To run Decision Toolkit as a server, type the following command:

shell
$ dsntk srv

Expected output should look like this:

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

​Decision Toolkit server is started. This server accepts connections from all available network interfaces 0.0.0.0 and listens on port 22022. During startup, the Decision Toolkit 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 Decision Toolkit server has found the dm directory containing one decision model file named dm.dmn. This file was loaded, and one invocable was deployed, a decision named Greeting Message.

This invocable can be evaluated by calling the following endpoint:

http://0.0.0.0:22022/evaluate/dm/org/decision-toolkit/0001/Greeting%20Message

To stop the Decision Toolkit server, press Ctrl+C.

The list of all deployed invocables with the endpoint names can be displayed during server startup by specifying the option -v or --verbose, like shown below:

shell
$ dsntk srv -v
Found 1 model.
Loaded 1 model.
Deployed 1 invocable.

Deployed invocables:
  dm/org/decision-toolkit/greetings/Greeting%20Message

dsntk 0.0.0.0:22022

Evaluating invocables ​

After starting the Decision Toolkit server, the deployed invocable can be evaluated by calling its endpoint with required input data, using, e.g. curl. In a separate terminal type:

shell
$ curl -s -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

The expected output should be:

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

The Decision Toolkit's version of a hello world program could look like this:

shell
$ curl -s -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 is:

text
{"data":"Hello world"}

Endpoint names ​

The common endpoint for evaluating invocables exposed by the Decision Toolkit 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

  • common 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 pu between Greeting and Message, which represents a space in percent-encoding. See RFC3986 for more details.