The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Kogitoを使用してアプリケーションにビジネスオートメーション機能を追加する

このガイドでは、QuarkusアプリケーションがKogitoを使用してビジネスオートメーションを追加し、ビジネスプロセスとルールでパワーアップする方法を説明します。

Kogitoは、有名なオープンソースプロジェクトであるDrools (ビジネスルール用)とjBPM (ビジネスプロセス用)から生まれた次世代のビジネスオートメーションツールキットです。Kogitoは、ビジネスナレッジ(プロセス、ルール、意思決定、予測)をドメイン固有の方法で公開することを主なメッセージとするビジネスオートメーションへの別のアプローチを提供することを目的としています。

前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE (VSCode is preferred with the Red Hat BPMN Editor VSCode Extension)

  • JDK 11+ がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.8.1+

  • 動作するコンテナランタイム(Docker, Podman)

  • 使用したい場合、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

モデリングプラグインをIDEにインストールする

Kogito Toolingは現在VSCodeでオンラインおよび他のプラットフォームでサポートされています。

VSCode

VSCode IDE からプロセス定義を編集およびモデル化するために、 Red Hat BPMN エディタVSCodeエクステンション をダウンロードしてインストールします。

Online

モデラーのインストールを避けるために、 BPMN.new を直接使用して、お気に入りのWebブラウザを使ってプロセスの設計とモデリングを行うことができます。

Eclipse

プロセスのビジュアル・モデリングを利用するには、Eclipse IDEをダウンロードし、MarketplaceからEclipse BPMN2 Modellerプラグイン(with jBPM Runtime Extension)をインストールします。

その他のプラットフォーム

Business Modeler Hubでは、 Kogito toolingリリースでサポートされている最新のプラットフォームをダウンロードすることができます。

アーキテクチャ

この例では、1つのRESTエンドポイントを提供する非常にシンプルなマイクロサービスを構築します。

  • /persons

このエンドポイントは、ビジネスプロセスに基づいて自動的に生成され、ひいてはビジネスルールを利用して処理中のデータに基づいて一定の判断を下すことになります。

ビジネスプロセス

ビジネスプロセスは、マイクロサービスのビジネスロジックをカプセル化する責任があります。これは、ビジネス目標を達成するためのステップの完全なセットを提供する必要があります。同時に、これはクライアントが消費することができるサービスへの入り口となります。

ビジネスルール

ビジネスルールでは、意思決定ロジックを、簡単に使える再利用可能なものに宣言的な方法で外部化することができます。ルールの書き方には、ディシジョンテーブル、ディシジョンツリー、ルールなど複数の書き方があります。この例では、DRL(Drools Rule Language)に裏打ちされたルール形式に焦点を当てています。

この例では、DRL(Drools Rule Language)に裏付けられたルール・フォーマットに焦点を当てていますが、同じビジネス・ロジックは、サポートされている他のKogito知識フォーマットでも表現できます。

ソリューション

次のセクションで紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Gitレポジトリをクローンするか git clone https://github.com/quarkusio/quarkus-quickstarts.gitアーカイブ をダウンロードします。

ソリューションは kogito-quickstart ディレクトリ にあります。

Mavenプロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

CLI
quarkus create app org.acme:kogito-quickstart \
    --extension=kogito,resteasy-reactive-jackson \
    --no-code
cd kogito-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストール方法については、Quarkus CLIガイドをご参照ください。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.11.1.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=kogito-quickstart \
    -Dextensions="kogito,resteasy-reactive-jackson" \
    -DnoCode
cd kogito-quickstart

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

このコマンドはMavenプロジェクトを生成し、アプリケーションにビジネス・オートメーションを装備するために必要な依存関係と設定をすべて備えた kogito エクステンションをインポートします。また、KogitoがRESTサービスを公開するのに必要な resteasy-reactive-jackson エクステンションをインポートします。

すでにQuarkusプロジェクトが設定されている場合は、プロジェクトのベースディレクトリーで以下のコマンドを実行することで、プロジェクトに kogito エクステンションを追加することができます。

CLI
quarkus extension add 'kogito'
Maven
./mvnw quarkus:add-extension -Dextensions="kogito"
Gradle
./gradlew addExtension --extensions="kogito"

これにより、 pom.xml に以下が追加されます:

pom.xml
<dependency>
    <groupId>org.kie.kogito</groupId>
    <artifactId>kogito-quarkus</artifactId>
</dependency>
build.gradle
implementation("org.kie.kogito:kogito-quarkus")

アプリケーションの記述

まずはシンプルなデータオブジェクト Person を実装してみましょう。下のソースコードを見ればわかるように、ただのPOJOです。

package org.acme.kogito.model;

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

}

次に、生成されたプロジェクトの src/main/resources/org/acme/kogito フォルダー内にルールファイル person-rules.drl を作成します。

package org.acme.kogito;

unit PersonUnit;

import org.acme.kogito.model.Person;

rule "Is adult"
when
    $person: /person[age > 18]
then
    modify($person) {
    	setAdult(true)
    };
end

This is really a simple rule that marks a person who is older than 18 years as an adult.

このルール例では、ルール・ユニットを使用しています。これは、Kogitoで導入された新しい概念で、ルールのセットと、それらのルールが照合されるファクトをカプセル化するのに役立ちます。挿入されたファクトは、型安全なエントリ・ポイントである DataStore に挿入されます。すべてを機能させるためには、 src/main/java/org/acme/kogito ディレクトリ内に新しいクラス PersonUnit を作成して、RuleUnit と DataStore の両方を定義する必要があります。

package org.acme.kogito;

import org.acme.kogito.model.Person;
import org.kie.kogito.rules.DataSource;
import org.kie.kogito.rules.RuleUnitData;
import org.kie.kogito.rules.SingletonStore;

public class PersonUnit implements RuleUnitData {

    private SingletonStore<Person> person;

    public PersonUnit() {
        this(DataSource.createSingleton());
    }

    public PersonUnit(SingletonStore<Person> person) {
        this.person = person;
    }

    public SingletonStore<Person> getPerson() {
        return person;
    }

    public void setPerson(SingletonStore<Person> person) {
        this.person = person;
    }
}

Finally, we create a business process that will make use of this rule and some other activities to approve a given person. Using new item wizard (File → New → Other → BPMN2 Model) create persons.bpmn inside src/main/resources/org/acme/kogito folder of the generated project.

このプロセスは次のように構成されています。

  • スタートイベント

  • ビジネスルールタスク

  • 専用ゲートウェイ

  • ユーザータスク

  • エンドイベント

そして、次のようになるはずです。

プロセス定義

簡単に開始するには、https://github.com/quarkusio/quarkus-quickstarts/tree/main/kogito-quickstart/src/main/resources/org/acme/kogito/persons.bpmn2[quickstart]からプロセス定義をコピーします。

このプロセスを自分でモデル化するには、以下の手順に従ってください(開始イベントが自動的に追加されます)。

  • org.acme.kogito.model.Person 型の person という名前を持つプロセス変数を定義します。

  • タスク→ビジネスルールタスクをパレットからドラッグしてスタートイベントの横にドロップし、スタートイベントとリンクさせます。

    • double-click on the business rule task

      • on the tab I/O Parameters, set data input and output (map person process variable to input data with name person and same for data output)

      • on the tab Business Rule Task, set rule flow group to the FQCN value of the RuleUnit using the unit: prefix (unit:org.acme.kogito.PersonUnit)

  • パレットからGateways → XOR gatewayをドラッグして、ビジネスルールタスクの横にドロップし、ルールタスクとリンクさせます。

  • パレットからTasks → User Taskをドラッグしてゲートウェイの横にドロップし、ゲートウェイと連携させます。

    • double-click on the user task

      • on the tab User Task, set task name to ChildrenHandling

      • on the tab I/O Parameters, set data input (map person process variable to input data with name person)

  • パレットからEnd Events → Endをドラッグして、ユーザータスクの横にドロップして、ユーザータスクとリンクさせます。

  • パレットからEnd Events → Endをドラッグして、ゲートウェイの横にドロップして、ユーザータスクとリンクさせます。

  • double-click on the gateway

    • on the tab Gateway, set the diverging direction for the gateway

    • on the tab Gateway, set conditions on sequence flow list

      • → going to end event return person.isAdult() == true; 言語: Java

      • → going to user task return person.isAdult() == false; 言語: Java

  • ファイルを保存する

アプリケーションの実行と使用

JVMモードでの実行

マイクロサービスを開発モードで実行する場合、次を実行して下さい:

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

JVMモードでの実行

When you’re done playing with dev mode, you can run it as a standard Java application.

まずコンパイルします。

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./gradlew build

それから実行してください。

java -jar target/quarkus-app/quarkus-run.jar

ネイティブモードでの実行

同じデモをネイティブコードにコンパイルすることができます。修正は必要ありません。

これは、生成されたバイナリーにランタイム技術が含まれており、最小限のリソースオーバーヘッドで実行できるように最適化されているため、本番環境にJVMをインストールする必要がないことを意味します。

コンパイルには少し時間がかかるので、このステップはデフォルトでは無効になっています。以下のコマンドでネイティブ実行可能ファイルをビルドしてみましょう。

CLI
quarkus build --native
Maven
./mvnw package -Dnative
Gradle
./gradlew build -Dquarkus.package.type=native

コーヒーを飲み終わると、このバイナリーは以下のように直接実行出来るようになります:

./target/kogito-quickstart-1.0.0-SNAPSHOT-runner

アプリケーションのテスト

アプリケーションをテストするには、人をJSONペイロードとして指定してサービスにリクエストを送信するだけです。

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

レスポンスの中では、本人は成人として認められているべきであり、それもレスポンスのペイロードの中で見えるようにしなければなりません。

{"id":"dace1d6a-a5fa-429d-b253-d6b66e265bbc","person":{"adult":true,"age":20,"name":"John Quark"}}

アクティブなインスタンスがないことを確認することもできます。

curl -X GET http://localhost:8080/persons \
    -H 'content-type: application/json' \
    -H 'accept: application/json'

To verify the non-adult case, send another request with the age set to less than 18

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

今回はアクティブなインスタンスが一つあるはずなので、 {uuid} をレスポンスから取得した id 属性に置き換えてください。

curl -X GET http://localhost:8080/persons/{uuid}/tasks \
    -H 'content-type: application/json' \
    -H 'accept: application/json'

別のエンドポイントを呼び出すことでタスクの詳細を取得することができます。 uuids をレスポンスから取得した値( uuid-1 はプロセスインスタンス ID、 uuid-2 はタスクインスタンス ID)に置き換えてください。最初の値はプロセスインスタンスIDに、もう一方の値はタスクインスタンスIDに対応します。

curl -X GET http://localhost:8080/persons/{uuid-1}/ChildrenHandling/{uuid-2} \
    -H 'content-type: application/json' \
    -H 'accept: application/json'

同じエンドポイントをPOSTで呼び出して、 uuids をレスポンスから取得した値( uuid-1 はプロセスインスタンス ID、 uuid-2 はタスクインスタンス ID)で置き換えて、この人物評価プロセスインスタンスを完成させることができます。

curl -X POST http://localhost:8080/persons/{uuid-1}/ChildrenHandling/{uuid-2} \
    -H 'content-type: application/json' \
    -H 'accept: application/json' \
    -d '{}'

永続化を有効にする

Since 0.3.0 of Kogito, there is an option to enable persistence to preserve process instance state across application restarts. That supports long-running process instances that can be resumed at any point in time.

前提条件

Kogito uses Infinispan as the persistence service, so you need to have Infinispan server installed and running. Version of the Infinispan is aligned with Quarkus BOM so make sure the right version is installed.

プロジェクトに依存関係を追加する

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-infinispan-client</artifactId>
</dependency>
<dependency>
    <groupId>org.kie.kogito</groupId>
    <artifactId>infinispan-persistence-addon</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-infinispan-client")
implementation("org.kie.kogito:infinispan-persistence-addon")

Infinispanサーバーとの接続設定

src/main/resources/application.propertiesファイルに以下を追加します(存在しない場合は作成してください)。

quarkus.infinispan-client.server-list=localhost:11222
Infinispan サーバーのインストールに合わせて、ホストとポート番号を調整します。

永続性を有効にしたテスト

プロジェクト レベルで永続性を設定した後、アプリケーションの再起動時にプロセス インスタンスの状態が保持されているかどうかをテストして確認できます。

  • Infinispan サーバーを起動する

  • プロジェクトをビルドして実行する

  • 非成人用ケースを実行する

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

アクティブなインスタンスがあることを確認することもできます。

curl -X GET http://localhost:8080/persons \
    -H 'content-type: application/json' \
    -H 'accept: application/json'

Infinispan サーバーを稼働させている間にアプリケーションを再起動します。

全く同じ ID を持つアクティブなインスタンスが表示されているかどうかを確認します。

curl -X GET http://localhost:8080/persons \
    -H 'content-type: application/json' \
    -H 'accept: application/json'

Kogito の永続化について詳しく知りたい方は こちらのページ をご覧ください。

DMN意思決定テーブルの使用

Kogitoは、Droolsのように、宣言型ロジックの視覚的かつ意味的な実行のための DMNオープン・スタンダードをサポートしています。この例のビジネス・ルールは、DRLやRuleUnitsの代わりに、DMN意思決定テーブルやその他のDMNの視覚的なパラダイムを使って表現することもできます。

KogitoでのDMNサポートの詳細については、 QuarkusでのKogito DMNサポートに特化したQuarkus手引きガイド、または以下のリンクにあるKogitoのドキュメントを参照してください。

レガシー意思決定テーブルの使用

Kogitoでは、Microsoft Excelファイルフォーマットを使用して、ビジネスルールをディシジョンテーブルとして定義することができます。このようなアセットをアプリケーションで使用するには、追加の依存関係が必要です。

pom.xml
<dependency>
    <groupId>org.kie.kogito</groupId>
    <artifactId>drools-decisiontables</artifactId>
</dependency>
build.gradle
implementation("org.kie.kogito:drools-decisiontables")

依存関係がプロジェクトに追加されると、 xlsxlsx 形式のディシジョンテーブルを適切に扱うことができます。