Designing a decision service using DMN models

Procedure

1. In Business Central, go to Menu → Design → Projects, click the project name, and select the DMN file you want to modify.

2. In the DMN designer canvas, select a decision node or business knowledge model that you want to define and click the Edit icon to open the DMN boxed expression designer:

   Figure 3.8. Opening a new decision node boxed expression

   

   View larger image

   

   Figure 3.9. Opening a new business knowledge model boxed expression

   

   View larger image

   

   By default, all business knowledge models are defined as boxed function expressions containing a literal FEEL expression, a nested context expression of an external JAVA or PMML function, or a nested boxed expression of any type.

   For decision nodes, you click the undefined table to select the type of boxed expression you want to use, such as a boxed literal expression, boxed context expression, decision table, or other DMN boxed expression.

   

   View larger image

   

   For business knowledge models, you click the top-left function cell to select the function type, or right-click the function value cell, select Clear, and select a boxed expression of another type.

   

   View larger image

   

3. For this example, use a decision node and select Decision Table as the boxed expression type.

   A decision table in DMN is a visual representation of one or more rules in a tabular format. Each rule consists of a single row in the table, and includes columns that define the conditions (input) and outcome (output) for that particular row.

4. Click the input column header to define the name and data type for the input condition. For example, name the input column Credit Score.FICO with a number data type. This column specifies numeric credit score values or ranges of loan applicants.

5. Click the output column header to define the name and data type for the output values. For example, name the output column Credit Score Rating and next to the Data Type option, click Manage to go to the Data Types page where you can create a custom data type with score ratings as constraints.

   

   View larger image

   

6. On the Data Types page, click Add and create a Credit_Score_Rating data type as a string.

   

   View larger image

   

7. Click Constraints, select Enumeration from the drop-down options, and add the following constraints:

   • "Excellent"
   • "Good"
   • "Fair"
   • "Poor"
   • "Bad"
   

   View larger image

   

   For information about constraint types and syntax requirements for the specified data type, see the Decision Model and Notation specification.

8. Click Ok to save the constraints and click Save to save the data type.
9. Return to the Credit Score Rating decision table, click the Credit Score Rating column header, and set the data type to this new custom data type.

10. Use the Credit Score.FICO input column to define credit score values or ranges of values, and use the Credit Score Rating column to specify one of the corresponding ratings you defined in the Credit_Score_Rating data type.

    Right-click any value cell to insert or delete rows (rules) or columns (clauses).

    Figure 3.10. Decision node decision table for credit score rating

    

    View larger image

    

11. After you define all rules, click the top-left corner of the decision table to define the rule Hit Policy and Builtin Aggregator (for COLLECT hit policy only).

    The hit policy determines how to reach an outcome when multiple rules in a decision table match the provided input values. The built-in aggregator determines how to aggregate rule values when you use the COLLECT hit policy.

    

    View larger image

    

    The following example is a more complex decision table that determines applicant qualification for a loan as the concluding decision node in the same loan prequalification decision model:

    Figure 3.11. Decision table for loan prequalification

    

    View larger image

    

Procedure

1. In Business Central, go to Menu → Design → Projects, click the project name, and select the DMN file you want to modify.
2. In the DMN designer canvas, select a decision node or business knowledge model for which you want to define the data types and click the Edit icon to open the DMN boxed expression designer.

3. If the boxed expression is for a decision node that is not yet defined, click the undefined table to select the type of boxed expression you want to use, such as a boxed literal expression, boxed context expression, decision table, or other DMN boxed expression.

   

   View larger image

   

4. Click the cell for the table header, column header, or parameter field (depending on the boxed expression type) for which you want to define the data type and click Manage to go to the Data Types page where you can create a custom data type.

   

   View larger image

   

   You can also set and manage custom output data types for a specified decision node or business knowledge model node by selecting the Diagram properties icon in the upper-right corner of the DMN designer:

   

   View larger image

   

   The data type that you define for a specified cell in a boxed expression determines the structure of the data that you use within that associated table, column, or field in the boxed expression.

   In this example, an output column Credit Score Rating for a DMN decision table defines a set of custom credit score ratings based on an applicant’s credit score.

5. On the Data Types page, click Add and create a Credit_Score_Rating data type as a string.

   

   View larger image

   

   If the data type requires a list of items, enable the List setting.

6. Click Constraints, select Enumeration from the drop-down options, and add the following constraints:

   • "Excellent"
   • "Good"
   • "Fair"
   • "Poor"
   • "Bad"
   

   View larger image

   

   For information about constraint types and syntax requirements for the specified data type, see the Decision Model and Notation specification.

7. Click Ok to save the constraints and click Save to save the data type.

8. Return to the Credit Score Rating decision table, click the Credit Score Rating column header, set the data type to this new custom data type, and define the rule values for that column with the rating constraints that you specified.

   Figure 3.14. Decision table for credit score rating

   

   View larger image

   

   In the DMN decision model for this scenario, the Credit Score Rating decision flows into the following Loan Prequalification decision that also requires custom data types:

   

   View larger image

   
9. Continuing with this example, return to the Data Types window, click Add, and create a Loan_Qualification data type as a Structure with no constraints.

10. Next to the Loan_Qualification data type, select the settings icon (three vertical dots) and select Insert nested field to insert sub-fields within this parent data type.

    

    View larger image

    

    You can use these sub-fields in association with the parent structured data type in boxed expressions, such as nested column headers in decision tables or nested table parameters in context or function expressions.

11. For this example, under the structured Loan_Qualification data type, add a Qualification field with "Qualified" and "Not Qualified" enumeration constraints, and a Reason field with no constraints. Add also a simple Back_End_Ratio and a Front_End_Ratio data type, both with "Sufficient" and "Insufficient" enumeration constraints.

    Click Save for each data type that you create.

    

    View larger image

    

12. Return to the decision table and, for each column, click the column header cell, set the data type to the new corresponding custom data type, and define the rule values as needed for the column with the constraints that you specified, if applicable.

    Figure 3.15. Decision table for loan prequalification

    

    View larger image

    

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>${rhdm.version}</version>
   </dependency>
   
   <!-- Required if not using classpath KIE container -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-ci</artifactId>
     <version>${rhdm.version}</version>
   </dependency>

   Copy to Clipboard Toggle word wrap

   The <version> is the Maven artifact version for Red Hat Decision Manager currently used in your project (for example, 7.18.0.Final-redhat-00002).

   Note

   Instead of specifying a Red Hat Decision 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.3.0.GA-redhat-00002</version>
     <scope>import</scope>
     <type>pom</type>
   </dependency>

   Copy to Clipboard Toggle word wrap

   For more information about the Red Hat Business Automation BOM, see What is the mapping between RHDM 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 );

   Copy to Clipboard Toggle word wrap

   Alternative option:

   KieServices kieServices = KieServices.Factory.get();
   
   KieContainer kieContainer = kieServices.getKieClasspathContainer();

   Copy to Clipboard Toggle word wrap

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);

   Copy to Clipboard Toggle word wrap

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());
     }
   }

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

   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

   Copy to Clipboard Toggle word wrap

Procedure

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

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

   Copy to Clipboard Toggle word wrap

   The <version> is the Maven artifact version for Red Hat Decision Manager currently used in your project (for example, 7.18.0.Final-redhat-00002).

   Note

   Instead of specifying a Red Hat Decision 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.3.0.GA-redhat-00002</version>
     <scope>import</scope>
     <type>pom</type>
   </dependency>

   Copy to Clipboard Toggle word wrap

   For more information about the Red Hat Business Automation BOM, see What is the mapping between RHDM 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);

   Copy to Clipboard Toggle word wrap

   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 Decision Server by invoking the method getServicesClient() on the KIE server Java client instance:

   DMNServicesClient dmnClient = kieServicesClient.getServicesClient(DMNServicesClient.class );

   Copy to Clipboard Toggle word wrap

   The dmnClient can now execute decision services on Decision 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());
       }
   }

   Copy to Clipboard Toggle word wrap

   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 Decision Server API selects it by default.

Procedure

1. Determine the base URL for accessing the Decision 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 Decision 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>

   Copy to Clipboard Toggle word wrap

   If Decision Server is configured with Red Hat Single Sign-On, the request must include a bearer token:

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

   Copy to Clipboard Toggle word wrap

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"

   Copy to Clipboard Toggle word wrap

   XML

   curl -H "accept: application/xml" -H "content-type: application/xml"

   Copy to Clipboard Toggle word wrap

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"

   Copy to Clipboard Toggle word wrap

   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>

   Copy to Clipboard Toggle word wrap

   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"
           } ]
         } ]
       }
     }
   }

   Copy to Clipboard Toggle word wrap

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}}"

   Copy to Clipboard Toggle word wrap

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

   Copy to Clipboard Toggle word wrap

   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>

   Copy to Clipboard Toggle word wrap
   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"
           }
         }
       }
     }
   }

   Copy to Clipboard Toggle word wrap

   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>

   Copy to Clipboard Toggle word wrap