Getting started with Red Hat build of Kogito in Red Hat Decision Manager

Red Hat Decision Manager 7.11

Abstract

This document describes how to get started with decision services and planning solutions in Red Hat Decision Manager.

Preface

As a developer of business decisions , you can use Red Hat build of Kogito to build cloud-native applications that adapt your business domain and tooling.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Part I. Getting started with Red Hat build of Kogito microservices

As a developer of business decisions, you can use Red Hat build of Kogito business automation to develop decision services using Decision Model and Notation (DMN) models, Drools Rule Language (DRL) rules, Predictive Model Markup Language (PMML) or a combination of all three methods.

Prerequisites

  • JDK 11 or later is installed.
  • Apache Maven 3.6.2 or later is installed.

Chapter 1. Red Hat build of Kogito microservices in Red Hat Decision Manager

Red Hat build of Kogito is a cloud-native business automation technology for building cloud-ready business applications. The name Kogito derives from the Latin "Cogito", as in "Cogito, ergo sum" ("I think, therefore I am"), and is pronounced [ˈkoː.d͡ʒi.to] (KO-jee-to). The letter K refers to Kubernetes, the base for Red Hat OpenShift Container Platform as the target cloud platform for Red Hat Decision Manager, and to the Knowledge Is Everything (KIE) open source business automation project from which Red Hat build of Kogito originates.

Red Hat build of Kogito in Red Hat Decision Manager is optimized for a hybrid cloud environment and adapts to your domain and tooling needs. The core objective of Red Hat build of Kogito microservices is to help you mold a set of decisions into your own domain-specific cloud-native set of services.

Important

In Red Hat Decision Manager 7.11 version, Red Hat build of Kogito support is limited to decision services, including Decision Model and Notation (DMN), Drools Rule Language (DRL), and Predictive Model Markup Language (PMML). This support will be improved and extended to Business Process Modeling Notation (BPMN) in a future release.

When you use Red Hat build of Kogito, you are building a cloud-native application as a set of independent domain-specific microservices to achieve some business value. The decisions that you use to describe the target behavior are executed as part of the microservices that you create. The resulting microservices are highly distributed and scalable with no centralized orchestration service, and the runtime that your microservice uses is optimized for what is required.

As a business rules developer, you can use Red Hat build of Kogito microservices in Red Hat Decision Manager to build cloud-native applications that adapt to your business domain and tooling.

1.1. Cloud-first priority

Red Hat build of Kogito microservices are designed to run and scale on a cloud infrastructure. You can use Red Hat build of Kogito microservices in Red Hat Decision Manager with the latest cloud-based technologies, such as Red Hat build of Quarkus, to increase start times and instant scaling on container application platforms, such as Red Hat OpenShift Container Platform.

For example, Red Hat build of Kogito microservices are compatible with the following technologies:

  • Red Hat OpenShift Container Platform is based on Kubernetes, and is the target platform for building and managing containerized applications.
  • Red Hat build of Quarkus is a native Java stack for Kubernetes that you can use to build applications, using the Red Hat build of Kogito microservices.
  • Spring Boot is an application framework that you can use to configure Spring Framework with Red Hat Decision Manager.

1.2. Red Hat build of Kogito microservices on Red Hat build of Quarkus and Spring Boot

The primary Java frameworks that Red Hat build of Kogito microservices support are Red Hat build of Quarkus and Spring Boot.

Red Hat build of Quarkus is a Kubernetes-native Java framework with a container-first approach to building Java applications, especially for Java virtual machines (JVMs) such as OpenJDK HotSpot. Red Hat build of Quarkus optimizes Java specifically for Kubernetes by reducing the size of both the Java application and container image footprint, eliminating some of the Java programming workload from previous generations, and reducing the amount of memory required to run those images.

For Red Hat build of Kogito microservices, Red Hat build of Quarkus is the preferred framework for optimal Kubernetes compatibility and enhanced developer features, such as live reload in development mode for advanced debugging.

Spring Boot is a Java-based framework for building standalone production-ready Spring applications. Spring Boot enables you to develop Spring applications with minimal configurations and without an entire Spring configuration setup.

For Red Hat build of Kogito microservices, Spring Boot is supported for developers who need to use Red Hat Decision Manager in an existing Spring Framework environment.

Chapter 2. DMN modelers for Red Hat build of Kogito microservices

Red Hat Decision Manager provides extensions or applications that you can use to design Decision Model and Notation (DMN) decision models for your Red Hat build of Kogito microservices using graphical modelers.

The following DMN modelers are available in the Business Modeler Hub desktop application:

  • VSCode extension: Enables you to view and design DMN models in Visual Studio Code (VSCode). The VSCode extension requires VSCode 1.46.0 or later.

    To install the VSCode extension directly in VSCode, select the Extensions menu option in VSCode and search for and install the Red Hat Business Automation Bundle extension.

  • Business Modeler standalone editors: Enable you to view and design DMN models embedded in your web applications. To download the necessary files, you can either use the NPM artifacts from the Kogito tooling repository or download the JavaScript files directly for the DMN standalone editor library at https://kiegroup.github.io/kogito-online/standalone/dmn/index.js.

2.1. Installing the Red Hat Decision Manager VSCode extension bundle

Red Hat Decision Manager provides a Red Hat Business Automation Bundle VSCode extension that enables you to design Decision Model and Notation (DMN) decision models, Business Process Model and Notation (BPMN) 2.0 business processes, and test scenarios directly in VSCode. VSCode is the preferred integrated development environment (IDE) for developing new business applications. Red Hat Decision Manager also provides individual DMN Editor and BPMN Editor VSCode extensions for DMN or BPMN support only, if needed.

Important

The editors in the VSCode are partially compatible with the editors in the Business Central, and several Business Central features are not supported in the VSCode.

Prerequisites

  • The latest stable version of VSCode is installed.

Procedure

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

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

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

After you install the VSCode extension bundle, any .dmn, .bpmn, or .bpmn2 files that you open or create in VSCode are automatically displayed as graphical models. Additionally, any .scesim files that you open or create are automatically displayed as tabular test scenario models for testing the functionality of your business decisions.

If the DMN, BPMN, or test scenario modelers open only the XML source of a DMN, BPMN, or test scenario file and displays an error message, review the reported errors and the model file to ensure that all elements are correctly defined.

Note

For new DMN or BPMN models, you can also enter dmn.new or bpmn.new in a web browser to design your DMN or BPMN model in the online modeler. When you finish creating your model, you can click Download in the online modeler page to import your DMN or BPMN file into your Red Hat Decision Manager project in VSCode.

2.2. Configuring the Red Hat Decision Manager standalone editors

Red Hat Decision Manager provides standalone editors that are distributed in a self-contained library providing an all-in-one JavaScript file for each editor. The JavaScript file uses a comprehensive API to set and control the editor.

You can install the standalone editors in three ways:

  • Download each JavaScript file manually
  • Use the NPM package

Procedure

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

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

    1. Download the JavaScript files.
    2. Add the downloaded Javascript files to your hosted application.
    3. Add the following <script> tag to your HTML page:

      Script tag for your HTML page for the DMN editor

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

      Script tag for your HTML page for the BPMN editor

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

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

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

      Adding the NPM package

      npm install @redhat/kogito-tooling-kie-editors-standalone

    2. Import each editor library to your TypeScript file:

      Importing each editor

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

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

    Opening the DMN standalone editor

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

    Use the following parameters with the editor API:

    Table 2.1. Example parameters

    ParameterDescription

    container

    HTML element in which the editor is appended.

    initialContent

    Promise to a DMN model content. This parameter can be empty, as shown in the following examples:

    • Promise.resolve("")
    • Promise.resolve("<DIAGRAM_CONTENT_DIRECTLY_HERE>")
    • fetch("MyDmnModel.dmn").then(content ⇒ content.text())

    readOnly (Optional)

    Enables you to allow changes in the editor. Set to false (default) to allow content editing and true for read-only mode in editor.

    origin (Optional)

    Origin of the repository. The default value is window.location.origin.

    resources (Optional)

    Map of resources for the editor. For example, this parameter is used to provide included models for the DMN editor or work item definitions for the BPMN editor. Each entry in the map contains a resource name and an object that consists of content-type (text or binary) and content (similar to the initialContent parameter).

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

    Table 2.2. Returned object methods

    MethodDescription

    getContent(): Promise<string>

    Returns a promise containing the editor content.

    setContent(content: string): void

    Sets the content of the editor.

    getPreview(): Promise<string>

    Returns a promise containing an SVG string of the current diagram.

    subscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): (isDirty: boolean) ⇒ void

    Sets a callback to be called when the content changes in the editor and returns the same callback to be used for unsubscription.

    unsubscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): void

    Unsubscribes the passed callback when the content changes in the editor.

    markAsSaved(): void

    Resets the editor state that indicates that the content in the editor is saved. Also, it activates the subscribed callbacks related to content change.

    undo(): void

    Undoes the last change in the editor. Also, it activates the subscribed callbacks related to content change.

    redo(): void

    Redoes the last undone change in the editor. Also, it activates the subscribed callbacks related to content change.

    close(): void

    Closes the editor.

    getElementPosition(selector: string): Promise<Rect>

    Provides an alternative to extend the standard query selector when an element lives inside a canvas or a video component. The selector parameter must follow the <PROVIDER>:::<SELECT> format, such as Canvas:::MySquare or Video:::PresenterHand. This method returns a Rect representing the element position.

    envelopeApi: MessageBusClientApi<KogitoEditorEnvelopeApi>

    This is an advanced editor API. For more information about advanced editor API, see MessageBusClientApi and KogitoEditorEnvelopeApi.

Chapter 3. Creating a Maven project for a Red Hat build of Kogito microservice

Before you can begin developing Red Hat build of Kogito microservices, you need to create a Maven project where you can build your assets and any other related resources for your application.

Procedure

  1. In a command terminal, navigate to a local folder where you want to store the new project.
  2. Enter the following command to generate a project within a defined folder:

    On Red Hat build of Quarkus

    $ mvn archetype:generate \
        -DarchetypeGroupId=org.kie.kogito \
        -DarchetypeArtifactId=kogito-quarkus-dm-archetype \
        -DgroupId=org.acme -DartifactId=sample-kogito \
        -DarchetypeVersion=1.5.0.redhat-00002 \
        -Dversion=1.0-SNAPSHOT

    On Spring Boot

    $ mvn archetype:generate \
        -DarchetypeGroupId=org.kie.kogito \
        -DarchetypeArtifactId=kogito-springboot-dm-archetype \
        -DgroupId=org.acme -DartifactId=sample-kogito \
        -DarchetypeVersion=1.5.0.redhat-00002 \
        -Dversion=1.0-SNAPSHOT

    This command generates a sample-kogito Maven project and imports the extension for all required dependencies and configurations to prepare your application for business automation.

    If you want to enable PMML execution for your project, add the following dependency to the pom.xml file in the Maven project that contains your Red Hat build of Kogito microservices:

    Dependency to enable PMML execution

    <dependency>
      <groupId>org.kie.kogito</groupId>
      <artifactId>kogito-pmml</artifactId>
    </dependency>
    <dependency>
      <groupId>org.jpmml</groupId>
      <artifactId>pmml-model</artifactId>
    </dependency>

    On Red Hat build of Quarkus, if you plan to run your application on OpenShift, you must also import the smallrye-health extension for the liveness and readiness probes, as shown in the following example:

    SmallRye Health extension for Red Hat build of Quarkus applications on OpenShift

    $ mvn quarkus:add-extension -Dextensions="smallrye-health"

    This command generates the following dependency in the pom.xml file of your Red Hat Decision Manager project on Red Hat build of Quarkus:

    SmallRye Health dependency for Red Hat build of Quarkus applications on OpenShift

    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-smallrye-health</artifactId>
    </dependency>

  3. Open or import the project in your VSCode IDE to view the contents.

Chapter 4. Example applications with Red Hat build of Kogito microservices

Red Hat build of Kogito microservices include example applications in the rhdm-7.11.0-decision-services-quickstarts.zip file. These example applications contain various types of services on Red Hat build of Quarkus or Spring Boot to help you develop your own applications. The services use one or more Decision Model and Notation (DMN) decision models, Drools Rule Language (DRL) rule units, Predictive Model Markup Language (PMML) models, or Java classes to define the service logic.

For information about each example application and instructions for using them, see the README file in the relevant application folder.

Note

When you run examples in a local environment, ensure that the environment matches the requirements that are listed in the README file of the relevant application folder. Also, this might require making the necessary network ports available, as configured for Red Hat build of Quarkus, Spring Boot, and docker-compose where applicable.

The following list describes some of the examples provided with Red Hat build of Kogito microservices:

Decision services
  • dmn-quarkus-example and dmn-springboot-example: A decision service (on Red Hat build of Quarkus or Spring Boot) that uses DMN to determine driver penalty and suspension based on traffic violations.
  • rules-quarkus-helloworld: A Hello World decision service on Red Hat build of Quarkus with a single DRL rule unit.
  • ruleunit-quarkus-example and ruleunit-springboot-example: A decision service (on Red Hat build of Quarkus or Spring Boot) that uses DRL with rule units to validate a loan application and that exposes REST operations to view application status.
  • dmn-pmml-quarkus-example and dmn-pmml-springboot-example: A decision service (on Red Hat build of Quarkus or Spring Boot) that uses DMN and PMML to determine driver penalty and suspension based on traffic violations.
  • dmn-drools-quarkus-metrics and dmn-drools-springboot-metrics: A decision service (on Red Hat build of Quarkus or Spring Boot) that enables and consumes the runtime metrics monitoring feature in Red Hat build of Kogito.
  • pmml-quarkus-example and pmml-springboot-example: A decision service (on Red Hat build of Quarkus or Spring Boot) that uses PMML.

For more information about using DMN, DRL, and PMML models in Red Hat Decision Manager, see Designing a decision service using DMN models, Designing a decision service using DRL rules, and Designing a decision service using PMML models.

Chapter 5. Designing the application logic for a Red Hat build of Kogito microservice using DMN

After you create your project, you can create or import Decision Model and Notation (DMN) decision models and Drools Rule Language (DRL) business rules in the src/main/resources folder of your project. You can also include Java classes in the src/main/java folder of your project that act as Java services or provide implementations that you call from your decisions.

The example for this procedure is a basic Red Hat build of Kogito microservice that provides a REST endpoint /persons. This endpoint is automatically generated based on an example PersonDecisions.dmn DMN model to make decisions based on the data being processed.

The business decision contains the decision logic of the Red Hat Decision Manager service. You can define business rules and decisions in different ways, such as with DMN models or DRL rules. The example for this procedure uses a DMN model.

Prerequisites

Procedure

  1. In the Maven project that you generated for your Red Hat Decision Manager service, navigate to the src/main/java/org/acme folder and add the following Person.java file:

    Example person Java object

    package org.acme;
    
    import java.io.Serializable;
    
    public class Person {
    
    	private String name;
    	private int age;
    	private boolean adult;
    
    	public String getName() {
    		return name;
    	}
    
    	public void setName(String name) {
    		this.name = name;
    	}
    
    	public int getAge() {
    		return age;
    	}
    
    	public void setAge(int age) {
    		this.age = age;
    	}
    
    	public boolean isAdult() {
    		return adult;
    	}
    
    	public void setAdult(boolean adult) {
    		this.adult = adult;
    	}
    
    	@Override
    	public String toString() {
    		return "Person [name=" + name + ", age=" + age + ", adult=" + adult + "]";
    	}
    
    }

    This example Java object sets and retrieves a person’s name, age, and adult status.

  2. Navigate to the src/main/resources folder and add the following PersonDecisions.dmn DMN decision model:

    Figure 5.1. Example PersonDecisions DMN decision requirements diagram (DRD)

    Image of PersonDecisions decision diagram

    Figure 5.2. Example DMN boxed expression for isAdult decision

    Image of PersonDecisions decision table

    Figure 5.3. Example DMN data types

    Image of PersonDecisions data types

    This example DMN model consists of a basic DMN input node and a decision node defined by a DMN decision table with a custom structured data type.

    In VSCode, you can add the Red Hat Business Automation Bundle VSCode extension to design the decision requirements diagram (DRD), boxed expression, and data types with the DMN modeler.

    To create this example DMN model quickly, you can copy the following PersonDecisions.dmn file content:

    Example DMN file

    <dmn:definitions xmlns:dmn="http://www.omg.org/spec/DMN/20180521/MODEL/" xmlns="https://kiegroup.org/dmn/_52CEF9FD-9943-4A89-96D5-6F66810CA4C1" xmlns:di="http://www.omg.org/spec/DMN/20180521/DI/" xmlns:kie="http://www.drools.org/kie/dmn/1.2" xmlns:dmndi="http://www.omg.org/spec/DMN/20180521/DMNDI/" xmlns:dc="http://www.omg.org/spec/DMN/20180521/DC/" xmlns:feel="http://www.omg.org/spec/DMN/20180521/FEEL/" id="_84B432F5-87E7-43B1-9101-1BAFE3D18FC5" name="PersonDecisions" typeLanguage="http://www.omg.org/spec/DMN/20180521/FEEL/" namespace="https://kiegroup.org/dmn/_52CEF9FD-9943-4A89-96D5-6F66810CA4C1">
      <dmn:extensionElements/>
      <dmn:itemDefinition id="_DEF2C3A7-F3A9-4ABA-8D0A-C823E4EB43AB" name="tPerson" isCollection="false">
        <dmn:itemComponent id="_DB46DB27-0752-433F-ABE3-FC9E3BDECC97" name="Age" isCollection="false">
          <dmn:typeRef>number</dmn:typeRef>
        </dmn:itemComponent>
        <dmn:itemComponent id="_8C6D865F-E9C8-43B0-AB4D-3F2075A4ECA6" name="Name" isCollection="false">
          <dmn:typeRef>string</dmn:typeRef>
        </dmn:itemComponent>
        <dmn:itemComponent id="_9033704B-4E1C-42D3-AC5E-0D94107303A1" name="Adult" isCollection="false">
          <dmn:typeRef>boolean</dmn:typeRef>
        </dmn:itemComponent>
      </dmn:itemDefinition>
      <dmn:inputData id="_F9685B74-0C69-4982-B3B6-B04A14D79EDB" name="Person">
        <dmn:extensionElements/>
        <dmn:variable id="_0E345A3C-BB1F-4FB2-B00F-C5691FD1D36C" name="Person" typeRef="tPerson"/>
      </dmn:inputData>
      <dmn:decision id="_0D2BD7A9-ACA1-49BE-97AD-19699E0C9852" name="isAdult">
        <dmn:extensionElements/>
        <dmn:variable id="_54CD509F-452F-40E5-941C-AFB2667D4D45" name="isAdult" typeRef="boolean"/>
        <dmn:informationRequirement id="_2F819B03-36B7-4DEB-AED6-2B46AE3ADB75">
          <dmn:requiredInput href="#_F9685B74-0C69-4982-B3B6-B04A14D79EDB"/>
        </dmn:informationRequirement>
        <dmn:decisionTable id="_58370567-05DE-4EC0-AC2D-A23803C1EAAE" hitPolicy="UNIQUE" preferredOrientation="Rule-as-Row">
          <dmn:input id="_ADEF36CD-286A-454A-ABD8-9CF96014021B">
            <dmn:inputExpression id="_4930C2E5-7401-46DD-8329-EAC523BFA492" typeRef="number">
              <dmn:text>Person.Age</dmn:text>
            </dmn:inputExpression>
          </dmn:input>
          <dmn:output id="_9867E9A3-CBF6-4D66-9804-D2206F6B4F86" typeRef="boolean"/>
          <dmn:rule id="_59D6BFF0-35B4-4B7E-8D7B-E31CB0DB8242">
            <dmn:inputEntry id="_7DC55D63-234F-497B-A12A-93DA358C0136">
              <dmn:text>&gt; 18</dmn:text>
            </dmn:inputEntry>
            <dmn:outputEntry id="_B3BB5B97-05B9-464A-AB39-58A33A9C7C00">
              <dmn:text>true</dmn:text>
            </dmn:outputEntry>
          </dmn:rule>
          <dmn:rule id="_8FCD63FE-8AD8-4F56-AD12-923E87AFD1B1">
            <dmn:inputEntry id="_B4EF7F13-E486-46CB-B14E-1D21647258D9">
              <dmn:text>&lt;= 18</dmn:text>
            </dmn:inputEntry>
            <dmn:outputEntry id="_F3A9EC8E-A96B-42A0-BF87-9FB1F2FDB15A">
              <dmn:text>false</dmn:text>
            </dmn:outputEntry>
          </dmn:rule>
        </dmn:decisionTable>
      </dmn:decision>
      <dmndi:DMNDI>
        <dmndi:DMNDiagram>
          <di:extension>
            <kie:ComponentsWidthsExtension>
              <kie:ComponentWidths dmnElementRef="_58370567-05DE-4EC0-AC2D-A23803C1EAAE">
                <kie:width>50</kie:width>
                <kie:width>100</kie:width>
                <kie:width>100</kie:width>
                <kie:width>100</kie:width>
              </kie:ComponentWidths>
            </kie:ComponentsWidthsExtension>
          </di:extension>
          <dmndi:DMNShape id="dmnshape-_F9685B74-0C69-4982-B3B6-B04A14D79EDB" dmnElementRef="_F9685B74-0C69-4982-B3B6-B04A14D79EDB" isCollapsed="false">
            <dmndi:DMNStyle>
              <dmndi:FillColor red="255" green="255" blue="255"/>
              <dmndi:StrokeColor red="0" green="0" blue="0"/>
              <dmndi:FontColor red="0" green="0" blue="0"/>
            </dmndi:DMNStyle>
            <dc:Bounds x="404" y="464" width="100" height="50"/>
            <dmndi:DMNLabel/>
          </dmndi:DMNShape>
          <dmndi:DMNShape id="dmnshape-_0D2BD7A9-ACA1-49BE-97AD-19699E0C9852" dmnElementRef="_0D2BD7A9-ACA1-49BE-97AD-19699E0C9852" isCollapsed="false">
            <dmndi:DMNStyle>
              <dmndi:FillColor red="255" green="255" blue="255"/>
              <dmndi:StrokeColor red="0" green="0" blue="0"/>
              <dmndi:FontColor red="0" green="0" blue="0"/>
            </dmndi:DMNStyle>
            <dc:Bounds x="404" y="311" width="100" height="50"/>
            <dmndi:DMNLabel/>
          </dmndi:DMNShape>
          <dmndi:DMNEdge id="dmnedge-_2F819B03-36B7-4DEB-AED6-2B46AE3ADB75" dmnElementRef="_2F819B03-36B7-4DEB-AED6-2B46AE3ADB75">
            <di:waypoint x="504" y="489"/>
            <di:waypoint x="404" y="336"/>
          </dmndi:DMNEdge>
        </dmndi:DMNDiagram>
      </dmndi:DMNDI>
    </dmn:definitions>

    To create this example DMN model in VSCode using the DMN modeler, follow these steps:

    1. Open the empty PersonDecisions.dmn file, click the Properties icon in the upper-right corner of the DMN modeler, and confirm that the DMN model Name is set to PersonDecisions.
    2. In the left palette, select DMN Input Data, drag the node to the canvas, and double-click the node to name it Person.
    3. In the left palette, drag the DMN Decision node to the canvas, double-click the node to name it isAdult, and link to it from the input node.
    4. Select the decision node to display the node options and click the Edit icon to open the DMN boxed expression editor to define the decision logic for the node.
    5. Click the undefined expression field and select Decision Table.
    6. Click the upper-left corner of the decision table to set the hit policy to Unique.
    7. Set the input and output columns so that the input source Person.Age with type number determines the age limit and the output target isAdult with type boolean determines adult status:

      Figure 5.4. Example DMN decision table for isAdult decision

      Image of PersonDecisions decision table
    8. In the upper tab options, select the Data Types tab and add the following tPerson structured data type and nested data types:

      Figure 5.5. Example DMN data types

      Image of PersonDecisions data types
    9. After you define the data types, select the Editor tab to return to the DMN modeler canvas.
    10. Select the Person input node, click the Properties icon, and under Information item, set the Data type to tPerson.
    11. Select the isAdult decision node, click the Properties icon, and under Information item, confirm that the Data type is still set to boolean. You previously set this data type when you created the decision table.
    12. Save the DMN decision file.

5.1. Using DRL rule units as an alternative decision service

You can also use a Drools Rule Language (DRL) file implemented as a rule unit to define this example decision service, as an alternative to using Decision Model and Notation (DMN).

A DRL rule unit is a module for rules and a unit of execution. A rule unit collects a set of rules with the declaration of the type of facts that the rules act on. A rule unit also serves as a unique namespace for each group of rules. A single rule base can contain multiple rule units. You typically store all the rules for a unit in the same file as the unit declaration so that the unit is self-contained. For more information about rule units, see Designing a decision service using DRL rules.

Prerequisites

Procedure

  1. In the src/main/resources folder of your example project, instead of using a DMN file, add the following PersonRules.drl file:

    Example PersonRules DRL file

    package org.acme
    unit PersonRules;
    
    import org.acme.Person;
    
    rule isAdult
    	when
    		$person: /person[ age > 18 ]
    	then
        modify($person) {
        	setAdult(true)
        };
    	end
    
    	query persons
    		$p : /person[ adult ]
    		end

    This example rule determines that any person who is older than 18 is classified as an adult. The rule file also declares that the rule belongs to the rule unit PersonRules. When you build the project, the rule unit is generated and associated with the DRL file.

    The rule also defines the condition using OOPath notation. OOPath is an object-oriented syntax extension to XPath for navigating through related elements while handling collections and filtering constraints.

    You can also rewrite the same rule condition in a more explicit form using the traditional rule pattern syntax, as shown in the following example:

    Example PersonRules DRL file using traditional notation

    package org.acme
    unit PersonRules;
    
    import org.acme.Person;
    
    rule isAdult
    	when
    		$person: Person(age > 18) from person
    	then
        modify($person) {
        	setAdult(true)
        };
    	end
    
    	query persons
    		$p : /person[ adult ]
    		end

Chapter 6. Running a Red Hat build of Kogito microservice

After you design the business decisions for your Red Hat build of Kogito microservice, you can run your Red Hat build of Quarkus or Spring Boot application in one of the following modes:

  • Development mode: For local testing. On Red Hat build of Quarkus, development mode also offers live reload of your decisions in your running applications for advanced debugging.
  • JVM mode: For compatibility with a Java virtual machine (JVM).

Procedure

In a command terminal, navigate to the project that contains your Red Hat build of Kogito microservice and enter one of the following commands, depending on your preferred run mode and application environment:

  • For development mode:

    On Red Hat build of Quarkus

    $ mvn clean compile quarkus:dev

    On Sprint Boot

    $ mvn clean compile spring-boot:run

  • For JVM mode:

    On Red Hat build of Quarkus and Spring Boot

    $ mvn clean package
    $ java -jar target/sample-kogito-1.0-SNAPSHOT-runner.jar

Chapter 7. Interacting with a running Red Hat build of Kogito microservice

After your Red Hat build of Kogito microservice is running, you can send REST API requests to interact with your application and execute your microservices according to how you set up the application.

This example tests the /persons REST API endpoint that is automatically generated the decisions in the PersonDecisions.dmn file (or the rules in the PersonRules.drl file if you used a DRL rule unit).

For this example, use a REST client, curl utility, or the Swagger UI configured for the application (such as http://localhost:8080/q/swagger-ui or http://localhost:8080/swagger-ui.html) to send API requests with the following components:

  • URL: http://localhost:8080/persons
  • HTTP headers: For POST requests only:

    • accept: application/json
    • content-type: application/json
  • HTTP methods: GET, POST, or DELETE

Example POST request body to add an adult (JSON)

{
  "person": {
    "name": "John Quark",
    "age": 20
  }
}

Example curl command to add an adult

curl -X POST http://localhost:8080/persons -H 'content-type: application/json' -H 'accept: application/json' -d '{"person": {"name":"John Quark", "age": 20}}'

Example response (JSON)

{
  "id": "3af806dd-8819-4734-a934-728f4c819682",
  "person": {
    "name": "John Quark",
    "age": 20,
    "adult": false
  },
  "isAdult": true
}

This example procedure uses curl commands for convenience.

Procedure

In a command terminal window that is separate from your running application, navigate to the project that contains your Red Hat build of Kogito microservice and use any of the following curl commands with JSON requests to interact with your running microservice:

Note

On Spring Boot, you might need to modify how your application exposes API endpoints in order for these example requests to function. For more information, see the README file included in the example Spring Boot project that you created for this tutorial.

  • Add an adult person:

    Example request

    curl -X POST http://localhost:8080/persons -H 'content-type: application/json' -H 'accept: application/json' -d '{"person": {"name":"John Quark", "age": 20}}'

    Example response

    {"id":"3af806dd-8819-4734-a934-728f4c819682","person":{"name":"John Quark","age":20,"adult":false},"isAdult":true}

  • Add an underage person:

    Example request

    curl -X POST http://localhost:8080/persons -H 'content-type: application/json' -H 'accept: application/json' -d '{"person": {"name":"Jenny Quark", "age": 15}}'

    Example response

    {"id":"8eef502b-012b-4628-acb7-73418a089c08","person":{"name":"Jenny Quark","age":15,"adult":false},"isAdult":false}

  • Complete the evaluation using the returned UUIDs:

    Example request

    curl -X POST http://localhost:8080/persons/8eef502b-012b-4628-acb7-73418a089c08/ChildrenHandling/cdec4241-d676-47de-8c55-4ee4f9598bac -H 'content-type: application/json' -H 'accept: application/json' -d '{}'

Part II. Deploying Red Hat build of Kogito microservices on Red Hat OpenShift Container Platform

As a developer of business decisions and processes, you can deploy Red Hat build of Kogito microservices on Red Hat OpenShift Container Platform for cloud implementation. The RHPAM Kogito Operator automates many of the deployment steps for you or guides you through the deployment process.

Prerequisites

  • Red Hat OpenShift Container Platform 4.6 or 4.7 is installed.
  • The OpenShift project for the deployment is created.

Chapter 8. Red Hat build of Kogito on Red Hat OpenShift Container Platform

You can deploy Red Hat build of Kogito microservices on Red Hat OpenShift Container Platform for cloud implementation. In this architecture, Red Hat build of Kogito microservices are deployed as OpenShift pods that you can scale up and down individually to provide as few or as many containers as required for a particular service.

To help you deploy your Red Hat build of Kogito microservices on OpenShift, Red Hat Decision Manager provides Red Hat Process Automation Manager Kogito Operator. This operator guides you through the deployment process. The operator is based on the Operator SDK and automates many of the deployment steps for you. For example, when you provide the operator with a link to the Git repository that contains your application, the operator automatically configures the components required to build your project from source and deploys the resulting services.

To install the Red Hat Process Automation Manager Kogito Operator in OpenShift web console, go to OperatorsOperatorHub in the left menu, search for and select RHPAM Kogito Operator, and follow the on-screen instructions to install the latest operator version.

Chapter 9. OpenShift deployment options with the RHPAM Kogito Operator

After you create your Red Hat build of Kogito microservices as part of a business application, you can use the Red Hat OpenShift Container Platform web console to deploy your microservices. The RHPAM Kogito Operator page in the OpenShift web console guides you through the deployment process.

The RHPAM Kogito Operator supports the following options for building and deploying Red Hat build of Kogito microservices on Red Hat OpenShift Container Platform:

  • Git source build and deployment
  • Binary build and deployment
  • Custom image build and deployment
  • File build and deployment

9.1. Deploying Red Hat build of Kogito microservices on OpenShift using Git source build and OpenShift web console

The RHPAM Kogito Operator uses the following custom resources to deploy domain-specific microservices (the microservices that you develop):

  • KogitoBuild builds an application using the Git URL or other sources and produces a runtime image.
  • KogitoRuntime starts the runtime image and configures it as per your requirements.

In most use cases, you can use the standard runtime build and deployment method to deploy Red Hat build of Kogito microservices on OpenShift from a Git repository source, as shown in the following procedure.

Note

If you are developing or testing your Red Hat build of Kogito microservice locally, you can use the binary build, custom image build, or file build option to build and deploy from a local source instead of from a Git repository.

Prerequisites

  • The RHPAM Kogito Operator is installed.
  • The application with your Red Hat build of Kogito microservices is in a Git repository that is reachable from your OpenShift environment.
  • You have access to the OpenShift web console with the necessary permissions to create and edit KogitoBuild and KogitoRuntime.
  • (Red Hat build of Quarkus only) The pom.xml file of your project contains the following dependency for the quarkus-smallrye-health extension. This extension enables the liveness and readiness probes that are required for Red Hat build of Quarkus projects on OpenShift.

    SmallRye Health dependency for Red Hat build of Quarkus applications on OpenShift

    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-smallrye-health</artifactId>
    </dependency>

Procedure

  1. Go to OperatorsInstalled Operators and select RHPAM Kogito Operator.
  2. To create the Red Hat build of Kogito build definition, on the operator page, select the Kogito Build tab and click Create KogitoBuild.
  3. In the application window, use Form View or YAML View to configure the build definition.

    At a minimum, define the application configurations shown in the following example YAML file:

    Example YAML definition for a Red Hat build of Quarkus application with Red Hat build of Kogito build

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this service
    kind: KogitoBuild  # Application type
    metadata:
      name: example-quarkus  # Application name
    spec:
      type: RemoteSource
      gitSource:
        uri: 'https://github.com/kiegroup/kogito-examples'  # Git repository containing application (uses default branch)
        contextDir: dmn-quarkus-example  # Git folder location of application

    Example YAML definition for a Spring Boot application with Red Hat build of Kogito build

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this service
    kind: KogitoBuild  # Application type
    metadata:
      name: example-springboot  # Application name
    spec:
      runtime: springboot
      type: RemoteSource
      gitSource:
        uri: 'https://github.com/kiegroup/kogito-examples'  # Git repository containing application (uses default branch)
        contextDir: dmn-springboot-example  # Git folder location of application

    Note

    If you configured an internal Maven repository, you can use it as a Maven mirror service and specify the Maven mirror URL in your Red Hat build of Kogito build definition to shorten build time substantially:

    spec:
      mavenMirrorURL: http://nexus3-nexus.apps-crc.testing/repository/maven-public/

    For more information about internal Maven repositories, see the Apache Maven documentation.

  4. After you define your application data, click Create to generate the Red Hat build of Kogito build.

    Your application is listed in the Red Hat build of KogitoBuilds page. You can select the application name to view or modify application settings and YAML details.

  5. To create the Red Hat build of Kogito microservice definition, on the operator page, select the Kogito Runtime tab and click Create KogitoRuntime.
  6. In the application window, use Form View or YAML View to configure the microservice definition.

    At a minimum, define the application configurations shown in the following example YAML file:

    Example YAML definition for a Red Hat build of Quarkus application with Red Hat build of Kogito microservices

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
    kind: KogitoRuntime  # Application type
    metadata:
      name: example-quarkus  # Application name

    Example YAML definition for a Spring Boot application with Red Hat build of Kogito microservices

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
    kind: KogitoRuntime  # Application type
    metadata:
      name: example-springboot  # Application name
    spec:
      runtime: springboot

    Note

    In this case, the application is built from Git and deployed using KogitoRuntime. You must ensure that the application name is same in KogitoBuild and KogitoRuntime.

  7. After you define your application data, click Create to generate the Red Hat build of Kogito microservice.

    Your application is listed in the Red Hat build of Kogito microservice page. You can select the application name to view or modify application settings and the contents of the YAML file.

  8. In the left menu of the web console, go to BuildsBuilds to view the status of your application build.

    You can select a specific build to view build details.

    Note

    For every Red Hat build of Kogito microservice that you create for OpenShift deployment, two builds are generated and listed in the Builds page in the web console: a traditional runtime build and a Source-to-Image (S2I) build with the suffix -builder. The S2I mechanism builds the application in an OpenShift build and then passes the built application to the next OpenShift build to be packaged into the runtime container image. The Red Hat build of Kogito S2I build configuration also enables you to build the project directly from a Git repository on the OpenShift platform.

  9. After the application build is complete, go to WorkloadsDeployments to view the application deployments, pod status, and other details.
  10. After your Red Hat build of Kogito microservice is deployed, in the left menu of the web console, go to NetworkingRoutes to view the access link to the deployed application.

    You can select the application name to view or modify route settings.

    With the application route, you can integrate your Red Hat build of Kogito microservices with your business automation solutions as needed.

9.2. Deploying Red Hat build of Kogito microservices on OpenShift using binary build and OpenShift web console

OpenShift builds can require extensive amounts of time. As a faster alternative for building and deploying your Red Hat build of Kogito microservices on OpenShift, you can use a binary build.

The operator uses the following custom resources to deploy domain-specific microservices (the microservices that you develop):

  • KogitoBuild processes an uploaded application and produces a runtime image.
  • KogitoRuntime starts the runtime image and configures it as per your requirements.

Prerequisites

  • The RHPAM Kogito Operator is installed.
  • The oc OpenShift CLI is installed and you are logged in to the relevant OpenShift cluster. For oc installation and login instructions, see the OpenShift documentation.
  • You have access to the OpenShift web console with the necessary permissions to create and edit KogitoBuild and KogitoRuntime.
  • (Red Hat build of Quarkus only) The pom.xml file of your project contains the following dependency for the quarkus-smallrye-health extension. This extension enables the liveness and readiness probes that are required for Red Hat build of Quarkus projects on OpenShift.

    SmallRye Health dependency for Red Hat build of Quarkus applications on OpenShift

    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-smallrye-health</artifactId>
    </dependency>

Procedure

  1. Build an application locally.
  2. Go to OperatorsInstalled Operators and select RHPAM Kogito Operator.
  3. To create the Red Hat build of Kogito build definition, on the operator page, select the Kogito Build tab and click Create KogitoBuild.
  4. In the application window, use Form View or YAML View to configure the build definition.

    At a minimum, define the application configurations shown in the following example YAML file:

    Example YAML definition for a Red Hat build of Quarkus application with Red Hat build of Kogito build

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this service
    kind: KogitoBuild  # Application type
    metadata:
      name: example-quarkus  # Application name
    spec:
      type: Binary

    Example YAML definition for a Spring Boot application with Red Hat build of Kogito build

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this service
    kind: KogitoBuild  # Application type
    metadata:
      name: example-springboot  # Application name
    spec:
      runtime: springboot
      type: Binary

  5. After you define your application data, click Create to generate the Red Hat build of Kogito build.

    Your application is listed in the Red Hat build of KogitoBuilds page. You can select the application name to view or modify application settings and YAML details.

  6. Upload the built binary using the following command:

    $ oc start-build example-quarkus --from-dir=target/ -n namespace
    • from-dir is equals to the target folder path of the built application.
    • namespace is the namespace where KogitoBuild is created.
  7. To create the Red Hat build of Kogito microservice definition, on the operator page, select the Kogito Runtime tab and click Create KogitoRuntime.
  8. In the application window, use Form View or YAML View to configure the microservice definition.

    At a minimum, define the application configurations shown in the following example YAML file:

    Example YAML definition for a Red Hat build of Quarkus application with Red Hat build of Kogito microservices

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
    kind: KogitoRuntime  # Application type
    metadata:
      name: example-quarkus  # Application name

    Example YAML definition for a Spring Boot application with Red Hat build of Kogito microservices

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
    kind: KogitoRuntime  # Application type
    metadata:
      name: example-springboot  # Application name
    spec:
      runtime: springboot

    Note

    In this case, the application is built locally and deployed using KogitoRuntime. You must ensure that the application name is same in KogitoBuild and KogitoRuntime.

  9. After you define your application data, click Create to generate the Red Hat build of Kogito microservice.

    Your application is listed in the Red Hat build of Kogito microservice page. You can select the application name to view or modify application settings and the contents of the YAML file.

  10. In the left menu of the web console, go to BuildsBuilds to view the status of your application build.

    You can select a specific build to view build details.

  11. After the application build is complete, go to WorkloadsDeployments to view the application deployments, pod status, and other details.
  12. After your Red Hat build of Kogito microservice is deployed, in the left menu of the web console, go to NetworkingRoutes to view the access link to the deployed application.

    You can select the application name to view or modify route settings.

    With the application route, you can integrate your Red Hat build of Kogito microservices with your business automation solutions as needed.

9.3. Deploying Red Hat build of Kogito microservices on OpenShift using custom image build and OpenShift web console

You can use custom image build as an alternative for building and deploying your Red Hat build of Kogito microservices on OpenShift.

The operator uses the following custom resources to deploy domain-specific microservices (the microservices that you develop):

  • KogitoRuntime starts the runtime image and configures it as per your requirements.

Prerequisites

  • The RHPAM Kogito Operator is installed.
  • You have access to the OpenShift web console with the necessary permissions to create and edit KogitoRuntime.
  • (Red Hat build of Quarkus only) The pom.xml file of your project contains the following dependency for the quarkus-smallrye-health extension. This extension enables the liveness and readiness probes that are required for Red Hat build of Quarkus projects on OpenShift.

    SmallRye Health dependency for Red Hat build of Quarkus applications on OpenShift

    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-smallrye-health</artifactId>
    </dependency>

Procedure

  1. Build an application locally.
  2. Create Containerfile in the project root folder with the following content:

    Example Containerfile for a Red Hat build of Quarkus application

    FROM registry.redhat.io/rhpam-7/rhpam-kogito-runtime-jvm-rhel8:7.11.0
    
    ENV RUNTIME_TYPE quarkus
    
    COPY target/quarkus-app/lib/ $KOGITO_HOME/bin/lib/
    COPY target/quarkus-app/*.jar $KOGITO_HOME/bin
    COPY target/quarkus-app/app/ $KOGITO_HOME/bin/app/
    COPY target/quarkus-app/quarkus/ $KOGITO_HOME/bin/quarkus/

    Example Containerfile for a Spring Boot application

    FROM registry.redhat.io/rhpam-7/rhpam-kogito-runtime-jvm-rhel8:7.11.0
    
    ENV RUNTIME_TYPE springboot
    
    COPY target/<application-jar-file> $KOGITO_HOME/bin

    • application-jar-file is the name of the JAR file of the application.
  3. Build the Red Hat build of Kogito image using the following command:

    podman build --tag <final-image-name> -f <Container-file>

    In the previous command, final-image-name is the name of the Red Hat build of Kogito image and Container-file is name of the Containerfile that you created in the previous step.

  4. Optionally, test the built image using the following command:

    podman run --rm -it -p 8080:8080 <final-image-name>
  5. Push the built Red Hat build of Kogito image to an image registry using the following command:

    podman push <final-image-name>
  6. Go to OperatorsInstalled Operators and select RHPAM Kogito Operator.
  7. To create the Red Hat build of Kogito microservice definition, on the operator page, select the Kogito Runtime tab and click Create KogitoRuntime.
  8. In the application window, use Form View or YAML View to configure the microservice definition.

    At a minimum, define the application configurations shown in the following example YAML file:

    Example YAML definition for a Red Hat build of Quarkus application with Red Hat build of Kogito microservices

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
    kind: KogitoRuntime # Application type
    metadata:
      name: example-quarkus # Application name
    spec:
      image: <final-image-name> # Kogito image name
      insecureImageRegistry: true # Can be omitted when image is pushed into secured registry with valid certificate

    Example YAML definition for a Spring Boot application with Red Hat build of Kogito microservices

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
    kind: KogitoRuntime # Application type
    metadata:
      name: example-springboot # Application name
    spec:
      image: <final-image-name> # Kogito image name
      insecureImageRegistry: true # Can be omitted when image is pushed into secured registry with valid certificate
      runtime: springboot

  9. After you define your application data, click Create to generate the Red Hat build of Kogito microservice.

    Your application is listed in the Red Hat build of Kogito microservice page. You can select the application name to view or modify application settings and the contents of the YAML file.

  10. After the application build is complete, go to WorkloadsDeployments to view the application deployments, pod status, and other details.
  11. After your Red Hat build of Kogito microservice is deployed, in the left menu of the web console, go to NetworkingRoutes to view the access link to the deployed application.

    You can select the application name to view or modify route settings.

    With the application route, you can integrate your Red Hat build of Kogito microservices with your business automation solutions as needed.

9.4. Deploying Red Hat build of Kogito microservices on OpenShift using file build and OpenShift web console

You can build and deploy your Red Hat build of Kogito microservices from a single file, such as a Decision Model and Notation (DMN), Drools Rule Language (DRL), or properties file, or from a directory with multiple files. You can specify a single file from your local file system path or specify a file directory from a local file system path only. When you upload the file or directory to an OpenShift cluster, a new Source-to-Image (S2I) build is automatically triggered.

The operator uses the following custom resources to deploy domain-specific microservices (the microservices that you develop):

  • KogitoBuild generates an application from a file and produces a runtime image.
  • KogitoRuntime starts the runtime image and configures it as per your requirements.

Prerequisites

  • The RHPAM Kogito Operator is installed.
  • The oc OpenShift CLI is installed and you are logged in to the relevant OpenShift cluster. For oc installation and login instructions, see the OpenShift documentation.
  • You have access to the OpenShift web console with the necessary permissions to create and edit KogitoBuild and KogitoRuntime.

Procedure

  1. Go to OperatorsInstalled Operators and select RHPAM Kogito Operator.
  2. To create the Red Hat build of Kogito build definition, on the operator page, select the Kogito Build tab and click Create KogitoBuild.
  3. In the application window, use Form View or YAML View to configure the build definition.

    At a minimum, define the application configurations shown in the following example YAML file:

    Example YAML definition for a Red Hat build of Quarkus application with Red Hat build of Kogito build

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this service
    kind: KogitoBuild  # Application type
    metadata:
      name: example-quarkus  # Application name
    spec:
      type: LocalSource

    Example YAML definition for a Spring Boot application with Red Hat build of Kogito build

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this service
    kind: KogitoBuild  # Application type
    metadata:
      name: example-springboot  # Application name
    spec:
      runtime: springboot
      type: LocalSource

    Note

    If you configured an internal Maven repository, you can use it as a Maven mirror service and specify the Maven mirror URL in your Red Hat build of Kogito build definition to shorten build time substantially:

    spec:
      mavenMirrorURL: http://nexus3-nexus.apps-crc.testing/repository/maven-public/

    For more information about internal Maven repositories, see the Apache Maven documentation.

  4. After you define your application data, click Create to generate the Red Hat build of Kogito build.

    Your application is listed in the Red Hat build of KogitoBuilds page. You can select the application name to view or modify application settings and YAML details.

  5. Upload the file asset using the following command:

    $ oc start-build example-quarkus-builder --from-file=<file-asset-path> -n namespace
    • file-asset-path is the path of the file asset that you want to upload.
    • namespace is the namespace where KogitoBuild is created.
  6. To create the Red Hat build of Kogito microservice definition, on the operator page, select the Kogito Runtime tab and click Create KogitoRuntime.
  7. In the application window, use Form View or YAML View to configure the microservice definition.

    At a minimum, define the application configurations shown in the following example YAML file:

    Example YAML definition for a Red Hat build of Quarkus application with Red Hat build of Kogito microservices

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
    kind: KogitoRuntime  # Application type
    metadata:
      name: example-quarkus  # Application name

    Example YAML definition for a Spring Boot application with Red Hat build of Kogito microservices

    apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
    kind: KogitoRuntime  # Application type
    metadata:
      name: example-springboot  # Application name
    spec:
      runtime: springboot

    Note

    In this case, the application is built from a file and deployed using KogitoRuntime. You must ensure that the application name is same in KogitoBuild and KogitoRuntime.

  8. After you define your application data, click Create to generate the Red Hat build of Kogito microservice.

    Your application is listed in the Red Hat build of Kogito microservice page. You can select the application name to view or modify application settings and the contents of the YAML file.

  9. In the left menu of the web console, go to BuildsBuilds to view the status of your application build.

    You can select a specific build to view build details.

    Note

    For every Red Hat build of Kogito microservice that you create for OpenShift deployment, two builds are generated and listed in the Builds page in the web console: a traditional runtime build and a Source-to-Image (S2I) build with the suffix -builder. The S2I mechanism builds the application in an OpenShift build and then passes the built application to the next OpenShift build to be packaged into the runtime container image.

  10. After the application build is complete, go to WorkloadsDeployments to view the application deployments, pod status, and other details.
  11. After your Red Hat build of Kogito microservice is deployed, in the left menu of the web console, go to NetworkingRoutes to view the access link to the deployed application.

    You can select the application name to view or modify route settings.

    With the application route, you can integrate your Red Hat build of Kogito microservices with your business automation solutions as needed.

Chapter 10. Probes for Red Hat build of Kogito microservices on Red Hat OpenShift Container Platform

The probes in Red Hat OpenShift Container Platform verify that an application is working or it needs to be restarted. For Red Hat build of Kogito microservices on Red Hat build of Quarkus and Spring Boot, probes interact with the application using an HTTP request, defaulting to the endpoints that are exposed by an extension. Therefore, to run your Red Hat build of Kogito microservices on Red Hat OpenShift Container Platform, you must import the extensions to provide application availability information for the liveness, readiness, and startup probes.

10.1. Adding health check extension for Red Hat build of Quarkus applications on Red Hat OpenShift Container Platform

You can add the health check extension for the Red Hat build of Kogito services that are based on Red Hat build of Quarkus on Red Hat OpenShift Container Platform.

Procedure

In a command terminal, navigate to the pom.xml file of your project and add the following dependency for the quarkus-smallrye-health extension:

SmallRye Health dependency for Red Hat build of Quarkus applications on Red Hat OpenShift Container Platform

<dependencies>
  <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-health</artifactId>
  </dependency>
</dependencies>

10.2. Adding health check extension for Spring Boot applications on Red Hat OpenShift Container Platform

You can add the health check extension for the Red Hat build of Kogito microservices that are based on Spring Boot on Red Hat OpenShift Container Platform.

Procedure

In a command terminal, navigate to the pom.xml file of your project and add the following Spring Boot actuator dependency:

Spring Boot actuator dependency for Spring Boot applications on Red Hat OpenShift Container Platform

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
</dependencies>

10.3. Setting custom probes for Red Hat build of Kogito microservices on Red Hat OpenShift Container Platform

You can also configure the custom endpoints for the liveness, readiness, and startup probes.

Procedure

  1. Define the probes in the KogitoRuntime YAML file of your project, as shown in the following example:

Example Red Hat build of Kogito microservice custom resource with custom probe endpoints

apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this service
kind: KogitoRuntime
metadata:
  name: process-quarkus-example # Application name
spec:
  replicas: 1
  probes:
    livenessProbe:
      httpGet:
        path: /probes/live # Liveness endpoint
        port: 8080
    readinessProbe:
      httpGet:
        path: /probes/ready # Readiness endpoint
        port: 8080
    startupProbe:
      tcpSocket:
        port: 8080

Chapter 11. Red Hat Process Automation Manager Kogito Operator interaction with Prometheus and Grafana

Red Hat build of Kogito in Red Hat Decision Manager provides a monitoring-prometheus-addon add-on that enables Prometheus metrics monitoring for Red Hat build of Kogito microservices and generates Grafana dashboards that consume the default metrics exported by the add-on. The RHPAM Kogito Operator uses the Prometheus Operator to expose the metrics from your project for Prometheus to scrape. Due to this dependency, the Prometheus Operator must be installed in the same namespace as your project.

If you want to enable the Prometheus metrics monitoring for your Red Hat build of Kogito microservices, add the following dependency to the pom.xml file in your project, depending on the framework you are using:

Dependency for Prometheus Red Hat build of Quarkus add-on

<dependency>
      <groupId>org.kie.kogito</groupId>
      <artifactId>monitoring-prometheus-quarkus-addon</artifactId>
</dependency>

Dependency for Prometheus Spring Boot add-on

<dependency>
      <groupId>org.kie.kogito</groupId>
      <artifactId>monitoring-prometheus-springboot-addon</artifactId>
</dependency>

When you deploy a Red Hat build of Kogito microservice that uses the monitoring-prometheus-addon add-on and the Prometheus Operator is installed, the Red Hat Process Automation Manager Kogito Operator creates a ServiceMonitor custom resource to expose the metrics for Prometheus, as shown in the following example:

Example ServiceMonitor resource for Prometheus

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  labels:
    app: onboarding-service
  name: onboarding-service
  namespace: kogito
spec:
  endpoints:
  - path: /metrics
    targetPort: 8080
    scheme: http
  namespaceSelector:
    matchNames:
    - kogito
  selector:
    matchLabels:
      app: onboarding-service

You must manually configure your Prometheus custom resource that is managed by the Prometheus Operator to select the ServiceMonitor resource:

Example Prometheus resource

apiVersion: monitoring.coreos.com/v1
kind: Prometheus
metadata:
  name: prometheus
spec:
  serviceAccountName: prometheus
  serviceMonitorSelector:
    matchLabels:
      app: dmn-drools-quarkus-metrics-service

After you configure your Prometheus resource with the ServiceMonitor resource, you can see the endpoint scraped by Prometheus in the Targets page in the Prometheus web console. The metrics exposed by the Red Hat Decision Manager service appear in the Graph view.

The RHPAM Kogito Operator also creates a GrafanaDashboard custom resource defined by the Grafana Operator for each of the Grafana dashboards generated by the add-on. The app label for the dashboards is the name of the deployed Red Hat build of Kogito microservice. You must set the dashboardLabelSelector property of the Grafana custom resource according to the relevant Red Hat build of Kogito microservice.

Example Grafana resource

apiVersion: integreatly.org/v1alpha1
kind: Grafana
metadata:
  name: example-grafana
spec:
  ingress:
    enabled: true
  config:
    auth:
      disable_signout_menu: true
    auth.anonymous:
      enabled: true
    log:
      level: warn
      mode: console
    security:
      admin_password: secret
      admin_user: root
  dashboardLabelSelector:
    - matchExpressions:
        - key: app
          operator: In
          values:
            - my-kogito-application

Chapter 12. Red Hat build of Kogito microservice deployment troubleshooting

Use the information in this section to troubleshoot issues that you might encounter when using the operator to deploy Red Hat build of Kogito microservices. The following information is updated as new issues and workarounds are discovered.

No builds are running

If you do not see any builds running nor any resources created in the relevant namespace, enter the following commands to retrieve running pods and to view the operator log for the pod:

View RHPAM Kogito Operator log for a specified pod

// Retrieves running pods
$ oc get pods

NAME                                     READY   STATUS      RESTARTS   AGE
kogito-operator-6d7b6d4466-9ng8t   1/1     Running     0          26m

// Opens RHPAM Kogito Operator log for the pod
$ oc logs -f kogito-operator-6d7b6d4466-9ng8t

Verify KogitoRuntime status

If you create, for example, KogitoRuntime application with a non-existing image using the following YAML definition:

Example YAML definition for a KogitoRuntime application

apiVersion: rhpam.kiegroup.org/v1 # Red Hat build of Kogito API for this microservice
kind: KogitoRuntime # Application type
metadata:
  name: example # Application name
spec:
  image: 'not-existing-image:latest'
  replicas: 1

You can verify the status of the KogitoRuntime application using the oc describe KogitoRuntime example command in the bash console. When you run the oc describe KogitoRuntime example command in the bash console, you receive the following output:

Example KogitoRuntime status

[user@localhost ~]$ oc describe KogitoRuntime example
Name:         example
Namespace:    username-test
Labels:       <none>
Annotations:  <none>
API Version:  rhpam.kiegroup.org/v1
Kind:         KogitoRuntime
Metadata:
  Creation Timestamp:  2021-05-20T07:19:41Z
  Generation:          1
  Managed Fields:
    API Version:  rhpam.kiegroup.org/v1
    Fields Type:  FieldsV1
    fieldsV1:
      f:spec:
        .:
        f:image:
        f:replicas:
    Manager:      Mozilla
    Operation:    Update
    Time:         2021-05-20T07:19:41Z
    API Version:  rhpam.kiegroup.org/v1
    Fields Type:  FieldsV1
    fieldsV1:
      f:spec:
        f:monitoring:
        f:probes:
          .:
          f:livenessProbe:
          f:readinessProbe:
        f:resources:
        f:runtime:
      f:status:
        .:
        f:cloudEvents:
        f:conditions:
    Manager:         main
    Operation:       Update
    Time:            2021-05-20T07:19:45Z
  Resource Version:  272185
  Self Link:         /apis/rhpam.kiegroup.org/v1/namespaces/ksuta-test/kogitoruntimes/example
  UID:               edbe0bf1-554e-4523-9421-d074070df982
Spec:
  Image:     not-existing-image:latest
  Replicas:  1
Status:
  Cloud Events:
  Conditions:
    Last Transition Time:  2021-05-20T07:19:44Z
    Message:
    Reason:                NoPodAvailable
    Status:                False
    Type:                  Deployed
    Last Transition Time:  2021-05-20T07:19:44Z
    Message:
    Reason:                RequestedReplicasNotEqualToAvailableReplicas
    Status:                True
    Type:                  Provisioning
    Last Transition Time:  2021-05-20T07:19:45Z
    Message:               you may not have access to the container image "quay.io/kiegroup/not-existing-image:latest"
    Reason:                ImageStreamNotReadyReason
    Status:                True
    Type:                  Failed

At the end of the output, you can see the KogitoRuntime status with a relevant message.

Chapter 13. Additional resources

Appendix A. Versioning information

Documentation last updated on Friday, July 16, 2021.

Appendix B. Contact information

Red Hat Decision Manager documentation team: brms-docs@redhat.com

Legal Notice

Copyright © 2021 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.