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.