Chapter 26. Configuring KIE Server to send information to ElasticSearch when a transaction is committed

You can configure KIE Server to send information to ElasticSearch automatically. In this case, KIE Server writes an ElasticSearch index entry every time a task, process, case, or variable is created, updated, or deleted. The index entry contains information about the modified object. KIE Server writes the index entry when it commits the transaction with the change.

You can use this functionality with any business process or case. You do not need to change anything in the process design.

This configuration is also available if you run your process service using Spring Boot.

KIE Server serializes the process, case, and task information as JSON documents. It uses the following ElasticSearch indexes:

  • processes for process information
  • cases for case information
  • tasks for task information

Prerequisites

Procedure

  1. To enable sending information to ElasticSearch, complete one of the following steps:

    1. If you deployed KIE Server on Red Hat JBoss EAP or another application server, complete the following steps:

      1. Download the rhpam-7.12.0-maven-repository.zip product deliverable file from the Software Downloads page of the Red Hat Customer Portal.
      2. Extract the contents of the file.
      3. Copy the maven-repository/org/jbpm/jbpm-event-emitters-elasticsearch/7.59.0.Final-redhat-00006/jbpm-event-emitters-elasticsearch-7.59.0.Final-redhat-00006.jar file into the deployments/kie-server.war/WEB-INF/lib subdirectory of the application server.

    2. If you deployed the application using Spring Boot, add the following lines to the <dependencies> list in the pom.xml file of your service: 

      <dependency>
  <groupId>org.jbpm</groupId>
  <artifactId>jbpm-event-emitters-elasticsearch</artifactId>
  <version>${version.org.kie}</version>
</dependency>

  2. Configure any of the following KIE Server system properties as necessary:

    • org.jbpm.event.emitters.elasticsearch.url: The URL of the ElasticSearch server. The default value is http://localhost:9200.
    • org.jbpm.event.emitters.elasticsearch.date_format: The timestamp format for the information. The default value is yyyy-MM-dd’T’HH:mm:ss.SSSZ .
    • org.jbpm.event.emitters.elasticsearch.user: The user name for authenticating to the ElasticSearch server.
    • org.jbpm.event.emitters.elasticsearch.password: The password for authenticating the user to the ElasticSearch server.
    • org.jbpm.event.emitters.elasticsearch.ignoreNull: If this property is true, null values are not written into the JSON output for ElasticSearch.

26.1. Customizing data for ElasticSearch

You can develop transformer classes to customize the data that Red Hat Process Automation Manager sends to ElasticSearch.

Information about processes, cases, tasks, and task operations is available as views. Red Hat Process Automation Manager includes the following view types:

  • CaseInstanceView
  • ProcessInstanceView
  • TaskInstanceView
  • TaskOperationView

You can see the definitions of these views in the GitHub repository.

Each view has a getCompositeId() method that returns an identifier. This identifier denotes a particular instance of a case, process, task, or task operation.

Each time a process, case, task, or task operation is created, updated, or deleted, the process engine calls a transformer and supplies the relevant view.

The transformer must generate an ESRequest object. In the parameters of the constructor of this object, the transformer must supply the necessary information for the ElasticSearch request, including the index.

The definitions of the transformer classes and the ESRequest class are available in the GitHub repository.

To create and use custom transformers, complete the following procedure.

Procedure

  1. Create the Java source code for the following classes:

    • ESInstanceViewTransformer: The transformer class. It provides index() and update() methods. Both of the methods take a view as a parameter and return an ESRequest object.

      When a process, case, task, or task operation instance is first created, the process engine calls the index() method. For subsequent changes related to the same instance, the process engine calls the update() method.

      You can create different ESInstanceViewTransformer implementations for different view types.

    • ESInstanceViewTransformerFactory: The transformer factory class. It returns an instance of the ESInstanceViewTransformer class for every view type.
  2. In Business Central, enter your project and click the Settings → Dependencies tab.
  3. Optional: Add any dependencies that your transformer classes require.
  4. Click the Assets tab.

  5. For each of the class source files, complete the following steps:

    1. Click Import Asset.
    2. In the Please select a file to upload field, select the location of the Java source file for the custom serializer class.
    3. Click Ok to upload the file.
  6. For the KIE Server instance that runs the service, set the org.jbpm.event.emitters.elasticsearch.factory system property to the fully qualified class name of your implementation of ESInstanceViewTransformerFactory.