Managing and monitoring Decision Server

Procedure

1. In Business Central, go to Menu → Design → Projects and click the project name.
2. Click the project Settings tab and then click Validation to open the list of repositories.

3. Select or clear any of the listed repository options to enable or disable duplicate GAV detection.

   In the future, duplicate GAVs will be reported for only the repositories you have enabled for validation.

   Note

   To disable this feature, set the org.guvnor.project.gav.check.disabled system property to true for Business Central at system startup:

   $ ~/EAP_HOME/bin/standalone.sh -c standalone-full.xml
   -Dorg.guvnor.project.gav.check.disabled=true

   Copy to Clipboard Toggle word wrap

Procedure

1. On the first computer, run the installer in interactive mode or CLI mode. See Installing and configuring Red Hat Decision Manager on Red Hat JBoss EAP 7.2 for more information.
2. On the Component Selection page, clear the Decision Server box.
3. Complete the Business Central installation.
4. On the second computer, run the installer in interactive mode or CLI mode.
5. On the Component Selection page, clear the Business Central box.
6. On the Configure Runtime Environment page, select Perform Advanced Configuration.
7. Select Customize Decision Server properties and click Next.

8. Enter the controller URL for Business Central and configure additional properties for Decision Server. The controller URL has the following form where <HOST:PORT> is the address of Business Central on the second computer:

   <HOST:PORT>/business-central/rest/controller

   Copy to Clipboard Toggle word wrap
9. Complete the installation.
10. To verify that the Decision Manager controller is now integrated with Business Central, go to the Execution Servers page in Business Central and confirm that the Decision Server that you configured appears under REMOTE SERVERS.

Procedure

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

   • Product: Decision Manager
   • Version: 7.4
2. Download Red Hat Decision Manager 7.4.0 Add Ons (the rhdm-7.4.0-add-ons.zip file).
3. Unzip the rhdm-7.4.0-add-ons.zip file. The rhdm-7.4-controller-ee7.zip file is in the unzipped directory.
4. Extract the rhdm-7.4-controller-ee7 archive to a temporary directory. In the following examples this directory is called TEMP_DIR.

5. Copy the TEMP_DIR/rhdm-7.4-controller-ee7/controller.war directory to EAP_HOME/standalone/deployments/.

   Warning

   Ensure that the names of the headless Decision Manager controller deployments you copy do not conflict with your existing deployments in the Red Hat JBoss EAP instance.

6. Copy the contents of the TEMP_DIR/rhdm-7.4-controller-ee7/SecurityPolicy/ directory to EAP_HOME/bin. When asked to overwrite files, select Yes.
7. In the EAP_HOME/standalone/deployments/ directory, create an empty file named controller.war.dodeploy. This file ensures that the headless Decision Manager controller is automatically deployed when the server starts.

Procedure

1. In a terminal application, navigate to EAP_HOME/bin.

2. If you installed the headless Decision Manager controller on the same Red Hat JBoss EAP instance as the Red Hat JBoss EAP instance where you installed the Decision Server, enter one of the following commands:

   • On Linux or UNIX-based systems:

     $ ./standalone.sh -c standalone-full.xml

     Copy to Clipboard Toggle word wrap

   • On Windows:

     standalone.bat -c standalone-full.xml

     Copy to Clipboard Toggle word wrap

3. If you installed the headless Decision Manager controller on a separate Red Hat JBoss EAP instance from the Red Hat JBoss EAP instance where you installed the Decision Server, you can start the headless Decision Manager controller with the standalone.sh script:

   Note

   In this case, ensure that you made all required configuration changes to the standalone.xml file.

   • On Linux or UNIX-based systems:

     $ ./standalone.sh

     Copy to Clipboard Toggle word wrap

   • On Windows:

     standalone.bat

     Copy to Clipboard Toggle word wrap

4. To verify that the headless Decision Manager controller is working on Red Hat JBoss EAP, enter the following command where <CONTROLLER> and <CONTROLLER_PWD> is the user name and password. The output of this command provides information about the Decision Server instance.

   curl -X GET "http://<HOST>:<PORT>/controller/rest/controller/management/servers" -H  "accept: application/xml" -u '<CONTROLLER>:<CONTROLLER_PWD>'

   Copy to Clipboard Toggle word wrap

Procedure

1. Navigate to the Software Downloads page in the Red Hat Customer Portal (login required), and select the product and version from the drop-down options:

   • Product: Decision Manager
   • Version: 7.4
2. Download Red Hat Decision Manager 7.4.0 Add Ons (the rhdm-7.4.0-add-ons.zip file).
3. Unzip the rhdm-7.4.0-add-ons.zip file. The rhdm-7.4-controller-ee7.zip file is in the unzipped directory.
4. Extract the rhdm-7.4-controller-ee7 archive to a temporary directory. In the following examples this directory is called TEMP_DIR.

5. Copy the TEMP_DIR/rhdm-7.4-controller-ee7/controller.war directory to EAP_HOME/standalone/deployments/.

   Warning

   Ensure that the names of the headless Decision Manager controller deployments you copy do not conflict with your existing deployments in the Red Hat JBoss EAP instance.

6. Copy the contents of the TEMP_DIR/rhdm-7.4-controller-ee7/SecurityPolicy/ directory to EAP_HOME/bin. When asked to overwrite files, select Yes.
7. In the EAP_HOME/standalone/deployments/ directory, create an empty file named controller.war.dodeploy. This file ensures that the headless Decision Manager controller is automatically deployed when the server starts.
8. Open the EAP_HOME/standalone/configuration/standalone.xml file in a text editor.

9. Add the following properties to the <system-properties> element and replace <NFS_STORAGE> with the absolute path to the NFS storage where the template configuration is stored:

   <system-properties>
     <property name="org.kie.server.controller.templatefile.watcher.enabled" value="true"/>
     <property name="org.kie.server.controller.templatefile" value="<NFS_STORAGE>"/>
   </system-properties>

   Copy to Clipboard Toggle word wrap

   If the value of the org.kie.server.controller.templatefile.watcher.enabled property is set to true, a separate thread is started to watch for modifications of the template file. The default interval for these checks is 30000 milliseconds and can be further controlled by the org.kie.server.controller.templatefile.watcher.interval system property. If the value of this property is set to false, changes to the template file are detected only when the server restarts.

10. To start the headless Decision Manager controller, navigate to EAP_HOME/bin and enter the following command:

    • On Linux or UNIX-based systems:

      $ ./standalone.sh

      Copy to Clipboard Toggle word wrap

    • On Windows:

      standalone.bat

      Copy to Clipboard Toggle word wrap

Procedure

1. To open the project deployment descriptors configuration in Business Central, open Menu → Design → $PROJECT_NAME → Settings → Deployments.
2. From the list of configuration settings, click Required Roles, then click Add Required Role.
3. In the Add Required Role window, type the name of the role that you want to have permission to access this deployment, then click Add.
4. To add more roles with permission to access the deployment, repeat the previous steps.
5. When you have finished adding all required roles, click Save.

Procedure

1. In your Decision Server instance, set the org.kie.prometheus.server.ext.disabled system property to false to enable the Prometheus extension. You can define this property when you start Decision Server or in the standalone.xml or standalone-full.xml file of Red Hat Decision Manager distribution.

2. If you are running Red Hat Decision Manager on Spring Boot, add the following dependencies in the pom.xml file of your Maven project and configure the required key in the application.properties system property:

   Spring Boot pom.xml dependencies for Prometheus

   <dependency>
     <groupId>org.kie.server</groupId>
     <artifactId>kie-server-services-prometheus</artifactId>
     <version>${rhdm.version}</version>
   </dependency>
   
   <dependency>
     <groupId>org.kie.server</groupId>
     <artifactId>kie-server-rest-prometheus</artifactId>
     <version>${rhdm.version}</version>
   </dependency>

   Copy to Clipboard Toggle word wrap

   Spring Boot application.properties key for Red Hat Decision Manager and Prometheus

   kieserver.drools.enabled=true
   kieserver.dmn.enabled=true
   kieserver.prometheus.enabled=true

   Copy to Clipboard Toggle word wrap

3. In the prometheus.yaml file of your Prometheus distribution, add the following settings in the scrape_configs section to configure Prometheus to scrape metrics from Decision Server:

   Scrape configurations in prometheus.yaml file

   scrape_configs:
     job_name: 'kie-server'
   metrics_path: /SERVER_PATH/services/rest/metrics
   Basic_auth:
   username: USER_NAME
   password: PASSWORD
   static_configs:
     - targets: ["HOST:PORT"]

   Copy to Clipboard Toggle word wrap

   Scrape configurations in prometheus.yaml file for Spring Boot (if applicable)

   scrape_configs:
     job_name: 'kie'
   metrics_path: /rest/metrics
   static_configs:
   - targets: ["HOST:PORT"]

   Copy to Clipboard Toggle word wrap

   Replace the values according to your Decision Server location and settings.

4. Start the Decision Server instance.

   Example start command for Red Hat Decision Manager on Red Hat JBoss EAP

   $ cd ~/EAP_HOME/bin
   $ ./standalone.sh --c standalone-full.xml

   Copy to Clipboard Toggle word wrap

   After you start the configured Decision Server instance, Prometheus begins collecting metrics and Decision Server publishes the metrics to the REST API endpoint http://HOST:PORT/SERVER/services/rest/metrics (or on Spring Boot, to http://HOST:PORT/rest/metrics).

5. In a REST client or curl utility, send a REST API request with the following components to verify that Decision Server is publishing the metrics:

   For REST client:

   • Authentication: Enter the user name and password of the Decision Server user with the kie-server role.

   • HTTP Headers: Set the following header:

     • Accept: application/json
   • HTTP method: Set to GET.
   • URL: Enter the Decision Server REST API base URL and metrics endpoint, such as http://localhost:8080/kie-server/services/rest/metrics (or on Spring Boot, http://localhost:8080/rest/metrics).

   For curl utility:

   • -u: Enter the user name and password of the Decision Server user with the kie-server role.

   • -H: Set the following header:

     • accept: application/json
   • -X: Set to GET.
   • URL: Enter the Decision Server REST API base URL and metrics endpoint, such as http://localhost:8080/kie-server/services/rest/metrics (or on Spring Boot, http://localhost:8080/rest/metrics).

   curl -u 'baAdmin:password@1' -H "accept: application/json" -X GET "http://localhost:8080/kie-server/services/rest/metrics"

   Copy to Clipboard Toggle word wrap

   Example server response

   # HELP kie_server_container_started_total Kie Server Started Containers
   # TYPE kie_server_container_started_total counter
   kie_server_container_started_total{container_id="task-assignment-kjar-1.0",} 1.0
   # HELP solvers_running Number of solvers currently running
   # TYPE solvers_running gauge
   solvers_running 0.0
   # HELP dmn_evaluate_decision_nanosecond DMN Evaluation Time
   # TYPE dmn_evaluate_decision_nanosecond histogram
   # HELP solver_duration_seconds Time in seconds it took solver to solve the constraint problem
   # TYPE solver_duration_seconds summary
   solver_duration_seconds_count{solver_id="100tasks-5employees.xml",} 1.0
   solver_duration_seconds_sum{solver_id="100tasks-5employees.xml",} 179.828255925
   solver_duration_seconds_count{solver_id="24tasks-8employees.xml",} 1.0
   solver_duration_seconds_sum{solver_id="24tasks-8employees.xml",} 179.995759653
   # HELP drl_match_fired_nanosecond Drools Firing Time
   # TYPE drl_match_fired_nanosecond histogram
   # HELP dmn_evaluate_failed_count DMN Evaluation Failed
   # TYPE dmn_evaluate_failed_count counter
   # HELP kie_server_start_time Kie Server Start Time
   # TYPE kie_server_start_time gauge
   kie_server_start_time{name="myapp-kieserver",server_id="myapp-kieserver",location="http://myapp-kieserver-demo-monitoring.127.0.0.1.nip.io:80/services/rest/server",version="7.4.0.redhat-20190428",} 1.557221271502E12
   # HELP kie_server_container_running_total Kie Server Running Containers
   # TYPE kie_server_container_running_total gauge
   kie_server_container_running_total{container_id="task-assignment-kjar-1.0",} 1.0
   # HELP solver_score_calculation_speed Number of moves per second for a particular solver solving the constraint problem
   # TYPE solver_score_calculation_speed summary
   solver_score_calculation_speed_count{solver_id="100tasks-5employees.xml",} 1.0
   solver_score_calculation_speed_sum{solver_id="100tasks-5employees.xml",} 6997.0
   solver_score_calculation_speed_count{solver_id="24tasks-8employees.xml",} 1.0
   solver_score_calculation_speed_sum{solver_id="24tasks-8employees.xml",} 19772.0

   Copy to Clipboard Toggle word wrap

   If the metrics are not available in Decision Server, review and verify the Decision Server and Prometheus configurations described in this section.

   You can also interact with your collected metrics in the Prometheus expression browser at http://HOST:PORT/graph, or integrate your Prometheus data source with a data-graphing tool such as Grafana:

   Figure 13.1. Prometheus expression browser with Decision Server metrics

   

   View larger image

   

   Figure 13.2. Prometheus expression browser with Decision Server target

   

   View larger image

   

   Figure 13.3. Grafana dashboard with Decision Server metrics for DMN models

   

   View larger image

   

   Figure 13.4. Grafana dashboard with Decision Server metrics for solvers

   

   View larger image

   

Procedure

1. In the DeploymentConfig object of your Decision Server deployment on OpenShift, set the PROMETHEUS_SERVER_EXT_DISABLED environment variable to false to enable the Prometheus extension. You can set this variable in the OpenShift web console or use the oc command in a command terminal:

   oc set env dc/<dc_name> PROMETHEUS_SERVER_EXT_DISABLED=false -n <namespace>

   Copy to Clipboard Toggle word wrap

   If you have not yet deployed your Decision Server on OpenShift, then in the OpenShift template that you plan to use for your OpenShift deployment (for example, rhdm74-prod-immutable-kieserver.yaml), you can set the PROMETHEUS_SERVER_EXT_DISABLED template parameter to false to enable the Prometheus extension.

   If you are using the OpenShift Operator to deploy Decision Server on OpenShift, then in your Decision Server configuration, set the PROMETHEUS_SERVER_EXT_DISABLED environment variable to false to enable the Prometheus extension:

   apiVersion: app.kiegroup.org/v1
   kind: KieApp
   metadata:
     name: enable-prometheus
   spec:
     environment: rhpam-trial
     objects:
       servers:
       - env:
         - name: PROMETHEUS_SERVER_EXT_DISABLED
           value: "false"

   Copy to Clipboard Toggle word wrap

2. Create a service-metrics.yaml file to add a service that exposes the metrics from Decision Server to Prometheus:

   apiVersion: v1
   kind: Service
   metadata:
     annotations:
       description: RHDM Prometheus metrics exposed
     labels:
       app: myapp-kieserver
       application: myapp-kieserver
       template: myapp-kieserver
       metrics: rhdm
     name: rhdm-app-metrics
   spec:
     ports:
       - name: web
         port: 8080
         protocol: TCP
         targetPort: 8080
     selector:
       deploymentConfig: myapp-kieserver
     sessionAffinity: None
     type: ClusterIP

   Copy to Clipboard Toggle word wrap

3. In a command terminal, use the oc command to apply the service-metrics.yaml file to your OpenShift deployment:

   oc apply -f service-metrics.yaml

   Copy to Clipboard Toggle word wrap
4. Create an OpenShift secret, such as metrics-secret, to access the Prometheus metrics on Decision Server. The secret must contain the "username" and "password" elements with Decision Server user credentials. For information about OpenShift secrets, see the Secrets chapter in the OpenShift Developer Guide.

5. Create a service-monitor.yaml file that defines the ServiceMonitor object. A service monitor enables Prometheus to connect to the Decision Server metrics service.

   apiVersion: monitoring.coreos.com/v1
   kind: ServiceMonitor
   metadata:
     name: rhdm-service-monitor
     labels:
       team: frontend
   spec:
     selector:
       matchLabels:
         metrics: rhdm
     endpoints:
       - port: web
         path: /services/rest/metrics
         basicAuth:
           password:
             name: metrics-secret
             key: password
           username:
             name: metrics-secret
             key: username

   Copy to Clipboard Toggle word wrap

6. In a command terminal, use the oc command to apply the service-monitor.yaml file to your OpenShift deployment:

   oc apply -f service-monitor.yaml

   Copy to Clipboard Toggle word wrap

   After you complete these configurations, Prometheus begins collecting metrics and Decision Server publishes the metrics to the REST API endpoint http://HOST:PORT/kie-server/services/rest/metrics.

   You can interact with your collected metrics in the Prometheus expression browser at http://HOST:PORT/graph, or integrate your Prometheus data source with a data-graphing tool such as Grafana.

   The host and port for the Prometheus expression browser location http://HOST:PORT/graph was defined in the route where you exposed the Prometheus web console when you installed the Prometheus Operator. For information about OpenShift routes, see the Routes chapter in the OpenShift Architecture documentation.

   Figure 13.5. Prometheus expression browser with Decision Server metrics

   

   View larger image

   

   Figure 13.6. Prometheus expression browser with Decision Server target

   

   View larger image

   

   Figure 13.7. Grafana dashboard with Decision Server metrics for DMN models

   

   View larger image

   

   Figure 13.8. Grafana dashboard with Decision Server metrics for solvers

   

   View larger image

   

Procedure

1. Create an empty Maven project and define the following packaging type and dependencies in the pom.xml file for the project:

   Example pom.xml file in the sample project

   <packaging>jar</packaging>
   
   <properties>
     <version.org.kie>7.23.0.Final-redhat-00002</version.org.kie>
   </properties>
   
   <dependencies>
     <dependency>
       <groupId>org.kie</groupId>
       <artifactId>kie-api</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie</groupId>
       <artifactId>kie-internal</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie.server</groupId>
       <artifactId>kie-server-api</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie.server</groupId>
       <artifactId>kie-server-services-common</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie.server</groupId>
       <artifactId>kie-server-services-drools</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie.server</groupId>
       <artifactId>kie-server-rest-common</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.drools</groupId>
       <artifactId>drools-core</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.drools</groupId>
       <artifactId>drools-compiler</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
       <version>1.7.25</version>
     </dependency>
   </dependencies>

   Copy to Clipboard Toggle word wrap

2. Implement the org.kie.server.services.api.KieServerApplicationComponentsService interface in a Java class in your project, as shown in the following example:

   Sample implementation of the KieServerApplicationComponentsService interface

   public class CusomtDroolsKieServerApplicationComponentsService implements KieServerApplicationComponentsService {  

   1

   
   
       private static final String OWNER_EXTENSION = "Drools";  

   2

   
   
       public Collection<Object> getAppComponents(String extension, SupportedTransports type, Object... services) {  

   3

   
           // Do not accept calls from extensions other than the owner extension:
           if ( !OWNER_EXTENSION.equals(extension) ) {
               return Collections.emptyList();
           }
   
           RulesExecutionService rulesExecutionService = null;  

   4

   
           KieServerRegistry context = null;
   
           for( Object object : services ) {
               if( RulesExecutionService.class.isAssignableFrom(object.getClass()) ) {
                   rulesExecutionService = (RulesExecutionService) object;
                   continue;
               } else if( KieServerRegistry.class.isAssignableFrom(object.getClass()) ) {
                   context = (KieServerRegistry) object;
                   continue;
               }
           }
   
           List<Object> components = new ArrayList<Object>(1);
           if( SupportedTransports.REST.equals(type) ) {
               components.add(new CustomResource(rulesExecutionService, context));  

   5

   
           }
   
           return components;
       }
   
   }

   Copy to Clipboard Toggle word wrap

   1

   Delivers REST endpoints to the Decision Server infrastructure that is deployed when the application starts.

   2

   Specifies the extension that you are extending, such as the Drools extension in this example.

   3

   Returns all resources that the REST container must deploy. Each extension that is enabled in your Decision Server instance calls the getAppComponents method, so the if ( !OWNER_EXTENSION.equals(extension) ) call returns an empty collection for any extensions other than the specified OWNER_EXTENSION extension.

   4

   Lists the services from the specified extension that you want to use, such as the RulesExecutionService and KieServerRegistry services from the Drools extension in this example.

   5

   Specifies the transport type for the extension, either REST or JMS (REST in this example), and the CustomResource class that returns the resource as part of the components list.

3. Implement the CustomResource class that the Decision Server can use to provide the additional functionality for the new REST resource, as shown in the following example:

   Sample implementation of the CustomResource class

   // Custom base endpoint:
   @Path("server/containers/instances/{containerId}/ksession")
   public class CustomResource {
   
       private static final Logger logger = LoggerFactory.getLogger(CustomResource.class);
   
       private KieCommands commandsFactory = KieServices.Factory.get().getCommands();
   
       private RulesExecutionService rulesExecutionService;
       private KieServerRegistry registry;
   
       public CustomResource() {
   
       }
   
       public CustomResource(RulesExecutionService rulesExecutionService, KieServerRegistry registry) {
           this.rulesExecutionService = rulesExecutionService;
           this.registry = registry;
       }
   
       // Supported HTTP method, path parameters, and data formats:
       @POST
       @Path("/{ksessionId}")
       @Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
       @Produces({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
       public Response insertFireReturn(@Context HttpHeaders headers,
               @PathParam("containerId") String id,
               @PathParam("ksessionId") String ksessionId,
               String cmdPayload) {
   
           Variant v = getVariant(headers);
           String contentType = getContentType(headers);
   
           // Marshalling behavior and supported actions:
           MarshallingFormat format = MarshallingFormat.fromType(contentType);
           if (format == null) {
               format = MarshallingFormat.valueOf(contentType);
           }
           try {
               KieContainerInstance kci = registry.getContainer(id);
   
               Marshaller marshaller = kci.getMarshaller(format);
   
               List<?> listOfFacts = marshaller.unmarshall(cmdPayload, List.class);
   
               List<Command<?>> commands = new ArrayList<Command<?>>();
               BatchExecutionCommand executionCommand = commandsFactory.newBatchExecution(commands, ksessionId);
   
               for (Object fact : listOfFacts) {
                   commands.add(commandsFactory.newInsert(fact, fact.toString()));
               }
               commands.add(commandsFactory.newFireAllRules());
               commands.add(commandsFactory.newGetObjects());
   
               ExecutionResults results = rulesExecutionService.call(kci, executionCommand);
   
               String result = marshaller.marshall(results);
   
   
               logger.debug("Returning OK response with content '{}'", result);
               return createResponse(result, v, Response.Status.OK);
           } catch (Exception e) {
               // If marshalling fails, return the `call-container` response to maintain backward compatibility:
               String response = "Execution failed with error : " + e.getMessage();
               logger.debug("Returning Failure response with content '{}'", response);
               return createResponse(response, v, Response.Status.INTERNAL_SERVER_ERROR);
           }
   
       }
   }

   Copy to Clipboard Toggle word wrap

   In this example, the CustomResource class for the custom endpoint specifies the following data and behavior:

   • Uses the base endpoint server/containers/instances/{containerId}/ksession
   • Uses POST HTTP method

   • Expects the following data to be given in REST requests:

     • The containerId as a path argument
     • The ksessionId as a path argument
     • List of facts as a message payload

   • Supports all Decision Server data formats:

     • XML (JAXB, XStream)
     • JSON
   • Unmarshals the payload into a List<?> collection and, for each item in the list, creates an InsertCommand instance followed by FireAllRules and GetObject commands.
   • Adds all commands to the BatchExecutionCommand instance that calls to the decision engine.
4. To make the new endpoint discoverable for Decision Server, create a META-INF/services/org.kie.server.services.api.KieServerApplicationComponentsService file in your Maven project and add the fully qualified class name of the KieServerApplicationComponentsService implementation class within the file. For this example, the file contains the single line org.kie.server.ext.drools.rest.CusomtDroolsKieServerApplicationComponentsService.
5. Build your project and copy the resulting JAR file into the ~/kie-server.war/WEB-INF/lib directory of your project. For example, on Red Hat JBoss EAP, the path to this directory is EAP_HOME/standalone/deployments/kie-server.war/WEB-INF/lib.

6. Start the Decision Server and deploy the built project to the running Decision Server. You can deploy the project using either the Business Central interface or the Decision Server REST API (a PUT request to http://SERVER:PORT/kie-server/services/rest/server/containers/{containerId}).

   After your project is deployed on a running Decision Server, you can start interacting with your new REST endpoint.

   For this example, you can use the following information to invoke the new endpoint:

   • Example request URL: http://localhost:8080/kie-server/services/rest/server/containers/instances/demo/ksession/defaultKieSession
   • HTTP method: POST

   • HTTP headers:

     • Content-Type: application/json
     • Accept: application/json

   • Example message payload:

     [
       {
         "org.jbpm.test.Person": {
           "name": "john",
           "age": 25
         }
       },
       {
         "org.jbpm.test.Person": {
           "name": "mary",
           "age": 22
         }
       }
     ]

     Copy to Clipboard Toggle word wrap
   • Example server response: 200 (success)

   • Example server log output:

     13:37:20,347 INFO  [stdout] (default task-24) Hello mary
     13:37:20,348 INFO  [stdout] (default task-24) Hello john

     Copy to Clipboard Toggle word wrap

Procedure

1. Create an empty Maven project and define the following packaging type and dependencies in the pom.xml file for the project:

   Example pom.xml file in the sample project

   <packaging>jar</packaging>
   
   <properties>
     <version.org.kie>7.23.0.Final-redhat-00002</version.org.kie>
   </properties>
   
   <dependencies>
     <dependency>
       <groupId>org.kie</groupId>
       <artifactId>kie-api</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie</groupId>
       <artifactId>kie-internal</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie.server</groupId>
       <artifactId>kie-server-api</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie.server</groupId>
       <artifactId>kie-server-services-common</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.kie.server</groupId>
       <artifactId>kie-server-services-drools</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.drools</groupId>
       <artifactId>drools-core</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.drools</groupId>
       <artifactId>drools-compiler</artifactId>
       <version>${version.org.kie}</version>
     </dependency>
     <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-api</artifactId>
       <version>1.7.25</version>
     </dependency>
     <dependency>
       <groupId>org.apache.mina</groupId>
       <artifactId>mina-core</artifactId>
       <version>2.1.3</version>
     </dependency>
   </dependencies>

   Copy to Clipboard Toggle word wrap

2. Implement the org.kie.server.services.api.KieServerExtension interface in a Java class in your project, as shown in the following example:

   Sample implementation of the KieServerExtension interface

   public class MinaDroolsKieServerExtension implements KieServerExtension {
   
       private static final Logger logger = LoggerFactory.getLogger(MinaDroolsKieServerExtension.class);
   
       public static final String EXTENSION_NAME = "Drools-Mina";
   
       private static final Boolean disabled = Boolean.parseBoolean(System.getProperty("org.kie.server.drools-mina.ext.disabled", "false"));
       private static final String MINA_HOST = System.getProperty("org.kie.server.drools-mina.ext.port", "localhost");
       private static final int MINA_PORT = Integer.parseInt(System.getProperty("org.kie.server.drools-mina.ext.port", "9123"));
   
       // Taken from dependency on the `Drools` extension:
       private KieContainerCommandService batchCommandService;
   
       // Specific to MINA:
       private IoAcceptor acceptor;
   
       public boolean isActive() {
           return disabled == false;
       }
   
       public void init(KieServerImpl kieServer, KieServerRegistry registry) {
   
           KieServerExtension droolsExtension = registry.getServerExtension("Drools");
           if (droolsExtension == null) {
               logger.warn("No Drools extension available, quiting...");
               return;
           }
   
           List<Object> droolsServices = droolsExtension.getServices();
           for( Object object : droolsServices ) {
               // If the given service is null (not configured), continue to the next service:
               if (object == null) {
                   continue;
               }
               if( KieContainerCommandService.class.isAssignableFrom(object.getClass()) ) {
                   batchCommandService = (KieContainerCommandService) object;
                   continue;
               }
           }
           if (batchCommandService != null) {
               acceptor = new NioSocketAcceptor();
               acceptor.getFilterChain().addLast( "codec", new ProtocolCodecFilter( new TextLineCodecFactory( Charset.forName( "UTF-8" ))));
   
               acceptor.setHandler( new TextBasedIoHandlerAdapter(batchCommandService) );
               acceptor.getSessionConfig().setReadBufferSize( 2048 );
               acceptor.getSessionConfig().setIdleTime( IdleStatus.BOTH_IDLE, 10 );
               try {
                   acceptor.bind( new InetSocketAddress(MINA_HOST, MINA_PORT) );
   
                   logger.info("{} -- Mina server started at {} and port {}", toString(), MINA_HOST, MINA_PORT);
               } catch (IOException e) {
                   logger.error("Unable to start Mina acceptor due to {}", e.getMessage(), e);
               }
   
           }
       }
   
       public void destroy(KieServerImpl kieServer, KieServerRegistry registry) {
           if (acceptor != null) {
               acceptor.dispose();
               acceptor = null;
           }
           logger.info("{} -- Mina server stopped", toString());
       }
   
       public void createContainer(String id, KieContainerInstance kieContainerInstance, Map<String, Object> parameters) {
           // Empty, already handled by the `Drools` extension
   
       }
   
       public void disposeContainer(String id, KieContainerInstance kieContainerInstance, Map<String, Object> parameters) {
         // Empty, already handled by the `Drools` extension
   
       }
   
       public List<Object> getAppComponents(SupportedTransports type) {
           // Nothing for supported transports (REST or JMS)
           return Collections.emptyList();
       }
   
       public <T> T getAppComponents(Class<T> serviceType) {
   
           return null;
       }
   
       public String getImplementedCapability() {
           return "BRM-Mina";
       }
   
       public List<Object> getServices() {
           return Collections.emptyList();
       }
   
       public String getExtensionName() {
           return EXTENSION_NAME;
       }
   
       public Integer getStartOrder() {
           return 20;
       }
   
       @Override
       public String toString() {
           return EXTENSION_NAME + " KIE Server extension";
       }
   }

   Copy to Clipboard Toggle word wrap

   The KieServerExtension interface is the main extension interface that Decision Server can use to provide the additional functionality for the new MINA transport. The interface consists of the following components:

   Overview of the KieServerExtension interface

   public interface KieServerExtension {
   
       boolean isActive();
   
       void init(KieServerImpl kieServer, KieServerRegistry registry);
   
       void destroy(KieServerImpl kieServer, KieServerRegistry registry);
   
       void createContainer(String id, KieContainerInstance kieContainerInstance, Map<String, Object> parameters);
   
       void disposeContainer(String id, KieContainerInstance kieContainerInstance, Map<String, Object> parameters);
   
       List<Object> getAppComponents(SupportedTransports type);
   
       <T> T getAppComponents(Class<T> serviceType);
   
       String getImplementedCapability();  

   1

   
   
       List<Object> getServices();
   
       String getExtensionName();  

   2

   
   
       Integer getStartOrder();  

   3

   
   }

   Copy to Clipboard Toggle word wrap

   1

   Specifies the capability that is covered by this extension. The capability must be unique within Decision Server.

   2

   Defines a human-readable name for the extension.

   3

   Determines when the specified extension should be started. For extensions that have dependencies on other extensions, this setting must not conflict with the parent setting. For example, in this case, this custom extension depends on the Drools extension, which has StartOrder set to 0, so this custom add-on extension must be greater than 0 (set to 20 in the sample implementation).

   In the previous MinaDroolsKieServerExtension sample implementation of this interface, the init method is the main element for collecting services from the Drools extension and for bootstrapping the MINA server. All other methods in the KieServerExtension interface can remain with the standard implementation to fulfill interface requirements.

   The TextBasedIoHandlerAdapter class is the handler on the MINA server that reacts to incoming requests.

3. Implement the TextBasedIoHandlerAdapter handler for the MINA server, as shown in the following example:

   Sample implementation of the TextBasedIoHandlerAdapter handler

   public class TextBasedIoHandlerAdapter extends IoHandlerAdapter {
   
       private static final Logger logger = LoggerFactory.getLogger(TextBasedIoHandlerAdapter.class);
   
       private KieContainerCommandService batchCommandService;
   
       public TextBasedIoHandlerAdapter(KieContainerCommandService batchCommandService) {
           this.batchCommandService = batchCommandService;
       }
   
       @Override
       public void messageReceived( IoSession session, Object message ) throws Exception {
           String completeMessage = message.toString();
           logger.debug("Received message '{}'", completeMessage);
           if( completeMessage.trim().equalsIgnoreCase("quit") || completeMessage.trim().equalsIgnoreCase("exit") ) {
               session.close(false);
               return;
           }
   
           String[] elements = completeMessage.split("\\|");
           logger.debug("Container id {}", elements[0]);
           try {
               ServiceResponse<String> result = batchCommandService.callContainer(elements[0], elements[1], MarshallingFormat.JSON, null);
   
               if (result.getType().equals(ServiceResponse.ResponseType.SUCCESS)) {
                   session.write(result.getResult());
                   logger.debug("Successful message written with content '{}'", result.getResult());
               } else {
                   session.write(result.getMsg());
                   logger.debug("Failure message written with content '{}'", result.getMsg());
               }
           } catch (Exception e) {
   
           }
       }
   }

   Copy to Clipboard Toggle word wrap

   In this example, the handler class receives text messages and executes them in the Drools service.

   Consider the following handler requirements and behavior when you use the TextBasedIoHandlerAdapter handler implementation:

   • Anything that you submit to the handler must be a single line because each incoming transport request is a single line.
   • You must pass a KIE container ID in this single line so that the handler expects the format containerID|payload.
   • You can set a response in the way that it is produced by the marshaller. The response can be multiple lines.
   • The handler supports a stream mode that enables you to send commands without disconnecting from a Decision Server session. To end a Decision Server session in stream mode, send either an exit or quit command to the server.
4. To make the new data transport discoverable for Decision Server, create a META-INF/services/org.kie.server.services.api.KieServerExtension file in your Maven project and add the fully qualified class name of the KieServerExtension implementation class within the file. For this example, the file contains the single line org.kie.server.ext.mina.MinaDroolsKieServerExtension.
5. Build your project and copy the resulting JAR file and the mina-core-2.0.9.jar file (which the extension depends on in this example) into the ~/kie-server.war/WEB-INF/lib directory of your project. For example, on Red Hat JBoss EAP, the path to this directory is EAP_HOME/standalone/deployments/kie-server.war/WEB-INF/lib.

6. Start the Decision Server and deploy the built project to the running Decision Server. You can deploy the project using either the Business Central interface or the Decision Server REST API (a PUT request to http://SERVER:PORT/kie-server/services/rest/server/containers/{containerId}).

   After your project is deployed on a running Decision Server, you can view the status of the new data transport in your Decision Server log and start using your new data transport:

   New data transport in the server log

   Drools-Mina KIE Server extension -- Mina server started at localhost and port 9123
   Drools-Mina KIE Server extension has been successfully registered as server extension

   Copy to Clipboard Toggle word wrap

   For this example, you can use Telnet to interact with the new MINA-based data transport in Decision Server:

   Starting Telnet and connecting to Decision Server on port 9123 in a command terminal

   telnet 127.0.0.1 9123

   Copy to Clipboard Toggle word wrap

   Example interactions with Decision Server in a command terminal

   Trying 127.0.0.1...
   Connected to localhost.
   Escape character is '^]'.
   
   # Request body:
   demo|{"lookup":"defaultKieSession","commands":[{"insert":{"object":{"org.jbpm.test.Person":{"name":"john","age":25}}}},{"fire-all-rules":""}]}
   
   # Server response:
   {
     "results" : [ {
       "key" : "",
       "value" : 1
     } ],
     "facts" : [ ]
   }
   
   demo|{"lookup":"defaultKieSession","commands":[{"insert":{"object":{"org.jbpm.test.Person":{"name":"mary","age":22}}}},{"fire-all-rules":""}]}
   {
     "results" : [ {
       "key" : "",
       "value" : 1
     } ],
     "facts" : [ ]
   }
   
   demo|{"lookup":"defaultKieSession","commands":[{"insert":{"object":{"org.jbpm.test.Person":{"name":"james","age":25}}}},{"fire-all-rules":""}]}
   {
     "results" : [ {
       "key" : "",
       "value" : 1
     } ],
     "facts" : [ ]
   }
   exit
   Connection closed by foreign host.

   Copy to Clipboard Toggle word wrap

   Example server log output

   16:33:40,206 INFO  [stdout] (NioProcessor-2) Hello john
   16:34:03,877 INFO  [stdout] (NioProcessor-2) Hello mary
   16:34:19,800 INFO  [stdout] (NioProcessor-2) Hello james

   Copy to Clipboard Toggle word wrap

Procedure

1. Create an empty Maven project and define the following packaging type and dependencies in the pom.xml file for the project:

   Example pom.xml file in the sample project

   <packaging>jar</packaging>
   
   <properties>
      <version.org.kie>7.23.0.Final-redhat-00002</version.org.kie>
    </properties>
   
    <dependencies>
      <dependency>
        <groupId>org.kie.server</groupId>
        <artifactId>kie-server-api</artifactId>
        <version>${version.org.kie}</version>
      </dependency>
      <dependency>
         <groupId>org.kie.server</groupId>
         <artifactId>kie-server-client</artifactId>
         <version>${version.org.kie}</version>
       </dependency>
      <dependency>
        <groupId>org.drools</groupId>
        <artifactId>drools-compiler</artifactId>
        <version>${version.org.kie}</version>
      </dependency>
    </dependencies>

   Copy to Clipboard Toggle word wrap

2. Implement the relevant ServicesClient interface in a Java class in your project, as shown in the following example:

   Sample RulesMinaServicesClient interface

   public interface RulesMinaServicesClient extends RuleServicesClient {
   
   }

   Copy to Clipboard Toggle word wrap

   A specific interface is required because you must register client implementations based on the interface, and you can have only one implementation for a given interface.

   For this example, the custom MINA-based data transport uses the Drools extension, so this example RulesMinaServicesClient interface extends the existing RuleServicesClient client API from the Drools extension.

3. Implement the RulesMinaServicesClient interface that the Decision Server can use to provide the additional client functionality for the new MINA transport, as shown in the following example:

   Sample implementation of the RulesMinaServicesClient interface

   public class RulesMinaServicesClientImpl implements RulesMinaServicesClient {
   
       private String host;
       private Integer port;
   
       private Marshaller marshaller;
   
       public RulesMinaServicesClientImpl(KieServicesConfiguration configuration, ClassLoader classloader) {
           String[] serverDetails = configuration.getServerUrl().split(":");
   
           this.host = serverDetails[0];
           this.port = Integer.parseInt(serverDetails[1]);
   
           this.marshaller = MarshallerFactory.getMarshaller(configuration.getExtraJaxbClasses(), MarshallingFormat.JSON, classloader);
       }
   
       public ServiceResponse<String> executeCommands(String id, String payload) {
   
           try {
               String response = sendReceive(id, payload);
               if (response.startsWith("{")) {
                   return new ServiceResponse<String>(ResponseType.SUCCESS, null, response);
               } else {
                   return new ServiceResponse<String>(ResponseType.FAILURE, response);
               }
           } catch (Exception e) {
               throw new KieServicesException("Unable to send request to KIE Server", e);
           }
       }
   
       public ServiceResponse<String> executeCommands(String id, Command<?> cmd) {
           try {
               String response = sendReceive(id, marshaller.marshall(cmd));
               if (response.startsWith("{")) {
                   return new ServiceResponse<String>(ResponseType.SUCCESS, null, response);
               } else {
                   return new ServiceResponse<String>(ResponseType.FAILURE, response);
               }
           } catch (Exception e) {
               throw new KieServicesException("Unable to send request to KIE Server", e);
           }
       }
   
       protected String sendReceive(String containerId, String content) throws Exception {
   
           // Flatten the content to be single line:
           content = content.replaceAll("\\n", "");
   
           Socket minaSocket = null;
           PrintWriter out = null;
           BufferedReader in = null;
   
           StringBuffer data = new StringBuffer();
           try {
               minaSocket = new Socket(host, port);
               out = new PrintWriter(minaSocket.getOutputStream(), true);
               in = new BufferedReader(new InputStreamReader(minaSocket.getInputStream()));
   
               // Prepare and send data:
               out.println(containerId + "|" + content);
               // Wait for the first line:
               data.append(in.readLine());
               // Continue as long as data is available:
               while (in.ready()) {
                   data.append(in.readLine());
               }
   
               return data.toString();
           } finally {
               out.close();
               in.close();
               minaSocket.close();
           }
       }
   }

   Copy to Clipboard Toggle word wrap

   This example implementation specifies the following data and behavior:

   • Uses socket-based communication for simplicity
   • Relies on default configurations from the Decision Server client and uses ServerUrl for providing the host and port of the MINA server
   • Specifies JSON as the marshalling format
   • Requires received messages to be JSON objects that start with an open bracket {
   • Uses direct socket communication with a blocking API while waiting for the first line of the response and then reads all lines that are available
   • Does not use stream mode and therefore disconnects the Decision Server session after invoking a command

4. Implement the org.kie.server.client.helper.KieServicesClientBuilder interface in a Java class in your project, as shown in the following example:

   Sample implementation of the KieServicesClientBuilder interface

   public class MinaClientBuilderImpl implements KieServicesClientBuilder {  

   1

   
   
       public String getImplementedCapability() {  

   2

   
           return "BRM-Mina";
       }
   
       public Map<Class<?>, Object> build(KieServicesConfiguration configuration, ClassLoader classLoader) {  

   3

   
           Map<Class<?>, Object> services = new HashMap<Class<?>, Object>();
   
           services.put(RulesMinaServicesClient.class, new RulesMinaServicesClientImpl(configuration, classLoader));
   
           return services;
       }
   
   }

   Copy to Clipboard Toggle word wrap

   1

   Enables you to provide additional client APIs to the generic Decision Server client infrastructure

   2

   Defines the Decision Server capability (extension) that the client uses

   3

   Provides a map of the client implementations, where the key is the interface and the value is the fully initialized implementation

5. To make the new client API discoverable for the Decision Server client, create a META-INF/services/org.kie.server.client.helper.KieServicesClientBuilder file in your Maven project and add the fully qualified class name of the KieServicesClientBuilder implementation class within the file. For this example, the file contains the single line org.kie.server.ext.mina.client.MinaClientBuilderImpl.
6. Build your project and copy the resulting JAR file into the ~/kie-server.war/WEB-INF/lib directory of your project. For example, on Red Hat JBoss EAP, the path to this directory is EAP_HOME/standalone/deployments/kie-server.war/WEB-INF/lib.

7. Start the Decision Server and deploy the built project to the running Decision Server. You can deploy the project using either the Business Central interface or the Decision Server REST API (a PUT request to http://SERVER:PORT/kie-server/services/rest/server/containers/{containerId}).

   After your project is deployed on a running Decision Server, you can start interacting with your new Decision Server client. You use your new client in the same way as the standard Decision Server client, by creating the client configuration and client instance, retrieving the service client by type, and invoking client methods.

   For this example, you can create a RulesMinaServiceClient client instance and invoke operations on Decision Server through the MINA transport:

   Sample implementation to create the RulesMinaServiceClient client

   protected RulesMinaServicesClient buildClient() {
       KieServicesConfiguration configuration = KieServicesFactory.newRestConfiguration("localhost:9123", null, null);
       List<String> capabilities = new ArrayList<String>();
       // Explicitly add capabilities (the MINA client does not respond to `get-server-info` requests):
       capabilities.add("BRM-Mina");
   
       configuration.setCapabilities(capabilities);
       configuration.setMarshallingFormat(MarshallingFormat.JSON);
   
       configuration.addJaxbClasses(extraClasses);
   
       KieServicesClient kieServicesClient =  KieServicesFactory.newKieServicesClient(configuration);
   
       RulesMinaServicesClient rulesClient = kieServicesClient.getServicesClient(RulesMinaServicesClient.class);
   
       return rulesClient;
   }

   Copy to Clipboard Toggle word wrap

   Sample configuration to invoke operations on Decision Server through the MINA transport

   RulesMinaServicesClient rulesClient = buildClient();
   
   List<Command<?>> commands = new ArrayList<Command<?>>();
   BatchExecutionCommand executionCommand = commandsFactory.newBatchExecution(commands, "defaultKieSession");
   
   Person person = new Person();
   person.setName("mary");
   commands.add(commandsFactory.newInsert(person, "person"));
   commands.add(commandsFactory.newFireAllRules("fired"));
   
   ServiceResponse<String> response = rulesClient.executeCommands(containerId, executionCommand);
   Assert.assertNotNull(response);
   
   Assert.assertEquals(ResponseType.SUCCESS, response.getType());
   
   String data = response.getResult();
   
   Marshaller marshaller = MarshallerFactory.getMarshaller(extraClasses, MarshallingFormat.JSON, this.getClass().getClassLoader());
   
   ExecutionResultImpl results = marshaller.unmarshall(data, ExecutionResultImpl.class);
   Assert.assertNotNull(results);
   
   Object personResult = results.getValue("person");
   Assert.assertTrue(personResult instanceof Person);
   
   Assert.assertEquals("mary", ((Person) personResult).getName());
   Assert.assertEquals("JBoss Community", ((Person) personResult).getAddress());
   Assert.assertEquals(true, ((Person) personResult).isRegistered());

   Copy to Clipboard Toggle word wrap