Chapter 7. DMN model execution

Procedure

1. In your client application, add the following dependencies to the relevant classpath of your Java project:

   <!-- Required for the DMN runtime API -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-dmn-core</artifactId>
     <version>${rhpam.version}</version>
   </dependency>
   
   <!-- Required if not using classpath KIE container -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-ci</artifactId>
     <version>${rhpam.version}</version>
   </dependency>

   The <version> is the Maven artifact version for Red Hat Process Automation Manager currently used in your project (for example, 7.67.0.Final-redhat-00024).

   Note

   Instead of specifying a Red Hat Process Automation Manager <version> for individual dependencies, consider adding the Red Hat Business Automation bill of materials (BOM) dependency to your project pom.xml file. The Red Hat Business Automation BOM applies to both Red Hat Decision Manager and Red Hat Process Automation Manager. When you add the BOM files, the correct versions of transitive dependencies from the provided Maven repositories are included in the project.

   Example BOM dependency:

   <dependency>
     <groupId>com.redhat.ba</groupId>
     <artifactId>ba-platform-bom</artifactId>
     <version>7.13.5.redhat-00002</version>
     <scope>import</scope>
     <type>pom</type>
   </dependency>

   For more information about the Red Hat Business Automation BOM, see What is the mapping between RHPAM product and maven library version?.

2. 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();

3. 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 = KieRuntimeFactory.of(kieContainer.getKieBase()).get(DMNRuntime.class);
   
   String namespace = "http://www.redhat.com/_c7328033-c355-43cd-b616-0aceef80e52a";
   String modelName = "dmn-movieticket-ageclassification";
   
   DMNModel dmnModel = dmnRuntime.getModel(namespace, modelName);

4. 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() + "', " +
                    "Result: " + 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

   If the DMN model was not previously compiled as an executable model for more efficient execution, you can enable the following property when you execute your DMN models:

   -Dorg.kie.dmn.compiler.execmodel=true

Procedure

1. In your client application, add the following dependency to the relevant classpath of your Java project:

   <!-- Required for the KIE Server Java client API -->
   <dependency>
     <groupId>org.kie.server</groupId>
     <artifactId>kie-server-client</artifactId>
     <version>${rhpam.version}</version>
   </dependency>

   The <version> is the Maven artifact version for Red Hat Process Automation Manager currently used in your project (for example, 7.67.0.Final-redhat-00024).

   Note

   Instead of specifying a Red Hat Process Automation Manager <version> for individual dependencies, consider adding the Red Hat Business Automation bill of materials (BOM) dependency to your project pom.xml file. The Red Hat Business Automation BOM applies to both Red Hat Decision Manager and Red Hat Process Automation Manager. When you add the BOM files, the correct versions of transitive dependencies from the provided Maven repositories are included in the project.

   Example BOM dependency:

   <dependency>
     <groupId>com.redhat.ba</groupId>
     <artifactId>ba-platform-bom</artifactId>
     <version>7.13.5.redhat-00002</version>
     <scope>import</scope>
     <type>pom</type>
   </dependency>

   For more information about the Red Hat Business Automation BOM, see What is the mapping between RHPAM product and maven library version?.

2. 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.

3. Obtain a DMNServicesClient from the KIE server Java client connected to the related KIE 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 KIE Server.

4. 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() + "', " +
                    "Result: " + 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.

   You can also execute only a specific DMN decision in the model by using alternative methods of the DMNServicesClient.

   Note

   If the KIE container only contains one DMN model, you can omit $modelNamespace and $modelName because the KIE Server API selects it by default.

Procedure

1. Determine the base URL for accessing the KIE Server REST API 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/)

   Example base URL in local deployment:

   http://localhost:8080/kie-server/services/rest/

2. Determine user authentication requirements.

   When users are defined directly in the KIE Server configuration, HTTP Basic authentication is used and 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 KIE Server is configured with Red Hat Single Sign-On, the request must include a bearer token:

   curl -H "Authorization: bearer $TOKEN" <request>

3. Specify the format of the request and response. The REST API 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"

4. Optional: Query the container for a list of deployed decision models:

   [GET] server/containers/{containerId}/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"
           } ]
         } ]
       }
     }
   }

5. Execute the model:

   [POST] server/containers/{containerId}/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 format):

   <?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>