Managing and monitoring Process 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

Procedure

1. On the first computer, run the installer in interactive mode or CLI mode. See Installing and configuring Red Hat Process Automation Manager on Red Hat JBoss EAP 7.1 for more information.
2. On the Component Selection page, clear the Process 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 Process Server properties and click Next.
8. On the Process Server Properties Configuration page, click New Server Configuration to add a Process Server and specify a unique name for that Process Server. This name will appear in Business Central and enable you to distinguish between different Process 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: Process Automation Manager
   • Version: 7.1
2. Download Red Hat Process Automation Manager 7.1.0 Add Ons (the rhpam-7.1.0-add-ons.zip file).
3. Unzip the rhpam-7.1.0-add-ons.zip file. The rhpam-7.1-controller-ee7.zip file is in the unzipped directory.
4. Extract the rhpam-7.1-controller-ee7 archive to a temporary directory. In the following examples this directory is called TEMP_DIR.

5. Copy the TEMP_DIR/rhpam-7.1-controller-ee7/controller.war directory to EAP_HOME/standalone/deployments/.

   Warning

   Ensure that the names of the headless Process Automation Manager controller deployments you are copying do not conflict with your existing deployments in the Red Hat JBoss EAP instance.

6. Copy the contents of the TEMP_DIR/rhpam-7.1-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 Process Automation Manager controller is automatically deployed when the server starts.

Procedure

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

2. Enter the following command:

   • On Linux or UNIX-based systems:

     $ ./standalone.sh

   • On Windows:

     standalone.bat

3. To verify that the headless Process Automation 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 Process Server instance.

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

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: Process Automation Manager
   • Version: 7.1
2. Download Red Hat Process Automation Manager 7.1.0 Add Ons (the rhpam-7.1.0-add-ons.zip file).
3. Unzip the rhpam-7.1.0-add-ons.zip file. The rhpam-7.1-controller-ee7.zip file is in the unzipped directory.
4. Extract the rhpam-7.1-controller-ee7.zip file to a temporary directory. In the following examples this directory is called TEMP_DIR.

5. Repackage the controller.war directory:

   1. Navigate to the TEMP_DIR/rhpam-7.1.0-add-ons/rhpam-7.1-controller-ee7/controller.war directory.
   2. Select the contents of the TEMP_DIR/rhpam-7.1.0-add-ons/rhpam-7.1-controller-ee7/controller.war directory and create the controller.zip file.
   3. Rename controller.zip to controller.war. This is the file that you will use to deploy the headless Process Automation Manager controller on the cluster nodes.
   4. If desired, copy the new controller.war file to a location that is more convenient to deploy from.
6. If you want to use a security manager with the headless Process Automation Manager controller, copy the contents of the TEMP_DIR/rhpam-7.1.0-add-ons/rhpam-7.1-controller-ee7/SecurityPolicy directory to the EAP_HOME/bin directory on each node of the cluster.
7. Add Red Hat JBoss EAP management users to the master node (where you configured the domain.xml file) as described in the Red Hat JBoss EAP 7.1 Configuration Guide.
8. On each node of the cluster, add users for the headless Process Automation Manager controller as described in the "Installing the headless Process Automation Manager controller" section of Installing and configuring Red Hat Process Automation Manager on Red Hat JBoss EAP 7.1.

9. Complete the following steps in the host.xml file on the master node and in the host-slave.xml file on each slave node:

   1. Open the EAP_HOME/domain/configuration/host.xml or EAP_HOME/domain/configuration/host-slave.xml file in a text editor.
   2. In the main-server-group <servers> element, add the servers that will be part of the cluster.

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

      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 deploy the controller.war file that you created previously into the server group, complete the following steps on the master node:

    1. Log in to the Red Hat JBoss EAP Administration console of your domain as a management user.
    2. Click Deployments → Server Groups→ main-server-group and click Add.
    3. In the dialog box, click Upload a new deployment and click Next.
    4. In the Upload Deployments dialog box, click Browse, select the controller.war file, and click Next.

    5. Click Enable and click Next.

       Note

       Make sure to check deployment unit readiness with every cluster member.

       When a deployment unit is created on a cluster node, it takes some time before it is distributed among all cluster members. You can check the deployment status using the server Administration console or REST API. However, if the query is sent to the node where the deployment was originally issued, the query will return a value of deployed. If the query is sent to a node where the deployment has not yet been distributed, the query returns DeploymentNotFoundException.

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 the previous steps.
5. When you have finished adding all required roles, click Save.

1. In Business Central, click Menu → Manage → Execution Errors.
2. Select an error from the list to open the Details tab. This displays information about the error or errors.
3. Click the Acknowledge button to acknowledge and clear the error. The error can still be viewed later by selecting Yes on the Acknowledged filter in the Manage Execution Errors page.

4. If the error was related to a task, a Go to Task button is displayed.

   Click the Go to Task button to view the associated job information in the Manage Tasks page.

   The Manage Tasks page allows you to restart, reschedule, or retry the corresponding task.

1. Task
2. Process
3. Job
4. DB

Prerequisite

1. Execution errors of one or more type have accumulated during processes execution but require no further attention.

Procedure

1. In Business Central, click Menu → Manage → Jobs.
2. In the top right of the screen, click New Job.
3. Type the process correlation key into the Business Key field.
4. In the Type field, add type of the auto acknowledge job type from the list above.

5. Select a Due On time for the job to be completed:

   1. To run the job immediately, select the Run now option.

   2. To run the job at a specific time, select Run later. A date and time field appears next to the Run later option. Click the field to open the calendar and schedule a specific time and date for the job.

      
6. Click Create to create the job and return to the Manage Jobs page.

1. Click on the Advanced tab.
2. Click the Add Parameter button.

3. Enter the configuration parameter you want to apply to the job:

   1. SingleRun: true or false
   2. NextRun: time expression, such as 2h, 5d, 1m, and so on.

   3. EmfName: custom entity manager factory name.

      

Procedure

1. To configure Process Server persistence, complete any of the following tasks:

   If you want to configure Process Server persistence using Red Hat JBoss EAP configuration file, complete the following tasks:

   1. In your Red Hat Process Automation Manager installation directory, navigate to the standalone-full.xml file. For example, if you use Red Hat JBoss EAP installation for Red Hat Process Automation Manager, go to $EAP_HOME/standalone/configuration/standalone-full.xml file.

   2. Open the standalone-full.xml file and under the <system-properties> tag, set your Hibernate or JPA parameters as system properties.

      Example of configuring Process Server persistence using Hibernate parameters

      <system-properties>
          ...
              <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
          ...
      <system-properties>

      Example of configuring Process Server persistence using JPA parameters

      <system-properties>
          ...
              <property name="javax.persistence.jdbc.url" value="jdbc:mysql://mysql.db.server:3306/my_database?useSSL=false&serverTimezone=UTC"/>
          ...
      <system-properties>

   If you want to configure Process Server persistence using command line, complete the following tasks:

   1. Pass the parameters directly from the command line using -Dkey=value as follows:

      Example of configuring Process Server persistence using Hibernate parameters:

      $EAP_HOME/bin/standalone.sh -Dhibernate.hbm2ddl.auto=create-drop

      Example of configuring Process Server persistence using JPA parameters:

      $EAP_HOME/bin/standalone.sh -Djavax.persistence.jdbc.url=jdbc:mysql://mysql.db.server:3306/my_database?useSSL=false&serverTimezone=UTC

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

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

   1

   Delivers REST endpoints to the Process 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 Process 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 Process 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);
           }
   
       }
   }

   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 Process 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 Process 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 Process Server and deploy the built project to the running Process Server. You can deploy the project using either the Business Central interface or the Process 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 Process 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
         }
       }
     ]

   • 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

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

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

   The KieServerExtension interface is the main extension interface that Process 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
   }

   1

   Specifies the capability that is covered by this extension. The capability must be unique within Process 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) {
   
           }
       }
   }

   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 Process Server session. To end a Process Server session in stream mode, send either an exit or quit command to the server.
4. To make the new data transport discoverable for Process 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 Process Server and deploy the built project to the running Process Server. You can deploy the project using either the Business Central interface or the Process 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 Process Server, you can view the status of the new data transport in your Process 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

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

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

   telnet 127.0.0.1 9123

   Example interactions with Process 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.

   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

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

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

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

   This example implementation specifies the following data and behavior:

   • Uses socket-based communication for simplicity
   • Relies on default configurations from the Process 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 Process 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;
       }
   
   }

   1

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

   2

   Defines the Process 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 Process 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 Process Server and deploy the built project to the running Process Server. You can deploy the project using either the Business Central interface or the Process 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 Process Server, you can start interacting with your new Process Server client. You use your new client in the same way as the standard Process 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 Process 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;
   }

   Sample configuration to invoke operations on Process 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());