Chapter 4. Options for invoking a DMN model

To invoke a decision that is defined in a DMN file, you must first package the file in a KIE container. A specific version of knowledge components comes in a knowledge JAR (KJAR), which you can either deploy to Decision Server for remote access, or manipulate directly as a dependency of the calling application. Covering all options for creating and deploying these knowledge packages is outside the scope of this document, although most are similar to other knowledge assets (for example, a Drools rule file or jBPM process definition). After you have packaged or deployed the decision, you have several options for invoking it.

4.1. Embedding a DMN call directly into the Java application

A KIE container is local when the knowledge assets are either embedded directly into the calling program, or are physically pulled in using Maven dependencies for the KJAR. You should embed knowledge assets directly into a project if there is a tight relationship between the version of the code and the version of the DMN definition. Any changes to the decision should only take effect after you have intentionally updated and redeployed the application. One potential benefit of this approach is that proper operation does not rely on any external dependencies to the runtime, which can be a limitation of locked down environments.

Using Maven dependencies enables further flexibility because the specific version of the decision can dynamically change, for example by using a system property, and it can be periodically scanned for updates and automatically updated. This introduces an external dependency on the deploy time of the service, but executes the decision locally, reducing reliance on an external service being available during runtime.

Prerequisites

A KJAR containing the DMN model to execute has been created.
The following dependencies have been added to the pom.xml file of the project:

<!-- Required for the DMN runtime API -->
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-dmn-core</artifactId>
  <version>${drools-version}</version>
</dependency>

<!-- Required if not using classpath kie container -->
<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-ci</artifactId>
  <version>${drools-version}</version>
</dependency>

Note

${drools-version} is a Maven property that should resolve to the precise version used for other KIE / Drools dependencies at runtime.

Procedure

Create a KIE container from classpath or ReleaseId:

KieServices kieServices = KieServices.Factory.get();

ReleaseId releaseId = kieServices.newReleaseId( "org.acme", "my-kjar", "1.0.0" );
KieContainer kieContainer = kieServices.newKieContainer( releaseId );

Alternative option:

KieServices kieServices = KieServices.Factory.get();

KieContainer kieContainer = kieServices.getKieClasspathContainer();

Obtain DMNRuntime from the KIE container and a reference to the DMN model to be evaluated, by using the model namespace and modelName:

DMNRuntime dmnRuntime = kieContainer.newKieSession().getKieRuntime(DMNRuntime.class);

String namespace = "http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a";
String modelName = "dmn-movieticket-ageclassification";

DMNModel dmnModel = dmnRuntime.getModel(namespace, modelName);

Execute the decision services for the desired model:

DMNContext dmnContext = dmnRuntime.newContext();  1

for (Integer age : Arrays.asList(1,12,13,64,65,66)) {
  dmnContext.set("Age", age);  2
  DMNResult dmnResult = dmnRuntime.evaluateAll(dmnModel, dmnContext);  3
  for (DMNDecisionResult dr : dmnResult.getDecisionResults()) {  4
    log.info("Age " + age + " Decision '" + dr.getDecisionName() + "' : " + dr.getResult());
  }
}

1: Instantiate a new DMN Context to be the input for the model evaluation. Note that this example is looping through the Age Classification decision multiple times.
2: Assign input variables for the input DMN context.
3: Evaluate all DMN decisions defined in the DMN model.
4: Each evaluation may result in one or more results, creating the loop.

This example prints the following output:

Age 1 Decision 'AgeClassification' : Child
Age 12 Decision 'AgeClassification' : Child
Age 13 Decision 'AgeClassification' : Adult
Age 64 Decision 'AgeClassification' : Adult
Age 65 Decision 'AgeClassification' : Senior
Age 66 Decision 'AgeClassification' : Senior

4.2. Executing DMN services remotely on Decision Server (Java)

The KIE remote API client provides a lightweight approach to invoking a remote DMN service either through the REST or JMS interfaces of Decision Server. This approach reduces the number of runtime dependencies necessary to interact with a knowledge base. Decoupling the calling code from the decision definition also increases flexibility by enabling them to iterate independently at the appropriate pace.

Prerequisites

Decision Server is installed and configured, including a known user name and credentials for a user with the kie-server role.
A KIE container is deployed in Decision Server in the form of a KJAR that includes the DMN model.
The container ID of the KIE container containing the DMN model. If more than one model is present, you must also know the model namespace and model name of the relevant model.
The following dependency is added to the pom.xml file of the project:

<dependency>
  <groupId>org.kie.server</groupId>
  <artifactId>kie-server-client</artifactId>
  <version>${drools-version}</version>
</dependency>

Note

${drools-version} is a Maven property that should resolve to the precise version used for other KIE / Drools dependencies at runtime.

Procedure

Instantiate a KieServicesClient instance with the appropriate connection information.
Example:
```
KieServicesConfiguration conf =
    KieServicesFactory.newRestConfiguration(URL, USER, PASSWORD); 1

conf.setMarshallingFormat(MarshallingFormat.JSON);  2

KieServicesClient kieServicesClient = KieServicesFactory.newKieServicesClient(conf);
```
1
The connection information:
Example URL: http://localhost:8080/kie-server/services/rest/server
The credentials should reference a user with the kie-server role.
2
The Marshalling format is an instance of org.kie.server.api.marshalling.MarshallingFormat. It controls whether the messages will be JSON or XML. Options for Marshalling format are JSON, JAXB, or XSTREAM.
Obtain a DMNServicesClient from the KIE server Java client connected to the related Decision Server by invoking the method getServicesClient() on the KIE server Java client instance:
```
DMNServicesClient dmnClient = kieServicesClient.getServicesClient(DMNServicesClient.class );
```
The dmnClient can now execute decision services on Decision Server.
Execute the decision services for the desired model.
Example:
```
for (Integer age : Arrays.asList(1,12,13,64,65,66)) {
	DMNContext dmnContext = dmnClient.newContext(); 1
	dmnContext.set("Age", age);       2
	ServiceResponse<DMNResult> serverResp =           3
			dmnClient.evaluateAll($kieContainerId,
					$modelNamespace,
					$modelName,
					dmnContext);

	DMNResult dmnResult = serverResp.getResult();   4
	for (DMNDecisionResult dr : dmnResult.getDecisionResults()) {
		log.info("Age " + age + " Decision '" + dr.getDecisionName() + "' : " + dr.getResult());
	}
}
```
1
Instantiate a new DMN Context to be the input for the model evaluation. Note that this example is looping through the Age Classification decision multiple times.
2
Assign input variables for the input DMN Context.
3
Evaluate all the DMN Decisions defined in the DMN model:
$kieContainerId is the ID of the container where the KJAR containing the DMN model is deployed
$modelNamespace is the namespace for the model.
$modelName is the name for the model.
4
The DMN Result object is available from the server response.
At this point, the dmnResult contains all the decision results from the evaluated DMN model.
Note
You can also execute only a specific DMN Decision in the model, by making use of alternative methods of the DMNServicesClient.
Tip
If the KIE container only contains one DMN Model, you can omit $modelNamespace and $modelName because the KIE API will select it by default.

4.3. Calling a DMN service on a remote server using REST APIs

Directly interacting with the REST endpoints of Decision Server provides the most separation between the calling code and the decision logic definition. The calling code is completely free of direct dependencies, and you can implement it in an entirely different development platform such as node.js or .net. The examples in this section demonstrate Nix-style curl commands but provide relevant information to adapt to any REST client.

Prerequisites

Decision Server is installed and configured, including service user accounts to allow access.
A KIE container is deployed in Decision Server in the form of a KJAR that includes the DMN model.
The container ID of the KIE container containing the DMN model. If more than one model is present, you must also know the model namespace and model name of the relevant model.

Procedure

Determine the base URL for accessing the REST endpoints. This requires knowing the following values (with the default local deployment values as an example):
- Host (localhost)
- Port (8080)
- Root context (kie-server)
- Base REST path (services/rest/server)
Local deployment example URL:
```
http://localhost:8080/kie-server/services/rest/server
```
Determine user authentication requirements.
When users are defined directly in the Decision Server configuration, BasicAuth is used which requires the user name and password. Successful requests require that the user have the kie-server role.
The following example demonstrates how to add credentials to a curl request:
```
curl -u username:password <request>
```
If Decision Server is configured with Red Hat Single Sign-On, the request must include a bearer token:
```
curl -H "Authorization: bearer $TOKEN" <request>
```
Specify the format of the request and response. The REST endpoints work with both JSON and XML formats and are set using request headers.
JSON
```
curl -H "accept: application/json" -H "content-type: application/json"
```
XML
```
curl -H "accept: application/xml" -H "content-type: application/xml"
```

(Optional) Query the container for a list of deployed decision models:

[GET] /containers/CONTAINER_ID/dmn

Example curl request:

curl -u krisv:krisv -H "accept: application/xml" -X GET "http://localhost:8080/kie-server/services/rest/server/containers/MovieDMNContainer/dmn"

Sample XML output:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response type="SUCCESS" msg="OK models successfully retrieved from container 'MovieDMNContainer'">
    <dmn-model-info-list>
        <model>
            <model-namespace>http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a</model-namespace>
            <model-name>dmn-movieticket-ageclassification</model-name>
            <model-id>_99</model-id>
            <decisions>
                <dmn-decision-info>
                    <decision-id>_3</decision-id>
                    <decision-name>AgeClassification</decision-name>
                </dmn-decision-info>
            </decisions>
        </model>
    </dmn-model-info-list>
</response>

Sample JSON output:

{
  "type" : "SUCCESS",
  "msg" : "OK models successfully retrieved from container 'MovieDMNContainer'",
  "result" : {
    "dmn-model-info-list" : {
      "models" : [ {
        "model-namespace" : "http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a",
        "model-name" : "dmn-movieticket-ageclassification",
        "model-id" : "_99",
        "decisions" : [ {
          "decision-id" : "_3",
          "decision-name" : "AgeClassification"
        } ]
      } ]
    }
  }
}

Execute the model:

[POST] /containers/CONTAINER_ID/dmn

Example curl request:

curl -u krisv:krisv -H "accept: application/json" -H "content-type: application/json" -X POST "http://localhost:8080/kie-server/services/rest/server/containers/MovieDMNContainer/dmn" -d "{ \"model-namespace\" : \"http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a\", \"model-name\" : \"dmn-movieticket-ageclassification\", \"decision-name\" : [ ], \"decision-id\" : [ ], \"dmn-context\" : {\"Age\" : 66}}"

Example JSON request:

{
  "model-namespace" : "http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a",
  "model-name" : "dmn-movieticket-ageclassification",
  "decision-name" : [ ],
  "decision-id" : [ ],
  "dmn-context" : {"Age" : 66}
}

Example XML request (JAXB style):

<?xml version="1.0" encoding="UTF-8"?>
<dmn-evaluation-context>
    <model-namespace>http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a</model-namespace>
    <model-name>dmn-movieticket-ageclassification</model-name>
    <dmn-context xsi:type="jaxbListWrapper" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <type>MAP</type>
        <element xsi:type="jaxbStringObjectPair" key="Age">
            <value xsi:type="xs:int" xmlns:xs="http://www.w3.org/2001/XMLSchema">66</value>
        </element>
    </dmn-context>
</dmn-evaluation-context>

Note

Regardless of the request format, the request requires the following elements:

Model namespace
Model name
Context object containing input values

Example JSON response:

{
  "type" : "SUCCESS",
  "msg" : "OK from container 'MovieDMNContainer'",
  "result" : {
    "dmn-evaluation-result" : {
      "messages" : [ ],
      "model-namespace" : "http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a",
      "model-name" : "dmn-movieticket-ageclassification",
      "decision-name" : [ ],
      "dmn-context" : {
        "Age" : 66,
        "AgeClassification" : "Senior"
      },
      "decision-results" : {
        "_3" : {
          "messages" : [ ],
          "decision-id" : "_3",
          "decision-name" : "AgeClassification",
          "result" : "Senior",
          "status" : "SUCCEEDED"
        }
      }
    }
  }
}

Example XML (JAXB format) response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response type="SUCCESS" msg="OK from container 'MovieDMNContainer'">
      <dmn-evaluation-result>
            <model-namespace>http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a</model-namespace>
            <model-name>dmn-movieticket-ageclassification</model-name>
            <dmn-context xsi:type="jaxbListWrapper" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <type>MAP</type>
                  <element xsi:type="jaxbStringObjectPair" key="Age">
                        <value xsi:type="xs:int" xmlns:xs="http://www.w3.org/2001/XMLSchema">66</value>
                  </element>
                  <element xsi:type="jaxbStringObjectPair" key="AgeClassification">
                        <value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">Senior</value>
                  </element>
            </dmn-context>
            <messages/>
            <decisionResults>
                  <entry>
                        <key>_3</key>
                        <value>
                              <decision-id>_3</decision-id>
                              <decision-name>AgeClassification</decision-name>
                              <result xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Senior</result>
                              <messages/>
                              <status>SUCCEEDED</status>
                        </value>
                  </entry>
            </decisionResults>
      </dmn-evaluation-result>
</response>

Where did the comment section go?

Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.

Log in to Your Red Hat Account

Red Hat Account

Customer Portal

Select Your Language

Infrastructure and Management

Cloud Computing

Storage

JBoss Development and Management

JBoss Integration and Automation

Mobile

Services

Tools

Red Hat Product Security Center

Security Updates

Resources

Customer Portal Community

Customer Events

Stories

Chapter 4. Options for invoking a DMN model

4.1. Embedding a DMN call directly into the Java application

4.2. Executing DMN services remotely on Decision Server (Java)

4.3. Calling a DMN service on a remote server using REST APIs

Where did the comment section go?