Developing decision services in Red Hat Decision Manager

Procedure

1. In your VS Code IDE, select the Extensions menu option and search for Red Hat Business Automation Bundle for DMN, BPMN, and test scenario file support.

   For DMN or BPMN file support only, you can also search for the individual DMN Editor or BPMN Editor extensions.

2. When the Red Hat Business Automation Bundle extension appears in VS Code, select it and click Install.
3. For optimal VS Code editor behavior, after the extension installation is complete, reload or close and re-launch your instance of VS Code.

Procedure

1. Install the standalone editors using one of the following methods:

   Download each JavaScript file manually: For this method, follow these steps:

   1. Download the JavaScript files.
   2. Add the downloaded Javascript files to your hosted application.

   3. Add the following <script> tag to your HTML page:

      Script tag for your HTML page for the DMN editor

      <script src="https://<YOUR_PAGE>/dmn/index.js"></script>

      Script tag for your HTML page for the BPMN editor

      <script src="https://<YOUR_PAGE>/bpmn/index.js"></script>

   Use the NPM package: For this method, follow these steps:

   1. Add the NPM package to your package.json file:

      Adding the NPM package

      npm install @kie-tools/kie-editors-standalone

   2. Import each editor library to your TypeScript file:

      Importing each editor

      import * as DmnEditor from "@kie-tools/kie-editors-standalone/dist/dmn"
      import * as BpmnEditor from "@kie-tools/kie-editors-standalone/dist/bpmn"

2. After you install the standalone editors, open the required editor by using the provided editor API, as shown in the following example for opening a DMN editor. The API is the same for each editor.

   Opening the DMN standalone editor

   const editor = DmnEditor.open({
     container: document.getElementById("dmn-editor-container"),
     initialContent: Promise.resolve(""),
     readOnly: false,
     origin: "",
     resources: new Map([
       [
         "MyIncludedModel.dmn",
         {
           contentType: "text",
           content: Promise.resolve("")
         }
       ]
     ])
   });

   Use the following parameters with the editor API:

   Table 2.1. Example parameters

   Parameter	Description
   container	HTML element in which the editor is appended.
   initialContent	Promise to a DMN model content. This parameter can be empty, as shown in the following examples: Promise.resolve("") Promise.resolve("<DIAGRAM_CONTENT_DIRECTLY_HERE>") fetch("MyDmnModel.dmn").then(content ⇒ content.text())
   readOnly (Optional)	Enables you to allow changes in the editor. Set to false (default) to allow content editing and true for read-only mode in editor.
   origin (Optional)	Origin of the repository. The default value is window.location.origin.
   resources (Optional)	Map of resources for the editor. For example, this parameter is used to provide included models for the DMN editor or work item definitions for the BPMN editor. Each entry in the map contains a resource name and an object that consists of content-type (text or binary) and content (similar to the initialContent parameter).

   The returned object contains the methods that are required to manipulate the editor.

   Table 2.2. Returned object methods

   Method	Description
   getContent(): Promise<string>	Returns a promise containing the editor content.
   setContent(path: string, content: string): void	Sets the content of the editor.
   getPreview(): Promise<string>	Returns a promise containing an SVG string of the current diagram.
   subscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): (isDirty: boolean) ⇒ void	Sets a callback to be called when the content changes in the editor and returns the same callback to be used for unsubscription.
   unsubscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): void	Unsubscribes the passed callback when the content changes in the editor.
   markAsSaved(): void	Resets the editor state that indicates that the content in the editor is saved. Also, it activates the subscribed callbacks related to content change.
   undo(): void	Undoes the last change in the editor. Also, it activates the subscribed callbacks related to content change.
   redo(): void	Redoes the last undone change in the editor. Also, it activates the subscribed callbacks related to content change.
   close(): void	Closes the editor.
   getElementPosition(selector: string): Promise<Rect>	Provides an alternative to extend the standard query selector when an element lives inside a canvas or a video component. The selector parameter must follow the <PROVIDER>:::<SELECT> format, such as Canvas:::MySquare or Video:::PresenterHand. This method returns a Rect representing the element position.
   envelopeApi: MessageBusClientApi<KogitoEditorEnvelopeApi>	This is an advanced editor API. For more information about advanced editor API, see MessageBusClientApi and KogitoEditorEnvelopeApi.

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 node that you want to define and click the Edit icon to open the DMN boxed expression designer:

   Figure 6.11. Opening a new decision node boxed expression

   

   Figure 6.12. Opening a new business knowledge model boxed expression

   

   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.

   Figure 6.13. Selecting the logic type for a decision node

   

   For business knowledge model nodes, 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.

   Figure 6.14. Selecting the function or other logic type for a business knowledge model

   

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.

   Figure 6.15. Managing data types for a column header value

   

6. On the Data Types page, click New Data Type to add a new data type or click Import Data Object to import an existing data object from your project that you want to use as a DMN data type.

   If you import a data object from your project as a DMN data type and then that object is updated, you must re-import the data object as a DMN data type to apply the changes in your DMN model.

   For this example, click New Data Type and create a Credit_Score_Rating data type as a string:

   Figure 6.16. Adding a new data type

   

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

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

   Figure 6.17. Adding constraints to the new data type

   

   To change the order of data type constraints, you can click the left end of the constraint row and drag the row as needed:

   Figure 6.18. Dragging constraints to change constraint order

   

   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 the check mark to the right of the data type 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 6.19. Decision node decision table for credit score rating

    

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.

    Figure 6.20. Defining the decision table hit policy

    

    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 6.21. Decision table for loan prequalification

    

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.

   Figure 6.24. Selecting the logic type for a decision node

   

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.

   Figure 6.25. Managing data types for a column header value

   

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

   Figure 6.26. Managing data types in decision requirements diagram (DRD) properties

   

   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 New Data Type to add a new data type or click Import Data Object to import an existing data object from your project that you want to use as a DMN data type.

   If you import a data object from your project as a DMN data type and then that object is updated, you must re-import the data object as a DMN data type to apply the changes in your DMN model.

   For this example, click New Data Type and create a Credit_Score_Rating data type as a string:

   Figure 6.27. Adding a new data type

   

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

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

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

   Figure 6.28. Adding constraints to the new data type

   

   To change the order of data type constraints, you can click the left end of the constraint row and drag the row as needed:

   Figure 6.29. Dragging constraints to change constraint order

   

   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 the check mark to the right of the data type 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 6.30. Decision table for credit score rating

   

   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:

   Figure 6.31. Decision table for loan prequalification

   

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

   When you save the new structured data type, the first sub-field appears so that you can begin defining nested data fields in this parent data type. 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.

   For additional sub-fields, select the addition icon next to the Loan_Qualification data type:

   Figure 6.32. Adding a new structured data type with nested fields

   

10. 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 the check mark to the right of each data type that you create to save your changes.

    Figure 6.33. Adding nested data types with constraints

    

    To change the order or nesting of data types, you can click the left end of the data type row and drag the row as needed:

    Figure 6.34. Dragging data types to change data type order or nesting

    

11. 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 6.35. Decision table for loan prequalification

    

Procedure

1. In Business Central, navigate to your DMN project and create or import a DMN file in the project.
2. Open the new or imported DMN file to view the DRD in the DMN designer, and begin designing or modifying the DRD using the DMN nodes in the left toolbar.

3. For any DMN nodes that you want to define in a separate nested DRD, select the node, click the DRD Actions icon, and select from the available options.

   Figure 6.49. DRD actions icon for subdividing a DRD

   

   The following options are available:

   • Create: Use this option to create a nested DRD where you can separately define the DMN components and diagram for the selected node.
   • Add to: If you already created a nested DRD, use this option to add the selected node to an existing DRD.
   • Remove: If the node that you selected is already within a nested DRD, use this option to remove the node from that nested DRD.

   After you create a nested DRD within your DMN decision model, the new DRD opens in a separate DRD canvas and the available DRD and components are listed in the Decision Navigator left menu. You can use the Decision Navigator menu to rename or remove a nested DRD.

   Figure 6.50. Rename new nested DRD in the Decision Navigator menu

   
4. In the separate canvas for the new nested DRD, design the flow and logic for all required components in this portion of the DMN model, as usual.

5. Continue adding and defining any other nested DRDs for your decision model and save the completed DMN file.

   For example, the following DRD for a loan prequalification decision model contains all DMN components for the model without any nested DRDs. This example relies on the single DRD for all components and logic, resulting in a large and complex diagram.

   Figure 6.51. Single DRD for loan prequalification

   

   Alternatively, by following the steps in this procedure, you can divide this example DRD into multiple nested DRDs to better organize the decision requirements, as shown in the following example:

   Figure 6.52. Multiple nested DRDs for loan prequalification

   

   Figure 6.53. Overview of front end ratio DRD

   

   Figure 6.54. DRD for front end ratio

   

   Figure 6.55. Overview of credit score rating DRD

   

   Figure 6.56. DRD for credit score rating

   

   Figure 6.57. Overview of back end ratio DRD

   

   Figure 6.58. DRD for back end ratio

   

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 Decision Manager currently used in your project (for example, 7.67.0.Final-redhat-00024).

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

   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 Decision Manager currently used in your project (for example, 7.67.0.Final-redhat-00024).

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

   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>

Procedure

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

   <!-- Required for the PMML compiler -->
   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>kie-pmml-dependencies</artifactId>
     <version>${rhpam.version}</version>
   </dependency>
   
   <!-- Required for the KIE public API -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-api</artifactId>
     <version>${rhpam.version}</version>
   </dependencies>
   
   <!-- 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 Decision Manager currently used in your project (for example, 7.67.0.Final-redhat-00024).

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

   Alternative option:

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

3. Create an instance of the PMMLRuntime that is used to execute the model:

   PMMLRuntime pmmlRuntime = KieRuntimeFactory.of(kieContainer.getKieBase()).get(PMMLRuntime.class);

4. Create an instance of the PMMLRequestData class that applies your PMML model to a data set:

   PMMLRequestData pmmlRequestData = new PMMLRequestData({correlation_id}, {model_name});
   pmmlRequestData.addRequestParam({parameter_name}, {parameter_value})
   ...

5. Create an instance of the PMMLContext class that contains the input data:

   PMMLContext pmmlContext = new PMMLContextImpl(pmmlRequestData);

6. Retrieve the PMML4Result while executing the PMML model with the required PMML class instances that you created:

   PMML4Result pmml4Result = pmmlRuntime.evaluate({model_name}, pmmlContext);

Procedure

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

   <!-- Required for the PMML compiler -->
   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>kie-pmml</artifactId>
     <version>${rhpam.version}</version>
   </dependency>
   
   <!-- Required for the KIE public API -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-api</artifactId>
     <version>${rhpam.version}</version>
   </dependencies>
   
   <!-- 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 Decision Manager currently used in your project (for example, 7.67.0.Final-redhat-00024).

   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.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 RHDM product and maven library version?.

   Important

   To use the legacy implementation, ensure that the kie-pmml-implementation system property is set as legacy.

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. Create an instance of the PMMLRequestData class, which applies your PMML model to a set of data:

   public class PMMLRequestData {
       private String correlationId; 1
       private String modelName; 2
       private String source; 3
       private List<ParameterInfo<?>> requestParams; 4
       ...
   }

   1

   Identifies data that is associated with a particular request or result

   2

   The name of the model that should be applied to the request data

   3

   Used by internally generated PMMLRequestData objects to identify the segment that generated the request

   4

   The default mechanism for sending input data points

4. Create an instance of the PMML4Result class, which holds the output information that is the result of applying the PMML-based rules to the input data:

   public class PMML4Result {
       private String correlationId;
       private String segmentationId; 1
       private String segmentId; 2
       private int segmentIndex; 3
       private String resultCode; 4
       private Map<String, Object> resultVariables; 5
       ...
   }

   1

   Used when the model type is MiningModel. The segmentationId is used to differentiate between multiple segmentations.

   2

   Used in conjunction with the segmentationId to identify which segment generated the results.

   3

   Used to maintain the order of segments.

   4

   Used to determine whether the model was successfully applied, where OK indicates success.

   5

   Contains the name of a resultant variable and its associated value.

   In addition to the normal getter methods, the PMML4Result class also supports the following methods for directly retrieving the values for result variables:

   public <T> Optional<T> getResultValue(String objName, String objField, Class<T> clazz, Object...params)
   
   public Object getResultValue(String objName, String objField, Object...params)

5. Create an instance of the ParameterInfo class, which serves as a wrapper for basic data type objects used as part of the PMMLRequestData class:

   public class ParameterInfo<T> { 1
       private String correlationId;
       private String name; 2
       private String capitalizedName;
       private Class<T> type; 3
       private T value; 4
       ...
   }

   1

   The parameterized class to handle many different types

   2

   The name of the variable that is expected as input for the model

   3

   The class that is the actual type of the variable

   4

   The actual value of the variable

6. Execute the PMML model based on the required PMML class instances that you have created:

   public void executeModel(KieBase kbase,
                            Map<String,Object> variables,
                            String modelName,
                            String correlationId,
                            String modelPkgName) {
       RuleUnitExecutor executor = RuleUnitExecutor.create().bind(kbase);
       PMMLRequestData request = new PMMLRequestData(correlationId, modelName);
       PMML4Result resultHolder = new PMML4Result(correlationId);
       variables.entrySet().forEach( es -> {
           request.addRequestParam(es.getKey(), es.getValue());
       });
   
       DataSource<PMMLRequestData> requestData = executor.newDataSource("request");
       DataSource<PMML4Result> resultData = executor.newDataSource("results");
       DataSource<PMMLData> internalData = executor.newDataSource("pmmlData");
   
       requestData.insert(request);
       resultData.insert(resultHolder);
   
       List<String> possiblePackageNames = calculatePossiblePackageNames(modelName,
                                                                       modelPkgName);
       Class<? extends RuleUnit> ruleUnitClass = getStartingRuleUnit("RuleUnitIndicator",
                                                                   (InternalKnowledgeBase)kbase,
                                                                   possiblePackageNames);
   
       if (ruleUnitClass != null) {
           executor.run(ruleUnitClass);
           if ( "OK".equals(resultHolder.getResultCode()) ) {
             // extract result variables here
           }
       }
   }
   
   protected Class<? extends RuleUnit> getStartingRuleUnit(String startingRule, InternalKnowledgeBase ikb, List<String> possiblePackages) {
       RuleUnitRegistry unitRegistry = ikb.getRuleUnitRegistry();
       Map<String,InternalKnowledgePackage> pkgs = ikb.getPackagesMap();
       RuleImpl ruleImpl = null;
       for (String pkgName: possiblePackages) {
         if (pkgs.containsKey(pkgName)) {
             InternalKnowledgePackage pkg = pkgs.get(pkgName);
             ruleImpl = pkg.getRule(startingRule);
             if (ruleImpl != null) {
                 RuleUnitDescr descr = unitRegistry.getRuleUnitFor(ruleImpl).orElse(null);
                 if (descr != null) {
                     return descr.getRuleUnitClass();
                 }
             }
         }
       }
       return null;
   }
   
   protected List<String> calculatePossiblePackageNames(String modelId, String...knownPackageNames) {
       List<String> packageNames = new ArrayList<>();
       String javaModelId = modelId.replaceAll("\\s","");
       if (knownPackageNames != null && knownPackageNames.length > 0) {
           for (String knownPkgName: knownPackageNames) {
               packageNames.add(knownPkgName + "." + javaModelId);
           }
       }
       String basePkgName = PMML4UnitImpl.DEFAULT_ROOT_PACKAGE+"."+javaModelId;
       packageNames.add(basePkgName);
       return packageNames;
   }

   Rules are executed by the RuleUnitExecutor class. The RuleUnitExecutor class creates KIE sessions and adds the required DataSource objects to those sessions, and then executes the rules based on the RuleUnit that is passed as a parameter to the run() method. The calculatePossiblePackageNames and the getStartingRuleUnit methods determine the fully qualified name of the RuleUnit class that is passed to the run() method.

Procedure

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

   Example of legacy implementation

   <!-- Required for the PMML compiler -->
   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>kie-pmml</artifactId>
     <version>${rhpam.version}</version>
   </dependency>
   
   <!-- Required for the KIE public API -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-api</artifactId>
     <version>${rhpam.version}</version>
   </dependencies>
   
   <!-- Required for the KIE Server Java client API -->
   <dependency>
     <groupId>org.kie.server</groupId>
     <artifactId>kie-server-client</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>

   Important

   To use the legacy implementation, ensure that the kie-pmml-implementation system property is set as legacy.

   Example of trusty implementation

   <!-- Required for the PMML compiler -->
   <dependency>
     <groupId>org.drools</groupId>
     <artifactId>kie-pmml-dependencies</artifactId>
     <version>${rhpam.version}</version>
   </dependency>
   
   <!-- Required for the KIE public API -->
   <dependency>
     <groupId>org.kie</groupId>
     <artifactId>kie-api</artifactId>
     <version>${rhpam.version}</version>
   </dependencies>
   
   <!-- Required for the KIE Server Java client API -->
   <dependency>
     <groupId>org.kie.server</groupId>
     <artifactId>kie-server-client</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 Decision Manager currently used in your project (for example, 7.67.0.Final-redhat-00024).

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

   Alternative option:

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

3. Create a class for sending requests to KIE Server and receiving responses:

   public class ApplyScorecardModel {
     private static final ReleaseId releaseId =
             new ReleaseId("org.acme","my-kjar","1.0.0");
     private static final String containerId = "SampleModelContainer";
     private static KieCommands commandFactory;
     private static ClassLoader kjarClassLoader; 1
     private RuleServicesClient serviceClient; 2
   
     // Attributes specific to your class instance
     private String rankedFirstCode;
     private Double score;
   
     // Initialization of non-final static attributes
     static {
       commandFactory = KieServices.Factory.get().getCommands();
   
       // Specifications for kjarClassLoader, if used
       KieMavenRepository kmp = KieMavenRepository.getMavenRepository();
       File artifactFile = kmp.resolveArtifact(releaseId).getFile();
       if (artifactFile != null) {
         URL urls[] = new URL[1];
         try {
           urls[0] = artifactFile.toURI().toURL();
           classLoader = new KieURLClassLoader(urls,PMML4Result.class.getClassLoader());
         } catch (MalformedURLException e) {
           logger.error("Error getting classLoader for "+containerId);
           logger.error(e.getMessage());
         }
       } else {
         logger.warn("Did not find the artifact file for "+releaseId.toString());
       }
     }
   
     public ApplyScorecardModel(KieServicesConfiguration kieConfig) {
       KieServicesClient clientFactory = KieServicesFactory.newKieServicesClient(kieConfig);
       serviceClient = clientFactory.getServicesClient(RuleServicesClient.class);
     }
     ...
     // Getters and setters
     ...
   
     // Method for executing the PMML model on KIE Server
     public void applyModel(String occupation, int age) {
       PMMLRequestData input = new PMMLRequestData("1234","SampleModelName"); 3
       input.addRequestParam(new ParameterInfo("1234","occupation",String.class,occupation));
       input.addRequestParam(new ParameterInfo("1234","age",Integer.class,age));
   
       CommandFactoryServiceImpl cf = (CommandFactoryServiceImpl)commandFactory;
       ApplyPmmlModelCommand command = (ApplyPmmlModelCommand) cf.newApplyPmmlModel(request); 4
   
       ServiceResponse<ExecutionResults> results =
           ruleClient.executeCommandsWithResults(CONTAINER_ID, command); 5
   
       if (results != null) {  6
         PMML4Result resultHolder = (PMML4Result)results.getResult().getValue("results");
         if (resultHolder != null && "OK".equals(resultHolder.getResultCode())) {
           this.score = resultHolder.getResultValue("ScoreCard","score",Double.class).get();
           Map<String,Object> rankingMap =
                (Map<String,Object>)resultHolder.getResultValue("ScoreCard","ranking");
           if (rankingMap != null && !rankingMap.isEmpty()) {
             this.rankedFirstCode = rankingMap.keySet().iterator().next();
           }
         }
       }
     }
   }

   1

   Defines the class loader if you did not include the KJAR in your client project dependencies

   2

   Identifies the service client as defined in the configuration settings, including KIE Server REST API access credentials

   3

   Initializes a PMMLRequestData object

   4

   Creates an instance of the ApplyPmmlModelCommand

   5

   Sends the command using the service client

   6

   Retrieves the results of the executed PMML model

4. Execute the class instance to send the PMML invocation request to KIE Server.

   Alternatively, you can use JMS and REST interfaces to send the ApplyPmmlModelCommand command to KIE Server. For REST requests, you use the ApplyPmmlModelCommand command as a POST request to http://SERVER:PORT/kie-server/services/rest/server/containers/instances/{containerId} in JSON, JAXB, or XStream request format.

   Example POST endpoint

   http://localhost:8080/kie-server/services/rest/server/containers/instances/SampleModelContainer

   Example JSON request body

   {
     "commands": [ {
         "apply-pmml-model-command": {
           "outIdentifier": null,
           "packageName": null,
           "hasMining": false,
           "requestData": {
             "correlationId": "123",
             "modelName": "SimpleScorecard",
             "source": null,
             "requestParams": [
               {
                 "correlationId": "123",
                 "name": "param1",
                 "type": "java.lang.Double",
                 "value": "10.0"
               },
               {
                 "correlationId": "123",
                 "name": "param2",
                 "type": "java.lang.Double",
                 "value": "15.0"
               }
             ]
           }
         }
       }
     ]
   }

   Example curl request with endpoint and body

   curl -X POST "http://localhost:8080/kie-server/services/rest/server/containers/instances/SampleModelContainer" -H "accept: application/json" -H "content-type: application/json" -d "{ \"commands\": [ { \"apply-pmml-model-command\": { \"outIdentifier\": null, \"packageName\": null, \"hasMining\": false, \"requestData\": { \"correlationId\": \"123\", \"modelName\": \"SimpleScorecard\", \"source\": null, \"requestParams\": [ { \"correlationId\": \"123\", \"name\": \"param1\", \"type\": \"java.lang.Double\", \"value\": \"10.0\" }, { \"correlationId\": \"123\", \"name\": \"param2\", \"type\": \"java.lang.Double\", \"value\": \"15.0\" } ] } } } ]}"

   Example JSON response

   {
     "results" : [ {
       "value" : {"org.kie.api.pmml.DoubleFieldOutput":{
     "value" : 40.8,
     "correlationId" : "123",
     "segmentationId" : null,
     "segmentId" : null,
     "name" : "OverallScore",
     "displayValue" : "OverallScore",
     "weight" : 1.0
   }},
       "key" : "OverallScore"
     }, {
       "value" : {"org.kie.api.pmml.PMML4Result":{
     "resultVariables" : {
       "OverallScore" : {
         "value" : 40.8,
         "correlationId" : "123",
         "segmentationId" : null,
         "segmentId" : null,
         "name" : "OverallScore",
         "displayValue" : "OverallScore",
         "weight" : 1.0
       },
       "ScoreCard" : {
         "modelName" : "SimpleScorecard",
         "score" : 40.8,
         "holder" : {
           "modelName" : "SimpleScorecard",
           "correlationId" : "123",
           "voverallScore" : null,
           "moverallScore" : true,
           "vparam1" : 10.0,
           "mparam1" : false,
           "vparam2" : 15.0,
           "mparam2" : false
         },
         "enableRC" : true,
         "pointsBelow" : true,
         "ranking" : {
           "reasonCh1" : 5.0,
           "reasonCh2" : -6.0
         }
       }
     },
     "correlationId" : "123",
     "segmentationId" : null,
     "segmentId" : null,
     "segmentIndex" : 0,
     "resultCode" : "OK",
     "resultObjectName" : null
   }},
       "key" : "results"
     } ],
     "facts" : [ ]
   }