Article

Demystifying the Red Hat Decision Manager and Process Automation Manager Remote Client

December 10, 2018
Java
Duncan Doyle
Red Hat Decision Manager

KIE-Server is the light-weight, cloud-native, rules and process execution runtime of the Red Hat Decision Manager (RHDM) and Red Hat Process Automation Manager (RHPAM) platforms. Lately, I've gotten more and more questions on how to use the KIE-Server Client Java API to interact with the KIE-Server execution runtime of RHDM (formerly called Red Hat JBoss BRMS) and RHPAM (RHPAM). To answers these questions, and to create a future reference, I decided to write a number of code examples, accompanied by this article.

The KIE-Server Client Java API provides an easy way for Java applications to communicate with the KIE-Server execution engine of RHDM and RHPAM. The API abstracts the application from the underlying REST and/or JMS communication protocol and transport, making integrations with the server easier to build, test, and maintain.

What is the KIE-Server Client?

The KIE-Server Client is a small, lightweight Java library, providing a pure Java API, that allows Java clients to interact with Red Hat Decision Manager and RHPAM execution servers over a RESTful (or JMS) communication channel. This abstracts the client from the marshaling of the request and response data into the format that the execution server expects (either JSON, JAXB, or XSTREAM), as well as the handling of sending requests and receiving responses over HTTP (or via a JMS Broker when using the JMS API). This greatly simplifies the code of Java clients that want to interact with our platforms.

The API

Let's first look at the API itself. The API is structured around the KieServicesClient. The KieServicesClient is one of the main components that can be built from the KieServicesFactory, and it gives us access to the various runtimes that KIE-Server provides. KIE-Server uses a plug-in based system, and every functionality of the platform is provided through plug-ins.

For each plugin that exposes a remote interface, the client provides a matching client-side service. For example, to execute rules via the KIE-Server rules engine, we use the RuleServicesClient, Decision Model and Notation (DMN) models are evaluated with the DMNServicesClient, and interaction with the process engine is done via the ProcessServicesClient. Other available clients are:

  • CaseServicesClient to interact with the Case Management system
  • UserTaskServicesClient to interact with the process engine's UserTask engine
  • QueryServicesClient to execute queries against the server
  • SolverServicesClient to integrate with the OptaPlanner capabilities

And there are various administration clients.

The code below shows how a specific client, in this case, a ProcessServicesClient, can be retrieved from the main KieServicesClient:

KieServicesClient kieServicesClient = KieServicesFactory.newKieServicesClient(kieServicesConfig);
ProcessServicesClientprocessClient=kieServicesClient.getServicesClient(ProcessServicesClient.class);

The various remote client APIs, where possible, are very close to the standard Java APIs that KIE, Drools, Red Hat JBoss Frameworks (formerly Red Hat JBoss jBPM), and OptaPlanner expose. However, there are some differences that users need to be aware of.

Using the right KIE-Session

When using Decision Manager/Drools as an embedded library, a KieSession, the session in which you insert data and executes rule, is retrieved from a KieContainer. The KieContainer API allows you to select the specific KieSession you want to use. Different KieSessions can be configured in the kmodule.xml deployment descriptor of the rules deployment unit (the KJAR). This allows us to define and configure different kinds of sessions, for example, stateless KieSessions, stateful KieSessions, or KieSessions that use a pseudo-clock—whatever our use-case requires.

Selecting the right KieSession when using the remote KIE-Server Client is done differently, because the API does not expose the KieContainer. Instead, we need to specify the "ID" of the KieSession to be used in a BatchExecutorCommand, as shown here:

BatchExecutionCommand batchExecutionCommand = commandFactory.newBatchExecution(commands, "default-stateless-kiession");

This will result in a JSON payload that contains a "lookup" entry, which tells the KIE-Server which session to use for the given request:

{
  "lookup" : "default-stateless-ksession",
  "commands" : [ {

The ID should match the ID of a KieSession defined in the KJAR's kmodule.xml, as shown here:

<kmodule xmlns="http://www.drools.org/xsd/kmodule" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <kbase name="default-kbase" default="true" eventProcessingMode="cloud" equalsBehavior="equality">
    <ksession name="default-stateless-ksession" type="stateless" default="true" clockType="realtime"/>
  </kbase>
</kmodule>

When using the remote client API, it is recommended to use stateless KieSessions, unless your use-case explicitly requires stateful sessions.

Marshaling and custom data types

When using a remote API, data needs to be sent from the client to the server in a format that both parties understand. KIE-Server supports three formats: JSON, JAXB, and XSTREAM. Some of the KIE-Server APIs, for example, the API to start a business process, accept generic datatypes as input, such as a Map. This Map is used to send process start variables to the process execution engine.

When our process variables consist of custom defined datatypes, for example, Applicant or Loan, we need to register these datatypes with the KIE-Server Client. This allows the Marshaller component to correctly marshal and unmarshal these datatypes when communicating with the remote KIE-Server. Java classes can simply be registered via the KieServicesConfiguration, as shown here:

KieServicesConfiguration kieServicesConfig = KieServicesFactory.newRestConfiguration(KIE_SERVER_URL, credentialsProvider);
Set<Class<?>> extraClasses = new HashSet<>();
extraClasses.add(Application.class);
extraClasses.add(Applicant.class);
extraClasses.add(Property.class);
kieServicesConfig.addExtraClasses(extraClasses);

Examples

In this GitHub repository, I've collected three examples of KIE-Server Clients that communicate with remote services on the KIE-Server. The examples show how to:

  • Start a business process.
  • Execute rules.
  • Evaluate a DMN model.

Three Main classes are provided that demonstrate the usage of the API. Comments in the code provide further explanation of the APIs being used.

Conclusion

This article provided a brief introduction to the KIE-Server Client Java API, provided some tips and tricks for how to best use the API, and concluded with examples that demonstrate how to start a process, execute rules, and evaluate a DMN model.

Here are related articles that might be of interest:

Duncan Doyle

About the author:

Duncan Doyle is the Technical Marketing Manager for the Decision Manager and Process Automation Manager platforms at Red Hat. With a background in Red Hat Consulting and Services, Duncan has worked extensively with large Red Hat customers to build advanced, open-source, business-rules and business process management solutions.

He has a strong background in technologies and concepts such as Service Oriented Architecture, Continuous Integration and Delivery, rules engines, and BPM platforms and is a subject matter expert (SME) on multiple JBoss Middleware technologies, including, but not limited to, JBoss EAP, HornetQ, Fuse, DataGrid, BRMS, and BPMSuite. When he’s not working on open-source solutions and technology, he is building Lego with his son and daughter or jamming along some 90’s rock-music on his Fender Stratocaster.

Last updated: January 22, 2024