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 and the current directory contains only the examples directory (see Saving examples for details).
$ ls
The expected output should be:
examples
Running a server
To run Decision Toolkit as a 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
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 having .dmn extension.
In our example, during directory scanning, the Decision Toolkit server has found the examples directory containing one subdirectory named e2 with decision model file named e2.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/examples/e2/io/dsntk/2_0001/compliance-level-2-test-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:
$ 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 invocables
Having the Decision Toolkit server started, the deployed invocable can be evaluated by calling its endpoint with required input data, using, e.g. curl:
$ 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
The expected output should be:
{"data":"Hello John Doe"}
The Decision Toolkit's 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
Expected output:
{"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:
protocol:
http://
orhttps://
host address:
0.0.0.0
or127.0.0.1
ormy.domain.com
common endpoint name:
evaluate
directory names where the file containing the DMN™ model was found during scanning:
examples/e2
model namespace converted to RDNN-like path:
io/dsntk/2_0001/compliance-level-2-test-0001
the name of the invocable:
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 URLs, there is %20
between Greeting
and Message
, which represents a space in percent-encoding. See RFC3986 for more details.